# Module `payment` — Thanh toán online

> 07/7/2026 · Giai đoạn: **v2** · WS đào tạo · Bản HTML: [payment.html](payment.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 — adapter theo cổng (VNPay/MoMo/chuyển khoản QR…).

## 1. Vai trò
Cổng **thanh toán online** cho học phí đợt và phiên thuê xe chip — làm **sau khi có app học viên**. Giao dịch cổng đổ về phiếu thu tuition và đối soát cổng.

## 2. Feature / BO / Action

| Feature | BO chính | Action |
|---|---|---|
| `transaction` | Giao dịch cổng | view·export·**refund** |
| `gateway-reconcile` | Đối soát cổng | view·**reconcile** |

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

| BO | Trường chính |
|---|---|
| **Giao dịch** | Mã GD cổng · loại (học phí đợt / phiên thuê) · tham chiếu (công nợ đợt / phiên booking) · số tiền · trạng thái (khởi tạo/thành công/thất bại/hoàn) · thời gian |
| **Đối soát cổng** | Kỳ × Σ giao dịch thành công ↔ file đối soát cổng ↔ phiếu thu đã sinh — chênh lệch + xử lý |

## 4. Quy tắc nghiệp vụ
1. GD thành công → **tự sinh phiếu thu tuition** (hoặc gạch nợ phiên booking) — một nguồn sự thật về tiền vẫn là tuition/finance
2. Hoàn tiền (refund) đi kèm phiếu hoàn bên tuition
3. Adapter theo cổng — thêm cổng mới không sửa lõi
4. Webhook idempotent (GD trùng không ghi đôi)

## 5. Liên kết chéo
- **tuition** — sinh phiếu thu/gạch nợ
- **booking** — thu phiên thuê
- **portal** — thanh toán trong app
- **finance** — đối soát doanh thu

## 6. Câu hỏi mở
- Chọn cổng nào trước (phí, độ phủ)?
- Chính sách hoàn khi hủy phiên thuê?

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

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

```json
[
  {
    "group": "main",
    "feature": "transaction",
    "label": "Giao dịch cổng",
    "actions": [
      "view",
      "export",
      "refund"
    ]
  },
  {
    "group": "main",
    "feature": "gateway-reconcile",
    "label": "Đối soát cổng",
    "actions": [
      "view",
      "reconcile"
    ]
  }
]
```

> ⚠️ Action đặc thù (`reconcile`, `refund`) 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` | `KE_TOAN` |
|---|:--:|:--:|:--:|
| `transaction` | R | R | W |
| `gateway-reconcile` | R | 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 đủ: `payment.main.<feature>.<action>`.
> Đặc thù: +refund, +reconcile (KE_TOAN)