23 KiB
KẾ HOẠCH 13 — Control Plane (Dashboard giám sát + quản lý + settings)
Status 2026-07-08: 🟡 Governance CORE + Track 1/2/3 + FinOps/SLO + Command Center + local-prod deploy smoke DONE (managed prod còn). Track 1 built: real NestJS API + React UI at
packages/casan-control-panel/(read-only monitoring over harness telemetry: overview/runs/governance/security/incidents/tools/ traceability/drift/cost/command + stale-aware/healthz). API serves REAL data; harness gate untouched (64/0/3). Run:npm run console:api+npm run console:ui. Track 2 built: settings API + React Settings page wrap existing harness corecontrol-plane-settings.pyand callrbac-check.pybefore writes; supports list policy/current settings, governed set, rollback, settings-audit tail, audit verify, role-aware UI controls. Track 3: kill-switch API + Incidents UI callkill-switch.shwith RBAC (operatorengage,org-adminclear); Approval Inbox API/UI wraps harness-ownedapproval-inbox.py;delegation-policy.yamlresolves L0-L5 gates; oversight log is hash-linked and SoD is enforced. Backend tests now 20/0 for viewer deny, org-admin write, rollback audit, sensitive approval gate, kill-switch engage/clear, approval inbox approve/apply, self-approval deny, IdP group→RBAC role mapping, and Command Center provenance widget contract. Harness targeted suites:phase-control-plane9/0,phase-control-plane-hitl9/0,phase-rbac12/0,phase-c7-incident15/0; suite HITL đã nối vàoci-harness-gate.sh. Track 4 offline partial: FinOps/SLO page reads provider usage + business KPI artifacts and budget cap setting without fabricating missing values. Command Center §8.6 built:GET /api/v1/commandreturns eight evidence-backed widgets with{source, artifact_path, commit, run_at, verified}envelopes; React/commandpage has executive briefing VI/EN, live governance ticker, and evidence drawer. Deploy scaffold + local-prod smoke:Dockerfile.control-panel-api,Dockerfile.control-panel-ui,docker-compose.control-panel.yml,docker-compose.control-panel.local.yml,nginx/control-panel.confvalidate được bằngdocker compose config; nginx config passesnginx -twith a temp cert/upstream aliases;packages/casan-control-panel/scripts/local-prod-smoke.shpassesCP_LOCAL_SMOKE_PASS https_oidc=true actor=oidc-ops role=org-adminand asserts/api/v1/commandreturns all 8 widgets with provenance envelopes.prod-readiness-check.shvalidates managed-prod host prerequisites (compose, TLS, oauth2-proxy OIDC env, nginx) without printing secrets.managed-prod-smoke.shvalidates deployed endpoint auth enforcement (unauth blocked, spoofed identity headers blocked) and, with a real IdP cookie jar, authenticated/settings+/commandbehavior. Local-prod now runs that managed smoke with the mock-IdP authenticated cookie jar and emitsCP_MANAGED_SMOKE_PASS actor=oidc-ops role=org-admin widgets=8. Nginxauth_requestoverwrites identity headers and API maps IdP groups → RBAC roles. Còn: managed host/cert/enterprise IdP env thật (07 T2).Status 2026-07-06: 🟡 Governance CORE implemented + tested (harness-owned). Sửa kiến trúc: Control Plane là tài sản của core harness, KHÔNG nằm trong app OKR (OKR chỉ là testbed được gen). Governance core đã dời vào harness:
packages/casan-harness/scripts/bash/control-plane-settings.py(settings store versioned + audit hash-chain + deny-by-default + approval cho key nhạy cảm + rollback + verify), testpackages/casan-harness/tests/phase-control-plane-tests.sh7/0 (WSL), nối CI (phase-control-plane). Phần đã nhét nhầm trongapps/okrđã gỡ bỏ (OKR về sạch: backend 46/0/3-skip, frontend 16/16). Đã nối tiếp 2026-07-08: web app React+NestJS độc lập hiện nằm ởpackages/casan-control-panel/; monitoring + settings management đã bọc harness core (single-source governance). Approval inbox/HITL và OIDC claim→role mapping đã có bản offline/scaffold. Còn lại: live deploy prod TLS/OIDC (07 TIER 2).Nhãn trạng thái: xem legend ở
CASAN_BACKLOG_STATUS.md. Phụ thuộc: 07 (H5 audit, C4 approval/IdP, D3 dashboard hosting, kill-switch) · 14 (RBAC — ai được xem/đổi gì) · 04 (đổi setting = proposal→approval→apply) · 01 (đường dẫn sau restructure). Chặn mềm bởi 14 cho phần quản lý.
1. Quyết định kiến trúc — web app control-plane thật
Repo đã có frontend React + backend NestJS thật. Control Plane là web app thật (admin/ops console) tích hợp vào stack hiện có. Sàn tối thiểu = React + NestJS (frontend + API thật) — không thấp hơn. HTML tĩnh KHÔNG bao giờ được dùng làm control-plane. Nếu cân nhắc bản nhẹ hơn, nó vẫn phải là web app thật (ví dụ SPA gọn + API tối thiểu), có đủ monitoring + settings API + governance — không phải trang tĩnh sinh sẵn. Dashboard HTML sinh sẵn hiện tại chỉ giữ vai trò export/offline read-only, không phải control-plane.
flowchart LR
UI["Ops Console (React)
monitor + manage + settings"] --> API["Control-Plane API (NestJS)"]
API --> RBAC["RBAC (Plan-14)"]
API --> APPROVAL["Proposal→Approval (Plan-04 + 07-C4 IdP)"]
API --> AUDIT["H5 audit-chain (mọi thay đổi)"]
API --> STORE["Settings store
(versioned: policy/threshold/routing)"]
API --> READ["Read-only telemetry
(metrics/drift/incident/cost)"]
READ --> HARNESS["Core harness .specify/**"]
STORE --> HARNESS
style AUDIT fill:#fff3cd,stroke:#8a6d3b,stroke-width:2px
style RBAC fill:#d0e8ff,stroke:#2c3e91,stroke-width:2px
2. Nguyên tắc (governance-first)
- Đọc ≠ Ghi: phần monitoring đọc telemetry là read-only; phần management (đổi settings/threshold/kill-switch) đi qua RBAC + proposal→approval + H5 audit.
- Mọi thay đổi setting đều bất biến & rollback được: ghi audit-chain (H5) + version cũ→mới + actor + reason; hoàn tác qua H7 checkpoint.
- Không nới lỏng bảo mật ngầm: đổi setting kiểu "nới" (giảm ngưỡng chặn, tắt
gate) bắt buộc nhãn
security-sensitive+ duyệt cấp cao (tái dùng Plan-04 §4.8). - Không đường vòng qua UI: UI không được bypass gate — nó chỉ ghi vào settings store mà harness đọc; harness vẫn là nguồn quyết định cuối.
- Fail-loud: control-plane sập/không đọc được telemetry → hiển thị
STALE/503, không hiển thị số liệu cũ như thật (tái dùng/healthzstale-aware của D3).
3. Phạm vi tính năng
3.1 Monitoring (mở rộng từ D3 read-only)
| Nhóm | Nội dung | Nguồn |
|---|---|---|
| Harness verdicts | pass/fail từng gate H1→H7 theo run/step | .specify/logs, evidence pack |
| Cost & token | cost_per_run, token_saved, budget vs actual | H6 telemetry, provider-usage.jsonl |
| Drift & quality | drift-report, H3 reject rate, hallucination rate | drift-detect, business-kpi |
| Incident | incident severity, kill-switch state | incident.sh, kill-switch.sh |
| Traceability | REQ→code→test coverage (Plan-10) | traceability-matrix.json |
3.2 Management / Settings (mới — phần chính)
| Setting | Đối tượng file (harness đọc) | Ràng buộc đổi |
|---|---|---|
| Compression policy (Plan-08) | compression-policy.yaml |
mode/ratio/exclude/must-keep; đổi → audit |
| Thresholds (cost/circuit/FP) | thresholds.yaml |
siết = duyệt thường; nới = duyệt cấp cao |
| Model routing (Plan-03/02) | model-fallback.yaml |
đổi provider/model → approval |
| Kill-switch (Plan-07 C7) | kill-switch scope |
engage/disengage → HIGH audit + alert |
| Approval reviewers (Plan-07 C4) | reviewers.registry |
chỉ org-admin (RBAC Plan-14) |
| Feature flags (bật/tắt track) | mới feature-flags.yaml |
audit |
3.3 FinOps & SLO (gộp vào đây, không tách plan)
- Budget theo dự án/org + cảnh báo vượt; biểu đồ xu hướng cost/token.
- SLO/KPI platform (block_rate, FP, token_saved, time_to_approval…) — kế thừa Future B6.
3.4 Human-in-the-loop surface (hiện thân của "Human-led, AI-first" — FPT §4.3/§4.4)
Control Plane là nơi con người nhìn thấy & hành động trong vòng lặp — làm cho tư tưởng Human-led, AI-first hiển thị được, không chỉ là approval token ngầm.
| Thành phần | Nội dung | Nguồn |
|---|---|---|
| Approvals inbox | Hàng đợi hành động đang chờ người duyệt (setting nhạy cảm, nới ngưỡng, kill-switch, self-improve proposal) → duyệt/từ chối kèm lý do; verify JWT (SEC-07), chống replay (X-06), SoD | control-plane-settings + approval-verify + self-improve |
| Delegation level L0–L5 | Đặt mức uỷ quyền AI per project/action theo CASAN §4.4 (L1 người duyệt toàn bộ … L5 tự chủ vùng đã governance); mức quyết định hành động nào cần vào inbox | mới delegation-policy.yaml (managed qua Control Plane) |
| Oversight log | Nhật ký ai duyệt/từ chối, khi nào, vì sao + human-oversight events (kill-switch, override) — cho RAI report (Plan-15) | H5 audit + governance-report |
| Pending gate view | Hiển thị step đang bị chặn chờ người (REQUIRE_APPROVAL) + context để quyết | security-check/action-gate verdict |
Tasks (bổ sung Plan-13):
| Task | Việc | Verify |
|---|---|---|
| 13H.1 | delegation-policy.yaml (L0–L5 per project/action) + resolver: mức quyết định action nào cần approval |
✅ đổi mức → action tương ứng vào/không-vào inbox |
| 13H.2 | Approvals inbox API + UI: list pending → approve/reject (SoD + reason), ghi audit | ✅ self-approve DENY; approve setting proposal → apply qua governed store |
| 13H.3 | Oversight log view (ai-duyệt-gì) + xuất vào RAI report | ✅ 1 quyết định → truy được actor/reason/time/hash |
Nguyên tắc: mức uỷ quyền chỉ giảm human-gate khi rủi ro thấp; nới mức (tăng tự chủ) là thay đổi security-sensitive → cần approval cấp cao. Đây là điểm nối trực tiếp giữa tư tưởng CASAN và bề mặt vận hành.
4. Tasks theo track
Track 1 — Read-only monitoring API + console
| Task | Việc | Verify | Done |
|---|---|---|---|
| 13.1 | Control-Plane API (NestJS) đọc telemetry/audit/traceability (read-only) | GET trả metrics đúng nguồn | API đọc được |
| 13.2 | Ops Console (React) hiển thị verdicts/cost/drift/incident/traceability | render đúng số liệu, stale→badge | console xem được |
| 13.3 | Stale-aware /healthz + hiển thị STALE khi telemetry chết |
ngắt telemetry → UI báo stale, không giả tươi | fail-loud |
Track 2 — Settings store versioned + audit
| Task | Việc | Verify | Done |
|---|---|---|---|
| 13.4 | Settings store versioned (đọc/ghi các key harness dùng) qua API/UI bọc core CLI | ghi setting → version mới + giữ cũ | ✅ API/UI hoạt động |
| 13.5 | Mọi thay đổi → H5 audit-chain (actor/reason/diff) | sửa 1 setting → audit có bản ghi; verify-audit OK | ✅ bất biến |
| 13.6 | Rollback setting qua governed store | rollback → về version cũ, có audit | ✅ hoàn tác được |
Track 3 — Management có governance (RBAC + approval)
| Task | Việc | Verify | Done |
|---|---|---|---|
| 13.7 | Gắn RBAC (Plan-14): role quyết định xem/đổi setting nào | viewer đổi setting → DENY; admin → cho | ✅ settings API enforcement |
| 13.8 | Đổi setting nhạy cảm → proposal→approval (Plan-04 + 07-C4 IdP) | nới ngưỡng → yêu cầu duyệt cấp cao mới apply | ✅ inbox + SoD + claim mapping |
| 13.9 | Kill-switch engage/disengage qua UI → HIGH audit + alert (Plan-07 C7/D1) | engage → harness từ chối chạy + alert bắn | ✅ API/UI bọc kill-switch.sh |
Track 4 — FinOps / SLO / production deploy
| Task | Việc | Verify | Done |
|---|---|---|---|
| 13.10 | Budget theo dự án/org + cảnh báo vượt | vượt budget → cảnh báo + chặn theo policy | 🟡 FinOps UI cảnh báo từ cap setting; policy chặn nằm H6 |
| 13.11 | SLO/KPI board (kế thừa Future B6) | KPI hiển thị theo thời gian | ✅ KPI board |
| 13.12 | Deploy production-like: host + TLS + OIDC (nối Plan-07 T2.3/T2.6) | truy cập qua HTTPS + OIDC, không auth → chặn | ✅ local-prod smoke + authenticated managed-smoke on local-prod + prod-readiness checker; live managed run cần cert/IdP/host thật |
5. Red-team / test
| Test | Kỳ vọng |
|---|---|
adv-settings-change-no-audit (đổi setting bỏ qua audit) |
BLOCK / phát hiện mismatch |
adv-loosen-threshold-no-approval (nới ngưỡng không duyệt) |
DENY |
adv-viewer-writes-setting (role thấp ghi setting) |
DENY (RBAC) |
adv-ui-bypass-gate (UI cố ghi verdict trực tiếp) |
không thể — UI chỉ ghi settings store |
adv-stale-telemetry-shown-fresh (telemetry chết vẫn hiện tươi) |
UI báo STALE |
benign-settings-roundtrip (đổi hợp lệ + rollback) |
PASS + audit đầy đủ |
6. Tiêu chí HOÀN THÀNH
- Monitoring đọc đúng telemetry, stale-aware, không giả số liệu.
- Mọi thay đổi setting qua Control Panel: RBAC + (approval nếu nhạy cảm) + H5 audit + rollback được.
- UI không bypass được gate; harness vẫn là nguồn quyết định cuối.
- Các key settings đang whitelist trong
control-plane-settings.pyquản lý được qua console (compression/cost/model/security/kill-switch/loop); kill-switch UI có. - FinOps/SLO board đọc provider usage + business KPI artifact thật; thiếu budget cap thì báo chưa cấu hình.
- Approval inbox + delegation L0-L5 + oversight log có API/UI và test SoD/apply.
- Command Center §8.6 có API/UI: 8 widget evidence-backed, provenance envelope, executive briefing VI/EN, live ticker, evidence drawer.
- Local production-like deploy có TLS + OIDC + oauth2-proxy + nginx
auth_request; smoke pass qua HTTPS. - Managed production readiness checker cho cert/host/enterprise IdP env thật.
- Managed production endpoint smoke script cho unauth/spoof/authenticated-cookie checks.
- Authenticated managed endpoint smoke pass trên local-prod HTTPS/OIDC endpoint (
CP_MANAGED_SMOKE_PASS actor=oidc-ops role=org-admin widgets=8). - Managed production deploy với cert/host/enterprise IdP thật (nối Plan-07 TIER 2).
- Red-team mục 5 targeted xanh: control-plane 9/0 + HITL 9/0 + RBAC 12/0 + C7 15/0; full gate dài đã pass qua adversarial 44/0 nhưng A6 mất thời gian nên không claim full-gate xanh trong lượt này.
7. Ghi chú trung thực
- Control Plane không thay quyền quyết định của harness; nó là lớp quản trị + quan sát có governance.
- Phần "quản lý" hiện đã đi qua Plan-14 RBAC + approval/HITL + H5 audit; prod thật vẫn cần enterprise IdP/cert/host.
8. Kế hoạch thực thi — web app độc lập (historical baseline; đã build trong packages/casan-control-panel/)
Governance core (settings + RBAC) nằm trong harness và test xanh. Web app là lớp trình bày bọc core, không chứa logic governance riêng. Baseline này đã được hiện thực trong
packages/casan-control-panel/; §8.6 Command Center và Ask CASAN read-only đã có, các mục còn lại nên đi theo RAI view, Chat MVP-1 Operator, hoặc managed production rollout.
Vị trí: packages/casan-control-plane/ (sibling packages/casan-harness; Plan-01 ✅ done). KHÔNG nằm trong apps/okr.
Nguyên tắc: NestJS API không chứa logic governance — mọi set/rollback/authz gọi harness CLI (control-plane-settings.py, rbac-check.py) để governance chỉ có một nguồn trong harness. UI role-gated. Harness vẫn là nguồn quyết định cuối.
Cấu trúc & tasks:
| Task | Việc | Verify |
|---|---|---|
| 13W.1 | control-plane/api (NestJS): main.ts, app.module.ts, harness.service.ts (exec control-plane-settings.py + rbac-check.py qua child_process), control-plane.controller.ts (GET settings/monitoring/audit; POST set/rollback → gọi rbac-check trước, rồi control-plane-settings.py) |
✅ npm run console:build |
| 13W.2 | api/test/control-plane.e2e.test.ts: viewer→403, org-admin→200; set thật ghi vào harness store; sensitive không approval→403 |
✅ npm run console:test 20/0 |
| 13W.3 | control-plane/web (Vite React): App.tsx, MonitoringCards/SettingsTable (tái tạo), lib/api.ts gọi API |
✅ vite build |
| 13W.4 | web/src/__tests__/*.test.tsx: RBAC gating (canEdit), stale badge |
✅ backend/API coverage + targeted harness suites; frontend unit can be added later |
| 13W.5 | Deploy prod: host + TLS + OIDC (nối Plan-07 T2.3/T2.6) | ✅ local-prod smoke; 🔌 managed prod |
Chi phí: 2 npm install + 2 build + 2 test (Windows Node, NODE_OPTIONS=--use-system-ca).
Bất biến: app độc lập, không đụng OKR/core harness 245/0.
8.6 CASAN Command Center — trực quan hóa TƯ TƯỞNG lõi cho lãnh đạo
Mục tiêu: tư tưởng CASAN không chỉ nằm trong code mà hiện rõ trên giao diện — lãnh đạo nhìn phát wow ngay. Nhưng "wow" phải là wow thực chất: mọi con số đọc từ artifact thật của core, click xuống được bằng chứng. Đây là "kính buồng lái", không phải áp phích.
Nguyên tắc bất di (chống "dashboard diễn")
- Real glass, not paint — mỗi widget đọc từ artifact core ĐÃ CÓ (không bịa số).
- Provenance envelope bắt buộc — mọi số kèm
{source, artifact_path, commit, run_at}; UI hiển thị badge nguồn. Thiếu provenance → không render số, hiện "chưa có dữ liệu". - Click-to-evidence khắp nơi — click số → mở audit/trace/log gốc. Đây là điểm phân biệt sống còn với demo thường: "Không tin? Bấm xem tận gốc."
- Không vanity metric — cấm widget mà data phải phỏng đoán (vd "ROI dự phóng"). Chỉ hiển thị cái core chứng minh được — nếu không, phá vỡ chính tư tưởng evidence-based.
- Fail-honest — data cũ/không verify được → badge vàng "stale", audit hỏng → seal đỏ. Không bao giờ tô xanh khi chưa chứng thực.
8 widget — mỗi cái map 1 tư tưởng, gắn nguồn thật
| # | Widget | Tư tưởng CASAN | Artifact nguồn (đã có) | API |
|---|---|---|---|---|
| V1 | Maturity gauge + radar H1–H7 (hero) | 5 mức CASAN + 7 thành phần harness | phase3-real-run-scoring.md + telemetry counts |
GET /api/v1/command |
| V2 | Human-in-the-loop panel: vòng L0–L5 + approvals inbox + feed "AI đề xuất → người quyết" | Human-led, AI-first (§4.3/4.4) | approval store + oversight | GET /api/v1/command |
| V3 | Kill-switch đỏ + guardrail badges (deny-by-default) | Kiểm soát / rollback / accountability | incidents.jsonl |
GET /api/v1/command |
| V4 | Traceability Sankey: Yêu cầu→Code→Test→Evidence, gap đỏ | Truy vết, không code mồ côi | traceability-matrix.json |
GET /api/v1/command |
| V5 | Security posture: "N tấn công → N chặn, block_rate %" + red-team | Security-by-default, fail-closed | security.jsonl |
GET /api/v1/command |
| V6 | Token economy / FinOps: token tiết kiệm nhờ nén → quy ra $ | Context engineering, kỷ luật chi phí | provider-usage.jsonl + business KPI |
GET /api/v1/command |
| V7 | Certified-run seal: CERTIFIED/NOT_CERTIFIED + toàn vẹn audit-chain | Evidence + accountability + audit integrity | audit-head.txt + audit tail |
GET /api/v1/command |
| V8 | Self-improve pipeline: propose → chờ duyệt → applied | Tự cải thiện CÓ kiểm soát | self-improve.py primitive + approval proposals |
GET /api/v1/command |
3 tính năng "chốt hạ"
- Executive Briefing mode (1 nút) — gộp thành 1 màn kể chuyện: Trưởng thành → Kiểm soát (HITL + kill-switch) → An toàn (block rate) → Tiết kiệm ($) → Đã chứng thực (seal). Song ngữ VI/EN cho lãnh đạo + đối tác quốc tế.
- Live governance ticker — dòng sự kiện chạy realtime: "14:03 AI xin nới ngưỡng → Trưởng phòng TỪ CHỐI", "14:05 Certified run #128 ✅". Biến governance trừu tượng thành thứ nhìn thấy đang sống.
- Evidence drawer — panel trượt ra khi click bất kỳ số nào: hiển thị artifact JSON gốc + commit + link chạy lại lệnh core sinh ra số đó.
Data contract (để "wow thực chất")
- API không tính toán governance — chỉ đọc & bọc artifact/core telemetry hiện có; nguồn quyết định vẫn là harness.
- Các nguồn chưa có artifact queue (ví dụ self-improve proposal) hiển thị
no_data/primitive-present, không bịa số. - Mỗi widget bọc
envelope: {source, artifact_path, commit, run_at, verified: bool, status}.
Tasks (bổ sung Plan-13; UI theo chuẩn UI/UX hạng nhất — sizing/touch-target/hover đồng nhất)
| Task | Việc | Verify |
|---|---|---|
| 13V.0 | Chuẩn hóa envelope provenance trong Control API; core --json bổ sung sau khi có widget cần gọi CLI live |
✅ commandCenter() envelope có source/artifact_path/commit/run_at/verified/status |
| 13V.1 | API GET /api/v1/command gom 8 widget đọc-only, không ghi state |
✅ console:test contract 20/0 |
| 13V.2 | V1 Maturity gauge + radar H1–H7 (click widget → evidence drawer) | ✅ /command widget + drawer |
| 13V.3 | V2 HITL panel + approvals inbox/oversight | ✅ đọc approval store; thiếu artifact → no_data |
| 13V.4 | V3 kill-switch + guardrail badges; V7 certified seal | ✅ đọc incidents + audit-head/audit tail |
| 13V.5 | V4 traceability; V5 security posture; V6 FinOps token→$ | ✅ số lấy từ traceability/security/provider artifacts |
| 13V.6 | V8 self-improve pipeline | ✅ hiển thị primitive present + proposal nếu có trong inbox; không fabricate queue |
| 13V.7 | Executive Briefing mode (song ngữ VI/EN) + Live ticker + Evidence drawer dùng chung | ✅ /command page |
| 13V.8 | Provenance guard: thiếu source→no_data/missing, stale vẫn qua freshness |
✅ contract test + UI status badge |
Hiện trạng: Command Center baseline đã có. Widget Loop/Chat chuyên sâu và RAI view nằm ở Plan-17/18/15 follow-up, không còn chặn Plan-13 baseline.
Liên quan: CASAN_PLAN_07_PRODUCTION_HARDENING.md (D3 dashboard, C4 IdP, C7 kill-switch, TIER 2 deploy) · CASAN_PLAN_14_RBAC.md (phân quyền) · CASAN_PLAN_04_SELFIMPROVE.md (proposal→approval) · CASAN_PLAN_08_CONTEXT_COMPRESSION.md (compression-policy là settings) · CASAN_PLAN_15_RESPONSIBLE_AI_DATA_GOV.md (RAI/data view).