# Module `chip` — Xe chip ôn luyện

> 07/7/2026 · Giai đoạn: **v2** · WS đào tạo · Bản HTML: [chip.html](chip.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: v2 — cần firmware/thiết bị đi kèm (xem tài liệu thiết bị phần cứng).

## 1. Vai trò
Chấm điểm **ôn luyện sa hình** bằng xe gắn chip (GNSS-RTK + cảm biến): cấu hình **12 bài sa hình**, nhận kết quả phiên ôn, đọc lỗi từng bài. **Không cần thẩm định** — bán được ngay; dữ liệu tích lũy là hồ sơ chứng minh khi đi thẩm định hệ sát hạch sau này.

## 2. Feature / BO / Action

| Feature | BO chính | Action |
|---|---|---|
| `device` | Thiết bị chip trên xe + trạm RTK | view·create·edit |
| `lesson` | 12 bài sa hình (config điểm trừ/vị trí) | view·configure |
| `session` | Phiên ôn + kết quả/lỗi từng bài | view·import·export·**score** |

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

| BO | Trường chính |
|---|---|
| **Thiết bị** | Seri · xe gắn · phiên bản firmware · trạm base RTK của sân |
| **Bài sa hình** | 12 bài theo chuẩn thi · bản đồ số vị trí/vạch · lỗi + điểm trừ (config — đổi bài thi chỉ cập nhật bản đồ) |
| **Phiên ôn** | Học viên (quẹt thẻ/khuôn mặt) × xe × thời gian · điểm tổng · lỗi từng bài · quỹ đạo |

## 4. Quy tắc nghiệp vụ
1. Kết quả từng phiên **đẩy về app học viên** (portal): bài yếu, lỗi lặp lại
2. Dữ liệu ôn luyện → dự báo tỷ lệ đậu, tư vấn mua thêm phiên (bán thêm)
3. Chuẩn chấm bám quy định thi nhưng **tự do công nghệ** (không thẩm định)
4. Lưu quỹ đạo đầy đủ — bộ dữ liệu chứng minh độ chính xác khi trình thẩm định hệ sát hạch (v3)

## 5. Liên kết chéo
- **portal** — kết quả về app
- **booking** — phiên thuê xe chip
- **student** — học viên ôn
- **bi** — dự báo tỷ lệ đậu

## 6. Câu hỏi mở
- Chuẩn 12 bài + điểm trừ theo TT 108/2026-BCA (cập nhật nhất)?
- Sân Vĩnh An đủ thoáng cho RTK chưa (khảo sát che khuất)?

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

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

```json
[
  {
    "group": "main",
    "feature": "device",
    "label": "Thiết bị chip & RTK",
    "actions": [
      "view",
      "create",
      "edit"
    ]
  },
  {
    "group": "main",
    "feature": "lesson",
    "label": "12 bài sa hình",
    "actions": [
      "view",
      "configure"
    ]
  },
  {
    "group": "main",
    "feature": "session",
    "label": "Phiên ôn",
    "actions": [
      "view",
      "import",
      "export",
      "score"
    ]
  }
]
```

> ⚠️ Action đặc thù (`score`) 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` | `KY_THUAT` | `GIAO_VU` | `GIAO_VIEN` | `HOC_VIEN` |
|---|:--:|:--:|:--:|:--:|:--:|:--:|
| `device` | R | R | W | — | — | — |
| `lesson` | R | R | W | — | — | — |
| `session` | R | R | — | W | 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 đủ: `chip.main.<feature>.<action>`.
> Đặc thù: session +import (GIAO_VU) · score = hệ thống chấm tự động

### 7.3 Quyền mức record (row-level)

**(a) Manifest — bổ sung `fields` + `scopeVars` vào các feature bị scope** *(mở rộng schema theo [plan data-scope P1](../giai-doan-1-mvp/plan-data-scope-2026-07-06.md) — manifest chỉ khai "cái gì scope được", KHÔNG chứa rule)*:

```json
[
  {
    "group": "main",
    "feature": "session",
    "fields": [
      "ma_dk",
      "ma_gv"
    ],
    "scopeVars": [
      "current_ma_dk_list",
      "current_assigned_ma_dk_list"
    ]
  }
]
```

**(b) Điều kiện record theo vai trò:**

| Vai trò | Feature (action) | Điều kiện record |
|---|---|---|
| `GIAO_VIEN` | session (view) | ma_dk ∈ ctx.current_assigned_ma_dk_list (học viên phụ trách) |
| `HOC_VIEN` | session (view) | ma_dk ∈ ctx.current_ma_dk_list |

**(c) Seed `rt_role.grants` (kind `rule` — nhiều rule cùng resource+action = OR):**

```json
[
  {
    "kind": "rule",
    "module": "chip",
    "feature": "session",
    "actions": [
      "view"
    ],
    "predicate": {
      "op": "in",
      "field": "ma_dk",
      "values": [
        {
          "ctx": "current_assigned_ma_dk_list"
        }
      ]
    }
  },
  {
    "kind": "rule",
    "module": "chip",
    "feature": "session",
    "actions": [
      "view"
    ],
    "predicate": {
      "op": "in",
      "field": "ma_dk",
      "values": [
        {
          "ctx": "current_ma_dk_list"
        }
      ]
    }
  }
]
```

> Biến ngữ cảnh: `current_user_id` — engine có sẵn · `current_giao_vien_id`/`current_ma_gv` — module teacher tra từ user đăng nhập (ctxVars, plan P3) · `current_nguoi_lxid`/`current_ma_dk_list` — module student tra (1 người nhiều lượt đăng ký) · `current_assigned_*` — danh sách phụ trách/được phân công.