# Built-in `workflow` — Quy trình, phê duyệt & connector (built-in)

> 08/7/2026 · **Built-in module — WS runtime** (sẵn lúc boot, không cài qua .ogapp) · Bản HTML: [workflow-builtin.html](workflow-builtin.html) · [Review tổng core](core-review-2026-07-07.md) · [Quan hệ module](../quan-he-module-2026-07-07.md)
>
> 🎯 **Hạ tầng dùng chung — bật dần theo nhu cầu.** Hiện trạng: engine generic chưa module nào dùng. Đích = 2 vai trò rõ: luồng PHÊ DUYỆT dùng chung + két CONNECTOR/credential.

## 1. Vai trò
Hai việc dùng chung: **luồng phê duyệt** (miễn giảm, báo cáo, booking — thay vì mỗi module tự viết) và **connector + credential** — một cửa cho mọi tích hợp ngoài (vendor DAT, HĐĐT, cổng thanh toán, Zalo OA). State machine hồ sơ vẫn ở student.

## 2. Feature / BO / Action

| Feature | BO chính | Action |
|---|---|---|
| `definition` | Định nghĩa quy trình / luồng duyệt | view·configure |
| `ticket` | Phiếu việc chạy theo quy trình | view·create·assign·**approve** |
| `connector` | Kết nối hệ ngoài (adapter) | view·configure·**test** |
| `credential` | Két thông tin xác thực (mã hóa) | view·configure·**rotate** |

## 3. Manifest — khai báo permissions

Permission key: `workflow.<group>.<feature>.<action>`; `fields`/`scopeVars` theo plan data-scope (manifest v1.1).

```json
{
  "key": "workflow",
  "name": "Quy trình & Connector",
  "version": "1.1.0 (đích)",
  "permissions": [
    {
      "group": "workflow",
      "feature": "definition",
      "label": "Quy trình / Luồng duyệt",
      "actions": [
        "view",
        "configure"
      ]
    },
    {
      "group": "workflow",
      "feature": "ticket",
      "label": "Phiếu / Ticket",
      "actions": [
        "view",
        "create",
        "assign",
        "approve"
      ]
    },
    {
      "group": "integration",
      "feature": "connector",
      "label": "Kết nối (Connector)",
      "actions": [
        "view",
        "configure",
        "test"
      ]
    },
    {
      "group": "integration",
      "feature": "credential",
      "label": "Thông tin xác thực",
      "actions": [
        "view",
        "configure",
        "rotate"
      ]
    }
  ]
}
```

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

### Luồng duyệt
| Trường | Kiểu | Bắt buộc | Ghi chú |
|---|---|---|---|
| Tên luồng | text | ✔ |  |
| Các bước | jsonb | ✔ | Vai trò duyệt từng bước |
| Điều kiện | jsonb | — | vd số tiền > X → cần GĐ duyệt |
| SLA nhắc | number (giờ) | — | Quá hạn → notify |

### Ticket
| Trường | Kiểu | Bắt buộc | Ghi chú |
|---|---|---|---|
| Đối tượng nguồn | module + BO id | ✔ | vd tuition.discount #123 |
| Luồng / bước hiện tại | ref·text | ✔ |  |
| Người xử lý | ref | ✔ |  |
| Lịch sử qua bước | append-only | ✔ | Bằng chứng phê duyệt — không sửa |

### Connector
| Trường | Kiểu | Bắt buộc | Ghi chú |
|---|---|---|---|
| Mã / loại | text·enum | ✔ | dat-vendor / hddt / payment / zalo-oa |
| Endpoint / cấu hình | text·jsonb | ✔ |  |
| Trạng thái / lần chạy cuối | enum·datetime | — | Lỗi liên tục → cảnh báo QTHT |

### Credential
| Trường | Kiểu | Bắt buộc | Ghi chú |
|---|---|---|---|
| Tên | text | ✔ |  |
| Connector | ref | ✔ |  |
| Giá trị | text mã hóa at-rest | ✔ | Module chỉ đọc qua connector API — không thấy giá trị thô |
| Hạn / người quản lý | date·ref | — | Xoay khóa không sửa module |

## 5. Ma trận quyền — vai trò × feature

| Feature | QTHT | GIAM_DOC | QL_DAO_TAO | TUYEN_SINH | GIAO_VU | GIAO_VIEN | KE_TOAN | NHAN_SU |
|---|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|
| `definition` | W | R | — | — | — | — | — | — |
| `ticket` | R | R | A* | — | W* | — | A* | A* |
| `connector` | W | R | — | — | — | — | — | — |
| `credential` | W | — | — | — | — | — | — | — |

¹ chỉ bản ghi mình phụ trách · ² chỉ của chính mình · **W·A** = tạo/sửa + duyệt
* quyền duyệt ticket theo vai trò khai trong từng bước của luồng — ma trận chỉ là mặc định.

## 6. Quy tắc nghiệp vụ
1. Module **opt-in** luồng duyệt: đăng ký (BO, luồng) — vd tuition.discount, report.so-xd; không ép state machine hồ sơ vào đây
2. Credential chỉ đọc qua connector API; `rotate` không đụng module
3. Lịch sử ticket bất biến
4. Connector áp dụng pattern P4 (outbox retry) khi gọi ra ngoài

## 7. Liên kết chéo
- **dat** — connector vendor DAT (GĐ1)
- **finance** — connector HĐĐT
- **payment (v2)** — cổng thanh toán
- **notify** — credential Zalo OA
- **tuition/report** — luồng duyệt

## 8. Câu hỏi mở
- Interface chuẩn adapter — định nghĩa khi viết connector DAT đầu tiên
- Credential mã hóa bằng gì (libsodium/KMS)?