# design.md

## 브리프 3줄

- 무엇을: Windows 11용 DMF 설정/복구 앱과 매일 생성되는 DMF xlsx 리포트의 시각 언어·정보 위계·상태 표현을 개선한다.
- 누구에게: 개발자가 아닌 한국어 규제 실무자가 키 등록, 자동 실행, 오늘 리포트 확인을 막힘 없이 수행하게 한다.
- 제약: Python stdlib `tkinter`, XlsxWriter 단독, 런타임 의존성 추가 금지, 실제 9,084건 기준선, 기본 언어 ko-KR 한국어, Google/agy는 선택, No RED No Code.

## 레퍼런스와 근거

- R1 구조: Microsoft Windows/Fluent 설정·접근성 원칙. 설정은 단순 그룹, 상태와 다음 행동, 접근 가능한 기본 컨트롤을 사용한다.
- R2 톤: 규제 문서/감사 가능한 원장. 차분한 잉크·종이 표면, 기준일·출처·한계 문구를 숨기지 않는다.
- R3 디테일: Excel 접근성/대시보드 관습. A1 목적문, 명확한 시트명, 표/ListObject, 동결창, 의미 있는 하이퍼링크, 색 단독 금지.

## 한 문장 컨셉

**감사 가능한 조용한 계기판** — 사용자는 예쁜 화면보다 오늘 무엇이 막혔고 어떤 파일이 근거인지 즉시 알아야 한다.

## 프리셋

- designpaca `swiss-minimal` 기반.
- 이유: DMF 수집은 정보가 많고 신뢰가 전제인 내부 도구다. 실험적 장식보다 정렬, 대비, 필터 가능한 표, 출처 노출이 우선이다.

## 감수한 리스크 하나

- xlsx 대시보드 A1에 스크린리더용 목적문 행을 추가했다.
- 시각적으로는 한 줄이 늘어나지만, Excel 접근성상 빈 A1에서 시작하지 않고 파일 목적을 즉시 읽게 하는 편이 이 브리프에 맞다.

## 토큰

### Windows 앱

- 폰트: `맑은 고딕` 우선. Windows 한국어 환경에서 기본 탑재되고 추가 설치가 필요 없다.
- 색 역할:
  - 배경 `#FFFFFF`
  - 카드 `#F6F7F8`
  - 요약 표면 `#F3F6F8`
  - 본문 `#1F2328`
  - 보조 `#6E7781`
  - 경계 `#D0D7DE`
  - 강조 `#0072B2`
  - 상태: OK `#167A3C`, WARN `#C77700`, BAD `#BE2828`
- 간격: 4/8px 리듬. 외곽 28/24, 카드 14/12, 버튼 padding 14/8.
- 형태: 큰 그림자 없음. 카드/요약은 1px 선과 배경 톤 차이로만 구분.
- 모션: 없음. 긴 작업은 freeze 방지를 위해 worker thread + 상태 문장으로 피드백.

### xlsx

- 폰트: `맑은 고딕` 10pt, 제목 14/18pt, KPI 값 28pt.
- 팔레트: Okabe-Ito 기반. 강조 `#0072B2`, 신규 `#009E73`, 변경 `#E69F00`, 취하 `#D55E00`, 워치 `#CC79A7`, 잉크 `#1F2933`.
- 상태 표현: 배경색 + 폰트색 + 텍스트 라벨 + 기호. 취하는 취소선까지 사용.
- 열 폭: 데이터 시트의 visible column은 Excel 폭 약 48.75 이하로 제한. 긴 한글 값은 줄바꿈/필터/원장 조회로 흡수한다.
- 링크: `조회` 같은 모호한 문구 금지. 외부 원문은 `원문 조회`, 원장 내부 이동은 `원장 보기`처럼 목적을 쓴다.

## 성능·의존성 예산

- 새 런타임 의존성 0개.
- GUI 프레임워크 교체 없음. `tkinter` 유지.
- xlsx 생성 엔진 `XlsxWriter` 단독. openpyxl/pandas 금지 유지.
- GUI 모션/이미지/WebGL 없음.

## 채택한 효과와 폴백

- 효과 없음. 표면은 색·선·타입 위계로만 구성한다.
- xlsx는 Excel을 한 번도 열지 않아도 수식 캐시값으로 값이 보이게 한다.

## 의도적으로 하지 않은 것

- WinUI/PySide로 교체하지 않았다. 비개발자 PC에서 설치 의존성과 실패면이 늘어난다.
- 대시보드를 화려한 다크/네온/그라디언트로 만들지 않았다. 규제 원장과 한국어 표 읽기에는 조용한 라이트 표면이 맞다.
- Google/agy를 기본 설정 여정에 넣지 않았다. AI 요약은 선택 기능이고, 기본 수집·xlsx 생성은 막으면 안 된다.
- xlsx 데이터 시트에서 모든 긴 텍스트를 넓게 펼치지 않았다. 9,084건 원장은 스캔·필터가 우선이라 열 폭 상한을 둔다.

## 2026-09-03 변경 기록

- Windows 앱: 상단 상태 요약 strip(`필수/권장/정상`), `필수 설정/선택 기능/운영 상태` 그룹, 전용 상태 badge, 행 액션 버튼 최소 폭을 추가했다.
- xlsx: 문서 속성(title/subject/category/author/comments), 대시보드 A1 목적문, dashboard 내부 링크 검증, 데이터 시트 역링크 검증, 의미 있는 링크 문구, visible column width cap을 추가했다.
- 테스트: `tests/test_gui_design_contracts.py`, `tests/test_report_e2e_design.py` 디자인 RED를 추가했고 `pytest tests -q` 58 passed로 검증했다.