Wireframe ASCII per-flow

Từ v2.1.0, wireframe ASCII không còn viết per-screen (ascii-screen/) mà chuyển sang per-flow (ascii-wireframe/): mỗi flow nghiệp vụ một file. Trang này giải thích format, các gate bắt buộc, và cách migrate dự án cũ.

Vị trí trong pipeline

srs → use-case → userflow (duyệt) → wireframe → render-html

wireframe chạy sau khi userflow đã được duyệt (stage: flow-approved) và trước render-html. Nó mang Specification review gate — không ship wireframe khi chưa có Specification receipt current.

Cách gọi

/ba-start wireframe --slug <slug> --module <module_slug>

Điều kiện tiên quyết (HARD gates)

Thiếu bất kỳ điều kiện nào → command dừng và báo đúng phần thiếu:

Format: bảng 5 cột, Description 6 lớp

Mỗi file flow chứa bảng mô tả màn hình:

# | Items | Control type | Data type | Description

Mỗi ô Description phải mô tả hành vi bằng business language, đủ 6 lớp:

1. Business meaning — ý nghĩa nghiệp vụ của element
2. Validation + BR refs — rule validate, reference BR-*
3. States — các trạng thái (default, disabled, read-only, ...)
4. Navigation targets — bấm vào đi đâu
5. Error wording EXACT — câu chữ lỗi đúng nguyên văn từ 02_backbone/message-list.md (MSG/E codes)
6. Edge/security/compliance — edge cases, bảo mật, tuân thủ

Quy tắc message (MSG-*)

Text MSG-* là canonical từ 02_backbone/message-list.md. Dòng ▼ MSG-XX: trong ASCII wireframe là bản sao — phải khớp nguyên văn với câu canonical (không phân biệt hoa thường/dấu/phân cách). Lệch → build fail với MSG_TEXT_MISMATCH. Không bao giờ viết tắt hay viết lại message canonical trong wireframe.

Cấm trong Description

• HTTP verbs: POST/GET/PUT/PATCH/DELETE
• /api/ paths, endpoint URLs
• Tên framework/router function
• State-management calls

Vi phạm → BEHAVIOUR_FORMAT_VIOLATION. Sửa trước khi đi tiếp.

Nguồn dữ liệu

• Screen list + flow grouping: từ userflow Mục 2/3 đã duyệt — không tự chế thêm màn hình
• Portal/nav IDs: từ shared-shell-contract.md — chỉ reference, không định nghĩa lại
• State Visual Coverage: convention separate-screen + index annotation

Validators chạy sau khi viết

# Navigation consistency
ba-kit run-script validate-navigation-consistency.py --design {design_doc} \
  --screen-contract {flow_file_1} --screen-contract {flow_file_2} ...

# Index validation (bắt buộc)
ba-kit validate-index --index-key ascii_wireframe_index --slug <slug> --date <date> --module <module> --writeback

# Template conformance (bắt buộc)
ba-kit run-script check-template-conformance.py --artifact {index} --template ascii-wireframe-index-template.md
ba-kit run-script check-template-conformance.py --artifact {flow_file} --template ascii-wireframe-flow-template.md

Index FAIL → dừng, sửa index, chạy lại validator. Không đi tiếp khi index chưa PASS.

Kết quả tạo ra

03_modules/{module}/ascii-wireframe/
├── index.md          # Wireframe index
└── {flow-slug}.md    # 1 file per flow — bảng 5 cột + ASCII

Migration từ ascii-screen cũ

Dự án tạo trước v2.1.0 dùng per-screen ascii-screen/. Để migrate sang per-flow:

ba-kit run-script migrate-ascii-per-flow.py

Chạy per module. Contract keys ascii_screen_* vẫn đọc được thêm 1 release (deprecated) — file cũ không vỡ ngay, nhưng nên migrate sớm.

Lỗi thường gặp

• Tự định nghĩa portal/nav trong file flow → chỉ được reference từ shared-shell-contract.md
• Viết tắt message canonical → MSG_TEXT_MISMATCH, phải chép đúng nguyên văn
• Chạy wireframe khi userflow chưa duyệt → từ chối; duyệt userflow trước
• Module BA tự tạo DESIGN.md → không được; escalate Lead BA

Tiếp theo

• ba-start — toàn bộ pipeline
• Hướng dẫn từng bước — flow thực tế