Cơ sở dữ liệu

Cloudflare D1, database conan-compass. Một database cho cả ba mặt phẳng của Conan1.

File	Nội dung
0001_init.sql	Bảng lõi: năng lực, Brand, đánh giá, người dùng, nhật ký
0002_seed.sql	Sinh tự động từ scripts/model.mjs
0003_execution.sql	Tầng thực thi và chuyển đổi
0004_execution_seed.sql	Sinh tự động từ scripts/execution.mjs
0005_planes.sql	Hai mặt phẳng Products và Requirements, cộng sequences
0006_planes_seed.sql	Sinh tự động từ scripts/planes.mjs (và trường product / repository trong execution.mjs)
0007_requirement_depth.sql	Tiêu chí chấp nhận thành dòng và phụ thuộc giữa các yêu cầu — cộng thêm, chỉ tạo bảng mới
0008_requirement_depth_seed.sql	Sinh tự động từ scripts/planes.mjs — 12 tiêu chí tách từ văn xuôi nghiệm thu, 2 phụ thuộc; toàn INSERT OR IGNORE

capabilities — mô hình chuẩn

Cột	Kiểu	Ghi chú
id	TEXT PK	CAP-02-01-03 — bản thân ID thể hiện cây
code	TEXT UNIQUE	slug dùng trong URL
level	INTEGER	1–3
parent_id	TEXT FK	NULL với L1
sort	INTEGER	thứ tự hiển thị
name_en / name_vi	TEXT	song ngữ
definition_en / definition_vi	TEXT	mô tả WHAT
status	TEXT	active · draft · deprecated

Khoá ngoại parent_id dùng ON DELETE RESTRICT: không thể xoá một năng lực còn con.

brands

id dạng BRD-nemo12, code là slug, tên và mô tả song ngữ, status là active · draft · archived. Brand là bản sắc thị trường và phạm vi của Compass; nó không phải sản phẩm — xem Mô hình Products.

brand_capabilities — thực tế của Brand

Một dòng ở đây nghĩa là Brand đã kích hoạt năng lực đó.

Cột	Ghi chú
importance, priority, health, maturity, target_maturity	1–5, cho phép NULL
likelihood, impact, detectability	1–5, ba nguyên nhân của risk
owner	tên người chịu trách nhiệm
rationale	bắt buộc khi priority = 5
notes	ghi chú tự do

UNIQUE (brand_id, capability_id) đảm bảo mỗi Brand chỉ có một đánh giá cho mỗi năng lực.

Điểm rủi ro không được lưu thành cột. Nó là tích của ba nguyên nhân và được tính khi hiển thị — lưu lại chỉ tạo cơ hội để nó lệch khỏi nguồn.

users

Cột	Ghi chú
email	PK, khớp với email trong Access JWT
role	architect · executive · brand_owner · viewer
brand_id	phạm vi của brand_owner

audit_log

actor, action, entity, entity_id, before, after (JSON), created_at. Mọi thao tác ghi đều tạo một dòng. Bảng này không bao giờ bị xoá.

Tầng thực thi (0003_execution.sql)

Bảng	Vai trò
value_streams	Chuỗi giá trị, mỗi chuỗi nêu rõ stakeholder_en/vi
value_stream_stages	Chặng, mang câu statement_en/vi (phép thử "Tôi") và outcome_en/vi
stage_capabilities	Chặng phụ thuộc vào năng lực nào
processes	Quy trình L4, gắn với một năng lực, brand_id rỗng nghĩa là dùng chung
activities	Bước trong quy trình, có thứ tự
applications	Danh mục ứng dụng, có vòng đời; từ 0005 thêm product_id và repository
data_entities	Thực thể dữ liệu, có steward và mức phân loại
technologies	Công nghệ nền
capability_applications, capability_data	Năng lực ↔ ứng dụng, năng lực ↔ dữ liệu
application_technologies, application_data	Ứng dụng ↔ công nghệ, ứng dụng ↔ dữ liệu

Công nghệ không có bảng nối trực tiếp tới năng lực. Quan hệ đó được suy ra qua ứng dụng, nên không thể xuất hiện mâu thuẫn giữa hai đường dẫn.

Chuyển đổi

Bảng	Vai trò
initiatives	Sáng kiến, trạng thái, giai đoạn, đầu tư, tiến độ
initiative_capabilities	Sáng kiến cải thiện năng lực nào
kpis	Baseline / current / target, neo vào đúng một trong capability_id hoặc stage_id (cưỡng chế bằng CHECK)

OKR (0015_okr.sql)

Bảng	Vai trò
objectives	Kết quả muốn đạt: neo vào capability_id hoặc stage_id (CHECK), strategic_objective_id nối lên chiến lược, owner, period, status
key_results	Thước đo dưới một Objective: direction (up/down), baseline / current / target, status, và kpi_id trỏ về KPI nó được chuyển từ đó

Xem OKR về luật chuyển đổi và ý nghĩa của not_measured.

Products và Requirements (0005_planes.sql)

Bảng	Vai trò
sequences	name, last — bộ đếm cho id REQ- Q- D- EVI- REL- AC-, cấp bằng UPDATE … RETURNING
products	Sản phẩm: mệnh đề giá trị, miền kinh doanh domain_en/vi, kind, status; brand_id = NULL là nền tảng Conan1
product_capabilities	Năng lực ↔ sản phẩm — mắt xích đầu của chuỗi truy vết
application_urls	Điểm truy cập của ứng dụng, url UNIQUE, kind
features	Khả năng của sản phẩm, gắn ứng dụng và năng lực
requirements	Yêu cầu: Intent / User / Problem / Outcome / Acceptance, product_id NOT NULL … ON DELETE RESTRICT
questions	Câu hỏi hạng nhất: câu trả lời nháp, gợi ý đã chọn, câu trả lời cuối, người trả lời
ai_runs	Mỗi lần gọi Workers AI: model, phiên bản prompt, token, trạng thái
ai_suggestions	Văn bản do AI sinh — chỉ ở đây, bất biến
decisions	Bộ nhớ quyết định: tuyên bố, lý do, người quyết, phân tích AI, neo
decision_links	Dải Liên quan đóng băng lúc quyết
evidence	PR, commit, deployment, ảnh, tài liệu, mockup — điểm cuối của chuỗi
releases	Bản phát hành của một ứng dụng: version, released_at, status
release_requirements	Yêu cầu nào ra trong bản nào

Hai bảng thêm ở 0007_requirement_depth.sql, cùng mặt phẳng Requirements:

Bảng	Cột	Vai trò
acceptance_criteria	id (AC-NNNN), requirement_id (ON DELETE CASCADE), brand_id (ON DELETE SET NULL), sort, name_en/vi, description_en/vi, evidence_id (ON DELETE SET NULL), status CHECK (pending·met·failed), created_at, updated_at	Một dòng một tiêu chí nghiệm thu, mang được trạng thái và trỏ được sang bằng chứng đã chốt nó. Chỉ mục theo requirement_id và brand_id
requirement_dependencies	requirement_id, depends_on_id, PRIMARY KEY cả cặp, CHECK (requirement_id <> depends_on_id), cả hai ON DELETE CASCADE	"Cái này chờ cái kia." Một chiều; chỉ mục ngược theo depends_on_id cho chiều Chặn

requirements.acceptance_en/vi không bị bỏ: chúng là bản dự phòng khi một yêu cầu chưa có dòng acceptance_criteria nào. Không có cột blocked — trạng thái bị chặn được tính từ trạng thái của các yêu cầu đang chờ.

Chi tiết cột ở Mô hình Products, Requirements, Làm rõ có AI hỗ trợ và Quyết định.

Hai ràng buộc đáng nhớ: ai_suggestions có CHECK ((kind = 'question') = (question_id IS NULL)) — gợi ý câu hỏi thì chưa có câu hỏi, gợi ý trả lời thì phải có; và requirements.product_id là ON DELETE RESTRICT — không xoá được sản phẩm còn yêu cầu.

Quy ước brand_id

Với processes, applications, value_streams, initiatives và kpis, brand_id = NULL nghĩa là dùng chung toàn doanh nghiệp, không phải "thiếu dữ liệu". Giao diện hiển thị nhãn Dùng chung, và khi xem ở phạm vi một Brand thì các bản ghi dùng chung vẫn hiện.

Với products, features, requirements, questions, decisions, evidence và releases, NULL nghĩa là nền tảng Conan1 (nhãn Nền tảng Conan1), cùng quy tắc hiển thị. Trên features, requirements, questions, evidence, releases, cột này do Worker điền từ bản ghi cha — người dùng không gõ.

Nạp lại dữ liệu

cd api.conan1.com
node scripts/seed.mjs   # sinh lại 0002, 0004, 0006 và 0008 từ scripts/model.mjs + execution.mjs + planes.mjs
npm run db:local        # nạp toàn bộ migrations vào D1 local

Đưa lên production: sao lưu trước, rồi dựng lại — xem Chuyển dữ liệu.

npx wrangler d1 export conan-compass --remote --output=backup.sql
npm run db:remote

DANGER

0001, 0003 và 0005 bắt đầu bằng DROP TABLE IF EXISTS; các file seed (0002, 0004, 0006) bằng DELETE FROM, và 0006 còn đặt lại sequences. npm run db:remote trên production xoá sạch dữ liệu hiện có — và chạy riêng 0005 / 0006 cũng xoá sạch hai mặt phẳng Products và Requirements, không phải cộng thêm. Hôm nay điều đó chấp nhận được vì mọi thứ đều đến từ seed. Ngay khi production có yêu cầu hay quyết định do người nhập, không chạy lại file nào từ 0001 đến 0006; mọi thay đổi schema hay dữ liệu về sau phải là một file migration mới, tăng số thứ tự (0007 trở đi), không DROP / DELETE bảng, áp dụng riêng bằng wrangler d1 execute --remote --file=… — xem Chuyển dữ liệu.

0007 và 0008 là ví dụ đầu tiên của đường đi cộng thêm đó: CREATE TABLE IF NOT EXISTS, INSERT OR IGNORE, UPDATE sequences SET last = MAX(last, 12) — không DROP, không DELETE dòng nào, không đặt lại bộ đếm, không chạm bảng đã có. Hai file này áp dụng được lên database đang chạy đã có yêu cầu và quyết định thật, và chạy lại được mà không mất gì — khác hẳn 0005 / 0006:

npx wrangler d1 execute conan-compass --remote --file=migrations/0007_requirement_depth.sql
npx wrangler d1 execute conan-compass --remote --file=migrations/0008_requirement_depth_seed.sql

Hai bảng mới chỉ bị xoá bởi 0001_init.sql và 0003_execution.sql, tức đường dựng lại toàn bộ. 0007 cố ý không có dòng DROP nào, và chính file đó nói vì sao: xoá ở đây sẽ khiến chạy lại file này "erase hand-entered criteria and dependencies, which is exactly what an additive migration must not do".