hereby Platform

한국어

English

한국어

English

다크 모드

서비스 사양서 작성 가이드 (정본 표준) ​

2026-07-20 제정 (콸). 모든 HB* 사양서는 이 가이드를 따른다. 정본 = MD (spec-mirror/{APP}/{CODE}.md, git 추적 · docs/spec 배포본이 공개 정본). 컨플은 md2conf.py --publish로 생성되는 보조 열람용 — 컨플 직접 수정 금지.

1. 문서 단위 = 화면 depth 트리 ​

  • 메인 화면 HB{APP}{N}00 → 하위 화면(모달·서브뷰·상세)은 부모 코드 +1 단위 별도 문서 (예: HBIV210 → HBIV211 품목 추가·수정, HBIV212 수량·반품)
  • 부모 문서: 하위 목록 링크 / 하위 문서: 경로 라인에 부모 계보 표기
  • 사이드바(트리)는 폴더·인덱스 구조가 그대로 반영

2. 문서 구조 (섹션 순서 고정) ​

  1. # HB{코드}_{화면명} + 경로 라인 (Hereby) {앱} > {메뉴} > {화면}
  2. 메타 표 (앱·포트 / 대상 사용자 / 관련 정책 [[POL_…]] / Status / Owner)
  3. ## 개요 (1~3줄) · ## 문서 히스토리 (날짜/작성자/변경)
  4. ## Data I/O — Server→Client (${변수} + 엔티티.컬럼 + 값 없을 때), Client→Server (액션 + tRPC/SDK + 권한 토큰), 외부 통합
  5. ## 화면 플로우 — mermaid (진입·권한·화면 전환)
  6. ### {화면·모달별} 사양표 — 6컬럼 (번호/항목/타입/사양 및 기능 설명/연관·영향/비고), 서브 화면은 별도 표
  7. ## 권한·상태 분기 요약 표 · ## Open Question

3. 동작 깊이 기준 (GC700 수준) ​

모든 인터랙티브 요소는 6종 전부: ①기본 동작 ②상태 분기(case inline) ③Empty(-E 행) ④값 없음 처리 ⑤에러·실패 동작 ⑥권한별 차이. 라이브에서 확인된 것만 기술 — 미확인 = TBU, 추측 금지. UI 문구는 큰따옴표 원문 카피.

4. 표기 규약 ​

  • 상태: CASE01 [상태] / 권한: 조건1 [역할] / 단계: STEP1 (⚠ 색상 토큰 문법(case01Blue 등) 폐기 — 콸 지시 7/21)
  • 번호: 10단위 대분류, ㄴ/ㄴㄴ 하위, -E Empty
  • 참조: {Entity}.{column} · sdk.{svc}.{method}() · {res}:{act}.{scope} · [[문서]]

5. MD 렌더 규칙 (필수) ​

표 구분자행 |---| 필수 · 행별 컬럼 수 일치 · 셀 내 \| 이스케이프 · 셀 내 줄바꿈 <br/> · 발행 전 린트 통과

6. 검수 체크리스트 (제품 단위) ​

  • [ ] 트리: 하위 화면 분리·코드 체계·부모/자식 링크
  • [ ] 전 요소 깊이 6종 (특히 Empty·에러·값 없음)
  • [ ] Data I/O 값 없음 처리 전 변수
  • [ ] mermaid 플로우 존재
  • [ ] UI 원문 카피 (의역 0건)
  • [ ] 린트 통과 + 발행 확인

7. 가독성 규칙 (2026-07-21 추가 — 콸 지적 반영, GC00 기준) ​

  • 한 셀 = 핵심 동작 1~2문장. 상태분기(case)·Empty(-E)·값 없음·에러는 같은 셀에 밀어넣지 말고 ㄴ 하위 행으로 분리 (셀 내
    3줄 초과 금지)
  • TBU 흩뿌리기 금지 — 셀마다 "= TBU" 반복하지 말고, 행 비고에 TBU: 에러·세부UI 압축 표기하거나 문서 말미 Open Question 표로 취합
  • 항목/기능명 컬럼에 있는 라벨을 설명 서두에서 재인용하지 말 것 (중복)
  • 흐름 서사는 mermaid가 담당, 표는 요소 단위 사실만 — 표 셀에서 문단 서술 금지
  • 셀 길이 가이드: ~200자. 넘으면 행 분리 신호

8. 액션 표기 의무 (2026-07-21 추가 — 콸 지적) ​

  • 모든 인터랙티브 행(Button/MenuItem/Tab/Link/ListItem/Cell 액션)의 사양 설명 첫 줄은 반드시 명시적 액션: 클릭 → "{모달명}" 모달 / 클릭 → {화면코드} 전환 / 클릭 → 즉시 실행, 성공: {토스트·상태} / 클릭 → 컨펌 "{문구}" → 실행 / 입력 → {반응}
  • 목적지가 하위 문서면 클릭 → [[하위코드]] 로 링크
  • 액션 미확인이면 빈칸·서술 생략이 아니라 클릭 → TBU를 명시 (구멍 가시화)
  • "~를 관리한다/정의한다" 같은 기능 서술만 있고 액션 없는 행 = 미완성 행

9. 사양 셀 표준 스타일 (콸 확정판 2026-07-21) ​

셀 구조 = 기능 설명 → 액션 시 설명 → (필요시) 단계·케이스 명세. 정보 depth는 줄바꿈(
) + 전각공백(　) 들여쓰기로 표현:

• {기능 설명 — 무엇을 하는 기능인지 1문장}
• 클릭 시: {구체 결과}
　- STEP1 {…}
　- STEP2 {…}
　- CASE01 [조건]: {결과}
　- CASE02 [조건]: {결과}
  • 내용 없는 TBU 뼈대 ㄴ행 금지 — TBU는 비고 한 줄(TBU: {…}) 또는 OQ로만
  • ㄴ 하위 행은 실재 UI 하위 요소에만 (상태·에러 주석용 뼈대 행 남발 금지)
  • 연관/영향 컬럼에 부모 값 기계 복제 금지
  • 색상 토큰 폐기: CASE01 / 조건1 / STEP1 표기