LumiBaseDocs

Roadmap & Task Breakdown

Scope: Roadmap này dành cho LumiBase Studio — admin panel để quản lý data, collections, permissions, v.v. — và LumiBase CMS API chạy được trên cả Cloudflare Workers và Docker.

Consumer app (frontend end-user) ở apps/consumer (Next.js) là demo dùng SDK để gọi Delivery API — không phải CMS Studio.

Ngôn ngữ task: ngắn, có thể chuyển thẳng vào issue tracker. Mỗi task có scope rõ ràng, deliverable, và link tài liệu liên quan.

Quy ước:

  • [BE] apps/cms (Backend API - Hono)
  • [FE] apps/studio (Admin panel - React + Vite)
  • [DB] packages/database
  • [RT] packages/runtime (abstraction layer Cloudflare/Docker)
  • [AI] packages/ai-skills + AI Copilot
  • [SDK] packages/sdk (Type-safe client cho cả Studio và consumer apps)
  • [DOC] apps/docs hoặc tài liệu trong docs/
  • [OPS] infra/deploy/CI
  • Mỗi PR nên gắn 1 nhánh feature/<phase>-<short-name> theo Git hygiene rule.

Trạng thái tổng quan: Phase 0 → Phase G (GA hardening) đã xong. POST-GA và Dual Deployment + AI Copilot đã hoàn thành. Hiện tại tập trung vào polish, dev experience và mở rộng marketplace.

Active Ops Hardening Tasks

Nguồn: apps/docs/content/deployment/docker.md, apps/docs/content/guides/backup-recovery.md.

  • [OPS] Docker image chạy non-root user.
  • [BE] Validate production config khi NODE_ENV=production hoặc LUMIBASE_ENV=production.
  • [BE] Hỗ trợ Docker secret files qua *_FILE trước migration/server startup.
  • [BE] CORS allowlist qua CORS_ALLOWED_ORIGINS; reject wildcard production.
  • [BE] Require ENCRYPTION_KEY production và validate AES key format.
  • [BE] Require DB TLS sslmode=require|verify-ca|verify-full production, trừ khi explicit DATABASE_SSL_MODE=disable.
  • [OPS] docker-compose.prod.yml không publish port cho stateful internal services.
  • [DOC] Cập nhật Docker deployment docs và environment reference.
  • [DOC] Bổ sung restore drill, row-count verification, app health check sau restore, media/search rebuild, RTO/RPO documentation.
  • [DOC] Bổ sung Cloudflare DR validation cho Workers, Hyperdrive, R2, KV, Queues, MeiliSearch Cloud, DNS/WAF/Access.
  • [OPS] Cấu hình TLS termination thực tế tại load balancer/reverse proxy của môi trường deploy.
  • [OPS] Tự động hóa restore drill định kỳ cho Docker và Cloudflare restore environment.

Phase 0 — Foundation (DONE)

Mục tiêu: bộ khung monorepo chạy được, schema lõi, auth Logto, CI.

  • [OPS] Tạo apps/cms (Hono + Cloudflare Workers template + wrangler config).
  • [OPS] Tạo apps/studio (Vite + React + TS + Tailwind + shadcn init).
  • [OPS] Tạo packages/contracts, packages/sdk, packages/ui, packages/extension-sdk (boilerplate + tsconfig + lint).
  • [DB] Bổ sung schema: users, user_sites, teams, team_members, roles, policies, role_policies, user_policies, permissions (xem data-model.md).
  • [DB] Drizzle migration runner cho Hyperdrive (local + remote scripts).
  • [BE] Middleware withAuth (Logto JWKS), withTenant (site_id từ subdomain/header), withLogger.
  • [BE] GET /auth/me + GET /utils/health.
  • [FE] App shell + module bar + routing skeleton + Logto login flow.
  • [FE] API client trong packages/sdk (fetch wrapper, error format, site header).
  • [OPS] Pipeline CI (lint, typecheck, test, build) + preview deploy.
  • [DOC] Cập nhật architecture.md (root) khi cấu trúc thay đổi.

Phase A — Schema engine (DONE)

Mục tiêu: tạo/quản lý collection & field qua API + UI.

  • [DB] Bảng collections, fields, relations.
  • [BE] SchemaService (CRUD + compile cache).
  • [BE] Endpoints /collections, /fields, /relations.
  • [BE] Endpoint diff /collections/diff + PUT /collections/:name/schema.
  • [BE] Validation tên collection/field, kiểm tra dependency khi xoá.
  • [SDK] Type-safe client cho schema.
  • [BE] Script CLI apps/cms/scripts/typegen.ts + alias lumibase typegen.
  • [FE] Module Settings → Data Model (list collection).
  • [FE] Collection wizard 3 bước.
  • [FE] Collection detail tabs (Fields, Display, Archive, Raw JSON).
  • [FE] Field inspector cơ bản (interfaces input, input-multiline, toggle, select-dropdown, datetime, json-raw).
  • [FE] Live JSON pane (Monaco) cho schema collection, two-way sync.
  • [FE] Drag-drop reorder field (dnd-kit).
  • [BE] Endpoint GET /typegen/schema (manifest đã apply permission).
  • [SDK] Generator core packages/sdk/src/typegen/.
  • [FE] Trang Settings → Developer → Types (preview + download).

Phase B — Items & Field system mở rộng (DONE)

  • [DB] Bảng items, revisions, activity + indexes GIN.
  • [BE] ItemService build query Drizzle động (fields, filter, sort, paginate, deep).
  • [BE] Endpoints /items/:collection đầy đủ.
  • [BE] Revision write + revert.
  • [BE] Activity log middleware cho mutation.
  • [BE] Validation pipeline (Zod + JSONata) chạy server-side.
  • [BE] Conditions evaluator (server + helper xuất sang client).
  • [BE] Per-field encryption service (AES-GCM, key Workers Secret/env).
  • [FE] Content module list view (tabular layout) + filter builder + sort + paginate.
  • [FE] Detail editor + tabs side panel (Revisions, Raw JSON).
  • [FE] Interface registry hoàn chỉnh: text, number, choice, boolean, date, relation, file, json-raw, code, wysiwyg, markdown, slug, color, tags, rating, repeater, presentation.
  • [FE] Display registry: formatted-value, raw, boolean-icon, datetime, image, labels, mustache-template.
  • [FE] Raw toggle component (Monaco) cho mọi interface.
  • [FE] Bulk raw editor cho toàn item.
  • [FE] Revisions diff viewer.
  • [FE] Mustache display template editor.
  • [BE] POST /utils/render-template (mustache only Phase B).

Phase C — Permissions & Access (DONE)

  • [BE] PermissionService (compile rule, cache, field mask).
  • [BE] Endpoints CRUD /roles, /policies, /policies/:id/permissions, attach/detach.
  • [BE] GET /permissions/me + POST /permissions/check (trace).
  • [BE] Tích hợp Permission vào ItemService (where injection + post-check).
  • [BE] Magic vars $CURRENT_USER, $CURRENT_SITE, $CURRENT_ROLE, $NOW, $IP, $HEADERS.*.
  • [BE] Time-bound + IP allow/deny ở policy level.
  • [BE] Permission compose rules.
  • [FE] Module Access Control: Roles, Policies (GUI + JSON Monaco), Permission matrix, Test sandbox.
  • [FE] Field-level hide/disable trong form theo /permissions/me.
  • [FE] List view hide column nếu không có quyền read field.
  • [FE] Hide/disable bulk action theo permission.

Phase C2 — Presets, Bookmarks, Translations cơ bản (DONE)

  • [DB] Bảng presets, translations.
  • [BE] CRUD /presets, scope resolution (user > role > site).
  • [BE] CRUD /translations (namespace ui, field, content).
  • [BE] Locale settings (settings.locales.*).
  • [FE] Preset switcher + save/edit dialog ở list view.
  • [FE] Module Translations (UI strings tab + content tab JSONB).
  • [FE] Interface translatable-text (JSONB map locale).
  • [FE] i18n cho Studio UI (react-i18next bind to translations API).

Phase D — Users, Files, Settings (DONE)

  • [BE] /users, /users/invite, /users/:id/impersonate, sessions.
  • [BE] /teams, /team_members.
  • [BE] Files: presigned R2/S3 upload, /files, /assets/:id transform, /media (StorageProvider abstraction).
  • [BE] Settings storage + cache + settings.changed event.
  • [BE] Webhooks CRUD + dispatcher (Queues / BullMQ).
  • [BE] Activity log endpoint (filter, paginate).
  • [FE] Module Users + Teams.
  • [FE] Module Files (grid + folders + drag-drop upload).
  • [FE] Module Settings (general, locales, security, files, webhooks, activity).
  • [FE] Notifications inbox (qua realtime).

Phase E — Realtime / WebSocket (DONE)

  • [OPS] Tạo Durable Object class SiteRoom (Wrangler binding).
  • [BE] Endpoint /realtime upgrade WS, route tới DO theo siteId.
  • [BE] Protocol subscribe/unsubscribe/presence.
  • [BE] Publish pipeline trong ItemService.commit().
  • [BE] Permission re-check khi fan-out event.
  • [BE] Rate limit + heartbeat.
  • [SDK] Client realtime trong packages/sdk.
  • [FE] Hook useRealtimeSubscription, usePresence.
  • [FE] Presence chip topbar + detail editor.
  • [FE] List view "Live mode" toggle.
  • [FE] Smart preset subscribe.
  • [FE] Notifications realtime.

Phase F — Extensions & Display Templates nâng cao (DONE)

  • [DB] Bảng extensions.
  • [BE] Extension uploader (multipart → R2/S3) + manifest validator + capability registry.
  • [BE] Sandbox loader (dynamic import + proxy ctx + capability gate).
  • [BE] Hook dispatcher tích hợp ItemService (before/after).
  • [BE] Endpoint mount /extensions/:name/* từ extension type endpoint.
  • [BE] /utils/render-template hỗ trợ component DSL.
  • [FE] Module Settings → Extensions (upload, review caps, enable/disable, version).
  • [FE] Dynamic loader UI extensions (interface/display/layout/panel/module).
  • [FE] Display template editor mode component (block builder).
  • [DOC] Tutorial "Build your first extension" trong docs/features/extensions-system.md.

Phase G — Hardening & GA (DONE)

  • [BE] Postgres RLS policies bổ sung qua middleware withRls() (defence-in-depth).
  • [BE] Tag-based invalidation hoàn thiện (revalidateTag webhook → Next.js consumer).
  • [BE] Backups + restore qua endpoints /api/v1/admin/backup + /api/v1/admin/restore (NDJSON bundle).
  • [BE] Config export/import CLI (apps/cms/scripts/config-cli.ts).
  • [FE] Accessibility audit + fix.
  • [FE] Bundle size audit, lazy module splitting (TanStack Router lazy-load).
  • [OPS] Load test (k6) cho delivery API và realtime — apps/cms/k6/.
  • [OPS] SLO dashboards (Workers Analytics Engine + Grafana cho Docker).
  • [DOC] Public docs site (apps/docs — Vite + React + Markdown).

Phase POST-GA1 — Translation Memory + MT (DONE)

  • [DB] Bảng translation_memory + glossary.
  • [BE] Service translation-memory.ts với providers: DeepL, OpenAI, Workers AI, echo fallback.
  • [BE] Routes /api/v1/tm (list/upsert/lookup fuzzy/translate pipeline TM → glossary → MT).
  • [FE] UI tích hợp TM trong module Translations.
  • [DOC] features/translation-memory.md.

Phase POST-GA2 — Collaborative cursors (DONE)

  • [BE] cursor-protocol.ts (CRDT-lite: last-write-wins position + Y-style update vector).
  • [BE] Broadcast qua Durable Object SiteRoom (CF) hoặc in-process (Docker).
  • [FE] Render cursors + selection trong WYSIWYG / text fields.

Phase POST-GA3 — Flows / Operations engine (DONE)

  • [DB] Bảng flows, flow_runs, operations.
  • [BE] Service flow-service.ts runner với operation types: condition, transform, http, mail, log, sleep, run-extension, item.create|update|delete, notify.
  • [BE] Routes /api/v1/flows + manual /run + /runs history.
  • [BE] Trigger types: webhook, event (item.*), schedule (cron), manual.
  • [FE] Module Automation → Flows (list page).
  • [DOC] features/flows-automation.md.

Phase POST-GA4 — SCIM 2.0 provisioning (DONE)

  • [BE] /scim/v2/Users + /Groups + ServiceProviderConfig + Schemas + ResourceTypes (RFC 7644 subset).
  • [BE] Bearer token auth riêng (SCIM_TOKEN), không dùng Logto JWT.
  • [BE] Mapping: SCIM Group → LumiBase Team.
  • [DOC] features/scim-provisioning.md.

Phase POST-GA5 — Marketplace extensions (DONE)

  • [DB] Bổ sung cột signature, signatureAlg, publisherKeyId, publisher, marketplaceSlug, publishedAt, bundleSha256 vào extensions.
  • [BE] Routes /api/v1/marketplace/extensions (list, detail, install, publish).
  • [BE] Signature verification: SHA-256 bundle + ed25519/RSA-PSS qua WebCrypto, public keys load từ env MARKETPLACE_PUBLIC_KEYS.
  • [FE] Public Marketplace site dùng catalog API thật, SEO/static export/deploy checklist.
  • [DOC] Revenue sharing chốt hướng Free-first; commercial checkout/payout tách backlog pha sau.
  • [DOC] features/marketplace.md.

Phase POST-GA6 — Materialized collections (DONE)

  • [DB] Bảng materialized_collections.
  • [BE] Routes /api/v1/materialize (register, refresh, drop).
  • [BE] Logical refresh strategy (count + lastRefreshedAt). Full denormalized write còn để mở.
  • [DOC] features/materialized-collections.md.

Phase POST-GA7 — Advanced Permission Builder & RBAC (TODO)

Mục tiêu: nâng cấp Access Control hiện có thành hệ Role / Policy / Permission tương đương Directus nhưng fail-closed hơn, có conflict detection, policy flags, API keys theo role, import/export JSON và seed system permissions. Tham chiếu: docs/vi/features/permission-builder-directus-investigation.md.

Chuẩn bị bắt buộc

  • [BE] Audit PermissionService hiện tại: ghi rõ hành vi compose hiện có (OR rules, union fields, merge presets/validation) và các case có thể mở rộng quyền im lặng.
  • [DB] Thiết kế migration backward-compatible cho roles.admin_access/app_access → policy-level admin_access/app_access/enforce_tfa/ip_allow/ip_deny/valid_from/valid_until.
  • [DB] Thêm stable key/system_key cho roles/policies để phục vụ import/export idempotent.
  • [DOC] Chốt danh sách system collections được đưa vào Permission Builder và nhóm sensitive/admin-only trước khi seed.
  • [BE] Định nghĩa JSON schema version lumibase.access@v1 cho export/import roles, policies, permission rows, bindings và API key metadata.

Schema & evaluator hardening

  • [DB] Thêm unique constraint (policy_id, collection, action) cho permissions; migration phải detect/report duplicate hiện có trước khi apply.
  • [DB] Thêm bảng user_roles để hỗ trợ nhiều role/user/site; giữ user_sites.role_id làm primary/display role trong giai đoạn chuyển đổi.
  • [DB] Thêm policy flags explicit vào policies; giữ policies.rules cho custom/future guardrails.
  • [BE] Mở rộng IP guard hỗ trợ IPv4, IPv6, CIDR và precedence ipDeny thắng ipAllow.
  • [BE] Enforce update/delete trong ItemService bằng action permission và row-level WHERE.
  • [BE] Enforce field whitelist cho create/update, bao gồm structural fields status/sort.
  • [BE] Enforce permission-level validation trong write path.
  • [BE] Enforce app access từ effective active policies khi vào Studio; API key luôn bị chặn khỏi Studio.
  • [BE] Enforce enforceTfa=true: user phải enroll và pass TFA; API key attach policy có TFA phải bị conflict/warning.
  • [BE] Mở rộng magic vars: $CURRENT_ROLES, $CURRENT_POLICIES, $CURRENT_API_KEY, nested $CURRENT_USER.*, $NOW(+/- duration).
  • [BE] Fail closed cho unknown operator/magic var; thêm test cho _null, _nnull, _empty, _nempty, _regex, case-insensitive string ops.

Conflict detection

  • [BE] Tạo AccessConflictService phân loại compatible, warning, blocking cho overlap cùng collection + action.
  • [BE] Block conflict unconditional-vs-restricted rule, ["*"] vs whitelist fields, validation/preset cùng field khác value, admin bypass + granular policy.
  • [BE] Endpoint POST /api/v1/access/conflicts/check nhận target role/user/api_key + add/remove policies và trả diff có source policy.
  • [BE] Tích hợp conflict check vào attach role-policy, user-policy, API-key-policy; cho phép override warning có audit.
  • [BE] Tích hợp conflict check vào attach role-policy và user-policy; warning override ghi audit.
  • [FE] Role Detail gọi conflict check trước khi attach policy; blocking conflict không cho lưu.
  • [FE] Permission Matrix thêm Effective View hiển thị quyền cuối cùng và source policies.
  • [TEST] Property tests cho conflict classifier với các tổ hợp field/rule/preset/validation.

API Keys theo Roles/Policies

  • [DB] Thêm api_keys, api_key_roles, api_key_policies với token hash, prefix, expire/revoke/last_used metadata.
  • [BE] Bearer auth lookup API key bằng hash; principal type api_key compile quyền giống user.
  • [BE] Rotate/revoke API key; plaintext chỉ trả một lần khi tạo/rotate.
  • [BE] Audit create/rotate/revoke/use-denied cho API key, không log plaintext token.
  • [SDK] Thêm client methods cho API key CRUD, attach roles/policies, conflict preview.
  • [FE] Studio API Keys page: create, rotate, revoke, attach roles/policies, preview effective permissions.
  • [TEST] API key không truy cập Studio; revoked/expired key bị 401; key chỉ thấy fields/rows theo policy.

Import / Export Permission Builder

  • [BE] GET /api/v1/access/export xuất roles, policies, permissions, bindings, API key metadata bằng stable keys, không chứa secrets.
  • [BE] POST /api/v1/access/import?dryRun=true parse/validate/diff/conflict-check nhưng không ghi DB.
  • [BE] Import modes: merge, replace-managed, replace-all; apply trong transaction và audit diff summary.
  • [BE] Idempotency tests: import cùng manifest nhiều lần không tạo duplicate.
  • [SDK] Thêm access export/import client types.
  • [FE] Import dialog hiển thị diff, warnings, blocking conflicts và kết quả dry-run.
  • [OPS] CLI lumibase access export/import cho CI/CD giữa dev/staging/prod.

System permissions & seeding

  • [DB] Cập nhật seed-dev.ts seed policy_admin, role_administrator, policy_studio_self, policy_public.
  • [DB] Seed explicit permissions cho nhóm schema/access manager: collections, fields, relations, roles, policies, permissions.
  • [DB] Đảm bảo sensitive collections (system_state, audit_log, login_attempts, admin_backup_codes, scim_tokens, api_keys) admin/security-only.
  • [FE] Permission Builder phân nhóm system collections và ẩn sensitive collections khỏi non-admin.
  • [TEST] Public policy mặc định không đọc được content/system collections nếu chưa explicit grant.

Extension access control

  • [DOC] Ghi rõ Directus extension permission layers: install/enable, sandbox scopes, accountability services, app module self-check.
  • [DB] Thêm stable extensions.key và system access targets extensions, extension_modules, extension_endpoints, extension_operations.
  • [BE] Enforce extensions:read/configure/install/enable/delete/grant_capability trên extension management routes.
  • [BE] Enforce extensions:execute trước khi dispatch /api/v1/extensions/:name/*.
  • [BE] Extension data access mặc định dùng actor permissions; service-account mode cần policy/capability riêng và audit.
  • [FE] Studio extension loader/module bar chỉ hiển thị extension principal được phép đọc.
  • [FE] Permission Builder thêm nhóm Extension Access để gán user/role truy cập extension.
  • [TEST] User thiếu extensions:execute không gọi được endpoint extension dù extension enabled.

Share action

  • [DB] Thêm bảng shares với role share chuyên dụng, password hash, validity window, max uses, revoke.
  • [BE] Implement share action: chỉ user có quyền share mới tạo share link; read payload vẫn đi qua role share permission.
  • [FE] Share dialog chỉ cho chọn role có appAccess=false, adminAccess=false, read permissions tối thiểu.
  • [TEST] Share link chỉ đọc fields/rows role share được phép, hết hạn/max uses/revoked đều bị deny.

Phase Docker Dual-Deployment (DONE)

Mục tiêu: chạy được toàn bộ stack trên Docker không cần Cloudflare account.

  • [RT] Tạo package @lumibase/runtime với 6 interface: CacheProvider, StorageProvider, DatabaseProvider, SearchProvider, QueueProvider, MediaProcessor.
  • [RT] Cloudflare adapters: KV, R2, Hyperdrive, MeiliSearch Cloud HTTP, CF Queues, CF Image Resizing.
  • [RT] Docker adapters: Redis (ioredis), MinIO/S3 (@aws-sdk/client-s3), pg pool (postgres), MeiliSearch self-host, BullMQ on Redis, Imgproxy với signed URLs.
  • [RT] Factory createRuntime(env) chọn theo LUMIBASE_RUNTIME.
  • [BE] Refactor middleware/db.ts để dùng DatabaseProvider.
  • [BE] Refactor routes dùng KV/R2 sang c.get('runtime').<provider>.
  • [BE] Tạo apps/cms/src/serve.ts Node entrypoint với graceful shutdown (SIGTERM, 10s timeout).
  • [BE] Endpoint /health test connectivity (db, cache, search, storage, queue).
  • [BE] Endpoint /metrics Prometheus exposition format.
  • [BE] Endpoint /api/v1/search qua SearchProvider.
  • [BE] Auto-index/remove items qua QueueProvider khi item create/update/delete.
  • [BE] Media processing hook: enqueue thumbnail generation (150/300/600) khi upload.
  • [OPS] docker/Dockerfile multi-stage (Node 20 slim, non-root, HEALTHCHECK).
  • [OPS] docker/Dockerfile.dev cho hot-reload.
  • [OPS] docker/scripts/entrypoint.sh chạy migrations với retry exponential backoff.
  • [OPS] docker/docker-compose.yml: Postgres 16, Redis 7, MinIO, MeiliSearch, Imgproxy, CMS, Bull Board.
  • [OPS] docker/docker-compose.monitoring.yml: Prometheus + Grafana + Loki + pg-backup.
  • [OPS] docker/docker-compose.prod.yml cho production-like local testing.
  • [OPS] Pre-provisioned Grafana dashboard (request rate, latency p50/p95/p99, error rate, queue depth, cache hit ratio).
  • [OPS] docker/scripts/backup.sh + restore.sh (pg_dump → S3, retention 7 daily / 4 weekly).
  • [OPS] Workflow CI .github/workflows/docker.yml (build & push GHCR trên main, build-only PR, layer caching, health check verify).
  • [DOC] apps/docs/content/deployment/{overview,cloudflare,docker,local-development,environment-variables}.md.
  • [DOC] apps/docs/content/guides/{tooling-recommendations,backup-recovery}.md.
  • [DOC] features/runtime-abstraction.md + features/observability.md + features/search.md.

Phase AI-First Copilot (DONE)

Mục tiêu: AI Agent tương tác an toàn với CMS qua HITL.

  • [DB] Bảng ai_approvals (id nanoid 21 + siteId + agentName + skillName + arguments jsonb + status + context + decidedAt + decidedBy).
  • [AI] Package @lumibase/ai-skills với CORE_SKILLS (listCollections, createCollection, deleteCollection, createField, deleteField, listItems, createItem, updateItem, deleteItem) + OpenAI tool definitions.
  • [BE] Service ai-harness.ts (validateSkill, checkCapabilities với wildcard *, evaluateRisk, execute, executeApproved, rejectApproval, runSkill timeout 30s).
  • [BE] Routes /api/v1/ai/chat, /api/v1/ai/approvals, /api/v1/ai/approvals/:id/decide.
  • [BE] Property tests fast-check (15 properties, 100+ iterations) + integration tests.
  • [FE] components/ai-assistant.tsx floating panel 320×480 glassmorphism, max 50 messages.
  • [FE] modules/settings/ai-approvals.tsx card list pending approvals với Approve/Reject.
  • [DOC] features/ai-copilot.md + giữ features/ai-first-specification.md lịch sử.

Phase POST-GA — Nâng cao (TODO / In progress)

  • [AI] Tích hợp LLM provider thật (OpenAI / Anthropic / Workers AI) thay cho mock intent parser trong /ai/chat.
  • [AI] Thêm context memory (lịch sử conversation) trong AI Copilot.
  • [AI] Skill aiSuggestField + aiContentAssist (RAG via embeddings).
  • [BE] Materialize collection write thực sự (không chỉ logical refresh) — bảng vật lý + trigger refresh.
  • [BE] Multi-region Durable Objects sharding.
  • [FE] Marketplace browser UI trong Studio (browse, install với 1 click).
  • [FE] Flows visual editor (drag-drop graph) — hiện chỉ có list page.
  • [BE] SCIM Token rotation + audit.
  • [OPS] Multi-tenant isolation testing tự động (k6 cross-site leak detection).

Phase Agent Harness Layer (DONE)

Mục tiêu: biến LumiBase thành control plane nơi humans, agents, data, workflows và applications cùng tiến hoá có kiểm soát. Checklist chi tiết nằm ở agent-harness-implementation.md.

A. Lifecycle nền tảng

  • [DB] Thêm agent_goals, agent_runs, agent_plans, agent_tool_calls với siteId, lifecycle status, policy snapshot, budget, audit metadata và indexes theo siteId/runId/goalId.
  • [BE] Tạo AgentRunService để open/append/close/fail/retry run; refactor AISecureHarness để mọi execute runtime đều gắn goalId/runId.
  • [TEST] Property tests mở rộng cho multi-tenant isolation, run failed vẫn giữ audit trail, retry không duplicate tool calls/artifacts.

B. Tool Registry + capability policy

  • [DB] Thêm agent_tools và agent_permissions để khai báo input/output schema, required capabilities, risk policy, rate limit và validity window.
  • [BE] Implement ToolRegistryService load core skills + DB overrides; enforce disabled tool, capability, risk policy và rate limit.
  • [FE] Studio page “Agent Harness” hiển thị tools, risk, approvals, runs, artifacts và memory.
  • [SDK] Thêm types/client methods cho tools, capabilities và risk policies.

C. Approval tổng quát

  • [DB] Thêm agent_approvals cho plan / tool_call / artifact / schema_diff; bridge backward-compatible với ai_approvals.
  • [BE] Approval policy engine nền tảng: none, before_execute, before_commit, two_person_rule, owner_only, security_admin_only ở contract/policy field.
  • [FE] Nâng bề mặt Studio thành queue Agent Harness có subject type, status và decision surface.
  • [TEST] Dangerous plan không execute trước approval; rejected/expired approval không commit được.

D. Artifact Store + Evaluation Gate

  • [DB] Thêm agent_artifacts và agent_evaluations với content hash, version, status, eval kind/status/score/details.
  • [BE] Artifact writers đầu tiên: schema_diff, page_spec, component_spec, seed_data, api_spec, prompt, migration.
  • [BE] Eval runners đầu tiên: JSON schema validation, schema/migration guard, generated API spec validation, prompt safety check.
  • [FE] Artifact review UI tối thiểu trong Studio Agent Harness: list artifact, status, hash, generated app artifacts.
  • [TEST] Artifact fail eval không publish được; artifact hash ổn định; publish/rollback idempotent.

E. Memory + App Generation MVP

  • [DB] Thêm agent_memory với scope, provenance, confidence, expiry và optional embedding.
  • [BE] RAG context builder tôn trọng expiry, provenance và redaction secrets.
  • [AI] Skills generateAppSpec, generateApiDocs, generateSeedData sinh artifact payload thay vì ghi thẳng vào content/schema.
  • [FE] Action “Generate” trong Agent Harness tạo app artifacts từ products/orders/customers với budget và approval policy.
  • [TEST] E2E demo: generate storefront từ products/orders/customers → plan → artifacts → eval → approval → publish.

F. Operations

  • [BE] Metrics cho run success/fail, approval latency, tool latency, eval fail rate, token/cost estimate và budget stop reason.
  • [OPS] Grafana dashboard “Agent Harness” và dead-letter queue cho run/tool call fail nhiều lần.
  • [DOC] Cập nhật data-model.md, architecture/overview.md, OpenAPI, SDK docs và runtime limitations cho từng phase.

Phase POST-GA8 — Directus Data Model Parity (DONE)

Mục tiêu: nâng cấp Data Model / Collections Builder để một collection trong LumiBase có contract rõ như Directus: metadata đầy đủ, primary key strategy, system fields, field config nâng cao, relation metadata, schema permission, diff/apply atomic, SDK/typegen/OpenAPI và test parity. Tham chiếu chi tiết: docs/en/features/directus-data-model-parity-tasks.md.

Milestone 1 — Correctness fixes trước khi mở rộng (DONE)

  • [FE] Collection wizard gửi đúng top-level payload (note, accountability, versioning, singleton, primaryKeyType, storageMode) thay vì nhét vào meta.
  • [BE] ItemService.patch/replace/softDelete enforce permission update/delete, row-level scope và field-level update allowlist.
  • [BE] Relation delete/dependency check đủ cả hai chiều manyCollection và oneCollection; block xoá field/collection khi còn relation trỏ tới.
  • [TEST] Thêm regression tests cho wizard payload, update/delete permission và relation dependency checks.

Milestone 2 — Collection metadata + primary key contract (DONE)

  • [DB] Thêm first-class collection columns: label, pluralLabel, hidden, system, primaryKeyField, primaryKeyType, storageMode, unarchiveValue, itemDuplicationFields, translations.
  • [BE] Backfill/migration backward-compatible; route validation và SchemaService dùng field mới, giữ meta cho extension/custom UI hints.
  • [SDK] Cập nhật collection input/output types và schema client methods cho metadata mới.
  • [FE] Wizard có các bước Identity, Storage, System fields, Permissions defaults, Review JSON.
  • [BE] Implement primary key strategy cho jsonb: nanoid, uuid, string; defer hoặc block rõ integer/bigInteger nếu chưa có sequence.
  • [TEST] Create item respect primary key strategy; duplicate user-provided ID trả 409.

Milestone 3 — System fields và field configuration parity

  • [BE] Extend compiled schema với systemFields (id, status, sort, user_created, user_updated, created_at, updated_at, deleted_at).
  • [FE] Fields tab hiển thị system fields trong locked group; cho cấu hình display/hidden/readonly/translations/width nhưng không cho xoá.
  • [DB] Thêm field metadata: label, note, defaultValue, nullable, unique, indexed, searchable, length, precision, scale, special.
  • [FE] FieldInspector advanced tabs: Basics, Options, Display, Validation, Conditions, Layout, Storage, Translations.
  • [BE] Tách create/update/rename/delete/migration field path; reject đổi type/name khi đã có data nếu chưa có migration plan.
  • [TEST] FieldInspector không làm mất unknown options/displayOptions/validation/conditions; risky changes trả 409 hoặc cần confirm.

Milestone 4 — Relations parity và deep read

  • [BE] Validate relation references: collection/field tồn tại, relation name không duplicate, onDelete hợp lệ theo storage mode.
  • [DB] Mở rộng relation metadata: type, aliasField, relatedDisplayTemplate, junctionManyField, junctionOneField.
  • [BE] Hỗ trợ relation types m2o, o2m, m2m; reserve m2a và trả "not implemented" nếu chọn.
  • [BE] Implement relation expansion cho item query (fields=author.name,categories.*, deep[...]) với permission masking cho related collections.
  • [TEST] M2O trả object khi request expand; O2M/M2M trả array; batching tránh N+1 ở case phổ biến.

Milestone 5 — Schema permissions, diff/apply và storage positioning

  • [BE] Thêm schema permission actions: schema:read/create/update/delete/migrate.
  • [BE] Áp dụng requireSchemaPermission cho collections/fields/relations/compiled schema routes và AI schema skills.
  • [BE] Expand schema diff: collection metadata, field metadata, relation changes, risk classification và runtime impact.
  • [BE] PUT /collections/:name/schema validate toàn bộ, compute diff, apply transactionally khi runtime hỗ trợ, invalidate schema/permission/typegen cache và emit schema.changed.
  • [FE] Raw JSON schema tab hiển thị diff/risk trước khi apply.
  • [DOC] Ghi rõ storage modes jsonb/materialized/physical/external, kèm limitations badge trong Studio.
  • [DOC] Tạo design doc docs/en/architecture/physical-collections.md để quyết định physical/external mode.

Milestone 6 — SDK, typegen, OpenAPI, docs và parity tests

  • [SDK] Mở schema resources đầy đủ: collections/fields/relations CRUD, field rename/delete options, schema diff/apply.
  • [SDK] Giữ legacy methods hoặc deprecation wrapper; preserve error code/path/risk metadata.
  • [SDK] Typegen include primary key type, system fields, nullable/required, readonly/generated và relation-expanded response types.
  • [DOC] Cập nhật apps/cms/openapi.yaml, docs/en/features/collections-builder.md, docs/en/features/field-types-and-config.md, docs/en/data-model.md.
  • [DOC] Sync bản tiếng Việt sau khi English contract ổn định.
  • [TEST] Backend/frontend/SDK parity suite đủ các acceptance criteria trong directus-data-model-parity-tasks.md.

Cross-cutting checklist (mỗi phase)

  • Cập nhật architecture.md nếu thay đổi cấu trúc.
  • Viết unit + integration test trước khi merge; với logic phức tạp dùng property-based testing (fast-check).
  • Cập nhật OpenAPI spec (apps/cms/openapi.yaml) cho mọi endpoint mới.
  • Cập nhật packages/sdk types tương ứng.
  • Cập nhật docs trong docs/features/ hoặc apps/docs/content/.
  • Làm trực tiếp trên main theo chỉ dẫn repo hiện tại; commit theo conventional commits và push thẳng để giảm conflict với các luồng song song.
  • Đảm bảo route mới hoạt động trên CẢ hai runtime (Cloudflare + Docker) — nếu phụ thuộc API cụ thể, gate bằng feature flag và document trong features/runtime-abstraction.md.
Last modified: 26/09/2026