TK-FB-Project/docs/DOCUMENTATION_STANDARD.md

# 문서 작성 가이드

## 📋 문서 개요

**목적**: 프로젝트 문서 작성 표준 및 규칙 정의
**대상**: 개발자, 시스템 관리자
**버전**: v1.0.0
**최종 수정일**: 2026-01-26

---

## 📑 목차

1. [문서 작성 원칙](#문서-작성-원칙)
2. [문서 구조 표준](#문서-구조-표준)
3. [문서 유형별 가이드](#문서-유형별-가이드)
4. [작성 규칙](#작성-규칙)
5. [예시 템플릿](#예시-템플릿)

---

## 문서 작성 원칙

### 1.1 핵심 원칙

**명확성 (Clarity)**
- 독자가 한 번에 이해할 수 있도록 작성
- 전문 용어는 최초 사용 시 설명 추가
- 모호한 표현 금지

**일관성 (Consistency)**
- 프로젝트 전체에서 동일한 용어 사용
- 문서 구조를 표준화하여 예측 가능하게
- 날짜 형식, 버전 표기 등 통일

**완전성 (Completeness)**
- 배포/설치/사용에 필요한 모든 정보 포함
- "뻔하다"고 생각되는 내용도 명시
- 전제 조건, 환경 요구사항 명확히

**접근성 (Accessibility)**
- 목차를 통한 빠른 탐색 가능
- 섹션별 명확한 제목
- 코드 예시, 다이어그램 활용

**유지보수성 (Maintainability)**
- 버전 관리 및 변경 이력 기록
- 작성일, 수정일 명시
- 관련 문서 링크 제공

### 1.2 독자 고려사항

**대상 독자 정의**
- 누가 이 문서를 읽는가? (개발자, 관리자, 사용자)
- 독자의 기술 수준은? (초급, 중급, 고급)
- 독자가 달성하고자 하는 목표는?

**독자의 관점에서 작성**
- "무엇을 할 수 있는가" 중심으로 설명
- 단계별 가이드 제공
- 예상 질문에 대한 답변 포함

---

## 문서 구조 표준

### 2.1 필수 섹션

모든 문서는 다음 섹션을 포함해야 함:

1. **문서 헤더**
   ```markdown
   # [문서 제목]

   ## 📋 문서 개요

   **목적**: [문서의 목적을 한 문장으로]
   **대상**: [독자 대상]
   **버전**: [버전 번호]
   **최종 수정일**: [YYYY-MM-DD 형식]
   ```

2. **목차**
   ```markdown
   ## 📑 목차

   1. [섹션 1](#섹션-1)
   2. [섹션 2](#섹션-2)
   ...
   ```

3. **본문** (문서 유형에 따라 다름)

4. **관련 문서** (선택)
   ```markdown
   ## 📚 관련 문서

   - [문서 제목 1](./link-to-doc1.md)
   - [문서 제목 2](./link-to-doc2.md)
   ```

5. **문서 푸터**
   ```markdown
   ---

   **작성자**: [작성자명]
   **최종 수정일**: [YYYY-MM-DD]
   **문서 버전**: [버전 번호]
   ```

### 2.2 섹션 순서 가이드

#### 배포/설치 가이드 문서 구조:
1. 문서 개요
2. 목차
3. 시스템 개요
4. 배포 전 확인사항
5. 배포 절차
6. 기능 명세 (필요 시)
7. API 명세 (필요 시)
8. 프론트엔드 구현 (필요 시)
9. 테스트 가이드
10. 문제 해결
11. 변경 이력
12. 관련 문서
13. 문서 푸터

#### 기능 명세 문서 구조:
1. 문서 개요
2. 목차
3. 기능 개요
4. 요구사항
5. 기술 명세
6. 사용자 시나리오
7. 인터페이스 명세
8. 데이터베이스 스키마
9. API 명세
10. 에러 처리
11. 보안 고려사항
12. 성능 요구사항
13. 테스트 시나리오
14. 변경 이력
15. 관련 문서

#### API 문서 구조:
1. 문서 개요
2. 목차
3. API 개요
4. 인증 방식
5. 엔드포인트 목록
6. 엔드포인트 상세 (각 엔드포인트별)
   - 설명
   - HTTP 메서드
   - URL
   - 요청 파라미터
   - 요청 본문
   - 응답 형식
   - 예시 요청/응답
   - 에러 코드
7. 공통 에러 코드
8. 예시 코드
9. 변경 이력

---

## 문서 유형별 가이드

### 3.1 배포/설치 가이드

**목적**: 시스템을 배포하고 설치하는 방법 안내

**반드시 포함할 내용**:
- [ ] 환경 요구사항 (OS, 버전, 의존성)
- [ ] 배포 전 확인사항
- [ ] 단계별 배포 절차 (명령어 포함)
- [ ] 배포 검증 방법
- [ ] 롤백 절차
- [ ] 문제 해결 가이드
- [ ] 배포 체크리스트

**작성 예시**:
```markdown
## 배포 절차

### 3.1 데이터베이스 백업 (필수)

```bash
# 배포 전 백업
mysqldump -u root -p database_name > backup_$(date +%Y%m%d_%H%M%S).sql
```

**중요**: 모든 배포 전에 반드시 백업을 수행하세요.

### 3.2 마이그레이션 실행

1. 마이그레이션 파일 확인
   ```bash
   ls -l db/migrations/
   ```

2. 마이그레이션 실행
   ```bash
   npm run db:migrate
   ```

3. 결과 확인
   ```bash
   # 예상 출력:
   Batch 1 run: 2 migrations
   ```
```

### 3.2 기능 명세서

**목적**: 기능의 요구사항, 동작, 인터페이스를 상세히 기술

**반드시 포함할 내용**:
- [ ] 기능 개요 및 목적
- [ ] 사용자 시나리오 (최소 3개)
- [ ] 화면 또는 UI 설명 (스크린샷 포함 권장)
- [ ] 데이터베이스 스키마 (ERD 권장)
- [ ] API 엔드포인트 목록
- [ ] 에러 처리 방식
- [ ] 보안 고려사항
- [ ] 성능 요구사항

**작성 예시**:
```markdown
## 4.1 사용자 로그인 기능

### 목적
사용자가 이메일과 비밀번호로 시스템에 인증하는 기능

### 사용자 시나리오

#### 시나리오 1: 정상 로그인
1. 사용자가 로그인 페이지 접속
2. 이메일 입력: user@example.com
3. 비밀번호 입력: ********
4. "로그인" 버튼 클릭
5. 시스템이 인증 확인
6. 대시보드로 리다이렉트

#### 시나리오 2: 잘못된 비밀번호
1. 사용자가 잘못된 비밀번호 입력
2. "로그인" 버튼 클릭
3. 에러 메시지 표시: "이메일 또는 비밀번호가 올바르지 않습니다"
4. 로그인 실패 카운트 증가 (3회 초과 시 계정 잠금)

### API 명세

#### POST /api/auth/login

**요청 본문**:
```json
{
  "email": "user@example.com",
  "password": "password123"
}
```

**응답 (성공)**:
```json
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR...",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "홍길동"
  }
}
```

**응답 (실패)**:
```json
{
  "success": false,
  "message": "이메일 또는 비밀번호가 올바르지 않습니다"
}
```
```

### 3.3 API 문서

**목적**: API 엔드포인트 사용 방법 안내

**반드시 포함할 내용**:
- [ ] API 개요 및 Base URL
- [ ] 인증 방식 (JWT, API Key 등)
- [ ] 전체 엔드포인트 목록 (표 형식)
- [ ] 각 엔드포인트 상세 (HTTP 메서드, URL, 파라미터, 요청/응답)
- [ ] 공통 에러 코드 테이블
- [ ] 예시 요청/응답 (curl, JavaScript 등)
- [ ] Rate Limiting 정보 (있는 경우)

**작성 예시**:
```markdown
## API 개요

**Base URL**: `http://api.example.com/v1`
**인증 방식**: Bearer Token (JWT)

모든 요청 헤더에 다음을 포함해야 함:
```
Authorization: Bearer YOUR_JWT_TOKEN
```

## 엔드포인트 목록

| 메서드 | 경로 | 설명 | 인증 필요 |
|--------|------|------|-----------|
| POST | /auth/login | 로그인 | No |
| POST | /auth/logout | 로그아웃 | Yes |
| GET | /users/:id | 사용자 조회 | Yes |
| PUT | /users/:id | 사용자 수정 | Yes |

## POST /auth/login

**설명**: 이메일과 비밀번호로 로그인

**요청**:
```bash
curl -X POST http://api.example.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123"
  }'
```

**응답 (200 OK)**:
```json
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "홍길동"
  }
}
```

**에러 코드**:
- `400`: 잘못된 요청 (이메일 또는 비밀번호 누락)
- `401`: 인증 실패 (잘못된 이메일 또는 비밀번호)
- `429`: 너무 많은 요청 (Rate Limit 초과)
```

### 3.4 트러블슈팅/문제 해결 가이드

**목적**: 흔히 발생하는 문제와 해결 방법 제공

**반드시 포함할 내용**:
- [ ] 문제별 섹션 구분
- [ ] 증상 (오류 메시지, 로그 등)
- [ ] 원인 분석
- [ ] 해결 방법 (단계별)
- [ ] 예방 방법

**작성 예시**:
```markdown
## 8.1 데이터베이스 연결 오류

### 증상
```
Error: connect ECONNREFUSED 127.0.0.1:3306
```

### 원인
1. MySQL 서버가 실행되지 않음
2. 잘못된 DB 접속 정보 (호스트, 포트, 사용자명, 비밀번호)
3. 방화벽이 포트 차단

### 해결 방법

1. MySQL 서버 상태 확인
   ```bash
   sudo systemctl status mysql
   ```

2. 서버가 실행되지 않으면 시작
   ```bash
   sudo systemctl start mysql
   ```

3. 접속 정보 확인 (.env 파일)
   ```bash
   cat .env | grep DB_
   ```

   예상 내용:
   ```
   DB_HOST=localhost
   DB_PORT=3306
   DB_USER=root
   DB_PASSWORD=your_password
   ```

4. 방화벽 확인 (리눅스)
   ```bash
   sudo ufw status
   sudo ufw allow 3306
   ```

### 예방 방법
- 서버 재부팅 시 MySQL 자동 시작 설정
  ```bash
  sudo systemctl enable mysql
  ```
- 접속 정보를 환경 변수로 관리하고 git에 커밋하지 않기
```

### 3.5 변경 이력 (Changelog)

**목적**: 버전별 변경사항 기록

**작성 규칙**:
- 최신 버전이 위로 (역순)
- 버전 번호는 Semantic Versioning (MAJOR.MINOR.PATCH)
- 변경사항을 카테고리별로 분류
  - **기능 추가** (Added)
  - **기능 변경** (Changed)
  - **기능 삭제** (Deprecated)
  - **기능 제거** (Removed)
  - **버그 수정** (Fixed)
  - **보안** (Security)

**작성 예시**:
```markdown
## 변경 이력

### v1.2.0 (2026-01-26)

**기능 추가**:
- 대시보드 TBM 빠른 작업 배너 추가
- 페이지 접근 권한 기반 표시/숨김 처리
- `checkTbmPageAccess()` 함수 추가 (`modern-dashboard.js`)

**기능 변경**:
- 안전 체크리스트 카테고리 표시 개선 (그룹화)

**버그 수정**:
- TBM 팀원 자동 선택 시 중복 선택 문제 해결
- 날짜 선택 시 Draft 세션 우선 처리 로직 수정

**커밋**: `67e9c08`

### v1.1.0 (2026-01-20)

**기능 추가**:
- 작업 인계 시스템 추가
- TBM 상세보기 모달 추가

**커밋**: `4802069`

### v1.0.0 (2026-01-15)

**초기 배포**:
- TBM 시스템 기본 기능 구현
- 데이터베이스 스키마 생성 (5개 테이블)
- API 엔드포인트 17개

**커밋**: `4d0c4c0`
```

---

## 작성 규칙

### 4.1 마크다운 스타일

#### 제목 레벨
- `#`: 문서 제목 (1개만)
- `##`: 주요 섹션
- `###`: 하위 섹션
- `####`: 세부 항목
- 5단계 이상 중첩 금지

#### 코드 블록
- 언어 지정 필수: ` ```javascript`, ` ```bash`, ` ```sql`
- 주석으로 설명 추가
- 예상 출력 포함

```markdown
좋은 예시:
```bash
# 데이터베이스 백업
mysqldump -u root -p hyungi > backup.sql

# 예상 출력:
# Enter password:
# [백업 완료]
```

나쁜 예시:
```
mysqldump -u root -p hyungi > backup.sql
```
```

#### 링크
- 내부 링크: `[섹션 제목](#섹션-제목-소문자-하이픈)`
- 외부 링크: `[링크 텍스트](https://url)`
- 문서 링크: `[문서 제목](./path/to/doc.md)`

#### 강조
- **굵게**: `**중요한 내용**`
- *기울임*: `*강조*`
- `코드`: `` `변수명` ``
- 인용구: `> 주의사항`

#### 리스트
- 순서 있는 리스트: `1. `, `2. `
- 순서 없는 리스트: `- ` 또는 `* `
- 체크리스트: `- [ ] 미완료`, `- [x] 완료`

### 4.2 명명 규칙

#### 파일명
- 대문자와 밑줄 사용: `TBM_DEPLOYMENT_GUIDE.md`
- 카테고리 접두사 사용 (선택): `API_`, `GUIDE_`, `SPEC_`
- 날짜 포함 금지 (git 이력으로 관리)

#### 섹션 제목
- 명확하고 간결하게
- 동사형 사용: "배포하기", "설치하기"
- 번호 포함: "1.1 시스템 개요"

### 4.3 코드 예시 작성 규칙

#### 완전한 예시 제공
```markdown
좋은 예시:
```javascript
// TBM 세션 생성
async function createTbmSession(data) {
  try {
    const response = await window.apiCall('/tbm/sessions', 'POST', data);
    if (response.success) {
      console.log('TBM 세션 생성 성공:', response.data.session_id);
      return response.data;
    }
  } catch (error) {
    console.error('TBM 세션 생성 실패:', error);
    throw error;
  }
}

// 사용 예시
const session = await createTbmSession({
  session_date: '2026-01-26',
  leader_id: 1,
  project_id: 5
});
```

나쁜 예시:
```javascript
// TBM 세션 생성
async function createTbmSession(data) {
  // ... 생략 ...
}
```
```

#### 주석 활용
- 코드 블록 상단에 설명 주석 추가
- 중요한 파라미터에 인라인 주석
- 예상 결과 주석으로 표시

### 4.4 표 작성 규칙

#### 간결하고 읽기 쉽게
```markdown
좋은 예시:

| 필드명 | 타입 | 필수 | 설명 |
|--------|------|------|------|
| session_date | DATE | Yes | TBM 날짜 |
| leader_id | INT | Yes | 팀장 ID |
| project_id | INT | No | 프로젝트 ID |

나쁜 예시:

| 필드명 | 데이터 타입 (MySQL) | 필수 여부 | Nullable | Default | 설명 |
|--------|---------------------|-----------|----------|---------|------|
| session_date | DATE | 필수 | NO | NULL | TBM이 진행되는 날짜 (YYYY-MM-DD 형식) |
```

#### 열 수 제한
- 최대 5열까지 권장
- 더 많은 정보가 필요하면 섹션 분리

### 4.5 다이어그램 작성 규칙

#### ASCII 다이어그램 사용
```markdown
시스템 아키텍처:

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Frontend   │────▶│   Backend   │────▶│  Database   │
│   (React)   │     │   (Node.js) │     │   (MySQL)   │
└─────────────┘     └─────────────┘     └─────────────┘
```

데이터 흐름:

```
User → Login Page → API (/auth/login) → JWT Token → Dashboard
```
```

#### Mermaid 다이어그램 (GitHub 지원)
```markdown
```mermaid
sequenceDiagram
    participant U as User
    participant F as Frontend
    participant B as Backend
    participant D as Database

    U->>F: 로그인 요청
    F->>B: POST /auth/login
    B->>D: 사용자 확인
    D-->>B: 사용자 정보
    B-->>F: JWT 토큰
    F-->>U: 대시보드로 리다이렉트
```
```

### 4.6 버전 관리 규칙

#### Semantic Versioning 사용
- **MAJOR**: 호환성이 깨지는 변경 (예: API 구조 변경)
- **MINOR**: 기능 추가 (하위 호환)
- **PATCH**: 버그 수정 (하위 호환)

예시:
- `v1.0.0`: 초기 배포
- `v1.1.0`: 새 기능 추가
- `v1.1.1`: 버그 수정
- `v2.0.0`: API 구조 변경 (Breaking Change)

#### 문서 버전과 코드 버전 분리
- 문서 자체 버전: 문서 푸터에 "문서 버전"으로 명시
- 코드/시스템 버전: 변경 이력에 기록

---

## 예시 템플릿

### 5.1 배포 가이드 템플릿

```markdown
# [시스템/기능명] 배포 가이드

## 📋 문서 개요

**목적**: [배포 목적을 한 문장으로]
**대상**: 시스템 관리자, DevOps 엔지니어
**버전**: v1.0.0
**최종 수정일**: YYYY-MM-DD

---

## 📑 목차

1. [시스템 개요](#시스템-개요)
2. [배포 전 확인사항](#배포-전-확인사항)
3. [배포 절차](#배포-절차)
4. [테스트 가이드](#테스트-가이드)
5. [문제 해결](#문제-해결)
6. [롤백 절차](#롤백-절차)
7. [변경 이력](#변경-이력)

---

## 시스템 개요

### 1.1 [시스템/기능명]이란?

[시스템이나 기능에 대한 간단한 설명]

### 1.2 주요 기능

| 기능 | 설명 |
|------|------|
| 기능 1 | 설명 |
| 기능 2 | 설명 |

### 1.3 시스템 아키텍처

```
[다이어그램]
```

---

## 배포 전 확인사항

### 2.1 환경 요구사항

- **OS**: [운영체제 및 버전]
- **런타임**: [Node.js, Python 등 버전]
- **데이터베이스**: [MySQL, PostgreSQL 등 버전]
- **기타**: [의존성]

### 2.2 필수 의존성

```json
{
  "의존성": "버전"
}
```

### 2.3 기존 시스템 확인

```bash
# 확인 명령어
```

---

## 배포 절차

### 3.1 데이터베이스 백업 (필수)

```bash
# 백업 명령어
```

### 3.2 [단계별 배포]

#### 3.2.1 [하위 단계]

```bash
# 명령어
```

[설명]

#### 3.2.2 확인

```bash
# 확인 명령어
```

예상 결과:
```
[예상 출력]
```

### 3.3 배포 체크리스트

- [ ] 백업 완료
- [ ] [항목 1]
- [ ] [항목 2]

---

## 테스트 가이드

### 4.1 [테스트 유형 1]

[테스트 방법]

### 4.2 [테스트 유형 2]

[테스트 방법]

---

## 문제 해결

### 5.1 [문제 1]

**증상**:
```
[오류 메시지]
```

**원인**: [원인 설명]

**해결**:
```bash
# 해결 명령어
```

---

## 롤백 절차

### 6.1 데이터베이스 롤백

```bash
# 롤백 명령어
```

### 6.2 코드 롤백

```bash
# 롤백 명령어
```

---

## 변경 이력

### v1.0.0 (YYYY-MM-DD)

**초기 배포**:
- [변경사항 1]
- [변경사항 2]

**커밋**: `[커밋 해시]`

---

**작성자**: [작성자명]
**최종 수정일**: YYYY-MM-DD
**문서 버전**: 1.0
```

### 5.2 API 문서 템플릿

```markdown
# [API 이름] API 문서

## 📋 문서 개요

**목적**: [API 목적]
**대상**: 백엔드 개발자, 프론트엔드 개발자
**버전**: v1.0.0
**최종 수정일**: YYYY-MM-DD

---

## 📑 목차

1. [API 개요](#api-개요)
2. [인증](#인증)
3. [엔드포인트 목록](#엔드포인트-목록)
4. [엔드포인트 상세](#엔드포인트-상세)
5. [에러 코드](#에러-코드)
6. [예시 코드](#예시-코드)

---

## API 개요

**Base URL**: `http://api.example.com/v1`
**프로토콜**: HTTPS
**데이터 형식**: JSON

---

## 인증

### 2.1 인증 방식

[인증 방식 설명 - JWT, API Key 등]

### 2.2 인증 헤더

```
Authorization: Bearer YOUR_TOKEN
```

### 2.3 토큰 발급

[토큰 발급 방법]

---

## 엔드포인트 목록

| 메서드 | 경로 | 설명 | 인증 필요 |
|--------|------|------|-----------|
| POST | /auth/login | 로그인 | No |
| GET | /users/:id | 사용자 조회 | Yes |

---

## 엔드포인트 상세

### POST /endpoint-path

**설명**: [엔드포인트 설명]

**요청**:
```bash
curl -X POST http://api.example.com/v1/endpoint-path \
  -H "Content-Type: application/json" \
  -d '{
    "param1": "value1"
  }'
```

**요청 파라미터**:
| 파라미터 | 타입 | 필수 | 설명 |
|----------|------|------|------|
| param1 | string | Yes | 설명 |

**응답 (200 OK)**:
```json
{
  "success": true,
  "data": {
    "field1": "value1"
  }
}
```

**에러 응답**:
- `400`: 잘못된 요청
- `401`: 인증 실패
- `404`: 리소스 없음
- `500`: 서버 오류

---

## 에러 코드

| 코드 | 메시지 | 설명 |
|------|--------|------|
| 400 | Bad Request | 잘못된 요청 |
| 401 | Unauthorized | 인증 실패 |

---

## 예시 코드

### JavaScript (Fetch)

```javascript
const response = await fetch('http://api.example.com/v1/endpoint', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    param1: 'value1'
  })
});

const data = await response.json();
console.log(data);
```

---

**작성자**: [작성자명]
**최종 수정일**: YYYY-MM-DD
**문서 버전**: 1.0
```

---

## 문서 검토 체크리스트

배포 전 다음 항목을 확인:

### 내용 검토
- [ ] 문서 개요 (목적, 대상, 버전, 날짜) 작성됨
- [ ] 목차가 있고 모든 링크가 작동함
- [ ] 모든 필수 섹션이 포함됨
- [ ] 코드 예시가 완전하고 테스트됨
- [ ] 명령어가 정확하고 실행 가능함
- [ ] 예상 출력이 명시됨
- [ ] 문제 해결 섹션이 충분함
- [ ] 변경 이력이 업데이트됨

### 형식 검토
- [ ] 마크다운 문법이 올바름
- [ ] 코드 블록에 언어가 지정됨
- [ ] 링크가 모두 작동함
- [ ] 표 형식이 올바름
- [ ] 이미지/다이어그램이 표시됨
- [ ] 날짜 형식이 일관됨 (YYYY-MM-DD)
- [ ] 버전 번호가 일관됨

### 독자 관점 검토
- [ ] 초보자도 따라할 수 있는가?
- [ ] 모든 전제 조건이 명시되었는가?
- [ ] 모호한 표현이 없는가?
- [ ] 예시가 충분한가?
- [ ] 문제 상황 대응 방법이 있는가?

---

**작성자**: Claude
**최종 수정일**: 2026-01-26
**문서 버전**: 1.0