Quy trình thiết kế / sửa UI — cho Cowork/Codex

Mục tiêu: thiết kế/sửa UI đúng ý User, đồng thời đảm bảo UI đủ chuẩn để scanner đọc ra sổ khái niệm. Tài liệu này đứng trước hai quy trình sửa-rẻ: SR-LAP (lập sổ) và SR-SUA (sửa sổ).

---

1. Vòng làm việc

1. User nêu yêu cầu nghiệp vụ.
2. Cowork/Codex dựng bản nháp UI.
3. User xem và phản hồi.
4. Sửa từng vòng nhỏ, chỉ đụng đúng phần được yêu cầu.
5. Lặp đến khi User xác nhận: UI_DONE_BY_OWNER (UI mới) hoặc UI_EDIT_DONE_BY_OWNER (sửa UI cũ).

Trước khi có xác nhận, UI chỉ là bản nháp. Không ghi PG, không ghi sổ khái niệm, không chạy DOT.

---

2. Năm chuẩn UI để scanner đọc được

1. ui_id cố định — sửa giao diện không đổi id (vd master-list-quy-trinh-v1).
2. Có nguồn cấu trúc đọc-được-bằng-máy (JS object / JSON / YAML / schema), không chỉ text rời trên màn hình.
3. Mỗi khái niệm có key bền — field/nút/trạng thái/link/số-tính-toán đều có key ổn định (vd task_minutes, workflow_status). Không lấy nhãn hiển thị làm danh tính: nhãn đổi được, key thì đừng.
4. Mảng gộp được bằng [] — viết flows[].tasks[].minutes, KHÔNG flows[0].tasks[4].minutes. UI 1.000 task vẫn chỉ là 1 khái niệm tasks[].minutes.
5. Số liệu tính toán có marker riêng — tổng/tiến độ/cộng dồn phải có marker (vd total_minutes). Thiếu marker thì scanner chỉ đoán bằng text yếu và phải đưa review.

---

3. Ranh giới bắt buộc: khái niệm UI ≠ dữ liệu luồng

• Sổ khái niệm chỉ ghi LOẠI thuộc tính (UI concept layer): mã quy trình, tên task, số phút, trigger, người thực hiện, trạng thái, liên kết, tổng phút…
• Không nhét nội dung luồng cụ thể vào sổ (business-flow data layer): "WF-0001 gồm task nào", "task A mấy phút", "ai làm task B", input/output/điều kiện của một task cụ thể. Nếu cần lưu, để cho bảng workflow riêng — KHÔNG ghi vào sua_re_*.
• Phân biệt nhanh: đổi/thêm một loại thông tin → khái niệm (có thể vào sổ). Đổi/thêm một luồng, một task, một con số cụ thể → dữ liệu (không vào sổ).
  • Vd: thêm field "Người phê duyệt pháp lý" → khái niệm mới. Thêm task "Gửi thông báo" vào WF-0001 → dữ liệu luồng.

---

4. Nếu UI có luồng nghiệp vụ

Mô tả theo cấu trúc: flow → step → task → (actor, input, output, condition, minutes). Cấu trúc này giúp hệ hiểu nghiệp vụ, nhưng không có nghĩa từng task đi vào sổ khái niệm.

---

5. Xong thì đi đâu

• UI mới → chạy SR-LAP (lập sổ khái niệm).
• UI đã có sổ, vừa sửa → chạy SR-SUA (sửa sổ khái niệm).

---

Câu nhớ: Thiết kế đúng trước — scan biết khái niệm sau — không đếm dữ liệu thành khái niệm — không nhét luồng vào sổ.