US-P04: Cấu hình kết nối hệ ngoài theo môi trường (env_systems)

Thuộc FS: 00-overview.md — Nền tảng dùng chung của cụm tool SAPP (as-built @ e77c47a) Phần chung (tổng quan, roles, flow tổng, related features, NFR, Open Questions, References) xem ở Overview. File này chỉ chứa nội dung riêng của US.

Field	Value
US ID	US-P04
Role thực hiện	R2 - Admin CMS (đăng nhập CMS, có quyền env_systems) — Fact từ code
Phase	As-built (đã triển khai)
Priority	N/A — as-built
Status	Draft
NFR liên quan	NFR-P-03, NFR-P-04 — xem Overview §5
OQ liên quan	OQ-P-03, OQ-P-12, OQ-P-15, OQ-P-21 — xem Overview §6

Nguồn inventory: A-12.

1. US Statement

As a Admin CMS
I want nhập URL và credential của từng hệ ngoài (HubSpot, SAPP Ops, DB Ops, SAP service) cho từng môi trường prod / staging / dev
So that [Assumption] các tool SAPP gọi đúng hệ và đúng môi trường mà không phải sửa code hay khởi động lại dịch vụ

2. Dependencies & Definition Of Ready

N/A — đã triển khai (Mode B).

Dependency runtime: tài khoản CMS có quyền env_systems:*; giá trị credential thật do chủ hệ ngoài cung cấp.

3. Business Rules

ID	Rule	Áp dụng ở	Đã cover bởi (AC)	Nguồn code (Mode B/C)
BR-01	Đọc / tạo / sửa / xoá biến môi trường yêu cầu đăng nhập CMS và quyền env_systems tương ứng	M1, M2	AC-M1.1, EC-M1.1	be/apps/api/src/env-system/env-system.controller.ts:32-100
BR-02	Mỗi biến là một cặp key (duy nhất, bắt buộc) – value (văn bản, không bắt buộc)	M2	AC-M2.1	be/libs/database/src/lib/entities/env/env-system.entity.ts:4-12, fe/src/ui/components/cms/(env-systems)/create-form.tsx:15-30
BR-03	Dịch vụ SAPP đọc giá trị tại thời điểm gọi — đổi giá trị có hiệu lực ngay ở lời gọi sau, không cần khởi động lại	Mọi dịch vụ	AC-M2.2	be/libs/modules/src/lib/env-system/env-system-map.common.service.ts:38-55
BR-04	Mỗi hệ ngoài dùng một bộ key theo môi trường, tên key cố định trong code (bảng ở §4 M1 Fields). Tên key sai = coi như thiếu	M1	AC-M2.3	be/libs/constants/src/lib/env-system/env-system.constants.ts:6-55
BR-05	HubSpot: chỉ key ACCESS_TOKEN được đọc để gọi API; thiếu → lỗi 12001 "HubSpot access token is not configured for this environment"	Key HubSpot	AC-M2.3	be/libs/modules/src/lib/hubspot/common.service.ts:47-58, be/libs/constants/src/lib/hubspot/hubspot.constants.ts:10-32
BR-06	SAPP Ops (tự đăng nhập): cần đủ URL + username + password của môi trường; thiếu một → lỗi 13030 (US-P08)	Key Ops	AC-M2.3	be/libs/modules/src/lib/sapp/sapp-auth.common.service.ts:58-84, be/libs/constants/src/lib/sapp/sapp-ops.constants.ts:17-36
BR-07	SAPP Ops (bộ cũ, một bộ cho mọi môi trường): SAPP_BASE_API_URL + SAPP_API_TOKEN; token phải thay tay khi hết hạn	Key Ops cũ	AC-M2.4	be/libs/constants/src/lib/sapp/sapp.constants.ts:22-25, be/libs/modules/src/lib/sapp/common.service.ts:278-302
BR-08	DB Ops (SQL runner): chỉ có bộ key DEV và STAGING; thiếu host / name / username / password → môi trường đó "chưa cấu hình"; PORT không bắt buộc, mặc định 5432 (US-P09)	Key DB Ops	AC-M2.5	be/libs/constants/src/lib/sapp/sapp-26878-sql.constants.ts:281-307, be/libs/modules/src/lib/sapp/sapp-ops-sql.common.service.ts:83-104
BR-09	SAP service: cần URL + client id + HMAC secret của môi trường (quét thủ công chỉ cần URL); thiếu → lỗi 13037 và log nêu tên key thiếu; staging không dùng lại key prod (US-P05)	Key SAP	AC-M2.3	be/libs/modules/src/lib/sapp/sap-log.common.service.ts:79-113, :340-355
BR-10	Giá trị đọc ra được bỏ khoảng trắng đầu/cuối (URL còn bỏ dấu / cuối) trước khi dùng	Mọi key SAP / Ops DB	AC-M2.6	be/libs/modules/src/lib/sapp/sap-log.common.service.ts:85-87, :108-110, be/libs/modules/src/lib/sapp/sapp-ops-sql.common.service.ts:91-94
BR-11	Bảng quản trị hiện cột ID, Key, Value (che mặc định), Updated; tìm theo key; xoá phải xác nhận "Delete variable?"	M1	AC-M1.1, AC-M1.2	fe/src/ui/pages/cms/(env-systems)/page.tsx:134-196

⚠️ Observed (không phải BR): staging HubSpot dùng bộ key PROD (OQ-P-03); secret lưu dạng rõ (OQ-P-12); câu xác nhận xoá nói dịch vụ "fall back to their defaults" trong khi dịch vụ SAPP báo lỗi thiếu cấu hình (OQ-P-21).

4. Design

a. Mối liên hệ giữa các màn & User Flow

[/cms/env-systems  M1 "System Env"] ──Create/Edit──→ [M2 Form Key/Value] ──Submit──→ M1 (reload)
                                    └─Delete─→ xác nhận "Delete variable?" → M1
Giá trị → bảng env_systems (DB mind_keep) → mọi dịch vụ SAPP đọc lúc gọi (BR-03)

b. Chi tiết từng màn

Màn M1 - Danh sách biến môi trường ("System Env")

Field	Value
Figma frame	N/A — as-built, không có Figma
Trigger vào màn	Admin mở /cms/env-systems
Mô tả ngắn	Bảng key/value dùng chung cho mọi tính năng của mind_keep; cụm SAPP chỉ dùng các key ở bảng Fields dưới

UI States

State	Khi nào	Hiển thị	Figma frame
Default / Has data	Tải xong	Bảng "System Env"	N/A
Loading	Đang tải (timeout 10 s)	Trạng thái tải của bảng chung	N/A
Empty	Không có biến	Bảng rỗng	N/A
Error	API lỗi	"Failed to load env systems" + thông điệp; lỗi token → "Login again"	N/A
Disabled	N/A	—	N/A

Fields

Bộ key cụm SAPP đọc (Fact — be/libs/constants/src/lib/env-system/env-system.constants.ts:6-55):

Hệ ngoài	prod	staging	dev	Ghi chú
HubSpot CRM	SAPP_PROD_HUBSPOT_{API_URL,ACCESS_TOKEN,CLIENT_SERCET}	⚠️ dùng lại bộ PROD	SAPP_DEV_HUBSPOT_{…}	Chỉ ACCESS_TOKEN được đọc (BR-05); tên key viết sai chính tả SERCET đúng như code
SAPP Ops (tự đăng nhập)	SAPP_OPS_{API_URL,USERNAME,PASSWORD}_PROD	…_STAGING	…_DEV	BR-06
SAPP Ops (bộ cũ)	SAPP_BASE_API_URL, SAPP_API_TOKEN — một bộ, không theo môi trường			BR-07; dùng bởi FS 24395 (bulk product)
DB SAPP Ops	— (không có key, cố ý)	SAPP_OPS_DB_{HOST,PORT,NAME,USERNAME,PASSWORD}_STAGING	…_DEV	BR-08
SAP service	SAPP_SAP_{API_URL,CLIENT_ID,HMAC_SECRET}_PROD	…_STAGING	…_DEV	BR-09
Key riêng của FS nhóm	SAPP_PROD_ECONTRACT_DB_* (FS 20603), SAPP_LMS_API_URL_{DEV,STAGING} (FS 26297)			Mô tả ở FS nhóm tương ứng

Cột trên màn:

Field	Required	Type	Default	Format	Validation	Error Message	Visibility	Depends On
ID	—	Number	—	—	—	—	Always	—
Key	—	Text (mono)	—	—	—	—	Always	—
Value	—	Giá trị che	che	—	—	—	Always (che)	—
Updated	—	Datetime	—	—	—	—	Always	—

Filter / Search / Sort

Loại	Theo field	Kiểu	Default	Notes
Filter	—	—	—	Không có bộ lọc
Search	Key	free-text	—	"Search by key…" (fe/src/ui/pages/cms/(env-systems)/page.tsx:139)
Sort	—	—	Mặc định của API	Không có điều khiển
Pagination	—	—	10 / trang	:64-67

Actions

A1 - Tạo / sửa biến

Item	Description
Trigger	"Create variable" hoặc sửa một dòng → M2
Behavior	POST / PATCH /api/v1/env-systems. Ghi bảng env_systems — DB mind_keep. ⚠️ Ghi PROD (gián tiếp): sửa key …_PROD đổi đích gọi / credential của các thao tác prod ở mọi sub-tool
Success Result	"Env system created/updated — The env system has been … successfully."

Error cases:

Case	Expected Handling
Key trùng	Lỗi từ BE (key unique)
Không có quyền	Lỗi quyền CMS

A2 - Xoá biến

Item	Description
Trigger	Xoá một dòng → xác nhận "Delete variable?" — "<key> will be deleted. Services that read it fall back to their defaults."
Behavior	DELETE /api/v1/env-systems/:id. Xoá dòng trong env_systems — DB mind_keep
Success Result	"Env system deleted…"

Error cases:

Case	Expected Handling
Xoá một key SAPP đang dùng	Dịch vụ SAPP tương ứng báo lỗi "chưa cấu hình" ở lời gọi sau (BR-05…BR-09) — xem EC-M1.2

Acceptance Criteria của màn M1

AC-M1.1 - Xem danh sách có che giá trị

Given Admin có quyền env_systems:read
When mở /cms/env-systems
Then bảng "System Env" hiện ID, Key, Value (che), Updated

Maps to:

• Business Rule: BR-01, BR-11

AC-M1.2 - Xoá có xác nhận

Given Admin bấm xoá biến SAPP_SAP_API_URL_DEV
When xác nhận "Delete variable"
Then biến bị xoá và bảng tải lại

Maps to:

• Business Rule: BR-11

Negative AC / Edge Cases của màn M1

ID	Tình huống	Hành vi mong đợi
EC-M1.1	Phiên CMS hết hạn	"Failed to load env systems" + "Login again"
EC-M1.2	⚠️ Observed — Câu xác nhận xoá nói dịch vụ "fall back to their defaults"	Dịch vụ SAPP không có giá trị mặc định: báo 12001 / 13030 / 13037 / "chưa cấu hình" (OQ-P-21)
EC-M1.3	⚠️ Observed — Secret (mật khẩu Ops, DB, HMAC, token HubSpot) lưu dạng rõ	Hành vi hiện tại (be/libs/database/src/lib/entities/env/env-system.entity.ts:10-11; OQ-P-12)

Màn M2 - Form biến môi trường

Field	Value
Figma frame	N/A — as-built, không có Figma
Trigger vào màn	"Create variable" / sửa dòng ở M1
Mô tả ngắn	Form hai trường Key / Value

UI States

State	Khi nào	Hiển thị	Figma frame
Default	Mở form	Key, Value (sửa thì điền sẵn)	N/A
Error	BE từ chối	Hộp lỗi	N/A
Loading / Empty / Has data / Disabled	N/A — form	—	N/A

Fields

Field	Required	Type	Default	Format	Validation	Error Message	Visibility	Depends On
Key	Yes	Text	— ("Enter key")	Tên key đúng như bảng M1	Duy nhất (BR-02)	Lỗi BE	Always	—
Value	No	Text	— ("Enter value")	URL / token / mật khẩu	—	—	Always	Key

Filter / Search / Sort

N/A — không phải màn List.

Actions

A1 - Submit

Item	Description
Trigger	Bấm lưu
Behavior	Như M1 A1
Success Result	Giá trị có hiệu lực ở lời gọi sau (BR-03)

Error cases:

Case	Expected Handling
Thiếu Key	Form không gửi

Acceptance Criteria của màn M2

AC-M2.1 - Tạo biến

Given Admin nhập Key "SAPP_OPS_DB_HOST_STAGING" và Value
When lưu
Then biến được tạo trong env_systems

Maps to:

• Business Rule: BR-02

AC-M2.2 - Có hiệu lực không cần khởi động lại

Given sub-tool 26878 đang báo lỗi 13037 trên staging
When Admin thêm đủ SAPP_SAP_API_URL_STAGING, SAPP_SAP_CLIENT_ID_STAGING, SAPP_SAP_HMAC_SECRET_STAGING
Then lần tra vết SAP tiếp theo trên staging chạy được, không cần khởi động lại API

Maps to:

• Business Rule: BR-03, BR-09

AC-M2.3 - Thiếu key → lỗi theo hệ

Given thiếu SAPP_DEV_HUBSPOT_ACCESS_TOKEN
When một sub-tool gọi HubSpot dev
Then nhận lỗi 12001 "HubSpot access token is not configured for this environment"
And thiếu key Ops tự đăng nhập thì lỗi 13030, thiếu key SAP thì lỗi 13037

Maps to:

• Business Rule: BR-04, BR-05, BR-06, BR-09

AC-M2.4 - Bộ Ops cũ không theo môi trường

Given SAPP_BASE_API_URL trỏ tới một môi trường Ops
When sub-tool dùng bộ cũ (bulk product 24395) chạy
Then mọi lời gọi đi tới đúng URL đó bất kể người dùng chọn môi trường nào

Maps to:

• Business Rule: BR-07

AC-M2.5 - DB Ops chỉ dev/staging, PORT mặc định

Given có đủ SAPP_OPS_DB_HOST_DEV, _NAME_DEV, _USERNAME_DEV, _PASSWORD_DEV nhưng không có _PORT_DEV
When hỏi trạng thái SQL trên dev
Then configured = true và kết nối dùng cổng 5432
And không có key nào khiến prod "configured"

Maps to:

• Business Rule: BR-08

AC-M2.6 - Khoảng trắng thừa

Given SAPP_SAP_API_URL_DEV = " https://sap.example/ "
When dịch vụ SAP đọc
Then dùng "https://sap.example"

Maps to:

• Business Rule: BR-10

Negative AC / Edge Cases của màn M2

ID	Tình huống	Hành vi mong đợi
EC-M2.1	Gõ sai tên key (vd SAPP_OPS_DB_HOST_STG)	Lưu được, nhưng dịch vụ coi như thiếu key (BR-04)
EC-M2.2	⚠️ Observed — Đặt key HubSpot cho "staging"	Không có key staging: staging luôn dùng token PROD (be/libs/constants/src/lib/hubspot/hubspot.constants.ts:19-26; NFR-P-03, OQ-P-03)

5. Cross-feature AC

AC-X.1 - Mọi FS nhóm phụ thuộc cấu hình này

Given một key của hệ ngoài bị thiếu cho môi trường X
When bất kỳ sub-tool nào (HubSpot, 20603, 24395, 23954, 26878, 26297) gọi hệ đó trên X
Then sub-tool nhận lỗi "chưa cấu hình" tương ứng của hệ đó

Maps to:

• REL-01…REL-06 (Be Affected - 6 FS nhóm tool)