dabit-mcp/CLAUDE.md

# CLAUDE.md — DabitChe 모노레포 루트

LED 전광판 콘텐츠 제작 + 스케줄 관리 + 컨트롤러 전송 소프트웨어 (다빛솔루션 DABIT)

## 프로그램 정체성

DabitChe는 **LED 전광판 운영 소프트웨어**이다. 핵심 기능은 콘텐츠 제작(텍스트/이미지) → 스케줄 편집(PLA/BGP) → 컨트롤러 전송이다. 통신설정, 제어, 시뮬레이터는 보조 기능이다. dbSimulator(DBPS)는 dabitche의 부분집합으로, 프로토콜 시뮬레이터 기능에 해당한다. 사용자는 현장 설치기사/운영자이며, 프로토콜을 몰라도 사용 가능해야 한다.

## Naming 규칙 (3층) — 회사 / 제품 / 프로토콜

이름은 3층으로 나눈다. 새 프로젝트·모듈·MCP 명명 시 이 규칙을 따른다.

| 층 | 이름 | 적용 대상 | 예 |
|----|------|----------|-----|
| 회사/브랜드 | **Dabit** (다빛솔루션 DABIT) | 하드웨어 컨트롤러를 다루는 브랜드 레벨 자산 | MCP 서버 `Dabit.Mcp` (등록명 `dabit-led`) |
| 제품 | **DabitOne** (레거시명 = DabitChe) | PC 운영 앱 | `DabitOne.Desktop`, `DabitOne.AutoSend` |
| 프로토콜 | **DibdProtocol** | 제품 무관 프로토콜/전송 라이브러리 | `DibdProtocol.Core` / `.Transport` |

- **레거시 잔재 주의**: 폴더·namespace·sln은 아직 `DabitChe.*`(Desktop/AutoSend). 단 출력물(exe `DabitOne.exe`)·창 제목은 이미 `DabitOne`. 내부 `DabitChe`→`DabitOne` 전체 리네임은 **워크트리 다수 동시 진행**이라 충돌 위험 → main 단일 big-bang으로 일괄 처리 예정(보류).
- `Dabit.Mcp`가 형제 `DabitOne.*`와 이름이 다른 건 **의도된 계층 구분**(브랜드 vs 제품)이지 실수가 아니다. (2026-06-02 MCP만 선행 리네임: `DabitChe.Mcp`→`Dabit.Mcp`, 등록명 `dabitche-led`→`dabit-led`)

## UI/UX 원칙

| 원칙 | 설명 |
|------|------|
| **가로 우선 레이아웃** | 콘텐츠 편집 + 스케줄 그리드가 핵심 → 가로 공간을 넉넉히 확보 |
| **좁은 레이아웃 금지** | dbSimulator(580px 고정)의 좁은 배치를 그대로 가져오지 않음 — 가로 900px+ 기준으로 재배치 |
| **GroupBox 가로 병렬** | 통신설정 등에서 Serial/TCP/UDP를 세로로 쌓지 말고 가로 2~3열로 배치 |
| **입력 필드 폭 제한** | COM 포트(5글자), IP(15글자), Port(5글자) → 필드 폭을 내용에 맞춤, 우측 여백 과다 금지 |
| **전체 통일감** | 한 패널의 배치를 바꾸면 나머지 패널도 동일 원칙 적용 |
| **사이드바 5그룹** | 통신 → 설정 → 시뮬 → 편집 → 고급 (사용 순서 = 위→아래) |
| **Design Token System** | `Themes/` 폴더에 토큰 + implicit style 집중. **토큰 1곳 수정 → 전체 반영**이 핵심. 정본: `AI_Rules/080_ui-design-system.md` |
| **창 크기 기준** | 새 Window/팝업의 크기 요청 시 **메인 창(MainWindow) 대비 비율**로 확인. 예: "메인의 2/3", "메인의 1/2". 비율 미지정 시 사용자에게 "메인 창 대비 몇 분의 몇으로 할까요?" 확인 후 적용 |

### Design Token 필수 규칙

| 규칙 | 이유 |
|------|------|
| 인라인 FontSize/Height/Background/Foreground 금지 | 토큰 파일에서만 관리해야 전역 변경 가능 |
| RowDefinition Height="Auto" 필수 | 고정값은 Control.Margin을 찌그러뜨림 |
| 모든 입력 컨트롤에 FontWeight="Normal" 명시 | GroupBox SemiBold 상속 차단 |
| Window 태그에 `Background="{StaticResource Surface.Background}"` | Window는 implicit style 불가 |
| 새 컨트롤 추가 시 Themes/ implicit style 확인 | 토큰 시스템 밖에서 컨트롤이 생성되면 불일치 발생 |

### Design Token 현재 값 (참고)

값은 `Themes/_Typography.xaml`, `_Spacing.xaml`, `_Colors.xaml`에서 관리. 변경 시 해당 파일만 수정.

| 토큰 | 현재 값 | 파일 |
|------|--------|------|
| `Control.Height` | 26 (MinHeight) | `_Typography.xaml` |
| `Control.Margin` | 0,4,0,4 | `_Spacing.xaml` |
| `Font.Size.MD` | 12 | `_Typography.xaml` |

**Button 규칙:**
- 전역 스타일이 `MinHeight=26`, `Padding="12,0"`으로 설정됨 — **ComboBox/TextBox와 동일 높이**
- **인라인 Padding 금지** — 버튼마다 다른 Padding을 넣으면 높이가 달라져 이질적. 전역 스타일만 사용
- 인라인 `FontWeight`, `FontFamily`, `Height` 지정 금지 — 전역 스타일(`Themes/Button.xaml`)에서 관리
- 예외적으로 큰 버튼이 필요하면 Named Style(x:Key)로 별도 정의. 인라인 Padding은 여전히 금지

## 핵심 규칙

- **한국어 응답**, 간결함 최우선 (3~5줄), 인사말/서론/결론 생략
- **PowerShell 7.0+** 필수 (`pwsh.exe`), Bash/Linux 명령어 금지
- **C# nullable enable** (WPF), **TypeScript strict** (Electron)
- camelCase/PascalCase/SCREAMING_SNAKE_CASE, UTF-8 LF
- **Conventional Commits**: `<type>(<scope>): <desc>` (scope: protocol, ui, transport, settings, desktop, electron, test, docs)
- 환각 방지: 근거 부족 시 명시, 불확실 시 추측 표기 + 대안 제시

### AI 코딩 4대 원칙

1. **Think Before Coding** — 불확실하면 추측하지 말고 먼저 확인
2. **Simplicity First** — 요청받은 것만 구현
3. **Surgical Changes** — 수정 대상만 변경
4. **Goal-Driven Execution** — 명령보다 목표로 지시

### 모듈화(Modularity) 원칙

핵심 기능은 나중에 독립 앱/CLI/REST API로 추출할 수 있게 만든다:
- **Service 계층에 WPF 타입(Window, Dispatcher, Application 등) 직접 참조 금지** — UI 알림은 Result<T> 반환 후 ViewModel이 처리
- **DibdProtocol/은 플랫폼 무관 라이브러리로 유지** — System.Windows 참조 절대 금지
- **새 Service 추가 시 `DialogService.Instance` 직접 호출 금지** — IDialogService 주입 또는 ViewModel에서 처리
- **`DibdProtocol.Transport/Rpc/`** — DIBD JSON-RPC 2.0 envelope 96 method 본문, namespace `Dabit.LedProtocol` (Blazor WASM 회피 영역이라 Transport 어셈블리 적재, 0517a 트랙)

### 영속성(Persistence) 필수 규칙

새 기능/UI 추가 시 반드시 확인:
- **사용자가 입력한 모든 설정값은 앱 재시작 후에도 유지**되어야 한다
- 새 입력 컨트롤(ComboBox, TextBox, CheckBox 등) 추가 시 → AppSettings + config.properties 저장/복원 구현 필수
- 저장 경로: `AppSettings` → `PropertiesConfigRepository` → `config.properties`
- 슬롯 구조 데이터는 `SettingService.SetProperties()` 배치 저장 사용
- 앱 종료 시 `App.OnExit()`에서 자동 저장됨 — 새 ViewModel 추가 시 여기에 SaveSettings 호출 추가

## FORBIDDEN (19개)

위반 시 현장 장비 오동작 또는 아키텍처 붕괴. 예외 없음.

### 프로토콜/바이너리 (F3–F5, F7–F8, F16–F19)

| ID | 금지 | 이유 |
|----|------|------|
| F3 | OPCode 값 변경 금지 | 컨트롤러 펌웨어가 고정 OPCode에 의존 |
| F4 | HEX 프레임(DLE-STX) 포맷 변경 금지 | 컨트롤러 파싱 고정 |
| F5 | ASCII 프레임(`![...!]`) 포맷 변경 금지 | 레거시 호환 |
| F7 | `pendingDle` 상태 제거 금지 | TCP 버퍼 경계 DLE(0x10) 분할 시 패킷 손실 |
| F8 | `DLE_OPCODES` Set 변경 금지 | C# `ShouldApplyDle()`과 정확히 일치 |
| F16 | DisplaySignal 시그널 코드 변경 금지 | 70+ 모델이 의존 |
| F17 | CrcCalculator 수정 금지 | 펌웨어 CRC 테이블과 일치 필수 |
| F18 | MSchedule 25바이트 구조 변경 금지 | 펌웨어 `memcpy` 직접 매핑 |
| F19 | tsParameter 792바이트 구조/오프셋 변경 금지 | 바이너리 레이아웃 고정 |

### INI/설정 (F1–F2, F9, F11)

| ID | 금지 | 이유 |
|----|------|------|
| F1 | INI 키 오타 수정 금지 (`ColorOder`, `ShowInfomation`, `PorotocolType`) | 현장 장비 하위 호환성 |
| F2 | Boolean INI 값을 `true`/`false` 변경 금지 | 레거시 앱·컨트롤러가 `0`/`1`만 읽음 |
| F9 | API Key/비밀번호 하드코딩 금지 | 환경변수 사용 필수 |
| F11 | AppSettings static 필드 직접 수정 금지 | `IConfigRepository` 경유 필수 |

### 아키텍처 (F6, F10, F12–F15)

| ID | 금지 | 이유 |
|----|------|------|
| F6 | BrowserRouter 사용 금지 | Electron file:// 미지원, HashRouter 필수 (WPF 해당 없음) |
| F10 | Bash 명령어 금지 | PowerShell 7.0+ 사용 |
| F12 | SerialTransport `portLock`(SemaphoreSlim) 우회 금지 | 동시 접근 시 포트 충돌 |
| F13 | DI 외부에서 Service 직접 생성 금지 | DI 컨테이너 일관성 |
| F14 | ViewModel에서 직접 Transport 호출 금지 | Service 계층 경유 필수 |
| F15 | MQTT 토픽명 변경 금지 (`/db_msg`, `/db_set`, `/db_sch`, `/db_msg_r`, `/db_sch_r`) | 장비 구독 고정 |

### 읽기 전용

| 금지 | 이유 |
|------|------|
| `references/DabitChe-V2.2.1/` 소스 수정 | 읽기 전용 레거시 참조 — 마이그레이션 대조 기준 훼손 |

## Architecture

```
dabitche/
├── DabitChe.Desktop/             ← [NEW] C# .NET 9.0 + WPF + CommunityToolkit.Mvvm
│   ├── Views/                    │  XAML UI (19 FU 매핑)
│   ├── ViewModels/               │  MVVM ViewModel
│   ├── Services/                 │  비즈니스 로직
│   ├── Config/                   │  AppSettings, IConfigRepository
│   └── Helpers/                  │  EventBus, Result<T>
├── DabitChe.Desktop.Tests/       ← xUnit 데스크톱 테스트
├── DibdProtocol/                 ← [SHARED] 프로토콜 라이브러리 (Desktop + Simulator 공유)
│   ├── Protocol/                 │  HexCommand, AsciiCommand, PacketBuilder, PacketParser
│   ├── Codec/                    │  CrcCalculator, DleFramer, BccCalculator, EncodingConverter
│   ├── Transport/                │  ITransport, Serial/TCP/UDP/MQTT/BT
│   ├── Model/                    │  DisplayConfig, ConnectionState, MessageSlot
│   └── Image/                    │  DatBuilder, RgbConverter
├── DibdProtocol.Tests/           ← xUnit 프로토콜 테스트
├── DabitChe.Electron/            ← [현행] Electron 33 + React 19 + Vite 6 + Zustand 5
│   ├── src/main/                 │  Electron 메인 (IPC, services, transport)
│   ├── src/renderer/             │  React UI (10 pages, 44 components, 8 stores)
│   └── src/shared/               │  공유 타입/프로토콜/i18n
├── references/                  ← 참조 자료 집중
│   ├── DabitChe-V2.2.1/          │  [읽기 전용] C++ Builder 6 레거시
│   ├── DabitChe_Java/            │  [로컬 참조] Java 포팅 (git 추적 안 함)
│   ├── Font/                     │  .fnt + FontConverter (릴리즈에 복사)
│   ├── firmware/                 │  .bin 펌웨어 (릴리즈에 복사)
│   └── DabitChe_UserManual_v9.0.pdf
└── docs/                         ← 통합 문서
```

### 전환 전략

- **현행**: DabitChe.Electron 운영 중
- **목표**: DabitChe.Desktop(C# WPF)으로 점진적 대체
- **공유**: DibdProtocol/ 라이브러리를 Desktop과 dbSimulator가 공유
- 프로토콜 엔진은 DibdProtocol/에 집중, 앱별 중복 구현 금지

## Build & Test

```powershell
# ── C# WPF (새) ──
cd DabitChe.Desktop
dotnet build
dotnet test ../DibdProtocol.Tests
dotnet test ../DabitChe.Desktop.Tests

# ── Electron (현행) ──
cd DabitChe.Electron
npm test                    # Vitest 387+개
npm run test:e2e            # Playwright E2E
npm run dev                 # Vite dev (:5173)
npm run dev:electron        # 전체 앱
npm run package:win         # NSIS 인스톨러
```

### DibdProtocol.Core 변경 시 브라우저 안전성 게이트

`DibdProtocol.Core/` 하위 소스를 수정한 커밋은 CI(`.gitea/workflows/ci.yml`)에서
다음을 자동 실행·검증한다.

1. `dotnet build DabitChe.sln --configuration Release`
2. `dotnet test DibdProtocol.Tests` + `dotnet test DibdProtocol.Core.Tests`
3. `dotnet publish DibdProtocol.Core.BlazorCheck/... --configuration Release`

3번이 실패하면 Core에 브라우저 비호환 API(System.IO.Ports / System.Net.Sockets /
MQTTnet 등)가 섞인 것. 로컬에서도 Core 수정 후
`dotnet publish DibdProtocol.Core.BlazorCheck -c Release` 수동 실행을 권장한다.
`dotnet build`만으로는 WASM 링커 회귀를 감지 못 한다.

**단, publish 성공은 "WASM 링커·트림 통과"까지만 증명하고, 브라우저에서
`Pages/Home.razor`의 `OnInitialized()` smoke가 실제 실행됨을 보장하지는 않는다.**
런타임 증명이 필요하면 `dotnet run --project DibdProtocol.Core.BlazorCheck`로
브라우저에서 5-way smoke(CRC·DLE·EUC-KR·byte-font·ASCII)를 육안 확인하거나,
Phase 1+에서 Playwright 1회 접속 step을 CI에 추가한다.

## Hooks

DabitChe.Electron에 Claude Code hooks가 설정되어 있다.

| 패턴 | 동작 |
|------|------|
| 커밋 전 품질 게이트 | git commit 시 `npm run quality` 자동 실행, 실패 시 차단 |
| FORBIDDEN 위반 감지 | 파일 수정 시 FORBIDDEN 패턴 정규식 매칭, 위반 시 경고 |
| /careful 안전 모드 | `.claude/.careful` 존재 시 위험 명령 차단 |
| Gotchas 자동 수집 | 세션 종료 시 빌드/테스트 실패 패턴 분석 |

## 로그 작성 원칙

`LogService`는 4 레벨(Info/Warn/Error/Debug)을 제공한다. UI는 평소 Info/Warn/Error만 표시하고, Debug는 로그 헤더의 "Debug 보기" 토글(`MainWindow.xaml`)을 켜야 보인다. 호출부에서 적절한 레벨을 선택해 노이즈를 줄인다.

### 레벨 분류 기준

- **Info** — 사용자 시나리오 흐름. 작업 시작/완료, 핵심 결과, 세션 라이프사이클. **TX/RX 단발 명령은 Info 유지** (업체가 시스템 구현 시 protocol 참고용 — `_logService.Info($"TX: 시간동기화 ASCII ![0030...!]")` 같은 라인은 의도적으로 보임)
- **Warn** — 사용자 조치가 필요한 비정상. 파일 누락, 응답 status 비정상, 펌웨어 거부 가능성
- **Error** — 작업 실패. 통신 끊김, 예외
- **Debug** — 평소 OFF, 트러블슈팅 시 ON. 패킷 단위 hex 덤프(`TX[cmd] NB → RX MB (Tms)`), 반복 호출 진행률(블록 N/M), 분기 결정 trace, 동일값 반복 entry 출력

### 연속 전송 (펌웨어/폰트/이미지 다블록)

블록 단위 진행률은 **Debug**. 시작·요약(블록 수)·완료만 **Info**.

```
Info: 펌웨어 전송 시작 219블록
Debug: 펌웨어 전송: 1/219 (0%)        ← 블록 단위 진행률
Debug: 펌웨어 전송: 51/219 (23%)
...
Info: 펌웨어 전송 완료
```

### 임시 디버그 (`DEBUG-TEMP`)

특정 버그 추적·신규 기능 검증을 위해 박은 일회성 로그는 다음 중 하나로 마킹한다:

1. 메시지 접두사: `_logService.Debug($"[DEBUG-TEMP] ...")`
2. 코드 주석: `// DEBUG-TEMP: <목적>, <날짜>`

검증 완료 시점에 두 갈래로 정리:

- "환경에 따라 또 깨질 수 있나?" (예: TCP fragment, 재부팅 응답) → **영구 Debug로 강등** — `[DEBUG-TEMP]` 접두사 제거하고 `_logService.Debug`만 유지
- "한번 검증으로 끝났나?" (예: 특정 byte offset 확인) → **제거**

월 1회 또는 PR 직전 `git grep "DEBUG-TEMP"`로 잔존 검토.

### 영구 Debug 후보 — 시스템 경계

코드 안쪽 깊은 곳의 trace는 임시 디버그(검증 후 제거)지만, **시스템 경계의 객관적 사실**은 영구 Debug로 둔다:

- 외부 I/O raw byte (TX/RX hex, latency `(Tms)`)
- 분기 결정 (어떤 path 탔는지: legacy vs modern, ImageDir fallback 등)
- 재시도/fallback 작동 (`ack timeout, retry 2/3`)
- 외부 환경 로드 결과 (`config.properties NN키 로드, 인코딩=EUC-KR`)
- 변환 입출력 byte count (`ConvertToSplitDat: 3549B → 612B+893B`)

기준 한 줄: "사용자 환경에서만 재현되는 문제를 원격 진단할 때 결정적 단서인가?"

## Data Flow Chains (흐름 기반 탐색)

함수 시그니처는 AI 도구(grep/glob)로 직접 탐색한다.

### C# WPF (DabitChe.Desktop + DibdProtocol)

| 시나리오 | 호출 체인 |
|---------|----------|
| UI → 컨트롤러 명령 | View → ViewModel → Service → DibdProtocol.Protocol → DibdProtocol.Transport |
| 프로토콜 수신 파싱 | Transport → PacketParser → Service → ViewModel → View |
| INI 설정 로드 | Config → IConfigRepository → fs (EUC-KR → UTF-8) |
| 파일 블록 전송 | Service → 블록 분할 (1024B) → Protocol → Transport |
| 스케줄 파일 | Service → PLA 직렬화/역직렬화 (리틀엔디언) → fs |

### Electron (DabitChe.Electron)

| 시나리오 | 호출 체인 |
|---------|----------|
| UI → 컨트롤러 명령 | Renderer → preload (contextBridge) → IPC → DeviceCommandService → HexProtocolBuilder → Transport |
| 프로토콜 수신 파싱 | Transport → ProtocolParser (상태 머신) → CRC 검증 → DeviceCommandService → IPC → Renderer |
| INI 설정 로드 | Renderer → IPC → IniSettingsService → fs.readFileSync → iconv.decode (EUC-KR) |
| 파일 블록 전송 | Renderer → IPC → 블록 분할 (1024B) → DeviceCommandService → HexProtocolBuilder → Transport |
| 스케줄 파일 | Renderer → IPC → ScheduleFileService → PLA 직렬화/역직렬화 (리틀엔디언) |

## Symptom → Where to Look

| 증상 | 확인 위치 (C# WPF) | 확인 위치 (Electron) |
|------|--------------------|--------------------|
| 프로토콜 바이트 불일치 | `DibdProtocol/Protocol/` | `src/shared/protocol/` |
| UI 렌더링 문제 | `DabitChe.Desktop/Views/` | `src/renderer/pages/`, `src/renderer/components/` |
| 통신/시리얼 문제 | `DibdProtocol/Transport/` | `src/main/services/transport/` |
| INI 설정 문제 | `DabitChe.Desktop/Config/` | `src/main/services/settings/ini-settings-service.ts` |
| 빌드/테스트 실패 | `dotnet build` 출력 | `DabitChe.Electron/package.json` 스크립트 |
| 레거시 동작 참조 | `references/DabitChe-V2.2.1/CLAUDE.md` | 동일 |

## Decisions (왜 이렇게 했는지)

| 결정 | 이유 |
|------|------|
| C++ Builder → C# → Electron → C# WPF | 레거시 65개 TForm 직접 포팅 불가, 단계적 재작성 |
| dbSimulator DibdProtocol 공유 | 프로토콜 엔진 중복 개발 방지 |
| INI 오타(`ColorOder` 등) 보존 | 현장 장비 하위 호환성 유지 |
| INI 읽기 EUC-KR → 저장 UTF-8 | 점진적 인코딩 전환 |
| BCD 시간 인코딩 | 레거시 컨트롤러 RTC 호환 |
| 13바이트 밝기 payload | 시간대별 밝기 + CDS 센서 레거시 구조 |
| HexProtocolBuilder C# byte-identical | V3.0.0(C#)과 바이트 일치 보장 |
| Electron IPC preload.ts 경유 | contextIsolation 보안 모델 준수 |
| WPF ViewModel → Service → Transport | MVVM 계층 분리, Transport 직접 호출 금지 (F14) |
| DI 컨테이너 필수 | Service 생명주기 관리 일관성 (F13) |

## Markdown 작성 규칙 (`docs/` 편집 시)

1. **Frontmatter 필수**: title, tags, last_updated 3필드
2. **H1 1개**, 레벨 스킵 금지 (H2→H3 순서)
3. **첫 문장 = 문맥 앵커**: H2 직후 첫 문장에 주어+문맥 포함
4. **한 문단 = 한 줄** (Git Diff 가독성), 코드블록 독립 (언어 태그 필수)
5. **TL;DR**: 문서 상단에 무엇/왜/어떻게 3줄 요약

## Deep Context (심층 문서)

심볼 검색은 AI 도구(grep/glob)에 맡기고, 문서에는 코드가 말 못 하는 것만 담는다.

| 작업 유형 | 읽을 문서 |
|----------|----------|
| 정본 매트릭스 (SSOT) | `docs/00_AI_가이드/README.md` |
| 로드맵 | `docs/00_AI_가이드/10_ROADMAP.md` |
| 프로젝트 구조 | `docs/00_AI_가이드/11_프로젝트컨텍스트.md` |
| 코딩 패턴 | `docs/00_AI_가이드/20_CODE_PATTERNS.md` |
| 모듈/프로토콜 참조 | `docs/00_AI_가이드/30_MODULE_INDEX.md` |
| 워크플로우 절차 | `docs/00_AI_가이드/40_WORKFLOW.md` |
| 스킬 레퍼런스 | `docs/00_AI_가이드/41_SKILL_REFERENCE.md` |
| 빌드 함정/에러 패턴 | `docs/00_AI_가이드/50_BUILD_ERRORS.md` |
| 테스트 카탈로그 | `docs/00_AI_가이드/60_TEST_CATALOG.md` |
| 자율 루프 | `docs/00_AI_가이드/70_AUTONOMOUS_LOOP.md` |
| 시각 검증 | `docs/00_AI_가이드/72_VISUAL_VERIFY.md` |
| DeepDive (모듈별) | `docs/00_AI_가이드/Modules/` |
| 플랜+회고 | `docs/00_AI_가이드/Decisions/` |
| 프로토콜 바이트 명세 | `docs/01_protocols/protocol-reference.md` |
| 레거시 참조 | `references/DabitChe-V2.2.1/CLAUDE.md` |
| UI 디자인 시스템 | `AI_Rules/080_ui-design-system.md` (토큰 정의, 컴포넌트 스펙, 적용 절차) |

### PM 시스템 (장기 매니저 운영 + 자동 분업)

DabitONe의 통합 매니저 역할은 별도 문서·슬래시 커맨드·claude agents로 운영된다. 새 세션에서 PM 직책을 인수하려면 `/pm-start`로 부트스트랩, 종료 직전 `/pm-end`로 인계. 작업 분해 후 PM이 `@worker-isolated`, `@researcher`, `@code-reviewer`, `@dabitone-protocol-expert`를 자동 호출.

**시간축 (PM 시스템 문서·커맨드):**

| 산출물 | 용도 |
|--------|------|
| `PROJECT_BRAIN.md` (루트) | 현재 동적 상태 — 진행·보류·우선순위. 매 세션 갱신 |
| `docs/PM/PM_CONTEXT_MAP.md` | 영역 색인 — "어디에 뭐가 있나" |
| `docs/PM/PM_PROTOCOL.md` | PM 운영 룰 — 4-Role·검토·팀빌딩·가드레일 |
| `docs/PM/templates/spec.md` | Worker brief 표준 템플릿 |
| `docs/PM/templates/retrospective.md` | Phase 회고 템플릿 |
| `/pm-start` | PM 세션 부트스트랩 슬래시 커맨드 |
| `/pm-end` | PM 세션 종료 + `PROJECT_BRAIN.md` 갱신 |

**공간축 (claude agents 4종 — `.claude/agents/`):**

| Agent | 역할 | 호출 시점 |
|-------|------|---------|
| `worker-isolated` | 격리된 worktree에서 spec.md 따라 한 Phase·기능 구현. 빌드·테스트·commit | PM이 Phase 분해 후 호출 |
| `researcher` | 외부 자료·라이브러리·기술 비교 조사. WebFetch·WebSearch | 결정 분기 전 호출 |
| `code-reviewer` | Worker 완료 코드 독립 검토 (worker 대화 안 봄, 확증편향 회피) | Worker 완료 후 자동 호출 |
| `dabitone-protocol-expert` | DIBD 프로토콜 + 콘텐츠 포맷(DAT/PLA/BGP/ANI) + 전송 절차 전문가 | 프로토콜·콘텐츠·전송 영역 변경 시 자동 호출 |

**시행 강제 (Hook 1개 — `.claude/hooks/`):**

| 산출물 | 역할 | 호출 시점 |
|--------|------|---------|
| `r-pm-1-guard.ps1` | **R-PM-1 시행 강제** — PM 직접 grep/glob/read 3회 경고·5회 차단 | PreToolUse 자동 (`.claude/.pm-session-active` 존재 시 발동) |

**R-PM 직책 한도 (PM 세션에서 매번 준수)**:
- **R-PM-1**: 다중 grep/glob/read 직접 금지 — sub-agent(Explore/general-purpose)에 위임 필수. Hook이 3회 경고·5회 차단으로 시행 강제
- **R-PM-2**: 단일 핵심 문서 Read·작은 fix·사용자 인터뷰·PROJECT_BRAIN 갱신은 PM 직접 OK
- **R-PM-5**: 사용자 이미 답한 내용 재질문 금지·다음 단계 진입 전 명시 동의 받기·"잘못됐다" 지적 시 즉시 중단·결정 항목은 1~3개 선택지로 좁힘
- **R-PM-7**: Evidence Tier 강제 — 모든 결론 ✅사실(카메라/실기 확인) / 🟡추정(코드·논리 미검증) / ❌가정(미입증) 3분류 자동 분리. **코드 변경 ≠ 검증.** 사용자가 "근거는?" 묻기 *전에* 자발 분리. 사례: 2026-05-26 retry 정책 — PM이 코드 변경만 보고 "회복 + 견고" 단정했다가 사용자 지적
- 상세: `docs/PM/PM_PROTOCOL.md` 2.5 섹션, `AI_Rules/100_pm-system.md` "PM 직책 한도 R-PM-7"

**🚨 세션 종료 직전 반드시 `/pm-end`** — `PROJECT_BRAIN.md` 갱신 누락은 다음 PM 세션의 인계 단절 = 시스템 무결성 손상.

정본 가이드: `D:\Note\20_Marketing_Team\23_Resource\AI_Rules\100_pm-system.md` + `101_pm-system-guide.md`

### 프로토콜 점검 필수 참조

프로토콜 전송 코드(패킷 빌드, 바이트 매핑, msgType, /P 페이지 등)를 수정할 때 **반드시** 아래 5개 문서를 검토한다:

| 문서 | 용도 |
|------|------|
| `docs/01_protocols/ascii-reference.md` | ASCII 명령어 전체 목록 + 속성코드 |
| `docs/01_protocols/hex-protocol.md` | HEX 프레임 구조 + DLE 이스케이프 |
| `docs/01_protocols/hex-reference.md` | HEX 명령별 실전 예시 |
| `docs/01_protocols/protocol-reference.md` | DIBD 완전 레퍼런스 (ASCII+HEX 통합) |
| `docs/01_protocols/protocol-schema.json` | AI 파싱용 구조화 스키마 |

### 콘텐츠 편집 필수 참조 — **🚨 강제 규칙**

콘텐츠 편집(`TextEditorWindow`, `DatFileService`, `LegacyDatHeader`, `ConvertToSplitDat` 등) 관련 코드를 **수정·추가·리팩토링**할 때, 작업 전에 **반드시** 아래 문서를 읽는다. 호환성 가정을 깨뜨리면 레거시 파일을 읽을 수 없게 되어 마이그레이션이 실패한다.

| 문서 | 용도 |
|------|------|
| `docs/00_AI_가이드/85_EDITOR_LEGACY_COMPAT.md` | 레거시 분할 DAT 호환성 현황 + 파싱 누락 지점 + 수정 제안 |
| `docs/01_protocols/dat-bgp-pla-textbook.md` | DAT/PLA/BGP 바이트 포맷 전체 정의 (분할 DAT 2-섹션 구조 포함) |
| `memory/project_split_block_format.md` | 분할 블록 펌웨어 검증 기록 (Option[0], BFormKind=2, dsrCnt 필수) |

**원칙**: 바이트 포맷 호환성은 이미 맞춰져 있으므로 깨지 않는다. 파싱 로직은 누락되어 있으므로 수정 시 이 문서의 수정 범위(P0/P1/P2)를 따른다.

## Gotchas

- **Gitea 릴리즈 한국어 깨짐 방지** — Git Bash curl로 한국어 JSON 전송 시 인코딩 깨짐. 반드시 `pwsh.exe -NoProfile`에서 `ConvertTo-Json` + `[System.Text.Encoding]::UTF8.GetBytes()` + `Invoke-RestMethod` 조합 사용. curl 금지
- **ASCII 페이지 메시지 msgType은 항상 "1"** — 페이지 번호는 `/P{xx}` 속성(0-based)으로 지정. msgType에 페이지 번호를 넣으면 안됨
- **분할 DAT Section 2에 TextInfo 넣으면 XY 어긋남** — FCH(32B)만 기록, TextInfo(256B) 금지
- **BFormKind=1 대신 2 사용** — 펌웨어가 BFormKind=1을 다르게 처리하여 좌표 계산 오류 발생
- **분할 시 Option[0]=1 필수** — 누락 시 Y 5px 어긋남
- **분할 시 dsrCnt EDEffect 최소 0x01** — 0이면 컨트롤러가 분할을 인식 못함
- **레거시 분할 DAT의 Section1 FCH `RH`는 "메인 블록 폭"** — 전체 폭이 아님. H1F 샘플 파일의 `RH=16`인데 실제 전광판 폭은 96. `DatFileService.Load`가 현재 이를 전체 폭으로 오해하여 레거시 분할 파일을 못 읽음. 수정 전 반드시 `docs/00_AI_가이드/85_EDITOR_LEGACY_COMPAT.md` 참조
- **레거시 DAT 열기는 사이드카 기반** — `TextEditorWindow.OnLoadDat`는 `.blocks.json` 사이드카가 없으면 `BackgroundImagePath`에 경로만 할당하고 TextInfo 파싱을 건너뜀. 레거시 파일(사이드카 없음) 호환 작업 시 이 경로 수정 필요
- **레거시 BGP/PLA의 dat 참조는 bare 파일명** — V2.x는 `.bgp`(`Data\Playlist\`)와 `.dat`(`Data\Image\`)이 다른 폴더. `ScheduleFileService.ParseLegacyBinary`가 BGP 같은 폴더만 뒤지면 못 찾고 bare name(`"test_r.dat"`)으로 fallback → 전송 단계 `File.Exists` 실패 → 0블록 전송 → 컨트롤러 슬롯 모두 동일 메모리(블록 0) 가리킴 → "1~7번 모두 RED" 증상. 수정 후 해석 우선순위: **`AppPaths.ImageDir`/`VideoDir`(레거시 V2.x DestTextPath와 동일) → BGP 같은 폴더 → bare name**. `ScheduleTransferService.ResolveContentPath`가 전송 단계에서도 한번 더 구제(2026-05-07 fix)
- **펌웨어/폰트 청크 전송은 ACK 대기 필수 — Fire-and-forget 금지** — 시리얼/TCP에서 컨트롤러 처리 지연(플래시 쓰기 등)으로 일부 청크가 누락되면 침묵 회귀(전송 성공 같지만 미적용·한글 폰트 비트맵 손상). `FirmwareService` + `FontSettingsViewModel`의 청크 루프는 반드시 `AckPolicy.Required` + 청크별 3회 retry. timeout warning이 가끔 뜨더라도 **무결성 > 속도**. 정본: 67f1fe88(Fire-and-forget 도입)의 회귀 fix (2026-05-09 카메라 검증 — 한글 폰트가 색 채움 형태로 깨졌던 증상이 ACK 대기 복원으로 해결). 향후 속도 개선 시 청크 간 sleep 등 다른 방향으로 (ACK 대기는 유지)
- **FNT 폰트 글리프 시작 ASCII는 글리프 수로 분기** — `FntRenderer.RenderEngGlyph`는 `asciiCode * glyphSize`로 lookup하지만 폰트 파일별 시작 ASCII가 다름. 256/128 글리프 폰트(DABIT 표준, Gothic, Roman 8x16 등)는 ASCII 0부터, **95 글리프 폰트(ENG 16x16-ASCII-Roman/RN90, ENG 16x32-굴림체 등)는 ASCII 0x20(space)부터** 저장. 95 글리프는 `glyphIdx = asciiCode - 0x20` 보정 필요. 미리보기에서 "1" 입력 시 "Q"/"R" 같은 다른 글자가 나오면 이 보정 누락. 헤더 byte 12=W, byte 13=H, byte 14=glyphSize(B). 시작 ASCII는 헤더 명시 없어 글리프 수로 추정. 정본: FntRenderer 2026-05-10 fix
- **.NET 7+ SerialPort timeout은 IOException** — `SerialPort.ReadAsync` timeout이 .NET 6까지 `TimeoutException`이었으나 .NET 7부터 **`IOException`**으로 throw (GitHub dotnet/runtime#81035). 외부 catch가 `TimeoutException`만 잡으면 .NET 9 환경에서 회귀 — 시리얼 일시 timeout이 외부 retry 발동 안 함. transport retry 정책 작업 시 catch에 `IOException` + `SocketException` 추가 필수. `TransferSessionService.IsRetriable`은 이미 세 가지 다 잡으나, `FirmwareService` + `FontSettingsViewModel`의 청크 외부 retry는 좁아져 있을 수 있음. 정본: memory `reference_dotnet7_serialport_breaking`, 인계 doc `docs/00_AI_가이드/Decisions/2026-05-26-transport-retry-attempt-revert.md`

### Phase 1b Parser + VirtualControllerCore Gotchas (2026-04-21 v1.2 설계·플랜 반영)

- **Parser는 wire-faithful — text canonicalization 금지** — `PacketParser.TryParseDisplayMessagePayload`는 decode된 문자열을 **원문 그대로** 반환해야 한다. `\r`(0x0D) 제거 / `\n`→공백 변환 같은 canonicalization을 **parser 내부에서 절대 하지 말 것**. M07(CR/LF 원문 전송) Inv-1 byte stability를 보장하려면 wire-faithful 필수. Canonicalization은 `DisplayMessageSpecWireCanonicalizer.CanonicalizeForRoundTrip`에서만 수행
- **`CharColorCodec.Normalize`에 3-bit 마스킹 추가 금지** — Phase 1a `CharColorCodecTests`가 `{1, 2, 9, 9, 9}` 보존을 기대하므로 마스킹 추가 시 breaking. 3-bit (fg·bg ∈ [0, 7]) 정책은 **Phase 1b `DisplayMessageSpecWireCanonicalizer`에만** 적용. Phase 1a 정본 Codec은 건드리지 않는다
- **`VirtualControllerCore.ApplyHexFrame`에는 framed packet만 — payload 단독 입력 금지** — `ApplyHexFrame`은 `DleFramer.TryDeframe`을 경유하므로 입력은 `DLE STX DST LEN CMD DATA DLE ETX` 전체. payload(0x94 data)만 넣으면 `ApplyResult.MalformedFrame` 반환. payload만 있으면 `ApplyHexParsed(HexParsedResponse)`로 직접 진입할 것. 테스트 `FrameVsPayloadContractTests`가 계약 오사용을 검증
- **Empty-run canonical form 고정** — 빈 텍스트(M18, payload.Length == 16) payload는 `DefaultFg/DefaultBg/CharColors/FontGroup` 복원 불가. Parser와 `DisplayMessageSpecWireCanonicalizer` 모두 **`Text="", CharColors=null, DefaultFg=0, DefaultBg=0, FontGroup=Group0`** 으로 고정. `DisplayMessageSpecStructuralComparer`를 빈 텍스트 특례로 약화시키지 말 것
- **`VirtualControllerCore`는 Phase 1b에서 단일 스레드 전용** — 내부 `Dictionary`·`List` 기반이라 `Apply*`/`Snapshot`/`GetSection` concurrent 호출 시 레이스 → 동작 미정의. 호출자가 UI 스레드 or 전용 worker로 직렬화해야 한다. Phase 2+에서 concurrent 필요 시 `lock` 또는 `ConcurrentDictionary` 전환 검토. 구현 시 XML doc에 반드시 "Thread-safety: Phase 1b 단일 스레드 전용" 명시
- **`ControllerState.Sections`/`GetSection`은 deep-copy snapshot** — `ImmutableDictionary`/`ImmutableArray`는 컨테이너 불변성만 보장. `DisplayMessageSpec.Run.CharColors.Colors`가 가변 `int[]`이므로 `SectionManager.CloneSpec`에서 `Array.Copy`로 복제해야 내부 상태 aliasing 차단. Snapshot/GetSection 호출자는 반환값의 `NormalizedCharColors.Colors[0] = 999` 변경이 내부에 영향 주지 않음을 가정하고 설계. `SnapshotAliasMutationTests` 2건이 계약을 증명

## 커밋 시 문서 업데이트 규칙 — **🚨 강제 규칙**

### MANDATORY: 커밋 전 체크리스트

**커밋하기 직전에 반드시 다음 4가지를 확인한다. 하나라도 놓치면 커밋 금지.**

```
☐ 1. 프로토콜 바이트 구조 변경/발견이 있으면 → docs/01_protocols/*.md 업데이트
☐ 2. 레거시 대비 새 기능이면 → docs/00_AI_가이드/80_LEGACY_ENHANCEMENTS.md 업데이트
☐ 3. AI가 반복 실수한 패턴이면 → CLAUDE.md Gotchas 섹션 업데이트
☐ 4. 펌웨어 동작 검증 결과면 → memory/project_*.md 추가
```

### 발견 유형별 업데이트 대상

| 발견 유형 | 업데이트 대상 |
|----------|-------------|
| 프로토콜 바이트 구조, DAT/PLA/BGP/ANI 포맷 | `docs/01_protocols/dat-bgp-pla-textbook.md` |
| HEX/ASCII 명령 응답 포맷 | `docs/01_protocols/hex-reference.md`, `ascii-reference.md` |
| 레거시 대비 변경/확장 기능 | `docs/00_AI_가이드/80_LEGACY_ENHANCEMENTS.md` |
| AI가 반복한 실수 패턴 | 이 파일의 `Gotchas` 섹션 |
| 펌웨어 동작 검증 결과 | `memory/` (project 타입 메모리) |
| 새 ViewModel/Service 패턴 | `docs/00_AI_가이드/20_CODE_PATTERNS.md` |

### 강제 시행 절차

**커밋 프로세스:**

1. **코드 변경 완료** → `git diff`로 변경 내용 확인
2. **체크리스트 순회** → 4가지 업데이트 대상 중 해당하는 것 식별
3. **문서 업데이트** → 발견 사실을 해당 문서에 기록
4. **문서도 함께 스테이징** → `git add <code files> <doc files>`
5. **커밋 실행** → 코드+문서를 같은 커밋에 포함

### 위반 시 복구 절차

**이미 코드만 커밋했고 문서를 빼먹은 경우:**

```powershell
# 직후 커밋으로 문서 추가
git add docs/
git commit -m "docs: [커밋해시] 후속 — {발견 내용} 반영"
```

### Why 이 규칙이 강력한가

- **반복 실수 방지**: 세션마다 레거시 바이트를 재분석하면 시간 낭비
- **다음 세션 컨텍스트**: 문서가 최신이어야 다른 세션/에이전트가 올바른 정보로 작업
- **장기 유지보수**: 6개월 후 이 코드를 볼 때 "왜 이렇게 했지?"에 답해야 함
- **검증 이력**: "컨트롤러 검증 완료 (날짜)" 표시로 회귀 방지

### 구체적 사례 (2026-04-10)

ANI 파일 포맷 수정 세션에서 놓친 것:
- ✗ FCDavHeader 16B (32B가 아님) — 레거시 소스에서 발견
- ✗ TextInfo가 프레임 데이터 뒤에 옴 (앞이 아님)
- ✗ BlockText[1] Y=16 하드코딩 — 레거시 TFormMessageText.cpp:1936
- ✗ 0x9B BGP 비디오 opcode — 문서에 미기재
- ✗ HEX SetScreenSize 응답 [0xF1, rows, cols] — 기존 문서 [status] 오기재

**교훈**: 레거시 소스(`references/DabitChe-V2.2.1/`)를 분석했다면 그 발견을 즉시 텍스트북에 반영해야 다음 세션에서 같은 분석을 반복하지 않는다.