Project Operating System (DocHub V3)

1. Purpose

Tài liệu này định nghĩa cách dự án vận hành ở quy mô lớn bằng 1 hệ thống thống nhất:

• Quản lý spec và quyết định kiến trúc
• Quản lý code implementation theo module
• Quản lý tiến độ và work items
• Quản lý quality gates và checklist release

Mục tiêu cuối: đọc docs là triển khai ngay được task tiếp theo, không cần hỏi lại bối cảnh.

2. Operating Principles

1. Single Source of Truth: Chỉ docs_hub_v3 có quyền quy định.
2. Code-first Validation: Mọi claim trong spec phải đối chiếu với _generated/* hoặc code v2/.
3. Update-in-place: Không version chồng file (_v2, _final, new).
4. Traceability mandatory: Không có Feature Key thì không được bắt đầu task.
5. Decision before divergence: Mọi mâu thuẫn phải chốt DEC trước khi code thêm.

3. Artifact Layers

Layer A — Governance

• 00_GOVERNANCE/01_DECISION_LOG.md
• 01_ARCHITECTURE/03_SYSTEM_MODEL.md
• 04_OPERATIONS/06_ENGINEERING_RULES.md

Layer B — Execution Specs

• 02_SPECS/core/backend_api.md
• 02_SPECS/core/portal.md
• 02_SPECS/core/miniapp.md
• 02_SPECS/modules/*

Layer C — Delivery Control

• 03_TRACEABILITY/FEATURE_STATUS_MATRIX.md
• 03_TRACEABILITY/API_TRACEABILITY.md
• 03_TRACEABILITY/WORKITEM_BOARD.md
• 04_OPERATIONS/08_PROGRESS_AND_REPORTING.md
• 04_OPERATIONS/09_CHECKLISTS.md

Layer D — Code Truth (Generated)

• 05_GENERATED/backend_api_manifest.md
• 05_GENERATED/backend_entity_manifest.md
• 05_GENERATED/permission_manifest.md
• 05_GENERATED/ui_route_catalog.md

4. Standard Lifecycle (Spec → Code)

1. Chọn Feature Key trong FEATURE_STATUS_MATRIX.
2. Tạo task packet theo 02_SPECS/workitems/TASK_PACKET_TEMPLATE.md.
3. Đối chiếu DEC + Rules + API trace trước khi code.
4. Implement code trong v2.
5. Verify test/lint + cập nhật traceability status.
6. Nếu có khác biệt design/contract thì thêm Decision Log entry.

5. Ownership Model

Artifact	Owner	Reviewer
Decision Log	Architecture Lead	Tech Lead + QA
Module Spec	Module Owner	Architecture + Product
Feature Matrix	PM/Tech PM	Module Lead
API Traceability	Backend Lead	Frontend Lead
Workitem Board	Delivery Lead	All module owners

6. Update SLAs

• Sau mỗi PR merge có thay đổi API/UI/schema: cập nhật docs trong vòng 24h.
• Sau mỗi sprint: rà soát FEATURE_STATUS_MATRIX và WORKITEM_BOARD.
• Trước release: chạy full checklist tại 09_CHECKLISTS.md.

7. Non-Negotiable Quality Gates

1. Guard rules + RBAC theo DEC-003.
2. Datetime ISO UTC theo DEC-004.
3. Tenant isolation theo DEC-001.
4. DTO validation strict và không cho mutate audit fields.
5. Traceability mapping đủ: UI ↔ API ↔ Permission ↔ Entity.

8. Audit Trail Rules

• Mọi thay đổi lớn phải ghi vào 01_DECISION_LOG.md hoặc 08_PROGRESS_AND_REPORTING.md.
• Không log trạng thái bằng chat rời rạc; log vào tài liệu chính thức.
• Từ chối merge nếu thiếu cập nhật docs cho thay đổi hợp đồng API.