@fui-org/fui-cli 0.2.0 → 0.3.0

package/skills/fui-skill/references/db-workflow.md

@@ -0,0 +1,504 @@
+# DB Connection Workflow
+
+> File này sở hữu: **kết nối DB, dbToken, schema cache, workflow làm việc với SP, rollback**. Mức rủi ro + guard từng tool xem [tools-registry.md](tools-registry.md); checklist SP xem [verification.md](verification.md).
+
+Hướng dẫn toàn diện về kết nối database cho một FUI project — từ tìm thông tin kết nối, build token, đến quản lý schema và SP.
+
+---
+
+## 1. Thông tin kết nối lưu ở đâu
+
+Mỗi project có thư mục `_db/` riêng, **bên trong là một thư mục con cho MỖI kết nối** — một project
+FUI gọi được nhiều database cùng lúc, mỗi cái qua một alias (`apiName`) riêng:
+
+```
+{FUI_MCP_WORKDIR}/{projectId}/
+└── _db/
+    ├── _connections.json      ← MỌI kết nối của project + kết nối mặc định
+    ├── rights.json            ← cache quyền từ "acc", khoá theo alias
+    ├── {alias}/               ← alias = apiName = đoạn đầu trong "API": "/{alias}/Ten"
+    │   ├── schema.json        ← cache schema của DB đó
+    │   └── {name}.sql         ← SP của DB đó (KHÔNG có tầng "sp/")
+    └── {alias-khác}/…
+```
+
+**Alias là khoá nối mọi thứ lại**: đoạn đầu trong `"API": "/fee/HocPhi_Select"` của module.json chính
+là `apiName` trong tAPI, cũng chính là tên thư mục `_db/fee/`. Đọc module.json là biết ngay lời gọi
+đó chạy trên database nào và phải mở thư mục nào.
+
+> Mọi tool DB nhận tham số **`db`** (alias) để chọn kết nối. Bỏ trống thì MCP tự suy từ object đang
+> thao tác; **suy không ra thì nó trả về một MENU các alias** — chọn một cái rồi gọi lại, đừng đoán.
+
+Bản cũ **không** nằm cạnh bản hiện tại: mọi thứ sắp bị ghi đè/xoá đi về một kho chung
+`{FUI_MCP_WORKDIR}/_history/`, giữ nguyên hình dạng đường dẫn gốc:
+
+```
+{FUI_MCP_WORKDIR}/_history/{projectId}/_db/{alias}/{name}_{thời điểm}.sql
+{FUI_MCP_WORKDIR}/_history/{projectId}/_db/{alias}/{name}_{thời điểm}_deleted.sql   ← SP bị DROP
+```
+
+Một kho duy nhất cho cả project lẫn DB: lúc cần bản cũ chỉ phải nhớ **một** chỗ, và mọi bản của cùng
+một file nằm cạnh nhau (tìm theo tên file, không phải theo thời điểm). Kho này **không bao giờ tự
+dọn** — user tự xoá tay khi thấy đủ.
+
+**Cấu trúc `_db/_connections.json`:**
+
+```json
+{
+  "default": "acc",
+  "connections": {
+    "acc": {
+      "apiDomain": "api.example3.vn",
+      "sqlServer": "192.0.2.101",
+      "database":  "AccountUser",
+      "dbToken":   "<base64-encoded connection string>",
+      "userToken": "<bearer token — tùy chọn>"
+    },
+    "Dashboard": { "apiDomain": "api.example3.vn", "…": "…" }
+  }
+}
+```
+
+`default` chỉ áp cho thao tác **đọc** không nêu `db`. Thao tác **ghi** (`db_sql_execute` có lệnh ghi,
+`db_sql_execute_nonquery`, `db_token_rebuild`) không bao giờ tự dùng mặc định — phải nêu rõ `db`.
+
+| Field | Bắt buộc | Mô tả |
+|---|---|---|
+| khoá của mục | ✅ | Chính là `apiName`/alias — vừa là tên thư mục `_db/{alias}/`, vừa là đoạn đầu trong `"API": "/{alias}/Ten"` |
+| `apiDomain` | ✅ | **Chỉ host, KHÔNG có alias, KHÔNG có dấu `/` ở cuối** — ví dụ `api.example3.vn` |
+| `sqlServer` | ❌* | Host SQL Server — cần có để dùng `db_token_rebuild` |
+| `database` | ❌* | Tên database — cần có để dùng `db_token_rebuild` |
+| `dbToken` | ✅ | Chuỗi kết nối SQL Server đã base64-encode |
+| `userToken` | ❌ | Bearer token để test `spAPI_*` sau khi deploy |
+
+*Nên truyền khi `db_connect` để sau này có thể `db_token_rebuild` mà không cần hỏi lại.
+
+> **CRITICAL — `apiDomain` mang HAI nghĩa khác nhau trong hệ thống, đừng lẫn lộn:**
+> - `_db/_connections.json` (MCP, bảng trên) → **host trần**, không alias, không `/` cuối: `api.example3.vn`.
+> - `project.json`'s `data.apiDomain` (runtime FUI, mục 2a bên dưới) → **base URL đầy đủ** đã kèm sẵn `apiName` + `/` cuối: `https://tapi.example.vn/acc/`.
+>
+> Ghép URL thủ công bằng cách lấy `_db/_connections.json`'s `apiDomain` (host trần) rồi nối thẳng `apiName` vào — **không chèn `/`** — là lỗi hay gặp nhất khi tự gõ tay: `tapi.lhu.edu.vn` + `ts` → `tapi.lhu.edu.vnts` (sai, "ts" bị nuốt vào domain) thay vì `tapi.lhu.edu.vn/ts` (đúng). Xem thêm ví dụ đối chiếu ❌/✅ ở [tapi-reference.md](tapi-reference.md) §3. Cách an toàn nhất: đừng tự ghép — copy nguyên văn dòng `Wiring URL` từ `db_sp_verify`/`db_sp_help`.
+
+---
+
+## 2. Tìm thông tin kết nối của một project
+
+### 2a. Đọc `apiDomain` từ project.json
+
+`project.json` của mỗi project thường có trường `data.apiDomain` — đây là base URL của tAPI server kèm apiName:
+
+```json
+"data": {
+  "apiDomain": "https://tapi.example.vn/acc/",
+  ...
+}
+```
+
+Từ URL này:
+- **`apiDomain`** → `tapi.example.vn`
+- **`apiName`** → `acc` (phần path đầu tiên sau domain)
+
+Một số project có nhiều domain, mỗi domain dùng một tAPI server riêng:
+
+```json
+"domainSetting": {
+  "sec.example.vn": {
+    "apiDomain": "https://tapi.example.vn/acc/"
+  },
+  "sec.example3.vn": {
+    "apiDomain": "https://api.example3.vn/acc/"
+  }
+}
+```
+
+→ Hỏi user đang làm việc với domain nào để chọn `apiDomain` đúng.
+
+### 2b. Chỉ biết alias, chưa có dbToken → `db_alias_list` + `db_connect_by_name`
+
+`db_connect` đòi sẵn `dbToken`, mà `dbToken` là base64 của một chuỗi kết nối **kèm UID/PWD**. Khi bạn
+chỉ biết `apiName` thì **đừng đi tra tay bằng PowerShell** (moi UID/PWD ra command line là phơi
+credential, và cả quy trình đó nay đã có tool):
+
+**Bước 1 — xem mình được cấp những database nào:**
+```
+db_alias_list()
+```
+**Không cần tham số nào.** `SM_Modules_ManagerSelect` không nhận tham số: tAPI bơm `@sys_UserID` từ
+Bearer token ở phía server, nên danh sách trả về **đã lọc sẵn theo quyền quản lý của chính bạn**.
+Trả về bảng `APIName | SQLServer | DatabaseName | ModuleName | Enable`. Danh sách dài thì thêm
+`search` để lọc phía client (khớp `APIName`/`DatabaseName`/`ModuleName`, không phân biệt hoa-thường).
+
+**Bước 2 — kết nối:**
+```
+db_connect_by_name({ apiName: "basic" })
+```
+Tool làm trọn gói: tra `SQLServer`/`DatabaseName` từ acc → **mượn cặp UID/PWD** của một kết nối bạn đã
+có → dựng `dbToken` → **test `SELECT 1` trước khi lưu bất cứ thứ gì** → `saveConnection` +
+fetch schema về `_db/{alias}/`. Báo cáo giống hệt `db_connect`. **Không bao giờ in dbToken/UID/PWD.**
+
+Thứ đang mượn là **cặp tài khoản**, còn Server/Database thì lấy từ acc — đúng ranh giới của quy trình
+làm tay cũ. Workspace có nhiều login **khác nhau** → tool trả **menu** để bạn chọn, không đoán; nêu rõ
+bằng `borrowCredentialsFrom: "{projectId}/{alias}"`. (Một login xuất hiện ở nhiều kết nối cùng group
+là chuyện thường và **không** bị coi là nhập nhằng.)
+
+**Không tìm thấy `apiName` mang HAI nghĩa** — alias không tồn tại, **hoặc** bạn không được cấp quyền
+quản lý nó. Đừng vội kết luận là gõ sai tên: chạy `db_alias_list()` xem mình thực sự có gì.
+
+Project **chưa có kết nối nào** vẫn chạy được (đây đúng là lúc cần tool nhất): `apiDomain` bóc từ
+`project.json` local, `userToken` mượn từ kết nối của project khác cùng domain — chỉ tự chọn khi có
+đúng một ứng viên, nhiều thì trả menu. Bí quá thì truyền thẳng `apiDomain` + `userToken`.
+
+> ⚠️ Field `Password` trong response của `SM_Modules_ManagerSelect` là **hash nội bộ của tAPI**, không
+> phải SQL Server password thực — không dùng được để build dbToken. Tool **không in field này ra**.
+
+### 2c. Workflow đầy đủ — kết nối DB lần đầu cho project mới
+
+> Mục này giả định database **đã tồn tại và đã được đăng ký alias** trong `acc`. Chưa có (dựng dự án
+> từ số 0) → làm [project-provisioning.md](project-provisioning.md) trước: tạo DB, hai tài khoản SQL,
+> rồi `db_alias_new` để có alias — xong mới quay lại đây.
+
+```
+1. project_sync(projectId)          → có project.json local (nguồn của apiDomain)
+2. session_set({ projectId })       → khỏi phải truyền projectId ở mọi bước sau
+3. db_alias_list()                  → xem mình được cấp quyền quản lý những alias nào
+4. db_connect_by_name({ apiName })  → tra + dựng token + test + lưu + fetch schema, một lượt
+                                      (KHÔNG gọi db_schema_get thêm — đã fetch rồi)
+5. [Module gọi thêm alias khác?] lặp bước 4 cho từng alias còn thiếu.
+   Kết nối thêm KHÔNG tự giành `default` — muốn đổi thì `makeDefault: true`.
+```
+
+Đã cầm sẵn `dbToken` (ai đó đưa, hoặc chép từ nơi khác) thì bỏ qua bước 3–4, gọi thẳng `db_connect`.
+
+---
+
+## 3. Build dbToken
+
+> Chỉ cần khi bạn **có sẵn UID/PWD trong tay** và muốn gọi `db_connect` trực tiếp. Mượn credential từ
+> một kết nối đã có thì dùng `db_connect_by_name` (§2b) — nó dựng token giúp, và không in ra plain text.
+
+`dbToken` là chuỗi kết nối SQL Server được **base64-encode**. Chuỗi gốc:
+
+```
+Server={sqlServer};Database={database};UID={uid};PWD={pwd};Encrypt=True;TrustServerCertificate=True;
+```
+
+**Build bằng JavaScript:**
+```js
+Buffer.from("Server=192.0.2.101;Database=AccountUser;UID=sa;PWD=MyPass;Encrypt=True;TrustServerCertificate=True;").toString("base64")
+```
+
+**Build bằng PowerShell:**
+```powershell
+[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("Server=192.0.2.101;Database=AccountUser;UID=sa;PWD=MyPass;Encrypt=True;TrustServerCertificate=True;"))
+```
+
+---
+
+## 4. Workflow kết nối lần đầu
+
+### Xác định projectId trước khi kết nối
+
+Thông tin kết nối DB được lưu vào `{FUI_MCP_WORKDIR}/{projectId}/_db/_connections.json`, dưới khoá
+`apiName`. **Một project có thể có nhiều apiName** — `projectId` và `apiName` là hai thứ khác nhau,
+đừng suy cái này ra cái kia.
+
+**Quy tắc bắt buộc:** Nếu user không chỉ rõ projectId, hoặc alias/database chưa rõ thuộc project nào → **phải hỏi xác nhận** trước khi gọi `db_connect`:
+
+> _"Thông tin kết nối DB này sẽ được lưu vào project nào? (projectId)"_
+
+Không tự đoán projectId rồi gọi luôn — lưu sai project sẽ khiến schema/SP bị đặt nhầm chỗ và khó tìm lại.
+
+```
+db_connect(apiDomain, dbToken, apiName, [sqlServer, database, userToken])
+  → schema tự động được fetch và lưu vào _db/{alias}/schema.json
+  → KHÔNG gọi db_schema_get thêm sau bước này
+```
+
+### Project gọi nhiều database → gọi `db_connect` NHIỀU LẦN
+
+Mở `module.json` và quét mọi `"API": "/{alias}/…"`: **mỗi alias khác nhau là một kết nối cần có**.
+Gọi `db_connect` lần lượt cho từng alias — lần sau **không đụng** gì tới kết nối đã có, mỗi cái nằm
+trong thư mục `_db/{alias}/` của riêng nó.
+
+Thiếu một alias thì mọi lời gọi thuộc alias đó **không được kiểm gì cả**: `module_validate` không có
+schema để đối chiếu tên SP, `db_sp_verify`/`db_sp_get` không tìm thấy SP, và `db_sp_deploy` không có
+đường nào tới đúng database đó.
+
+Kết nối **thêm vào không tự giành mặc định** — kết nối đầu tiên vẫn là `default`. Muốn đổi thì
+`db_connect({ …, makeDefault: true })`.
+
+**Tham số đầy đủ nên truyền:**
+
+```json
+{
+  "projectId":  "my-project",
+  "apiDomain":  "tapi.example.vn",
+  "apiName":    "acc",
+  "sqlServer":  "192.0.2.101",
+  "database":   "MyDatabase",
+  "dbToken":    "<base64>",
+  "userToken":  "<bearer token nếu có>"
+}
+```
+
+Truyền `sqlServer` + `database` ngay từ đầu để sau này dùng được `db_token_rebuild` mà không cần hỏi lại.
+
+---
+
+## 5. Khi đổi mật khẩu — db_token_rebuild
+
+Khi UID hoặc PWD thay đổi nhưng Server và Database vẫn giữ nguyên:
+
+**Bước 1:** Xác nhận kết nối cần sửa đã có `sqlServer` và `database`
+```
+db_config_read(projectId)
+```
+
+**Bước 2:** Rebuild token — server tự lấy `sqlServer`/`database` từ kết nối đó, chỉ cần truyền thông tin thay đổi
+```
+db_token_rebuild({ projectId, db, uid, password })
+```
+
+Tool sẽ tự build lại `dbToken`, test kết nối, và lưu. Nếu `sqlServer`/`database` chưa có → phải dùng `db_connect` đầy đủ thay thế.
+
+**`db` là BẮT BUỘC khi project có nhiều hơn một kết nối** — đây là thao tác ghi đè credential, đoán
+sai thì ghi token của DB này đè lên DB kia. Một kết nối duy nhất thì bỏ trống được.
+
+---
+
+## 6. userToken — Mục đích và chia sẻ
+
+### Mục đích
+
+`userToken` là **Bearer token của người dùng** — dùng để gọi các `spAPI_*` endpoint sau khi deploy, nhằm test API như một user thực. Khác với `dbToken` là kết nối trực tiếp vào SQL Server.
+
+```
+dbToken   → kết nối SQL Server để chạy schema/SP
+userToken → gọi REST API của tAPI như một end-user (test spAPI_*)
+```
+
+### Chia sẻ userToken giữa các project
+
+**userToken có thể dùng chung** cho các project trong cùng một **GroupName** (xem trong `_projectInfo.json`):
+
+```json
+{ "GroupName": "GroupA" }
+```
+
+Nếu đã có `userToken` từ project GroupA khác → có thể set thẳng cho project mới mà không cần đăng nhập lại:
+
+```
+db_user_token_set({ projectId, db, userToken })
+```
+
+Hoặc bỏ qua `userToken` khi gọi tool — MCP sẽ tự scan workspace tìm token từ project cùng group.
+
+### userToken lưu THEO TỪNG KẾT NỐI
+
+`userToken` nằm trong mục của một alias trong `_db/_connections.json`, không phải một giá trị chung
+của project. Project nhiều database thì mỗi kết nối cần token riêng — truyền `db: "<alias>"` để nói
+rõ set vào kết nối nào; bỏ trống thì vào kết nối mặc định.
+
+Điều này quan trọng với `right_*`: nhóm tool quyền gọi alias `acc` bằng `userToken` lấy từ **kết nối
+khớp `apiName` đang thao tác** (không khớp thì kết nối mặc định) — thiếu token ở đúng kết nối đó thì
+tool quyền không chạy được dù kết nối khác đã có token.
+
+### Set userToken sau khi kết nối
+
+Nếu chưa có lúc `db_connect`, set riêng sau:
+```
+db_user_token_set({ projectId, db, userToken })
+```
+
+---
+
+## 6a. SSO theo tên miền — cùng domain cha thì token DÙNG ĐƯỢC, đừng hỏi lại
+
+**Sự thật nền tảng:** SSO giữa các API của các project FUI được chứng thực **theo tên miền cha**. Mọi
+API nằm dưới cùng một domain cha (ví dụ mọi host `*.lhu.edu.vn`: `tapi.lhu.edu.vn`, `api.lhu.edu.vn`,
+`capnhatluong.lhu.edu.vn`…) **chấp nhận cùng một `userToken`**.
+
+Hệ quả trực tiếp — đây là điểm hay bị làm sai:
+
+- **Đã có `userToken` của một project/alias thuộc domain cha đó thì dùng thẳng cho project/alias khác
+  cùng domain cha. KHÔNG hỏi lại người dùng "token này có gọi được không", KHÔNG đi thử một lời gọi
+  để "xác minh", KHÔNG bắt đăng nhập lại.** Câu trả lời đã biết trước từ tên miền.
+- Việc scan workspace tìm token sẵn có (`db_user_token_set` gọi không kèm `userToken`) là hợp lệ và
+  nên làm — nó chính là hiện thực hoá luật này.
+
+Ranh giới của luật (chỗ vẫn phải hỏi):
+
+| Tình huống | Xử lý |
+|---|---|
+| Cùng domain cha (`*.lhu.edu.vn` → `*.lhu.edu.vn`) | **Dùng ngay**, không hỏi, không thử |
+| Khác domain cha (`*.lhu.edu.vn` → `*.dhlh.vn`, `*.fap.vn`) | Token **không** áp dụng — cần token riêng của domain kia |
+| Project nhiều domain (`domainSetting` có nhiều host khác domain cha nhau) | Mỗi domain cha là một vùng SSO riêng — xem `domainSetting` trong `project.json` (mục 2a) để biết đang đứng ở vùng nào |
+
+> `GroupName` trong `_projectInfo.json` (mục 6 bên trên) là cách **gộp nhóm ở tầng quản trị**, còn
+> tên miền cha là thứ **thực sự quyết định** token có được chấp nhận hay không. Hai cái thường trùng
+> nhau; khi lệch thì tin vào tên miền.
+
+---
+
+## 7. Refresh schema
+
+| Khi nào | Tool |
+|---|---|
+| Sau `db_connect` | **Không cần** — schema đã tự fetch |
+| User yêu cầu refresh | `db_schema_get({ projectId, db })` |
+| Vừa tạo/đổi tên/xóa table hoặc SP | `db_schema_get({ projectId, db })` |
+| Schema local trông cũ/thiếu | `db_schema_get({ projectId, db })` |
+
+Đọc schema đã cache (nhanh, không gọi DB):
+```
+db_schema_read({ projectId, db, objectType?, search? })
+```
+`objectType`: `Table`, `View`, `API`, `API File`, `Procedure`, `Function`
+
+**Mỗi kết nối có schema riêng** (`_db/{alias}/schema.json`) và cả hai tool này thao tác trên **đúng
+một** kết nối. Project nhiều database thì `db_schema_get` một alias **không** làm mới alias còn lại —
+tra `db_config_read` xem có bao nhiêu kết nối rồi refresh từng cái. Không thấy một bảng/SP trong
+`db_schema_read` thường không phải "chưa có" mà là **đang đọc nhầm kết nối**.
+
+**Cũng tải lại thân SP:** `db_schema_get` làm mới **mọi thứ kết nối đó đang giữ** — `schema.json` lẫn
+từng file `_db/{alias}/{name}.sql`. Bản `.sql` local khác server được chép vào `_history/` trước rồi
+mới ghi đè, nên không mất; nhưng đừng coi file local là bản mới nhất nếu chưa refresh.
+
+**Tự dọn SP/function mồ côi khi refresh:** `db_connect`/`db_schema_get` quét **các file `.sql` thật
+trong `_db/{alias}/`** rồi xếp làm ba nhóm — chỉ trong phạm vi kết nối đó, không nhìn sang alias khác:
+
+| Nhóm | Điều kiện | Hành vi |
+|---|---|---|
+| Còn sống | tên có trong schema MỚI | giữ + tải lại thân từ server |
+| Đã xóa trên server | có ở schema CŨ, mất ở schema MỚI | **archive** vào `_history/{projectId}/_db/{alias}/{name}_{thời điểm}_deleted.sql` rồi xóa khỏi `_db/{alias}/` |
+| Chỉ có ở local | không có ở cả hai | **chỉ liệt kê, không xóa** — nhiều khả năng là SP đang soạn qua `db_sp_save` chưa deploy. Muốn dọn: `db_schema_get({ pruneLocalOnly: true })` |
+
+Không để lại file cũ tưởng là định nghĩa còn hiệu lực; tool in dòng `📋 Archived orphaned local SP
+file(s)...` nếu có. So tên **không phân biệt hoa-thường** (SQL Server không phân biệt, file có thể lệch case).
+
+---
+
+## 8. Workflow làm việc với SP
+
+```
+1. db_sp_list(projectId)              → xem danh sách SP — MỌI kết nối, ghi rõ SP nào thuộc alias nào
+2. db_sp_get(name, projectId)         → fetch định nghĩa SP từ DB → lưu _db/{alias}/{name}.sql
+3. [sửa file _db/{alias}/{name}.sql]
+4. db_sp_save(name, sql, projectId)   → lưu SQL vào local, chưa deploy
+5. db_sp_deploy(name, projectId)      → deploy lên DB
+                                         (bản ĐANG CHẠY trên server tự lưu vào _history/
+                                          trước khi ghi — đây là bản để rollback)
+                                         nếu tên là spAPI_*/spAPIFILE_* → tự gọi /help xoá
+                                         cache tAPI (một lần, hỏng thì bỏ qua — không chặn
+                                         deploy, không cần gọi lại)
+6. db_sp_help(name, projectId)        → BẮT BUỘC gọi thủ công khi SP được ALTER/deploy bằng
+                                         con đường khác ngoài db_sp_deploy (ví dụ:
+                                         db_sql_execute_nonquery chạy ALTER PROCEDURE
+                                         trực tiếp) — đường đó không có auto-clear.
+                                         Cũng dùng khi muốn xem tham số đầu vào của API
+                                         trước khi wire IN/OUT vào module.json.
+                                         Tool gọi MỘT lần theo URL chuẩn, hỏng thì chỉ báo
+                                         một dòng thông tin — ĐỪNG thử URL biến thể khác
+7. db_sp_verify(name, params)         → kiểm chứng TĨNH contract API vừa deploy (đọc hay ghi đều
+                                         qua tool này) — KHÔNG gọi endpoint nào, chỉ đọc thân SP
+                                         thật và suy luận response shape, contract lỗi, phân loại
+                                         đọc/ghi, sinh sẵn snippet apiMocks cho module_simulate.
+                                         BẮT BUỘC chạy trước khi viết apiMocks cho một SP đã tồn
+                                         tại — tự bịa cấu trúc là sai, module_simulate sẽ cảnh báo
+                                         nếu phát hiện mock khớp SP thật mà chưa được verify.
+```
+
+**Chọn kết nối trong cả 7 bước:** bỏ trống `db` thì MCP **suy từ chính tên SP** — dò tên đó trong
+schema và trong file `.sql` local của từng kết nối. Ra đúng một kết nối thì đi tiếp im lặng; ra
+**không** kết nối nào hoặc **nhiều hơn một** (SP trùng tên ở hai DB) thì tool trả về **menu các alias**,
+chọn một cái rồi gọi lại — đừng đoán. Riêng `db_sp_save` với SP **mới hoàn toàn** thì chưa có gì để
+suy: project nhiều kết nối phải nêu `db` ngay từ lần lưu đầu.
+
+> Cách suy luận của `db_sp_verify` (đọc thân SP thật, không đoán theo tên, lỗi cứng khi không đọc
+> được thân SP) và cách kiểm tra API ghi bằng module_simulate: xem
+> [tools-registry.md](tools-registry.md#quy-tắc-bắt-buộc-cho-db-tools). Các guard `DROP`/`ALTER
+> TABLE`, `DELETE`/`UPDATE` không `WHERE` đều enforce ở code level, không bypass được; lệnh ghi qua
+> `db_sql_execute`/`db_sql_execute_nonquery` cần `confirmWrite: true`.
+
+**Rollback SP:**
+1. Đọc file trong `{FUI_MCP_WORKDIR}/_history/{projectId}/_db/{alias}/{name}_{thời điểm}.sql`
+2. `db_sp_save(name, oldSql)` — ghi lại bản cũ vào local
+3. `db_sp_deploy(name)` — deploy lại
+
+---
+
+## 8a. Linked Server — quy ước `spIO_IN_` / `spIO_OUT_`
+
+SQL Server Linked Server đã có sẵn trong hệ thống FUI. Tuy nhiên, **vì lý do bảo mật, không thể truy vấn trực tiếp table của DB khác qua linked server** — chỉ được phép gọi một stored procedure đã định nghĩa sẵn phía kia.
+
+**Cú pháp gọi qua Linked Server trong thân SP:**
+```sql
+EXEC XDATA23.Calendar2015.dbo.spIO_IN_DeleteMonHocInfo @MonHocID, @ErrorDKMH OUTPUT
+--   ^^^^^^^^^^^^^^^^^^^^^^^^^                         ← 4 phần: linked-server.database.schema.tên-SP
+```
+
+### Quy ước đặt tên SP vượt ranh giới Linked Server
+
+| Tiền tố | Hướng dữ liệu | Khi nào dùng |
+|---|---|---|
+| `spIO_IN_` | Dữ liệu đi **vào** DB hiện tại (nhận/import từ DB kia) | SP nhận lệnh từ DB ngoài, tác động lên DB hiện tại |
+| `spIO_OUT_` | Dữ liệu đi **ra** khỏi DB hiện tại (xuất/cung cấp cho DB kia) | SP cung cấp dữ liệu cho DB ngoài gọi vào |
+
+**Hệ quả quan trọng:**
+
+- Khi thấy một SP trong `db_sp_list` / schema có tiền tố `spIO_IN_` hoặc `spIO_OUT_` → đó là SP biên giới Linked Server, **không phải tAPI endpoint** (dù tên có `spIO_`). Không wire vào `"API":` trong module.json.
+- Tiền tố giúp nhận ra ranh giới ngay trong `db_sp_list` mà không cần đọc thân SP — tên nói lên bản chất.
+- Khi tạo SP mới có tác dụng qua Linked Server: **bắt buộc đặt tiền tố** `spIO_IN_` hoặc `spIO_OUT_` theo đúng hướng dữ liệu, không đặt tên tự do.
+- SP loại này **không deploy được bằng `db_sp_deploy` sang DB kia** — nó chạy **trên DB hiện tại** nhưng bên trong `EXEC` gọi sang DB kia. Deploy bình thường vào alias của DB sở hữu SP đó.
+
+---
+
+## 9. Kiểm tra nhanh các kết nối hiện có
+
+```
+db_config_read(projectId)
+```
+
+Liệt kê **mọi kết nối** của project: alias (`db`), `apiDomain`, `sqlServer`, `database`, thư mục
+`_db/{alias}/`, trạng thái `dbToken`/`userToken` (có/không — **không trả giá trị token**), và alias
+nào đang là `default`.
+
+Gọi tool này **trước tiên** khi chưa chắc phải truyền `db` nào cho tool khác. Nó cũng nêu ra các thư
+mục trong `_db/` không thuộc kết nối nào (rác của bản cũ, hoặc kết nối đã bỏ) — không tool nào đọc
+chúng nữa, tự xóa tay khi chắc chắn không cần.
+
+---
+
+## 10. Cheat sheet — Tool theo tình huống
+
+| Tình huống | Tool cần dùng |
+|---|---|
+| **Database chưa tồn tại** — dựng dự án từ số 0 | [project-provisioning.md](project-provisioning.md) (kiểm 2 cổng quyền → CREATE DATABASE → 2 tài khoản → `db_alias_new`) |
+| Kiểm mình có quyền `CREATE DATABASE`/`CREATE LOGIN` trên máy chủ không | [project-provisioning.md](project-provisioning.md) §Bước 0 — `IS_SRVROLEMEMBER` + `HAS_PERMS_BY_NAME`, chỉ đọc |
+| Database đã có nhưng **chưa được đăng ký alias** trong `acc` | `db_alias_new` (xem [project-provisioning.md](project-provisioning.md) §Bước 5) |
+| Kết nối DB lần đầu, **đã có sẵn dbToken** | `db_connect` |
+| Kết nối DB nhưng **chỉ biết alias, không có dbToken** | `db_alias_list` → `db_connect_by_name` |
+| Xem mình được cấp quyền quản lý những database nào | `db_alias_list()` (không tham số) |
+| Project gọi thêm một database nữa (alias khác) | `db_connect_by_name` lần nữa với `apiName` mới |
+| Xem project đang có những kết nối nào, alias nào default | `db_config_read` |
+| Đổi UID/PWD, server/database giữ nguyên | `db_token_rebuild` (nêu `db` nếu nhiều kết nối) |
+| Set userToken sau khi connect | `db_user_token_set` (nêu `db` nếu nhiều kết nối) |
+| Xem danh sách tables/SPs | `db_sp_list` |
+| Lấy nội dung SP từ DB | `db_sp_get` |
+| Refresh schema từ DB thực | `db_schema_get` |
+| Đọc schema đã cache | `db_schema_read` |
+| Lưu SQL chỉnh sửa vào local | `db_sp_save` |
+| Deploy SP lên DB (tự xoá cache tAPI nếu là spAPI_*/spAPIFILE_*) | `db_sp_deploy` |
+| Xem tham số đầu vào của API đã deploy (trước khi wire vào module.json) | `db_sp_help` |
+| Xoá cache tAPI thủ công sau khi ALTER qua `db_sql_execute_nonquery` (đường đó không có auto-clear) | `db_sp_help` **(bắt buộc)** |
+| Kiểm chứng tĩnh API vừa deploy (trước khi wire vào UI, không gọi sống) | `db_sp_verify` |
+| Xóa SP khỏi DB | `db_sp_delete` |
+| Đổi tên SP | `db_sp_rename` |
+| Tìm SQLServer + DatabaseName của alias | `db_alias_list({ search })` (xem mục 2b) |
+| Build dbToken bằng cách mượn UID/PWD của kết nối sẵn có | `db_connect_by_name` làm luôn (xem mục 2b) — **đừng decode tay bằng PowerShell** |
+
+---
+
+## 11. Quy tắc thiết kế bảng
+
+Quy ước đặt tên bảng, khóa chính, trường timestamp và cột audit đã tách sang **[db-table-design.md](db-table-design.md)** — load file đó khi thiết kế schema mới.