# Module `booking` — Thuê xe chip & sân

> 07/7/2026 · Giai đoạn: **v2** · WS đào tạo · Bản HTML: [booking.html](booking.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 — scaffold cùng chip.

## 1. Vai trò
Vận hành **nguồn thu thuê xe chip ôn sa hình**: lịch sân/xe, đặt phiên qua app, **tính giờ tự động theo phiên chip**, thu phí và đối soát doanh thu từng xe/khung giờ.

## 2. Feature / BO / Action

| Feature | BO chính | Action |
|---|---|---|
| `calendar` | Lịch sân / xe theo khung giờ | view·configure |
| `rent` | Phiên thuê + bảng giá | view·create·report·**book**·**collect** |

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

| BO | Trường chính |
|---|---|
| **Lịch** | Xe chip × khung giờ × sân · trạng thái (trống/đã đặt/bảo trì) |
| **Phiên thuê** | Học viên · xe · khung giờ đặt ↔ **thời gian thực tế từ phiên chip** · đơn giá · thành tiền · trạng thái thu |
| **Bảng giá** | Theo khung giờ (cao điểm/thấp điểm) · theo gói (5/10 phiên) · hiệu lực |

## 4. Quy tắc nghiệp vụ
1. Giờ tính tiền = **giờ phiên chip thực tế**, không phải giờ đặt — đối soát tự động
2. Đặt qua app (portal) hoặc tại quầy; hủy trước X giờ theo chính sách
3. Doanh thu đối soát từng xe/khung giờ → finance
4. Gói nhiều phiên trừ dần, hết hạn theo cấu hình

## 5. Liên kết chéo
- **chip** — phiên thực tế để tính giờ
- **portal** — đặt qua app
- **tuition/finance** — thu phí, hóa đơn
- **bi** — hiệu suất khai thác sân

## 6. Câu hỏi mở
- Chính sách giá thuê hiện tại của Vĩnh An?
- Cho học viên trung tâm khác thuê không (khách vãng lai)?

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

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

```json
[
  {
    "group": "main",
    "feature": "calendar",
    "label": "Lịch sân/xe",
    "actions": [
      "view",
      "configure"
    ]
  },
  {
    "group": "main",
    "feature": "rent",
    "label": "Phiên thuê & bảng giá",
    "actions": [
      "view",
      "create",
      "report",
      "book",
      "collect"
    ]
  }
]
```

> ⚠️ Action đặc thù (`book`, `collect`) 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` | `GIAO_VU` | `KE_TOAN` | `HOC_VIEN` |
|---|:--:|:--:|:--:|:--:|:--:|
| `calendar` | R | R | W | — | R |
| `rent` | R | R | W | R | W² |

> **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 đủ: `booking.main.<feature>.<action>`.
> Đặc thù: rent +collect (KE_TOAN) · +book (GIAO_VU, HOC_VIEN)

### 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": "rent",
    "fields": [
      "ma_dk"
    ],
    "scopeVars": [
      "current_ma_dk_list"
    ]
  }
]
```

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

| Vai trò | Feature (action) | Điều kiện record |
|---|---|---|
| `HOC_VIEN` | rent (view, book) | ma_dk ∈ ctx.current_ma_dk_list (phiên thuê của mình) |

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

```json
[
  {
    "kind": "rule",
    "module": "booking",
    "feature": "rent",
    "actions": [
      "view",
      "book"
    ],
    "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.