Phase 2 documentation content plan (code anchors, C4, ops)

Purpose

이 문서는 Phase 2에서 다룰 문서 작업의 기획서입니다. 현재 문서는 내부 기술 인수인계 관점에서 이미 강한 편이며, 업계에서 말하는 **“완전체 패키지”**에 더 가깝게 가려면 다음이 핵심입니다.

코드 앵커 규칙의 전면 적용 — “코드에서 이렇게 동작한다”는 모두 추적 가능한 근거를 갖는다.
C4 container·엔드투엔드 데이터 흐름 — 서비스 경계와 돈/급여/통합 경로를 한눈에 설명한다.
테스트·릴리즈·사고 대응의 명문화 — 개발 산출물과 운영 Runbook의 간극을 메운다.

문서 범위: docs/src/content/docs 및 이 기획과 연동되는 인벤토리·로드맵 KPI(선택).

6. 코드 위주 설명 + 실제 개발 참조 규칙 (Phase 2에서 강제 권장)

6.1 원칙

문서에 적는 모든 **“코드에서 이렇게 동작한다”**는 서술은 반드시 추적 가능한 앵컨을 갖는다. 앵컨이 없으면 “의도된 동작”과 “문서의 추측”을 구분할 수 없다.

6.2 저장소 내 경로 (필수)

형식: leekimerp/.../파일명 (저장소 루트 기준 전체 경로).
Python/JS: 함수·클래스명을 괄호로 1회 명시한다.
예: tasks.handle_billing in leekimerp/leekimerp/tasks.py

6.3 Git 브랜치/태그 (권장)

장기 문서 상단(또는 공통 메타)에 기준 시점을 명시한다.
예: 기준: staging @ YYYY-MM-DD 또는 릴리즈 태그 vX.Y.Z.
리뷰 주기(아래 8.5)와 함께 쓰면 리팩터링 후 불일치를 줄일 수 있다.

6.4 외부 링크

Frappe/ERPNext 공식 문서 URL은 버전을 주석으로 남긴다.
예: “ERPNext v14 기준”.

6.5 DocType·훅

다음을 한 블록에 묶어 인용한다.

DocType 이름
생성/스키마 레퍼런스 링크(내부 DocType 페이지 또는 공식 문서)
해당 hooks.py의 줄/섹션(가능하면 섹션 제목까지; 줄만 단독은 지양)

6.6 금지/주의

줄 번호만 단독 인용은 지양한다(리팩터링·포맷으로 자주 깨짐).
심볼 이름 + 파일 경로를 우선한다.

6.7 How-to 페이지 필수 섹션

How-to(운영·배포·장애 포함)는 다음을 고정 목차로 갖는다.

전제 조건
단계
검증
롤백
관련 코드 경로
관련 테스트/명령

(템플릿 공통 메타와 결합해 §7의 Verification과 정렬한다.)

7. 추가로 만들 문서 (템플릿 개요) — Phase 2에서 채움

아래는 파일명/슬러그 제안과 고정 목차이다. 본 Phase 2 기획 시점에서는 파일을 생성하지 않는다 — 산출물은 §8.3에서 다시 정의한다.

각 문서 상단 공통 메타(제안):

---
title: <제목>
description: <한 줄>
sidebar: { order: N }
doc_type: explanation | how-to | reference | tutorial
review_cycle: quarterly
code_baseline: branch/tag + date
---

공통 본문 뼈대(제안):

Audience / Out of scope
Prerequisites (links)
Narrative / Steps
Code anchors (표: topic | path | symbol)
Verification
Related ADRs / Runbook section

#	제안 slug / 위치	목적 (Diátaxis)	템플릿 목차 (고정)
1	`reference/coding-conventions-links.md`	Reference	코드 인용 규칙, 경로 형식, ADR 링크 방법, 이 문서와의 관계
2	`architecture/container.md`	Explanation	C4 container: 서비스 경계, Bench, DB, 큐, 외부 SaaS, 신뢰 경계
3	`architecture/data-flows-critical.md`	Explanation	돈·급여·Xero·Application 네 가지 데이터 흐름(다이어그램 + 코드 앵컨)
4	`development/local-dev.md`	How-to	bench, env, 첫 실행, 자주 쓰는 명령, 트러블슈팅
5	`development/testing-strategy.md`	Explanation	단위/통합/수동, `bench run-tests` 매핑, CI와의 관계
6	`development/release-compatibility.md`	How-to	ERPNext/Frappe 버전, 마이그레이션, 호환성 표
7	`security/threat-model-lightweight.md`	Explanation	신뢰 경계, 주요 위협, 완화, guest API 목록과 연결
8	`operations/incident-response.md`	How-to	심각도, 연락, 로그 위치, 롤백, 사후 ADR
9	`reference/glossary-code-map.md`	Reference	용어 → 코드 경로 → DocType (한 페이지 인덱스)

참고: engineering-deliverables/ 아래에 이미 유사 주제(릴리즈, 테스트, 위협 모델 등)가 있으면, 중복보다는 한 곳을 “정본(canonical)”으로 정하고 나머지는 리다이렉트·짧은 요약 링크로 정리하는 것을 Phase 2 편집 규칙에 포함한다.

8. 기획서 (Phase 2 콘텐츠 생성용)

8.1 목표

개발자가 문서만으로 “어디를 고치면 되는지, 어떻게 검증하는지” 실행 가능하게 한다.
기획(경계·NFR) 과 개발(코드·테스트) 산출물 사이의 간극을 메운다.

8.2 범위

포함	제외 (별도 채널)
아키텍처·도메인·통합·훅·API·보안·운영	법무/계약서 본문, 고객용 매뉴얼 전문
코드 경로 규칙·검증 절차	제품 로드맵 상세 일정

8.3 산출물 (Phase 2)

§7 템플릿 9종의 초안 작성 (실제 파일 생성은 로드맵 스프린트에서 진행).
기존 페이지 상위 약 20개에 코드 앵컨 블록 삽입.
- 우선순위: Billing, Xero, Stripe, Salary Slip, Application PDF.
(선택) Documentation upgrade roadmap 또는 인벤토리 옆에 “코드 링크 커버리지 %” 등 단순 KPI 한 줄 추가.

8.4 우선순위 (P0 → P2)

단계	내용
P0	코드 링크 규칙 문서(§7-1 성격) + Billing / Xero / Payroll 엔드투엔드 1페이지씩 (데이터 흐름·앵컨 중심)
P1	Container(§7-2) + Testing strategy(§7-5) + Local dev(§7-4)
P2	Threat model light(§7-7) + Release compatibility(§7-6) + Incident response(§7-8) + Glossary code map(§7-9)

8.5 리스크

리스크	완화
코드 리팩터링 시 경로·심볼 불일치	`review_cycle: quarterly`, 문서별 `code_baseline`, PR에서 문서 변경 함께 검토
문서 과다로 읽기 피로	한 흐름당 한 페이지 원칙 유지; 긴 서술은 도메인 딥다이브와 링크로 분리

8.6 성공 기준

신입 개발자가 첫 주에 “Billing paid → email” 경로를 문서 + 코드로 따라갈 수 있다.
온콜이 Runbook·Incident 문서가 없더라도 최소한 어디 로그를 볼지 문서에서 찾을 수 있다.

Document control

Field	Value
doc_type	reference (planning meta)
review_cycle	quarterly
code_baseline	제안 — `staging @` 저장소 기준일 또는 팀 합의 태그