Truy vết

Compass và Requirements nối với nhau mà không trộn vào nhau. Chuỗi nối là khoá ngoại thật, giải một lần, đọc ở mọi nơi.

Enterprise Capability        Compass
    ↓  product_capabilities
Product                      Products
    ↓  applications.product_id
Application
    ↓  features.application_id
Feature
    ↓  requirements.feature_id
Requirement                  Requirements
    ↓  evidence.requirement_id
Evidence

Đầu "cái gì chứng minh" của chuỗi có hai bản ghi chứ không một: bằng chứng là sản phẩm kỹ thuật, tiêu chí chấp nhận là câu phải đúng — và tiêu chí trỏ sang bằng chứng đã chốt nó:

Requirement  REQ-1832
    ├── acceptance_criteria.requirement_id → AC-0007  status = met
    │                                            ↓  acceptance_criteria.evidence_id
    └── evidence.requirement_id            → EVI-0001  kind = pr, status = verified

Ví dụ đọc xuôi:

Learner Acquisition → Nemo12 → nemo12.com → Referral System → REQ-0241
→ "Phụ huynh có thể mời một gia đình khác" → PR → Deployment → Evidence verified

Đọc ngược: Evidence ↑ Requirement ↑ Feature ↑ Product ↑ Brand ↑ Conan1.

Xương sống được lưu bằng khoá ngoại

Mắt xích	Lưu ở
Capability → Product	`product_capabilities (product_id, capability_id)`
Product → Application	`applications.product_id`
Application → Feature	`features.application_id` (cùng `features.product_id`, `features.capability_id`)
Feature → Requirement	`requirements.feature_id` (cùng `product_id`, `application_id`, `capability_id`, `initiative_id`)
Requirement → Evidence	`evidence.requirement_id`
Requirement → Acceptance Criterion	`acceptance_criteria.requirement_id`
Acceptance Criterion → Evidence	`acceptance_criteria.evidence_id` — `ON DELETE SET NULL`
Requirement → Requirement	`requirement_dependencies (requirement_id, depends_on_id)` — một chiều, `requirement_id` chờ `depends_on_id`
Requirement → Release	`release_requirements`
Compass → Requirements	`requirements.initiative_id` — cầu nối duy nhất từ sáng kiến chuyển đổi sang yêu cầu

Không có bảng "trace". Chuỗi được giải từ các cột này, ở hai nơi cùng một quy tắc: client (src/lib/trace.ts → traceOf(requirement, arch)) và Worker (src/lib/trace.ts → loadTrace(env, requirementId), cũng phục vụ GET /v1/requirements/:id/trace).

Quy tắc "cột tường minh thắng"

Một yêu cầu có thể tự khai application_id và capability_id, hoặc để trống và nhờ feature:

Cột tường minh trên yêu cầu thắng.
Cột NULL thừa hưởng từ feature (feature.application_id, feature.capability_id).
Năng lực vẫn rỗng thì lấy năng lực đầu tiên của sản phẩm (product_capabilities).
Sản phẩm không bao giờ rỗng (product_id NOT NULL).

Kết quả là { capability?, initiative?, product, brand?, application?, feature?, requirement, evidence[] }, được component TraceChain vẽ thành chuỗi chip có liên kết trên đầu trang chi tiết yêu cầu, trang chi tiết quyết định, từng dòng feature trên trang sản phẩm và hộp thoại sáng kiến.

Sai

Ghi năng lực và ứng dụng lên mọi yêu cầu, rồi sửa 40 dòng khi feature chuyển sang ứng dụng khác.

Đúng

Để yêu cầu thừa hưởng từ feature. Chỉ khai tường minh khi yêu cầu này thật sự chạm một ứng dụng hay năng lực khác feature của nó — ví dụ một yêu cầu của Referral System lại nằm ở nemo12-api.

Quyết định nối vào chuỗi bằng cách khác: decision_links được ghi tại thời điểm quyết từ kết quả loadTrace — lịch sử đóng băng, không phải join sống. Xem Quyết định.

Yêu cầu chờ yêu cầu

Chuỗi truy vết đi xuống (năng lực → bằng chứng). Phụ thuộc đi ngang: requirement_dependencies nói "cái này chưa ra được cho tới khi cái kia ra".

REQ-1832  Gắn nhãn mục tiêu cho sản phẩm học tập
    ↑  requirement_dependencies (requirement_id = REQ-1833, depends_on_id = REQ-1832)
REQ-1833  Dòng thời gian bằng chứng          → chờ REQ-1832
REQ-1834  Ngưỡng cảnh báo tuyên bố           → chờ REQ-1832

Thuộc tính	Ghi chú
Chiều	Một chiều duy nhất: `requirement_id` chờ `depends_on_id`. Chặn không phải bảng thứ hai, chỉ là cùng dòng đó đọc từ phía `depends_on_id`
Khoá chính	`(requirement_id, depends_on_id)` — thêm lại cùng một cặp không sinh dòng thừa
`CHECK (requirement_id <> depends_on_id)`	Một yêu cầu không phụ thuộc chính nó
Xoá yêu cầu	`ON DELETE CASCADE` cả hai phía — quan hệ biến mất cùng bản ghi
Quyền ghi	Quan hệ `requirement-dependencies`, chỉ `architect`

Trạng thái "bị chặn" không được lưu

Không có cột blocked. Trang chi tiết tính nó tại chỗ: yêu cầu bị chặn khi có ít nhất một yêu cầu nó đang chờ chưa ở trạng thái shipped. Cùng lý do với điểm rủi ro của Compass — lưu một giá trị suy ra được chỉ tạo cơ hội để nó lệch khỏi nguồn.

Bộ chọn Thêm phụ thuộc trên giao diện đã loại sẵn chính nó và mọi yêu cầu đã nối theo bất kỳ chiều nào, vì Worker sẽ từ chối những trường hợp đó bằng 400 — xem Endpoints.

Tiêu chí chấp nhận nối vào bằng chứng

acceptance_criteria là đầu "cái gì chứng minh" của chuỗi, đứng cạnh evidence chứ không thay thế nó:

Tiêu chí là câu phải đúng (name_*), kèm cách kiểm (description_*) và status pending · met · failed.
Bằng chứng là sản phẩm kỹ thuật đã có thật (PR, deployment, ảnh chụp).
acceptance_criteria.evidence_id nối tiêu chí sang bằng chứng đã chốt nó. Giao diện chỉ cho chọn bằng chứng của chính yêu cầu đó — bằng chứng của yêu cầu khác không chứng minh tiêu chí này.
Khoá ngoại là ON DELETE SET NULL: xoá bằng chứng thì tiêu chí ở lại, chỉ mất phần trỏ. ON DELETE CASCADE sẽ nghĩa là xoá bằng chứng thì tiêu chí biến mất — mất đúng câu hỏi đang cần trả lời.

Danh sách /requirements cộng số này lên thành ô Tiêu chí đã đạt (met / tổng) trong phạm vi đang xem, cạnh Câu hỏi còn mở, Quyết định trong quý này và Chưa có bằng chứng.

Compass đọc chuỗi mà không sở hữu nó

Compass chỉ thêm thẻ chỉ đọc, tính từ gói arch bằng hai helper requirementsOf(entity, id, arch) và decisionsFor(entity, id, arch):

Ở đâu trên Compass	Thẻ
`/model/:code` (chi tiết năng lực)	Products · Requirements (kèm liên kết Xem tất cả → `/requirements?capability=…`) · Decisions
`/transformation` (hộp thoại sáng kiến)	Nhóm Requirements với chip trạng thái, chip đếm trên thẻ sáng kiến, và liên kết Yêu cầu mới → `/requirements?new=1&initiative=…&capability=…`
`/applications`	Chip sản phẩm và URL chính, tiêu đề dẫn sang `/products/applications/:code`

Không có form tạo yêu cầu nào trên Compass. Compass là bản đồ, không phải backlog.

Hai hành trình kiểm chứng

Hành trình 1 — "Vì sao phụ huynh không được sửa điểm thành thạo?"/requirements/decisions → lọc mastery → D-0182: tuyên bố, lý do, người quyết, phân tích AI thu gọn, dải Liên quan → REQ-0218, Q-0881, sản phẩm Nemo12, năng lực Assessment & Evidence, ứng dụng nemo12-learn. Từ Compass: /model/assessment → thẻ Decisions → cùng bản ghi, một cú bấm.

Hành trình 2 — chiến lược → khoảng cách → sáng kiến → sản phẩm → yêu cầu → kỹ thuật./gaps → năng lực Assessment & Evidence yếu → thẻ Initiatives → sáng kiến Evidence Engine trên /transformation → Yêu cầu mới → /requirements/REQ-1832 mở với chuỗi Assessment & Evidence › Nemo12 › coral.nemo12.com › Evidence Engine › REQ-1832 và kết thúc bằng Evidence — trạng thái verified của một deployment là tín hiệu "kỹ thuật đã đóng vòng". Chiều ngược: /products/nemo12 liệt kê feature → yêu cầu → bằng chứng.

Rule 9 – 11

GET /v1/governance kiểm tra thêm ba quy tắc và hai cảnh báo, cùng dạng issues như tám quy tắc của Compass:

Id	Quy tắc	Ý nghĩa
`rule-9-requirement-capability`	Yêu cầu phải truy được về một năng lực ✅ tự động	Yêu cầu chưa `dropped` mà `capability_id` rỗng, feature không có năng lực, và sản phẩm không có `product_capabilities` — một yêu cầu không phục vụ năng lực nào là một yêu cầu không có lý do tồn tại ở cấp doanh nghiệp
`rule-10-decision-rationale`	Quyết định phải có lý do ✅ tự động	Quyết định `decided` mà `rationale_en` trống
`rule-11-product-capability`	Sản phẩm phải hiện thực hoá ít nhất một năng lực ✅ tự động	Sản phẩm không có dòng nào trong `product_capabilities`
`feature-brand-mismatch`	Cảnh báo	`features.brand_id` khác `products.brand_id` — phạm vi bị lệch, Worker lẽ ra đã điền đúng
`application-without-product`	Cảnh báo	Ứng dụng thuộc một Brand (`brand_id` khác `NULL`) nhưng chưa có `product_id` — có chủ Brand mà không có chủ sản phẩm

Dữ liệu mẫu được nạp không vi phạm quy tắc nào: mọi yêu cầu có năng lực (trực tiếp hoặc qua feature), D-0182 có lý do, ba sản phẩm đều có năng lực.

Phạm vi và quyền dọc theo chuỗi

brand_id được phi chuẩn hoá lên mọi bảng theo Brand — sản phẩm, feature, yêu cầu, câu hỏi, quyết định, bằng chứng, release — để inScope, bộ chọn phạm vi và giá trị mặc định của form dùng lại y nguyên. Worker điền cột này từ bản ghi cha (brandFrom) trước khi kiểm tra quyền: feature từ sản phẩm, yêu cầu từ sản phẩm, câu hỏi và bằng chứng từ yêu cầu, release từ ứng dụng. Người dùng không bao giờ gõ brand_id, và không thể gắn bản ghi vào Brand khác.

Quyền thì khác nhau theo mặt phẳng: Products theo phạm vi Brand (canEditScope), Requirements chỉ architect (canEditModel). Xem Phân quyền.

Truy vết ​

Xương sống được lưu bằng khoá ngoại ​

Quy tắc "cột tường minh thắng" ​

Yêu cầu chờ yêu cầu ​

Tiêu chí chấp nhận nối vào bằng chứng ​

Compass đọc chuỗi mà không sở hữu nó ​

Hai hành trình kiểm chứng ​

Rule 9 – 11 ​

Phạm vi và quyền dọc theo chuỗi ​