# Module `report` — Báo cáo tuân thủ Sở XD

> 07/7/2026 · Giai đoạn: **MVP · Painkiller** · Bản HTML: [report.html](report.html) · Sơ đồ tổng thể: [../so-do-ws-module-feature-2026-07-06.md](../so-do-ws-module-feature-2026-07-06.md)
> Trạng thái code: **chưa có — scaffold mới**. Schema chi tiết: [§2.7](../giai-doan-1-mvp/schema-du-lieu-2026-07-06.md)
>
> ⚠ **Cập nhật 13/7/2026:** chiều **trao đổi file sát hạch với PC08** (BC1/BC2 đi — KQBC2/SBD/SAT_HACH về,
> đối soát, vòng khứ hồi) **tách sang module [`sh-exchange`](sh-exchange-2026-07-13.md)** chạy trên **WS hub riêng**
> (làm trước, painkiller). `report` giữ phần **sinh báo cáo theo mẫu** phía WS trung tâm; P3 sẽ sinh BC1/BC2
> và push sang hub. Lưu ý thẩm quyền đã đính chính: **phần HỌC → Sở GT/XD, phần SÁT HẠCH → PC08**
> (xem [hiện trạng báo cáo](../giai-doan-1-mvp/hien-trang-bao-cao-vinhan-2026-07-11.md)).

## 1. Vai trò
**Lý do trung tâm trả tiền**: tự động sinh báo cáo theo mẫu gửi Sở Xây dựng (kế hoạch đào tạo, danh sách học viên, báo cáo tốt nghiệp), đọc chéo dữ liệu student/course/dat. Mẫu là **dữ liệu cấu hình** — thông tư đổi mẫu thì cập nhật config, không sửa code.

## 2. Feature / BO / Action

| Feature | BO chính | Action |
|---|---|---|
| `template` | Mẫu báo cáo (version theo thông tư) | view·configure |
| `so-xd` | Báo cáo đã lập | view·**generate**·edit·**approve**·download |
| `registry` | Sổ theo dõi đã nộp (immutable) | view·export |

## 3. Dữ liệu chính

### Mẫu báo cáo (`template`) — *bảng `report_mau`*
| Trường | Kiểu | Ghi chú |
|---|---|---|
| Mã / tên mẫu | text | kế hoạch đào tạo · DS học viên · báo cáo tốt nghiệp · đăng ký sát hạch… |
| Cấu hình | jsonb | cột, nguồn dữ liệu (module/feature), định dạng xuất (Excel/PDF) |
| Hiệu lực từ | date | **version khi thông tư đổi mẫu** — mẫu cũ giữ nguyên cho báo cáo cũ |
| Trạng thái | bool | |

### Báo cáo đã lập (`so-xd`) — *bảng `report_da_lap`*
| Trường | Kiểu | Ghi chú |
|---|---|---|
| Mẫu | ref | |
| Khóa liên quan / kỳ báo cáo | text | |
| File đã sinh | file | **giữ nguyên bản đã nộp** |
| Trạng thái | enum | nháp → chờ duyệt → đã duyệt → **đã gửi** |
| Người lập / người duyệt | ref | duyệt = Giám đốc (vai trò GIAM_DOC) |
| Ngày lập / ngày gửi | datetime | |

### Sổ đã nộp (`registry`)
View tổng hợp các bản `da_gui` — immutable, phục vụ thanh tra.

## 4. Quy tắc nghiệp vụ
1. **File đã nộp không sửa/ghi đè** — sai thì lập bản mới; bản cũ giữ vết.
2. Sinh báo cáo đọc dữ liệu **tại thời điểm lập** (snapshot) — số liệu trong file không đổi khi dữ liệu nguồn đổi sau đó.
3. Quy trình duyệt: giáo vụ lập (`generate`) → Giám đốc duyệt (`approve`) → gửi (bước workflow, ghi ngày + người).
4. Báo cáo tốt nghiệp lấy **kết quả đối soát DAT** làm căn cứ — hồ sơ thiếu km/giờ không được vào danh sách.
5. Sau khi kế hoạch đào tạo `da_gui` → callback course đánh dấu khóa "đã báo Sở" → hồ sơ sang `da_bao_so`.

## 5. Liên kết chéo module
| Module | Dữ liệu đọc | Ghi chú |
|---|---|---|
| student | DS học viên, trạng thái hồ sơ | |
| course | khóa, kế hoạch, phân công | callback trạng thái "đã báo Sở" |
| dat | kết quả đối soát km/giờ | căn cứ tốt nghiệp |
| teacher / vehicle | DS GV/xe đăng ký | phần phụ lục báo cáo |
| catalog | mẫu, hạng | |

## 6. Câu hỏi mở
- Danh sách mẫu báo cáo Vĩnh An đang nộp (tên, tần suất, nộp giấy hay cổng điện tử?) → seed `report_mau`.
- Sở XD địa phương có cổng nhận điện tử không → tương lai thêm action `transmit`.

## 7. Ma trận phân quyền (→ manifest & seed role)

### 7.1 Khai báo `permissions[]` trong `manifest.json`

```json
[
  {
    "group": "main",
    "feature": "template",
    "label": "Mẫu báo cáo",
    "actions": [
      "view",
      "configure"
    ]
  },
  {
    "group": "main",
    "feature": "so-xd",
    "label": "Báo cáo Sở XD",
    "actions": [
      "view",
      "generate",
      "edit",
      "approve",
      "download"
    ]
  },
  {
    "group": "main",
    "feature": "registry",
    "label": "Sổ đã nộp",
    "actions": [
      "view",
      "export"
    ]
  }
]
```

> ⚠️ Action đặc thù (`generate`) cần bổ sung vào validator manifest — xem [plan data-scope P1](../giai-doan-1-mvp/plan-data-scope-2026-07-06.md).

### 7.2 Ma trận vai trò × feature (seed `rt_role`)

| Feature | `QTHT` | `GIAM_DOC` | `QL_DAO_TAO` | `GIAO_VU` |
|---|:--:|:--:|:--:|:--:|
| `template` | W | R | R | — |
| `so-xd` | R | R·A | W | W |
| `registry` | R | R | R | R |

> **R** xem · **W** tạo/sửa · **A** duyệt · **—** không có quyền · ¹ dữ liệu **phân công** · ² **của chính mình** · ³ **theo trạng thái** hồ sơ. Vai trò không liệt kê = không có quyền. Permission key đầy đủ: `report.main.<feature>.<action>`.
> Đặc thù: so-xd +generate (QL_DAO_TAO, GIAO_VU) · +download (QL_DAO_TAO) · gửi Sở = bước workflow sau approve