# Built-in `crm` — Tuyển sinh trên CRM (built-in — thay crm v1.5)

> 08/7/2026 · **Built-in module — WS runtime** (sẵn lúc boot, không cài qua .ogapp) · Bản HTML: [crm-builtin.html](crm-builtin.html) · [Review tổng core](core-review-2026-07-07.md) · [Quan hệ module](../quan-he-module-2026-07-07.md)
>
> 🎯 **Thay module kế hoạch `crm` v1.5.** Hiện trạng: phễu lead/opportunity/customer chuẩn nhưng thiếu convert→hồ sơ và hoa hồng CTV. Đích = crm built-in + 2 feature đặc thù, KHÔNG scaffold mới.

## 1. Vai trò
Phễu **tuyển sinh** chạy trên CRM built-in: lead từ Zalo/FB/web, phân bổ tư vấn viên, **convert lead → hồ sơ học viên** và **hoa hồng CTV** theo mốc thu tiền thật.

## 2. Feature / BO / Action

| Feature | BO chính | Action |
|---|---|---|
| `lead` | Lead / tiềm năng | view·create·edit·assign |
| `activity` | Hoạt động tương tác (gọi, hẹn, nhắn) | view·create |
| `convert` | Chuyển lead → hồ sơ ★đặc thù | view·**convert** |
| `commission` | Hoa hồng CTV ★đặc thù | view·export·**approve** |
| `campaign` | Nguồn / chiến dịch + báo cáo | view·create·edit·report |

## 3. Manifest — khai báo permissions

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

```json
{
  "key": "crm",
  "name": "Tuyển sinh (CRM)",
  "version": "2.0.0 (đích — thay crm v1.5)",
  "permissions": [
    {
      "group": "sales",
      "feature": "lead",
      "label": "Lead / Tiềm năng",
      "actions": [
        "view",
        "create",
        "edit",
        "assign"
      ],
      "fields": [
        "tu_van_vien_id",
        "trang_thai"
      ],
      "scopeVars": [
        "current_employee_id"
      ]
    },
    {
      "group": "sales",
      "feature": "activity",
      "label": "Hoạt động",
      "actions": [
        "view",
        "create"
      ]
    },
    {
      "group": "sales",
      "feature": "convert",
      "label": "Chuyển lead → hồ sơ",
      "actions": [
        "view",
        "convert"
      ]
    },
    {
      "group": "sales",
      "feature": "commission",
      "label": "Hoa hồng CTV",
      "actions": [
        "view",
        "approve",
        "export"
      ],
      "scopeVars": [
        "current_employee_id"
      ]
    },
    {
      "group": "analytics",
      "feature": "campaign",
      "label": "Chiến dịch & báo cáo",
      "actions": [
        "view",
        "create",
        "edit",
        "report"
      ]
    }
  ]
}
```

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

### Lead
| Trường | Kiểu | Bắt buộc | Ghi chú |
|---|---|---|---|
| Họ tên | text | ✔ |  |
| SĐT / Zalo | text | ✔ | Chống trùng; trùng học viên cũ → gợi ý nâng hạng |
| Nguồn / chiến dịch | ref | — | Đo hiệu quả kênh |
| Hạng quan tâm | ref catalog | — |  |
| Tư vấn viên | ref hrm | ✔ | Data scope: chỉ thấy lead mình phụ trách |
| Trạng thái | enum | ✔ | mới → đang tư vấn → hẹn nộp → **đã ghi danh** / mất (kèm lý do) |

### Convert ★
| Trường | Kiểu | Bắt buộc | Ghi chú |
|---|---|---|---|
| Lead | ref | ✔ |  |
| Hồ sơ sinh ra | ma_dk (student) | ✔ | Liên kết 2 chiều lead ↔ hồ sơ — đo nguồn ra học viên thật |
| Người / thời điểm convert | ref·datetime | ✔ | Một chiều — không sửa ngược |

### Hoa hồng CTV ★
| Trường | Kiểu | Bắt buộc | Ghi chú |
|---|---|---|---|
| Cộng tác viên | ref hrm (CTV) | ✔ | Chức danh CTV — ngoài biên chế |
| Hồ sơ | ma_dk | ✔ |  |
| Công thức / mức | money hoặc % | ✔ |  |
| Mốc ghi nhận | enum trạng thái hồ sơ | ✔ | Mặc định da_thu_dot1 — chống hoa hồng ảo |
| Kỳ chi trả / trạng thái duyệt | text·enum | ✔ |  |

### Chiến dịch
| Trường | Kiểu | Bắt buộc | Ghi chú |
|---|---|---|---|
| Tên / kênh / thời gian | text·enum·date | ✔ |  |
| Chi phí | money | — |  |
| Số lead / tỷ lệ chuyển đổi | number (view) | — | Theo từng bước phễu |

## 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 |
|---|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|
| `lead` | R | R | R | W¹ | — | — | — | — |
| `activity` | R | R | — | W¹ | — | — | — | — |
| `convert` | R | R | — | W | — | — | — | — |
| `commission` | R | A | — | R² | — | — | R | — |
| `campaign` | R | R | R | 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

## 6. Quy tắc nghiệp vụ
1. Chống trùng lead theo SĐT
2. `convert` tạo hồ sơ trạng thái `tu_van/tiep_nhan` bên student + điền sẵn thông tin — qua service API (P3), không ghi thẳng bảng
3. Hủy hồ sơ trước mốc ghi nhận → hủy hoa hồng
4. Nhắn lead qua **notify** (Zalo OA) — crm không tự gửi
5. Opportunity/Customer của CRM gốc ẩn được nếu không dùng (config)

## 7. Liên kết chéo
- **student** — convert → application
- **tuition** — mốc da_thu_dot1 tính hoa hồng
- **hrm** — CTV là Employee
- **notify** — nhắn Zalo lead
- **org** — scope theo phòng

## 8. Câu hỏi mở
- Vĩnh An có CTV không, công thức hoa hồng?
- Kênh lead chính — cần connector nào (Zalo OA webhook)?