Giao diện
System Profile — mind_keep ​
Đây là file duy nhất chứa thông tin riêng của dự án đích. Mọi skill trong
ba/.claude/skills/viết theo kiểu chung ("đọc nguồn API theo §2", "truy vết theo §3") và lấy chi tiết cụ thể từ đây. Dùng workflow cho dự án khác → copy_workflow/templates/system-profile/Template.mdđè lên file này rồi điền lại. Giữ nguyên số thứ tự section (§1–§7) vì skill tham chiếu theo số.Cập nhật lần cuối: 2026-09-30 — dựng từ cấu trúc repo thực tế (đã kiểm tra thư mục, chưa kiểm hết mọi domain).
§1. Hệ thống & thành phần ​
Tên hệ thống: mind_keep — monorepo cá nhân gồm backend, CMS web và mobile app; có một số tool tích hợp hệ thống SAPP.
| ID thành phần | Thư mục | Stack | Vai trò | Rulebook |
|---|---|---|---|---|
BE | be/ | Nx 22 + NestJS 11 (TypeScript) | 3 service: api (REST), schedule (cron/job), hook (webhook worker) | be/CLAUDE.md |
FE | fe/ | Next.js 16 + React 19 | CMS web (tool /works/*, trang quản trị /cms/*) | fe/CLAUDE.md |
APP | app/ | Flutter 3.32 / Dart 3.8 | Mobile app (UI tiếng Việt) | app/CLAUDE.md |
SHARED | shared/ | Markdown | Hợp đồng API, kênh trao đổi giữa lane, runbook — không phải code | root CLAUDE.md |
Handover (Bước 12) tách việc theo đúng các ID BE · FE · APP ở bảng này.
§2. Nguồn sự thật theo loại thông tin ​
Thứ tự ưu tiên khi hai nguồn lệch nhau: code đang chạy > API doc > map/tài liệu mô tả. Lệch nhau luôn được ghi thành finding/Open Question — lane ba/ không tự quyết bên nào sai.
| Loại | Nguồn | Ghi chú |
|---|---|---|
| Hợp đồng API (REST + MQTT) | shared/api-docs/<domain>.md, chung: shared/api-docs/overview.md | Mỗi domain 1 file. File lớn (vd sapp.md ~180 KB) → Grep rồi đọc đoạn nhỏ |
| Route / controller | be/apps/api/src/<domain>/*.controller.ts | ~51 controller |
| Business logic / rule | be/libs/modules/src/lib/<domain>/ (service.ts, common.service.ts, …) | |
| Request/response shape, validation | be/libs/interface/src/lib/dto/<domain>/*.dto.ts | class-validator decorator = rule validation thật |
| Data model | be/libs/database/src/lib/entities/<domain>/*.entity.ts, repository ở be/libs/database/src/lib/repositories/ | ERD: be/docs/database/schema-erd-v<N>.drawio (lấy N lớn nhất) |
| Job / cron / webhook | be/apps/schedule/src/, be/apps/hook/src/webhooks/; doc shared/api-docs/jobs.md, webhooks.md, mqtt.md | |
| Role / permission | shared/api-docs/permission.md, role*.md, user-permission.md; decorator ở be/apps/api/src/decorators/, guard ở be/apps/api/src/guards/ (+ Grep tên guard trong be/libs/) | Route @Public() = không cần quyền (19 controller có dùng, đếm 2026-09-30) |
| Bản đồ backend (đọc trước khi vào code) | be/.agents/maps/system.md, be/.agents/maps/modules/<domain>.md | Có thể stale — xác minh bằng code |
| Màn CMS web | route fe/app/**/page.tsx → UI fe/src/ui/pages/, fe/src/ui/components/ → gọi API ở fe/src/data/services/<domain>/ | Tool /works/* đăng ký qua TOOL_CODES |
| Màn mobile | app/lib/screens/*_screen.dart → app/lib/services/*_service.dart, model app/lib/models/ | |
| Vấn đề tích hợp đang mở | shared/integration/README.md (ledger) | Dòng chưa ✅ chạm domain = rủi ro/dependency |
| Quy trình vận hành đã chạy thật | shared/runbooks/ | Nguồn cho Transition / Cutover |
| Trao đổi đối tác SAPP | shared/external/sapp/ | Fact cho ticket sapp-* |
| Lịch sử thay đổi | git log -- <path> | Chỉ đọc |
§3. Công thức truy vết một tính năng trong code ​
Dùng ở /document-existing (viết tài liệu từ code) và khi cần xác minh "Existing" ở Impact / Field Intake.
- Điểm vào từ tên tính năng: Grep tên domain / nhãn UI / đoạn URL trong
shared/api-docs/,fe/app/,app/lib/screens/. - Từ màn hình xuống:
fe/app/<route>/page.tsx→ component trongfe/src/ui/→ hàm ởfe/src/data/services/<domain>/→ URL/api/v1/...app/lib/screens/<x>_screen.dart→app/lib/services/<x>_service.dart→ URL/api/v1/... - Từ API xuống: URL →
@Controller/@Get|Post|Patch|Deletetrongbe/apps/api/src/<domain>/→ service trongbe/libs/modules/src/lib/<domain>/→ DTO (be/libs/interface/...) → entity/repository (be/libs/database/...). - Đường phụ: job/cron (
be/apps/schedule), webhook (be/apps/hook), MQTT publish, gửi mail/notification — Grep tên service trong các app này. - Quyền: decorator trên controller/method (
@Public(), guard, permission code) +shared/api-docs/permission.md. - Đối chiếu doc: so kết quả với
shared/api-docs/<domain>.mdvàbe/.agents/maps/modules/<domain>.md→ ghi lệch vào mục Drift.
Ghi bằng chứng dạng đường/dẫn/file.ts:dòng (hoặc file.ts › ClassName.method).
§4. Ranh giới ghi ​
- Lane
ba/chỉ ghi trongba/. Đọc mọi thứ ở §2. - Chặn cứng bằng
denytrongba/.claude/settings.json:be/,fe/,app/,shared/. - Không chạy lệnh ghi (
install,generate,migration,format --write) ở bất kỳ thành phần nào.
§5. Quy ước ​
| Mục | Giá trị |
|---|---|
| Ngôn ngữ tài liệu | Tiếng Việt; thuật ngữ kỹ thuật giữ tiếng Anh |
| Mã BU trong tên project | MK (mind_keep) · SAPP (tool tích hợp SAPP) — vd 2026-MK-Webhook-retry |
| Role người dùng thường gặp | Admin CMS, người dùng app, public (route @Public()) — xác nhận với BA theo từng tính năng |
| Môi trường chụp màn hình | CMS: npm run dev ở fe/ (cổng 3000) hoặc staging do BA cung cấp — không dùng production |
§6. Knowledge base ngoài code ​
knowledge-base/sapp/— mục lục Confluence của hệ thống SAPP (LMS-Pro / Ops / HubSpot).
§7. Cách mở handover chính thức giữa các lane ​
Lane ba/ chỉ tạo ba/projects/<project>/docs/handover/*.md. Session của lane BE/FE/APP đọc file đó; nếu cần trao đổi chính thức thì session đó tự mở dòng trong shared/integration/README.md theo luật tại chính file đó.