Files

권혁성 db63fcff85 refactor: [docs] 팀별 폴더 구조 재편 (공유/개발/프론트/기획)

- 개발팀 전용 폴더 dev/ 생성 (standards, guides, quickstart, changes, deploys, data, history, dev_plans 이동)
- 프론트엔드 전용 폴더 frontend/ 생성 (api/ → frontend/api-specs/)
- 기획팀 폴더 requests/ 생성
- plans/ → dev/dev_plans/ 이름 변경
- README.md 신규 (사람용 안내), INDEX.md 재작성 (Claude Code용)
- resources.md 신규 (노션 링크용, assets/brochure 이관 예정)
- CURRENT_WORKS.md 삭제, TODO.md → dev/ 이동
- 전체 참조 경로 업데이트

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-05 16:46:03 +09:00

21 KiB

Raw Permalink Blame History

docs/ 종합 정비 계획

작성일: 2026-02-27 상태: ✅ 전체 완료 (Phase 0~4) 목적: 시스템 실제 분석 기반의 문서 재정비 — 현황 정확성 확보 + 구조 표준화 + 중복 제거

1. 배경 및 목적

1.1 왜 필요한가

docs/ 폴더가 초기에 체계적 분석 없이 점진적으로 쌓여왔으며, 시스템의 실제 상태와 문서 간 괴리가 심각해졌다.

핵심 문제:

DB 스키마 문서가 50+개 신규 테이블 미반영 (219개 기록 → 실제 270+개)
2026년 2월 추가된 대형 도메인(재무/회계, 전자서명, 설비, AI, 차량) 기능 문서 부재
실행 계획(plans/) 간 중복·대체 관계 미정리
문서 내 경로·버전 등 사실과 다른 기술 정보 다수
문서 정책(폴더 분류, 명명 규칙, 템플릿) 실제 준수율 낮음

1.2 목표

#	목표	완료 기준
G1	시스템 현황 문서 정확성 100%	DB 스키마, 아키텍처, 스펙이 실제 코드와 일치
G2	모든 활성 도메인에 기능 문서 존재	features/ 하위 도메인별 README.md
G3	실행 계획 통합·정리	중복 제거, 완료분 아카이브, 인덱스 동기화
G4	문서 정책 현행화	INDEX.md, CLAUDE.md, GUIDE.md 실제 반영
G5	중복 데이터 제거	동일 내용의 문서 단일 소스(SSOT) 확보

1.3 범위

분석 대상 (소스 코드)          문서화 대상 (docs/)
┌─────────────────────┐       ┌─────────────────────┐
│ api/   (Laravel 12)  │──→   │ system/              │ ← architecture/ + specs/ 통합
│  - 205 Models        │      │ standards/           │
│  - 179 Services      │      │ rules/               │
│  - 131 Controllers   │      │ features/            │
│  - 458 Migrations    │      │ guides/              │
│  - 18 Route domains  │      │ plans/               │ ← 작업 추적 (예정/진행/완료)
├─────────────────────┤       │ projects/            │ ← 프로젝트성 자료 보관
│ react/ (Next.js 15)  │      │ front/               │
│  - 249 Pages         │      │ quickstart/          │
│  - 612 Components    │      │ changes/             │
│  - 91 Server Actions │      │ deploys/             │
├─────────────────────┤       │ data/                │
│ mng/   (Laravel 12)  │      │ history/             │
│  - 171 Controllers   │      └─────────────────────┘
│  - 436 Blade views   │
│  - 185 Models        │
├─────────────────────┤
│ sales/ (추후 개발)    │
│ docker/ (Nginx 등)   │
└─────────────────────┘

2. 현황 감사 결과

2.1 시스템 vs 문서 격차 (Critical)

영역	문서 상태	실제 시스템	격차
DB 테이블 수	219개 (2026-01-29)	270+개 추정	50+개 미반영
API 도메인	일부만 기록	18개 라우트 도메인	features/ 누락 다수
React 페이지	미기록	249개 페이지	프론트 현황 문서 부재
MNG 기능	일부만 기록	171 컨트롤러, 436 뷰	MNG 현황 문서 부재
기술 스택	Laravel 11 기록	Laravel 12 + PHP 8.4	버전 불일치

2.2 미문서화 도메인 (2026년 2월 신규)

도메인	DB 테이블	API 존재	기능 문서
재무/회계 (Finance)	20+개	✅	❌ 없음
전자서명 (E-Sign)	6개	✅	❌ 없음
설비관리 (Equipment)	6개	✅	❌ 없음
차량관리 (Vehicle)	3개	✅	❌ 없음
AI/음성 (AI)	5개	✅	❌ 없음
면접 (Interview)	5개	✅	❌ 없음
채번규칙 (Numbering)	2개	✅	❌ 없음
문서서식 (DocTemplate)	4개	✅	❌ 없음
바로빌 연동 확장	5개	✅	❌ 없음
회의록 (Meeting)	2개	✅	❌ 없음

2.3 부정확한 문서

문서	문제	심각도
`docs/CLAUDE.md`	경로 `/home/aweso/sam/` (실제: `/Users/kent/...`), Laravel 11 기록	🔴
`docs/specs/database-schema.md`	50+개 테이블 누락, 테이블 수 219로 기록	🔴
`docs/TODO.md`	2025-12-21 이후 미갱신, 보안 이슈 방치	🟡
`docs/rules/README.md`	8개 중 2개만 목록에 있음	🟡
`SAM/CLAUDE.md` (루트)	`SAM_QUICK_REFERENCE.md` 등 경로 불일치	🟡
`docs/projects/mes/MES_PROGRESS_TRACKER.md`	2025-11-13 이후 미갱신	🟡
`docs/projects/api-integration/PROGRESS.md`	2025-12-20 이후 미갱신 (90%?)	🟡

2.4 계획 문서(plans/) 상태

상태	수량	비고
🟡 진행중 (ACTIVE)	18개	일부 장기 정체
⚪ 대기 (WAITING)	19개	선행조건 대기
✅ 완료 (ARCHIVE)	~40개	archive/ 이동 완료
⚠️ 아카이브 필요	2개	`docs-plans-cleanup-plan`, `product-code-traceability-plan`
⚠️ 장기 정체	4개	Phase 4에서 최종 정리 (하단 목록 참조)

장기 정체 계획 (3개월+ 미갱신) — Phase 4에서 최종 정리:

계획	진행률	마지막 갱신
`5130-to-mng-migration-plan.md`	13%	2025-12-17
`erp-api-development-plan.md`	Phase L 완료	2025-12-17
`mng-menu-system-plan.md`	구현 완료, 테스트 대기	2025-12-16
`simulator-ui-enhancement-plan.md`	60%	2025-12-30

3. 확정된 결정 사항

논의 완료 — 이후 모든 Phase에서 이 기준을 따른다

#	결정	내용
D1	DB 스키마 분할	도메인별 분할 — `system/database/` 하위에 도메인별 파일
D2	features/ 문서 깊이	기능 설명 + 엔드포인트 경로 목록 포함, 상세 요청/응답은 Swagger 참조
D3	파일명 정책	한글 허용 — 기술 문서는 영문 kebab-case, 업무/비즈니스 문서는 한글 허용, 혼용 금지
D4	plans/ vs projects/	분리 유지 — plans/=작업 추적(예정→진행→완료), projects/=프로젝트성 자료 보관
D5	architecture/ + specs/ 통합	`system/`으로 통합 — 현황(아키텍처+스펙+인프라)을 하나의 상위 폴더에
D6	장기 정체 계획	폐기하지 않음 — 한곳에 모아두고 Phase 4(최종 정리)에서 일괄 판단
D7	changes/ 날짜 포맷	`YYYYMMDD_description.md` 단일 형식으로 통일
D8	docs/CLAUDE.md 처리	삭제 — 유효 내용은 `docs/INDEX.md`에 통합, docs/CLAUDE.md 파일 제거
D9	docs/front/ 폴더	삭제 — 구 front 시절 잔재, 필요한 내용은 적절한 위치로 이동 후 폴더 제거
D10	plans/ 폴더	현행 유지 — 이미 정리 완료, 이번 정비에서 건드리지 않음
D11	deploys/ops-manual/	현행 유지 — 그대로 둠

D3 파일명 규칙 상세

✅ 기술 문서 (코드 참조):  api-rules.md, database-schema.md
✅ 업무/비즈니스 문서:     영업파트너가이드북.md, 수당지급.md
❌ 혼용 금지:             영업partner가이드.md, 메뉴badge기능.md

D5 system/ 폴더 구조

system/                              ← architecture/ + specs/ 통합
├── overview.md                      ← 전체 시스템 아키텍처
├── database/                        ← DB 스키마 (D1: 도메인별 분할)
│   ├── README.md                    ← 전체 테이블 인덱스 + 도메인 맵
│   ├── tenants.md                   ← 테넌트/인증/권한
│   ├── production.md                ← 생산/작업지시/BOM
│   ├── finance.md                   ← 재무/회계
│   ├── sales.md                     ← 영업/견적/수주
│   ├── hr.md                        ← 인사/근태/급여
│   ├── items.md                     ← 품목/자재/재고
│   ├── documents.md                 ← 문서/서식/전자서명
│   ├── commons.md                   ← 공통(파일, 메뉴, 게시판, 감사로그)
│   └── others.md                    ← 설비, 차량, AI, 면접, 바로빌 등
├── api-structure.md                 ← API 라우트 도메인·엔드포인트 현황
├── react-structure.md               ← React 페이지·컴포넌트·패턴 현황
├── mng-structure.md                 ← MNG 컨트롤러·뷰·패턴 현황
├── security-policy.md               ← 보안 정책
├── scaling-roadmap.md               ← 스케일링 로드맵
├── docker-setup.md                  ← Docker/인프라 환경
├── remote-work-setup.md             ← 원격 접속 설정
├── board-system-spec.md             ← 게시판 시스템 스펙
└── item-master-integration.md       ← 품목 마스터 통합 스펙

4. 작업 계획

Phase 0: 문서 정책 재정립 (선행 필수)

이후 모든 작업의 기준이 되므로 먼저 확정

#	작업	산출물
0-1	docs/ 폴더 구조 정책 재정의 (D5 system/ 통합 반영)	폴더 구조 확정
0-2	문서 분류 기준 확정 (폴더별 역할, 중복 방지 SSOT 규칙)	분류 가이드
0-3	파일명·포맷·템플릿 표준 확정 (D3 반영)	표준 문서
0-4	`docs/CLAUDE.md` 유효 내용 → `INDEX.md` 통합, 파일 삭제 (D8)	INDEX.md 갱신
0-5	`docs/front/` 필요 내용 이관 후 폴더 삭제 (D9)	front/ 제거
0-6	`changes/` 기존 파일명 → `YYYYMMDD_description.md` 통일 (D7)	파일명 변경

Phase 0 결정 사항 모두 확정됨 (D1~D9)

Phase 1: 시스템 현황 문서화 (최우선)

실제 코드를 분석하여 "지금 시스템이 어떤 상태인가"를 정확하게 기록 산출물은 모두 system/ 폴더에 배치

1-A. DB 스키마 전면 재작성

#	작업	상세
1A-1	전체 마이그레이션 분석 (458개)	테이블 목록, 컬럼, 관계 추출
1A-2	도메인별 테이블 그룹핑	기존 + 신규 도메인 분류
1A-3	`system/database/` 도메인별 파일 작성	README.md(인덱스) + 도메인별 스키마
1A-4	기존 `specs/database-schema.md` 폐기 처리	system/database/로 이전 완료 표기

1-B. API 시스템 현황

#	작업	상세
1B-1	18개 라우트 도메인별 엔드포인트 경로 목록	routes/api/v1/ 분석
1B-2	모델-서비스-컨트롤러 매핑 현황	205 모델 기준 도메인 분류
1B-3	인증/권한 구조 현황	Sanctum + Spatie Permission
1B-4	`system/overview.md` 작성	전체 아키텍처 + 기술 스택 (Laravel 12, PHP 8.4)
1B-5	`system/api-structure.md` 작성	API 도메인·라우트 현황

1-C. React(프론트엔드) 현황

#	작업	상세
1C-1	페이지 라우트 구조 현황	249개 페이지, 도메인별 분류
1C-2	컴포넌트 아키텍처 현황	Atomic Design: 55 ui + 3 atoms + 11 molecules + 12 organisms
1C-3	상태관리·API연동 패턴 현황	Zustand 13 stores, 91 Server Actions
1C-4	`system/react-structure.md` 작성	Next.js 15, React 19, Tailwind v4

1-D. MNG(관리자) 현황

#	작업	상세
1D-1	컨트롤러·뷰 도메인 구조 현황	171 컨트롤러, 436 블레이드
1D-2	HTMX + DaisyUI 프론트 패턴 현황	서버 렌더링, Vite 7
1D-3	api ↔ mng 모델 공유/차이 현황	205(api) vs 185(mng) 비교
1D-4	`system/mng-structure.md` 작성	MNG 전체 구조 현황

1-E. 인프라/환경 현황

#	작업	상세
1E-1	Docker 구성 현황 분석	컨테이너, 네트워크, 볼륨
1E-2	도메인·환경 구성 현황 정리	*.sam.kr(로컬), codebridge-x.com(개발)
1E-3	`system/docker-setup.md` 갱신	현재 Docker 구성 반영

Phase 2: 기존 문서 정비

부정확한 정보 수정, 폴더 이관, 불필요한 문서 정리

2-A. 폴더 구조 이관

#	작업	상세
2A-1	`architecture/` → `system/` 이관	파일 이동 + 내용 갱신
2A-2	`specs/` → `system/` 이관	파일 이동 + 내용 갱신
2A-3	기존 폴더 제거 또는 리다이렉트 안내	혼란 방지

2-B. 부정확 문서 수정

#	대상	수정 내용
2B-1	`docs/CLAUDE.md`	경로 수정 (`/Users/kent/...`), Laravel 12, 역할 재정의
2B-2	`SAM/CLAUDE.md` (루트)	문서 참조 경로 수정, system/ 반영
2B-3	`docs/TODO.md`	현행화 — 해결된 항목 정리, 미해결 항목 갱신
2B-4	`docs/rules/README.md`	실제 8개 파일 목록과 동기화
2B-5	`docs/standards/quality-checklist.md`	현재 기준에 맞게 갱신

2-C. 계획 문서 정리 → 제외 (D10: plans/ 이미 정리 완료, 건드리지 않음)

2-D. 구조 표준화

#	작업	상세
2D-1	`changes/` 파일명 포맷 통일	단일 날짜 형식 적용
2D-2	`guides/` 파일명 정리	D3 기준 적용 (한글/영문 혼용 수정)
2D-3	`projects/` 프로젝트별 상태 갱신	PROGRESS.md 현행화
2D-4	중복 문서 통합	동일 주제 다중 문서 → SSOT 확보

Phase 3: 신규 도메인 기능 문서 작성

Phase 1 현황 분석 결과를 바탕으로 누락된 기능 문서 신규 작성 각 문서: 기능 설명 + 엔드포인트 경로 목록 + Swagger 참조 안내 (D2)

#	도메인	위치	우선순위
3-1	재무/회계 (Finance)	`features/finance/` 확장	🔴
3-2	전자서명 (E-Sign)	`features/esign/` 신규	🔴
3-3	설비관리 (Equipment)	`features/equipment/` 신규	🟡
3-4	차량관리 (Vehicle)	`features/card-vehicle/` 확장	🟡
3-5	AI/음성	`features/ai/` 신규	🟢
3-6	면접 시스템	`features/hr/` 확장	🟢
3-7	채번규칙	`rules/numbering-rules.md` 신규	🟢
3-8	문서서식 템플릿	`features/documents/` 확장	🟢
3-9	바로빌 연동 확장	`features/barobill-kakaotalk/` 확장	🟢
3-10	회의록	`features/meeting/` 신규	🟢

Phase 4: 최종 검증 및 정리

모든 Phase 완료 후 — 문서 전체 정합성 확인 + 장기 정체 계획 최종 판단

#	작업	상세
4-1	`docs/INDEX.md` 전면 재작성	system/ 반영, 모든 문서 네비게이션
4-2	`docs/CLAUDE.md` 최종 갱신	정확한 경로·정책·폴더 구조 반영
4-3	`SAM/CLAUDE.md` 동기화	docs/ 참조 경로 최종 확인
4-4	교차 참조 검증	문서 간 링크 유효성 확인
4-5	문서 크기 검증	10KB 초과 문서 분할
~~4-6~~	~~장기 정체 계획 최종 정리~~	제외 (D10: plans/ 건드리지 않음)

5. 의존 관계 및 실행 순서

Phase 0 (정책 재정립)
    │
    ├──→ Phase 1-A (DB 스키마)    ──┐
    ├──→ Phase 1-B (API 현황)      ├──→ Phase 3 (신규 기능 문서)
    ├──→ Phase 1-C (React 현황)    │         │
    ├──→ Phase 1-D (MNG 현황)      │         │
    └──→ Phase 1-E (인프라 현황)  ──┘         │
              │                               │
              ├──→ Phase 2 (기존 문서 정비)  ──┘
              │                               │
              └──────────────────────────────→ Phase 4 (최종 검증 + 장기계획 정리)

Phase 0 → 모든 Phase의 선행 조건
Phase 1 (A~E) → 병렬 가능
Phase 2 → Phase 1과 부분 병렬 가능 (2-B, 2-C는 독립 선행 가능)
Phase 2-A (폴더 이관) → Phase 1 이후 (system/ 내용이 먼저 작성되어야 이관 가능)
Phase 3 → Phase 1 완료 후 (현황 기반)
Phase 4 → 모든 Phase 완료 후

6. 예상 산출물

Phase	주요 산출물
0	문서 정책서 (폴더 구조, 분류 기준, 명명 규칙, 템플릿, SSOT 원칙)
1-A	`system/database/` — README.md + 도메인별 스키마 파일 (~9개)
1-B	`system/overview.md` + `system/api-structure.md`
1-C	`system/react-structure.md`
1-D	`system/mng-structure.md`
1-E	`system/docker-setup.md` 갱신
2	정비된 기존 문서 + architecture/specs/ → system/ 이관
3	10개 도메인 기능 문서 (신규/확장)
4	INDEX.md + SAM/CLAUDE.md 최종본

7. 확정된 폴더 구조 (Phase 0 완료 후 목표)

docs/
├── INDEX.md                     ← 마스터 네비게이션
├── CURRENT_WORKS.md             ← docs 작업 추적
│                                  (CLAUDE.md 삭제 → INDEX.md 통합 — D8)
│
├── system/                      ← 🆕 시스템 현황 (architecture/ + specs/ 통합)
│   ├── overview.md              ← 전체 아키텍처 + 기술 스택
│   ├── database/                ← DB 스키마 (도메인별)
│   ├── api-structure.md         ← API 도메인·라우트 현황
│   ├── react-structure.md       ← React 구조 현황
│   ├── mng-structure.md         ← MNG 구조 현황
│   ├── security-policy.md       ← 보안 정책
│   ├── scaling-roadmap.md       ← 스케일링
│   ├── docker-setup.md          ← Docker/인프라
│   └── ...                      ← 기타 스펙
│
├── standards/                   ← 코딩 표준·컨벤션
├── rules/                       ← 비즈니스 규칙·정책
├── features/                    ← 기능별 상세 문서
├── guides/                      ← 구현 가이드·매뉴얼
│                                  (front/ 삭제 — D9)
├── quickstart/                  ← 개발자 빠른 시작
│
├── plans/                       ← 작업 추적 (예정 → 진행 → 완료 → archive/)
│   ├── index_plans.md
│   ├── GUIDE.md
│   ├── [계획 문서들]
│   └── archive/
│
├── projects/                    ← 프로젝트성 자료 (분석, 설계, 참고)
├── changes/                     ← 변경 이력
├── deploys/                     ← 운영 매뉴얼
├── data/                        ← 데이터 분석
├── history/                     ← 히스토리 기록
├── api/                         ← API 통합 문서
├── requests/                    ← 요청/기획 문서
└── assets/                      ← BI 등 정적 자산

변경 이력

날짜	변경 내용
2026-02-27	초안 작성 — 시스템 분석 결과 기반 계획 수립
2026-02-27	Q1~~Q6 결정 사항 반영 — D1~~D6 확정, Phase별 산출물 구체화
2026-02-27	D7~D9 추가 확정 — 날짜 포맷, CLAUDE.md→INDEX.md 통합, front/ 삭제
2026-02-27	D10~D11 추가 — plans/, deploys/ops-manual/ 현행 유지(건드리지 않음)
2026-02-27	Phase 0 완료 — INDEX.md 재작성, CLAUDE.md→INDEX.md 통합, front/→guides/ 이관, changes/ 포맷 통일
2026-02-27	Phase 1 완료 — system/ 문서 14개 작성 (overview, api-structure, react-structure, mng-structure, docker-setup, database/README + 9개 도메인 스키마)
2026-02-27	Phase 2 완료 — 2-A: architecture/+specs/→system/ 이관(6개 이동, 4개 폐기), 2-B: rules/README.md 갱신, 경로 참조 수정(13개 파일), 2-D: changes/ 파일명 D7 통일(3개), guides/ D3 위반 수정(1개)
2026-02-27	Phase 3 완료 — 7개 도메인 문서 작성: esign/(1), documents/(1), ai/(1), equipment/(1), numbering-rules(1), finance/ 확장(9+README갱신), barobill/ 확장(API 설정 섹션). 건너뜀: Vehicle(문서 완성), Interview(문서 완성), Meeting(API 미구현)
2026-02-27	Phase 4 완료 — INDEX.md 링크검증(96개 중 1개 깨짐→수정), 교차참조검증(7개 파일 11개 깨진링크→전수 수정), SAM/CLAUDE.md 동기화(docs/ 참조 이상 없음, root 참조 깨짐 5건은 docs/ 범위 밖), 문서크기검증(활성 문서 모두 10KB 이내, plans/history/projects는 D10/D11 대상 제외)

21 KiB Raw Permalink Blame History

docs/ 종합 정비 계획

1. 배경 및 목적

1.1 왜 필요한가

1.2 목표

1.3 범위

2. 현황 감사 결과

2.1 시스템 vs 문서 격차 (Critical)

2.2 미문서화 도메인 (2026년 2월 신규)

2.3 부정확한 문서

2.4 계획 문서(plans/) 상태

3. 확정된 결정 사항

D3 파일명 규칙 상세

D5 system/ 폴더 구조

4. 작업 계획

Phase 0: 문서 정책 재정립 (선행 필수)

Phase 1: 시스템 현황 문서화 (최우선)

1-A. DB 스키마 전면 재작성

1-B. API 시스템 현황

1-C. React(프론트엔드) 현황

1-D. MNG(관리자) 현황

1-E. 인프라/환경 현황

Phase 2: 기존 문서 정비

2-A. 폴더 구조 이관

2-B. 부정확 문서 수정

2-C. 계획 문서 정리 → 제외 (D10: plans/ 이미 정리 완료, 건드리지 않음)

2-D. 구조 표준화

Phase 3: 신규 도메인 기능 문서 작성

Phase 4: 최종 검증 및 정리

5. 의존 관계 및 실행 순서

6. 예상 산출물

7. 확정된 폴더 구조 (Phase 0 완료 후 목표)

변경 이력

21 KiB

Raw Permalink Blame History