# Module `finance` — Kế toán & hóa đơn điện tử

> 07/7/2026 · Giai đoạn: **v1.5** · WS đào tạo · Bản HTML: [finance.html](finance.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: Chưa có trong code — scaffold ở v1.5.

## 1. Vai trò
Xuất **hóa đơn điện tử** (tích hợp nhà cung cấp HĐĐT), sổ thu–chi, doanh thu theo khóa/hạng và **đối soát doanh thu** học phí ↔ hóa đơn. Phần gắn hồ sơ học viên vẫn ở `tuition`.

## 2. Feature / BO / Action

| Feature | BO chính | Action |
|---|---|---|
| `invoice` | Hóa đơn điện tử | view·export·**issue**·**void** |
| `ledger` | Sổ thu–chi, doanh thu theo khóa/hạng | view·report·export |
| `reconcile` | Đối soát doanh thu | view·**reconcile** |

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

| BO | Trường chính |
|---|---|
| **Hóa đơn** | Số HĐ (từ nhà cung cấp HĐĐT) · phiếu thu gốc (ref tuition) · người mua · tiền · thuế · trạng thái (phát hành/hủy/thay thế) · file XML/PDF |
| **Sổ thu–chi** | Khoản thu/chi · nguồn (học phí/thuê xe/khác) · khóa/hạng · kỳ |
| **Đối soát** | Kỳ × Σ phiếu thu (tuition) ↔ Σ hóa đơn đã phát hành ↔ giao dịch cổng (payment v2) — chênh lệch + lý do |

## 4. Quy tắc nghiệp vụ
1. Hóa đơn phát hành từ **phiếu thu tuition**; số HĐ ghi ngược về công nợ đợt
2. Hủy/thay thế hóa đơn theo đúng quy định HĐĐT — giữ vết bản gốc
3. Khóa sổ kỳ: sau khóa sổ không sửa chứng từ trong kỳ (chỉ bút toán điều chỉnh)
4. Tích hợp nhà cung cấp HĐĐT qua adapter (đổi nhà cung cấp không sửa lõi)

## 5. Liên kết chéo
- **tuition** — phiếu thu → hóa đơn
- **payment (v2)** — giao dịch cổng vào đối soát
- **bi (v3)** — dữ liệu doanh thu–chi phí

## 6. Câu hỏi mở
- Vĩnh An dùng nhà cung cấp HĐĐT nào (Viettel/VNPT/Misa…)?
- Có cần sổ kế toán đầy đủ hay chỉ doanh thu (kế toán thuế làm ngoà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": "invoice",
    "label": "Hóa đơn điện tử",
    "actions": [
      "view",
      "export",
      "issue",
      "void"
    ]
  },
  {
    "group": "main",
    "feature": "ledger",
    "label": "Sổ thu–chi",
    "actions": [
      "view",
      "report",
      "export"
    ]
  },
  {
    "group": "main",
    "feature": "reconcile",
    "label": "Đối soát doanh thu",
    "actions": [
      "view",
      "reconcile"
    ]
  }
]
```

> ⚠️ Action đặc thù (`issue`, `reconcile`, `void`) 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` |
|---|:--:|:--:|:--:|
| `invoice` | R | R | W |
| `ledger` | R | R | R |
| `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 đủ: `finance.main.<feature>.<action>`.
> Đặc thù: invoice +issue,void (hủy HĐĐT theo quy định) · reconcile +reconcile (KE_TOAN)