Endpoints

Tất cả đường dẫn dưới đây yêu cầu danh tính Cloudflare Access hợp lệ.

Danh tính

GET /v1/me

{ "email": "dac2205@gmail.com", "name": "Đắc", "role": "architect", "brand_id": null }

Năng lực chuẩn

Chỉ vai trò architect được ghi.

Method	Path	Mô tả
GET	/v1/capabilities	Toàn bộ mô hình chuẩn, sắp xếp theo level và sort
GET	/v1/capabilities/:idOrCode	Một năng lực, kèm con và đánh giá của các Brand
POST	/v1/capabilities	Tạo mới; ID sinh tự động từ ID cha
PATCH	/v1/capabilities/:id	Sửa; chỉ những cột được gửi mới bị đổi
DELETE	/v1/capabilities/:id	Xoá, hoặc chuyển sang deprecated nếu đã có Brand đánh giá

POST body:

{
  "name_vi": "Thu hút tự nhiên",
  "name_en": "Organic Acquisition",
  "definition_vi": "Khả năng ...",
  "definition_en": "The ability to ...",
  "parent_id": "CAP-02",
  "level": 2,
  "sort": 1
}

ID sinh theo cây: con thứ nhất của CAP-02 là CAP-02-01. Nhìn ID là biết vị trí trong mô hình.

Rule 8

DELETE không bao giờ xoá một năng lực đã được Brand đánh giá. Nó chuyển status thành deprecated và trả về { "deprecated": true, "reason": "in_use_by_brands" }. Lịch sử không bị mất.

Brand

Method	Path	Mô tả
GET	/v1/brands	Danh sách Brand
POST	/v1/brands	Tạo Brand (chỉ architect)
PATCH	/v1/brands/:code	Sửa Brand

Bản đồ năng lực của Brand

Method	Path	Mô tả
GET	/v1/brands/:code/capabilities	Mọi năng lực chuẩn, kèm đánh giá của Brand này (assessment_id là null nếu chưa kích hoạt)
PUT	/v1/brands/:code/capabilities/:capabilityId	Kích hoạt hoặc cập nhật đánh giá
DELETE	/v1/brands/:code/capabilities/:capabilityId	Bỏ kích hoạt

PUT với body rỗng {} nghĩa là "kích hoạt, chưa chấm điểm". Body có thể chứa bất kỳ tập con nào của:

{
  "importance": 5, "priority": 5, "health": 3,
  "maturity": 2, "target_maturity": 4,
  "likelihood": 4, "impact": 5, "detectability": 2,
  "owner": "Đắc", "rationale": "...", "notes": "..."
}

Quyền ghi: architect và executive ghi được mọi Brand; brand_owner chỉ ghi được Brand của mình.

So sánh

GET /v1/compare?capability=learner-acquisition

Trả về cùng một năng lực dưới góc nhìn của mọi Brand đang hoạt động, kể cả Brand chưa kích hoạt (các trường điểm là null).

Tầng thực thi và chuyển đổi

GET /v1/architecture

Một request trả về toàn bộ tầng thực thi: value stream và các chặng, process và activity, application, data entity, technology, mọi bảng nối, initiative và KPI. Frontend gọi đúng một lần khi khởi động rồi tính mọi màn hình tại client.

CRUD chung

Chín tài nguyên dùng chung một bộ endpoint, chỉ khác nhau ở cột:

GET    /v1/:resource
POST   /v1/:resource
PATCH  /v1/:resource/:id
DELETE /v1/:resource/:id

:resource là một trong: value-streams, value-stream-stages, processes, activities, applications, data-entities, technologies, initiatives, kpis.

• name_en và name_vi bắt buộc khi tạo.
• ID sinh từ prefix cộng slug, ví dụ PRC-develop-authentic-content.
• PATCH chỉ ghi các cột được gửi lên.

Quyền ghi:

Tài nguyên	Ai được ghi
applications, data-entities, technologies, value-stream-stages	architect
processes, activities, value-streams, initiatives, kpis	architect, executive, hoặc brand_owner với bản ghi thuộc Brand của mình

WARNING

Bản ghi có brand_id = NULL là bản ghi dùng chung. brand_owner không sửa được chúng — chỉ architect hoặc executive. Đổi brand_id sang Brand khác cũng cần quyền ghi ở Brand đích.

Quan hệ

POST   /v1/links/:link          body: { "a": "...", "b": "..." }
DELETE /v1/links/:link?a=...&b=...

:link	a	b
stage-capabilities	stage_id	capability_id
capability-applications	capability_id	application_id
capability-data	capability_id	data_entity_id
application-technologies	application_id	technology_id
application-data	application_id	data_entity_id
initiative-capabilities	initiative_id	capability_id

POST dùng INSERT OR IGNORE, nên gọi lại một quan hệ đã có không gây lỗi. Chỉ architect và executive được đổi quan hệ.

Quản trị

GET /v1/governance

Kiểm tra toàn bộ dữ liệu theo các quy tắc quản trị và trả về danh sách vi phạm. brand_code rỗng nghĩa là bản ghi dùng chung, không thuộc Brand nào:

{
  "checked": 51,
  "issues": [
    {
      "rule": "rule-5-owner-required",
      "brand_code": "nemo12",
      "capability_id": "CAP-06",
      "capability_code": "assessment",
      "detail": "Importance >= 4 but no owner assigned"
    }
  ]
}

Nhật ký

GET /v1/audit?entity=capability&id=CAP-02&limit=50

Mọi thay đổi đều lưu cả trạng thái trước và sau dưới dạng JSON.