Requirements

compass.conan1.com/requirements

Products trả lời Conan đang xây cái gì. Requirements trả lời nó phải làm được chính xác điều gì — và vì sao đã quyết như vậy.

Một yêu cầu không phải một dòng trong backlog. "Phụ huynh xem được tiến bộ của người học" chỉ có nghĩa khi trả lời được: tiến bộ là gì, ai được xem, cập nhật bao lâu một lần, cần bằng chứng gì, thiếu bằng chứng thì sao. Mặt phẳng này lưu câu hỏi, câu trả lời, quyết định và bằng chứng quanh mỗi yêu cầu — để sáu tháng sau, khi CEO hỏi "vì sao phụ huynh không được sửa điểm thành thạo?", hệ thống trả lời được bằng một bản ghi chứ không bằng trí nhớ của ai đó.

Requirements là bộ nhớ quyết định của tổ chức, không chỉ là backlog.

Product
    ↓
Feature
    ↓
Requirement  REQ-0241
    ├── Intent · User · Problem · Outcome
    ├── Acceptance Criterion  AC-0004  ← một dòng một bản ghi, trỏ tới bằng chứng đã chốt nó
    ├── Question  Q-0881          ← có AI hỗ trợ làm rõ
    │       └── Decision  D-0182  ← con người quyết
    ├── Mockup                    ← evidence, kind = mockup
    ├── Evidence  EVI-0001        ← PR, commit, deployment, ảnh chụp, tài liệu
    ├── Depends on  REQ-1832      ← yêu cầu này chờ yêu cầu kia
    └── Release   REL-0001        ← ra trong bản nào

Id đọc lên được

Yêu cầu, câu hỏi, quyết định được nhắc tên trong họp — "REQ-0241", "D-0182" — nên chúng có id ngắn, tuần tự, toàn hệ thống, không theo Brand:

Thực thể	Id	Bảng đếm
Requirement	REQ-0001	sequences('requirements')
Question	Q-0001	sequences('questions')
Decision	D-0001	sequences('decisions')
Acceptance Criterion	AC-0001	sequences('acceptance_criteria')
Evidence (kể cả mockup)	EVI-0001	sequences('evidence')
Release	REL-0001	sequences('releases')

Số được cấp nguyên tử bằng UPDATE sequences SET last = last + 1 … RETURNING last, đệm bốn chữ số. Feature giữ id dạng slug (FEA-referral-system) vì nó là khái niệm sản phẩm, không phải bản ghi bộ nhớ.

Requirement

Bảng requirements, ID REQ-NNNN.

Thuộc tính	Ghi chú
product_id	Bắt buộc. Sản phẩm đã có yêu cầu thì retired, không xoá được (ON DELETE RESTRICT)
feature_id	Feature chứa yêu cầu — mỗi yêu cầu thuộc đúng một feature
application_id · capability_id	Tuỳ chọn; để trống thì thừa hưởng từ feature
initiative_id	Cầu nối duy nhất từ Compass sang: sáng kiến chuyển đổi nào sinh ra yêu cầu này
brand_id	Phạm vi, Worker tự điền từ sản phẩm
name_en / name_vi	Yêu cầu trong một câu
intent_* · user_* · problem_* · outcome_*	Ý định · Người dùng · Vấn đề · Kết quả — bốn khối tường thuật song ngữ
acceptance_*	Văn xuôi tiêu chí nghiệm thu, mỗi dòng một tiêu chí — bản dự phòng khi yêu cầu chưa có dòng acceptance_criteria nào
priority	1–5
owner	Người chịu trách nhiệm
status	draft → clarifying → ready → building → shipped, hoặc dropped

Yêu cầu bắt đầu ở draft. Thêm câu hỏi đầu tiên tự chuyển nó sang clarifying. Một yêu cầu có bằng chứng deployment đã verified có thể được một người đánh dấu shipped.

Sai

Yêu cầu: "Tích hợp Figma và làm dashboard cho phụ huynh."

Đúng

• Intent: Phụ huynh hiểu con đang tiến bộ ở đâu mà không phải hỏi giáo viên
• User: Phụ huynh của người học Nemo12
• Problem: Hôm nay phụ huynh phải hỏi mới có thông tin
• Outcome: Phụ huynh mở Learner Dashboard là thấy tiến bộ theo bằng chứng
• Acceptance: một dòng một tiêu chí, kiểm chứng được

Yêu cầu nói cái gì phải đúng, không nói dùng công cụ gì. Công cụ là chuyện của Application và Evidence.

Acceptance Criterion

Bảng acceptance_criteria, ID AC-NNNN. Văn xuôi nhiều dòng đọc thì xuôi nhưng không theo dõi được gì: không nói được tiêu chí nào đã đạt, cũng không chỉ được bằng chứng đã chốt nó. Một dòng một tiêu chí thì nói được.

Thuộc tính	Ghi chú
requirement_id	Bắt buộc; xoá yêu cầu thì xoá tiêu chí (ON DELETE CASCADE)
brand_id	Phạm vi, Worker tự điền từ yêu cầu
sort	Thứ tự hiển thị trong thẻ
name_en / name_vi	Tiêu chí, đúng một câu
description_en / description_vi	Kiểm bằng cách nào; mặc định rỗng
evidence_id	Bằng chứng chốt tiêu chí này — ON DELETE SET NULL
status	pending · met · failed

Hai cột văn xuôi requirements.acceptance_en/_vi vẫn còn và vẫn được ghi. Trang chi tiết yêu cầu hiện các dòng khi yêu cầu đã có dòng, và rơi về văn xuôi khi chưa có dòng nào — kèm thanh tiến độ đã đạt / tổng ở đầu thẻ. Migration 0008_requirement_depth_seed.sql chuyển dữ liệu mẫu từng dòng một, được 12 tiêu chí.

WARNING

evidence_id là ON DELETE SET NULL, không phải CASCADE: xoá bằng chứng không được xoá luôn tiêu chí mà nó lẽ ra chứng minh. Tiêu chí ở lại, chỉ mất phần trỏ tới bằng chứng.

Phụ thuộc giữa các yêu cầu

Bảng requirement_dependencies (requirement_id, depends_on_id) — "cái này chưa ra được cho tới khi cái kia ra". Một chiều: requirement_id chờ depends_on_id. Chiều ngược lại là cùng một dòng đọc từ phía bên kia, nên trang chi tiết hiện cả Chờ và Chặn mà không cần bảng thứ hai. Chi tiết ở Truy vết.

Question

Câu hỏi là thực thể hạng nhất, không phải ghi chú. Mỗi câu hỏi lưu riêng câu trả lời con người viết, các gợi ý của AI, phương án đã chọn, phần con người sửa và câu trả lời cuối — vòng đời open → suggested → answered → decided. Toàn bộ ở Làm rõ có AI hỗ trợ.

Decision

Quyết định D-NNNN luôn có tuyên bố, lý do, người quyết (email từ Cloudflare Access) và một dải Liên quan được đóng băng tại thời điểm quyết. Không bao giờ bị xoá — chỉ superseded hoặc reverted. Toàn bộ ở Quyết định.

Mockup và Evidence

Bảng evidence, ID EVI-NNNN — điểm cuối của chuỗi truy vết đi xuống: sản phẩm kỹ thuật chứng minh yêu cầu đã được làm.

Thuộc tính	Ghi chú
requirement_id	Bắt buộc; xoá yêu cầu thì xoá bằng chứng
kind	issue · pr · commit · deployment · test · screenshot · mockup · doc · metric
url	Đường dẫn tới PR, commit, deployment, ảnh, tài liệu…
status	pending · verified · rejected

Mockup là evidence với kind = mockup (URL + ghi chú), hiện trong danh sách Mockups riêng phía trên các bằng chứng khác trên trang chi tiết yêu cầu. Không có bảng riêng, không tải file, không tích hợp GitHub — chỉ đường dẫn và ghi chú.

Release

Yêu cầu ra trong bản phát hành nào được ghi ở release_requirements; trang chi tiết yêu cầu có dải Releases. Bản ghi Release thuộc một ứng dụng và được mô tả ở Mô hình Products.

Màn hình

Màn hình	Đường dẫn	Mục đích
Requirements	/requirements	Bốn ô số theo phạm vi đang xem — Câu hỏi còn mở, Quyết định trong quý này, Chưa có bằng chứng, Tiêu chí đã đạt — rồi danh sách theo sản phẩm; lọc theo product, status, initiative, capability, feature trong query string; ?new=1 mở form tạo với giá trị mặc định từ query
Requirement Detail	/requirements/:id	Chuỗi truy vết trên đầu trang, bốn khối tường thuật, tiêu chí chấp nhận, phụ thuộc, câu hỏi, gợi ý AI, quyết định, mockup, bằng chứng, release
Questions	/requirements/questions	Hộp thư câu hỏi còn open / suggested của mọi yêu cầu trong phạm vi — màn hình làm việc hằng ngày
Decisions	/requirements/decisions	Tìm theo id, tuyên bố, lý do; lọc trạng thái
Decision Detail	/requirements/decisions/:id	Tuyên bố, lý do, người quyết, phân tích AI, dải Liên quan, thay thế / bị thay thế, nhật ký

Compass tạo yêu cầu bằng liên kết, không bằng dialog: hộp thoại sáng kiến trên /transformation có nhóm Requirements và liên kết Yêu cầu mới trỏ tới /requirements?new=1&initiative=INI-…&capability=CAP-…. Mọi thao tác tạo/sửa yêu cầu, câu hỏi, quyết định, bằng chứng đều diễn ra dưới /requirements.

Ai được ghi

Mặt phẳng Requirements là của kiến trúc sư. requirements, questions, decisions, evidence, acceptance-criteria, releases, quan hệ requirement-dependencies và mọi endpoint riêng của mặt phẳng này yêu cầu vai trò architect; executive và brand_owner chỉ đọc (API trả 403). Giao diện ẩn mọi nút Thêm / Sửa / Trả lời / Quyết / Gợi ý / Thu hồi sau canEditModel.

brand_id vẫn được điền lên yêu cầu, câu hỏi, quyết định và bằng chứng — nhưng chỉ để lọc theo phạm vi, không phải để cấp quyền. Ở phạm vi một Brand, màn hình hiện yêu cầu của Brand đó cộng với yêu cầu của sản phẩm nền tảng Conan1.

Chưa mô hình hoá

Chưa tách work item khỏi bằng chứng, chưa tải file, chưa tích hợp GitHub. Trạng thái bị chặn không được lưu — nó được tính từ trạng thái của các yêu cầu đang chờ.

Đọc tiếp

• Làm rõ có AI hỗ trợ — vòng đời câu hỏi, Workers AI và hợp đồng lỗi
• Quyết định — bộ nhớ quyết định
• Truy vết — chuỗi Capability → Product → Application → Feature → Requirement → Evidence và Rule 9–11