# Ghi chú UI reviewer cho preview sinh tài liệu

Tài liệu này mô tả màn hình reviewer dùng để kiểm tra **preview dữ liệu trước khi render DOCX** cho pilot `bien_ban_ban_giao_mat_bang`.

## 1. Mục tiêu

UI preview phục vụ 3 việc chính:

- cho reviewer nhìn nhanh tài liệu đã **đủ dữ liệu để render** hay chưa
- chỉ ra field nào:
  - đã xác minh từ nguồn
  - chỉ là gợi ý
  - còn thiếu và cần nhập tay
- ghi nhận quyết định review trước khi chuyển sang bước render hoặc bổ sung dữ liệu

Nguyên tắc thống nhất với kế hoạch triển khai:

- backend trả sẵn:
  - `payload`
  - `field_statuses`
  - `readiness`
  - `active_template`
  - `review_workflow`
- frontend **chỉ hiển thị**, không tự tính lại readiness, confidence hay logic mapping

## 2. Đầu vào UI

Nguồn dữ liệu chính:

- internal preview API cho `bien_ban_ban_giao_mat_bang`

Shape dữ liệu UI nên đọc trực tiếp từ response:

| Nhóm | Mục đích |
| --- | --- |
| `payload` | xem dữ liệu chuẩn hóa trước render |
| `field_statuses` | xem trạng thái từng field |
| `readiness` | xem mức sẵn sàng tổng thể |
| `active_template` | biết template và version đang áp dụng |
| `review_workflow` | xem trạng thái review hiện tại |
| `source_project_code` | truy vết hồ sơ/project đang được xem |
| `source_note` | phân biệt dữ liệu thật hay sample |

## 3. Màn hình nên có gì

Nên giữ UI đơn giản, dễ quét, gồm 5 khu vực.

### 3.1. Khối bộ lọc và tải preview

Cho phép:

- nhập hoặc chọn `project_code`
- chạy preview với dữ liệu thật
- chạy preview với sample data khi cần demo
- refresh lại preview sau khi dữ liệu nguồn đổi

Thông tin nên hiển thị gần ô nhập:

- `source_project_code`
- `source_note`
- thời điểm tải preview gần nhất

### 3.2. Khối tổng quan

Hiển thị các thông tin quan trọng nhất của preview:

- loại tài liệu
- tên dự án / hồ sơ
- mã hồ sơ nếu có
- template đang active
- version template
- readiness status
- readiness summary

Có thể dùng card ngắn:

| Trường | Gợi ý hiển thị |
| --- | --- |
| Document type | `bien_ban_ban_giao_mat_bang` |
| Template | tên template + version |
| Readiness | badge màu |
| Summary | mô tả ngắn về mức sẵn sàng |

### 3.3. Khối field status

Đây là phần quan trọng nhất với reviewer.

Mỗi dòng nên có:

- `label`
- `field_name`
- `value`
- `status`
- `confidence`
- `is_required`
- `is_resolved`
- `notes`

Bộ lọc nhanh nên có:

- chỉ field bắt buộc
- chỉ field chưa resolved
- chỉ field cần nhập tay
- chỉ field là gợi ý
- tìm theo tên field hoặc label

### 3.4. Khối payload chuẩn hóa

Mục đích:

- giúp reviewer và dev đối chiếu dữ liệu nguồn với dữ liệu sẽ đưa vào render
- hỗ trợ debug mapping nếu field status chưa đủ rõ

Cách hiển thị phù hợp:

- JSON pretty
- hoặc chia theo nhóm ngắn:
  - project / dossier
  - bên bàn giao
  - bên nhận
  - người ký
  - context bổ sung

Không cần biến khối này thành form nhập liệu ở giai đoạn đầu.

### 3.5. Khối review workflow và audit

Hiển thị snapshot review hiện tại:

- `review_workflow.status`
- reviewer hiện tại hoặc người xử lý gần nhất
- `reviewed_at`
- `review_notes`
- blocker hoặc warning nếu có

Nếu chưa có review thật, vẫn nên render trạng thái mặc định để UI ổn định.

## 4. Field status nên hiển thị như thế nào

### 4.1. Ý nghĩa các trạng thái chính

Nên bám sát phân loại đang dùng trong lớp preview và readiness.

| Field status | Ý nghĩa với reviewer | Màu gợi ý |
| --- | --- | --- |
| `verified_from_source` | dữ liệu đã xác minh từ nguồn | xanh lá |
| `suggested_from_similar_template` | dữ liệu chỉ là gợi ý, cần xem lại | vàng |
| `manual_input_required` | thiếu dữ liệu, cần nhập tay hoặc bổ sung nguồn | đỏ |

Nếu có thêm trạng thái mở rộng sau này, UI vẫn nên ưu tiên 3 mức trên để reviewer hiểu nhanh.

### 4.2. Confidence

`confidence` nên được xem như tín hiệu phụ, không thay thế field status.

Cách dùng trong UI:

- hiển thị dạng badge hoặc phần trăm
- cho phép sort giảm dần / tăng dần
- nổi bật các field có confidence thấp

Nguyên tắc đọc:

- confidence cao + `verified_from_source`: thường không cần can thiệp
- confidence trung bình hoặc thấp + `suggested_from_similar_template`: reviewer cần kiểm tra
- `manual_input_required`: confidence không quan trọng bằng việc field đang thiếu

### 4.3. Gợi ý ưu tiên thị giác

Nên ưu tiên reviewer thấy ngay:

1. field bắt buộc nhưng chưa resolved
2. field `manual_input_required`
3. field có confidence thấp
4. field chỉ là gợi ý từ template tương tự

## 5. Hành động reviewer

UI giai đoạn đầu chỉ cần hỗ trợ các hành động mức nhẹ, chưa cần workflow phức tạp.

### 5.1. Hành động tối thiểu

- xem preview
- lọc các field có vấn đề
- mở payload để đối chiếu
- ghi nhận ghi chú review
- đánh dấu kết quả review

### 5.2. Kết quả review nên có

Tối thiểu nên hỗ trợ các quyết định sau:

| Quyết định | Ý nghĩa |
| --- | --- |
| `approved_for_render` | đủ điều kiện chuyển bước render |
| `needs_revision` | cần bổ sung hoặc sửa dữ liệu |
| `blocked` | chưa thể xử lý tiếp do thiếu nguồn hoặc lỗi nghiêm trọng |

Nếu giai đoạn đầu chưa có API ghi review, UI vẫn có thể hiển thị trước các trạng thái dự kiến này để thống nhất ngôn ngữ.

## 6. Trạng thái review

Trạng thái review nên đọc từ `review_workflow` và được trình bày ngắn gọn.

| Review status | Cách hiểu |
| --- | --- |
| `pending_review` | đang chờ reviewer kiểm tra |
| `in_review` | đang được kiểm tra |
| `approved_for_render` | đã duyệt để render |
| `needs_revision` | cần bổ sung/chỉnh dữ liệu |
| `blocked` | có blocker, chưa thể tiếp tục |

Quan hệ với readiness:

- `ready_for_render` không có nghĩa là đã được reviewer duyệt
- `review_required` thường dẫn tới `pending_review` hoặc `in_review`
- quyết định cuối để render nên dựa trên cả:
  - readiness
  - review status

## 7. Log và audit

Reviewer UI cần đủ thông tin để truy vết, dù chưa cần hệ thống audit đầy đủ.

### 7.1. Thông tin nên lưu hoặc hiển thị

- `project_code`
- loại tài liệu
- template name + version
- thời điểm preview được tạo
- người review
- thời điểm review
- quyết định review
- ghi chú review
- danh sách field còn blocker/warning tại thời điểm review

### 7.2. Cách hiển thị trong UI

Có thể dùng một bảng ngắn hoặc timeline nhỏ:

| Mốc | Nội dung |
| --- | --- |
| Preview created | nguồn dữ liệu nào, template nào |
| Review started | ai bắt đầu review |
| Review updated | ghi chú mới nhất |
| Review decision | approved / revision / blocked |

Mục tiêu là:

- dễ truy vết tại sao một bản preview được duyệt hay bị trả lại
- hỗ trợ debug khi preview khác với tài liệu render sau này

## 8. Mapping màu khuyến nghị

Để đồng bộ với dashboard và tài liệu nghiên cứu hiện có, có thể dùng mapping sau.

### 8.1. Field status

- xanh lá:
  - `verified_from_source`
- vàng:
  - `suggested_from_similar_template`
- đỏ:
  - `manual_input_required`

### 8.2. Readiness

- xanh lá:
  - `ready_for_render`
- vàng:
  - `review_required`
- xanh dương hoặc vàng nhẹ:
  - `draft_ready`
- đỏ:
  - `not_ready`

### 8.3. Review status

- xám:
  - `pending_review`
- xanh dương:
  - `in_review`
- xanh lá:
  - `approved_for_render`
- vàng:
  - `needs_revision`
- đỏ:
  - `blocked`

## 9. Nguyên tắc triển khai

Để giữ ranh giới rõ giữa dữ liệu và giao diện:

- backend chịu trách nhiệm:
  - assemble payload
  - tính field status
  - tính readiness
  - xác định review workflow snapshot nếu có
- frontend chịu trách nhiệm:
  - hiển thị
  - lọc
  - sắp xếp
  - hỗ trợ reviewer đọc và quyết định nhanh

Không nên để frontend:

- tự suy luận placeholder
- tự tính readiness
- tự gán lại confidence
- sửa trực tiếp payload chuẩn hóa nếu chưa có workflow chỉnh dữ liệu riêng

## 10. Phạm vi giai đoạn đầu

Nên ưu tiên bản UI nhỏ nhưng dùng được ngay:

- 1 màn hình preview nội bộ
- 1 khối summary
- 1 bảng field status có filter
- 1 khối payload JSON
- 1 khối review + audit ngắn

Chưa cần trong đợt đầu:

- editor chỉnh field trực tiếp trên preview
- so sánh nhiều version preview
- workflow phân quyền phức tạp
- lịch sử audit đầy đủ nhiều bước

## 11. Kết quả mong muốn

Khi hoàn tất, reviewer có thể trả lời nhanh 4 câu hỏi:

1. hồ sơ này đã đủ để render chưa
2. field nào còn thiếu hoặc chỉ là gợi ý
3. reviewer đã duyệt hay yêu cầu bổ sung
4. quyết định đó được ghi nhận và truy vết ra sao

Đây là nền tảng để nối sang bước tiếp theo:

- review workflow rõ ràng hơn
- draft DOCX generation
- audit trail đầy đủ cho quá trình phát hành tài liệu