# Module `sh-gateway` — Truyền dữ liệu Cục CSGT

> 07/7/2026 · Giai đoạn: **WS sát hạch · v3** · WS sát hạch · Bản HTML: [sh-gateway.html](sh-gateway.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: v3 — thành phần tích hợp bắt buộc; mọi module sát hạch đi qua đây.

## 1. Vai trò
Cổng **truyền dữ liệu về hệ thống Cục CSGT**: kết quả thi, hình ảnh, dữ liệu giám sát — theo **API RESTful JSON của Phụ lục QCVN 40:2024** (HTTPS + TLS, UTF-8, UNIX time UTC+7).

## 2. Feature / BO / Action

| Feature | BO chính | Action |
|---|---|---|
| `packet` | Gói tin truyền | view·export·**transmit**·**retry** |
| `log` | Nhật ký truyền / gửi bù | view·report |

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

| BO | Trường chính |
|---|---|
| **Gói tin** | Loại (kết quả LT / sa hình / đường trường / giám sát / hình ảnh) · payload chuẩn Phụ lục · trạng thái (chờ/đã gửi/lỗi) · số lần retry |
| **Nhật ký** | Thời điểm gửi · phản hồi đầu nhận · gửi bù khi mất sóng (tự động) |

## 4. Quy tắc nghiệp vụ
1. Chuẩn **API Phụ lục QCVN 40:2024**: HTTPS + TLS (TCCS 01:2020/CATTT), UTF-8, UNIX time UTC+7
2. Hàng đợi bền: mất kết nối không mất gói — tự gửi bù khi có sóng
3. Mọi module sát hạch **không tự truyền** — đi qua gateway để log một chỗ
4. Nhật ký truyền immutable — đối chứng khi tranh chấp dữ liệu

## 5. Liên kết chéo
- **sh-theory/yard/road/moto** — kết quả thi
- **sh-monitor** — dữ liệu giám sát
- **sh-schedule** — hồ sơ kỳ thi

## 6. Câu hỏi mở
- Xin spec API + môi trường test của Cục CSGT (đầu mối?)
- Theo dõi dự thảo QCVN thay thế do BCA soạn — có đổi chuẩn kết nối?

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

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

```json
[
  {
    "group": "main",
    "feature": "packet",
    "label": "Gói tin truyền CSGT",
    "actions": [
      "view",
      "export",
      "transmit",
      "retry"
    ]
  },
  {
    "group": "main",
    "feature": "log",
    "label": "Nhật ký truyền",
    "actions": [
      "view",
      "report"
    ]
  }
]
```

> ⚠️ Action đặc thù (`retry`, `transmit`) 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` | `SAT_HACH` |
|---|:--:|:--:|:--:|
| `packet` | W | R | R |
| `log` | 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 đủ: `sh-gateway.main.<feature>.<action>`.
> Đặc thù: packet +transmit,retry (QTHT)