@fui-org/fui-cli 1.3.2 → 2.0.0

package/skills/fui-skill/references/project-provisioning.md

@@ -1,37 +1,25 @@
-# Dựng hạ tầng cho một dự án FUI mới
+# Provisioning a New FUI Project
 
-> File này sở hữu: **quy trình dựng hạ tầng cho một dự án FUI mới — tạo database SQL Server, hai loại tài khoản SQL (ứng dụng execute-only vs dev db_owner), đăng ký alias vào `acc`, tạo project FUI, cấp quyền quản trị project**. Kết nối/schema/SP xem [db-workflow.md](db-workflow.md); thiết kế app nhiều module xem [system-design.md](system-design.md); quy ước đặt tên bảng xem [db-table-design.md](db-table-design.md); khái niệm quyền người dùng cuối xem [permission-system.md](permission-system.md).
+> Owns: **new-project infrastructure — SQL Server database, two SQL accounts (execute-only app vs db_owner dev), `acc` alias, FUI project, project admin rights**. Connection/schema/SP: [db-workflow.md](db-workflow.md); multi-module design: [system-design.md](system-design.md); table naming: [db-table-design.md](db-table-design.md); end-user rights: [permission-system.md](permission-system.md). Flags: `fui <command> --help`.
 
-Dùng file này khi user nói **"tạo dự án mới"**, **"tạo DB + project FUI mới"**, hoặc khi
-[system-design.md](system-design.md) Bước 0 rơi vào nhánh *"dựng mới hoàn toàn"*. Đây là bước **trước**
-mọi thứ trong `system-design.md`: chưa có database và chưa có project thì không có gì để thiết kế lên.
+Use for **"new project"** / **"new DB + FUI project"**, or [system-design.md](system-design.md) Step 0 → _"build from scratch"_. Comes **before** all of `system-design.md`.
 
-**Làm Bước 0 rồi đủ 6 bước theo đúng thứ tự, không bỏ bước nào** trừ khi user yêu cầu khác đi. Thứ tự
-này **không tuỳ tiện**: có **hai** cổng quyền ở hai hệ thống khác nhau và cả hai phải được kiểm trước
-khi tạo bất cứ thứ gì — xem mục ngay dưới.
+**Do Step 0, then Steps 1–6 in order, skipping none** unless the user says otherwise. Two permission gates in two systems must both pass before anything is created.
 
 ---
 
-## 🛑 Bước 0 — Kiểm HAI cổng quyền trước khi tạo bất cứ thứ gì
+## 🛑 Step 0 — Check BOTH gates first
 
-Dựng một dự án mới đụng vào **hai hệ thống độc lập**, mỗi hệ thống một cổng quyền riêng. Thiếu bất kỳ
-cổng nào thì quy trình không đi hết được — nhưng nếu phát hiện muộn thì đã kịp để lại rác không dọn
-được bằng tool:
+| Gate                     | Needs                             | Check with                 |
+| ------------------------ | --------------------------------- | -------------------------- |
+| **A. FUI platform**      | `SystemRight >= 3` on system `fp` | `fui project new` (Step 1) |
+| **B. Target SQL Server** | create database + create login    | read-only `SELECT` below   |
 
-| Cổng | Cần gì | Kiểm bằng |
-|---|---|---|
-| **A. Nền tảng FUI** | `SystemRight >= 3` trên hệ thống `fp` | gọi `project_new` (Bước 1) |
-| **B. SQL Server đích** | quyền tạo database + tạo login | một câu `SELECT` chỉ đọc (ngay dưới) |
+**Check B BEFORE A.** B has no side effects; A only answers by actually creating the project. Reverse order ⇒ orphan FUI project if the DB can't be created. Late discovery leaves garbage fui can't clean up.
 
-**Kiểm cổng B TRƯỚC cổng A.** Cổng B là câu truy vấn chỉ đọc, hoàn toàn không có tác dụng phụ; cổng A
-thì phải *thật sự tạo project* mới biết. Làm ngược lại là tạo ra một project FUI mồ côi khi hoá ra
-không có quyền tạo database.
+### Gate B — target SQL Server
 
-### Cổng B — quyền trên SQL Server đích
-
-`CREATE DATABASE` và `CREATE LOGIN` là thao tác **cấp máy chủ**, tài khoản dev thường ngày (chỉ
-`db_owner` trên vài database) **không làm được**. Chạy câu này qua `db_sql_execute` trên một kết nối
-**tới đúng SQL Server sắp tạo DB** (`db_alias_list()` cho biết alias nào nằm trên server nào):
+`CREATE DATABASE`/`CREATE LOGIN` are server-level; a normal dev account (`db_owner` on some DBs) can't. Run with `fui query` on a connection **to the exact target server** (`fui db alias list` shows alias → server):
 
 ```sql
 SELECT SUSER_NAME()                                        AS LoginHienTai,
@@ -42,30 +30,19 @@ SELECT SUSER_NAME()                                        AS LoginHienTai,
        HAS_PERMS_BY_NAME(NULL, NULL, 'ALTER ANY LOGIN')     AS taoDuocLogin;
 ```
 
-Đủ quyền khi: `sysadmin = 1`, **hoặc** `taoDuocDB = 1` **và** `taoDuocLogin = 1`.
+Pass: `sysadmin = 1`, **or** `taoDuocDB = 1` **and** `taoDuocLogin = 1`.
 
-- **Không phải cứ "phải là `sa`".** `sa` là đường thường gặp nhất vì nó là `sysadmin`, nhưng
-  `dbcreator` + `securityadmin` cũng đủ. Nói "cần `sa`" rồi dừng là chặn oan một cấu hình hợp lệ.
-- **Cần CẢ HAI quyền, không chỉ quyền tạo DB.** Bước 3 tạo login cho tài khoản ứng dụng — `dbcreator`
-  đơn thuần tạo được database nhưng **không** tạo được login, và ca đó hỏng ở giữa chừng: database đã
-  có, login thì không.
-- `IS_SRVROLEMEMBER` trả `NULL` (không phải `0`) khi tên role sai hoặc login không hợp lệ — đọc `NULL`
-  thành "không có quyền" là kết luận sai; coi như **không biết** và hỏi user.
-- **Kết nối phải đúng SQL Server đích.** Kết nối mượn của project anh em có thể trỏ sang máy chủ khác;
-  lúc đó câu trên trả quyền của máy chủ *sai*, và kết quả xanh là xanh nhầm chỗ.
-- ⚠️ Ở đây `HAS_PERMS_BY_NAME` là **đúng công cụ** vì ta đang hỏi về *chính principal đang kết nối*.
-  Đừng đem cách này đi hỏi quyền của principal **khác** (ví dụ `[public]` có `EXECUTE` không) — nó trả
-  lời cho người đang hỏi, nên sẽ luôn xanh với login `db_owner` và cho một câu trả lời sai. Ca đó phải
-  đọc `sys.database_permissions`.
+- `sa` not required — `dbcreator` + `securityadmin` also pass. Don't block a valid setup with "needs `sa`".
+- Need BOTH: `dbcreator` alone creates the DB but not the Step 3 login ⇒ fails midway.
+- `IS_SRVROLEMEMBER` returns `NULL` (not `0`) for a bad role name/invalid login ⇒ **unknown**, ask the user.
+- A connection borrowed from a sibling project may point at another server ⇒ green for the wrong server.
+- ⚠️ `HAS_PERMS_BY_NAME` answers only for the _connected principal_ — correct here. Never use it for another principal (e.g. `[public]` `EXECUTE`): always green for `db_owner`. Read `sys.database_permissions` instead.
 
-Thiếu quyền ⇒ **dừng, báo user xin cấp quyền trên máy chủ đó**. Đừng chạy `CREATE DATABASE` để "xem nó
-có lỗi không" — và cũng đừng tự hạ tiêu chuẩn xuống bằng cách cấp `db_datareader` cho tài khoản ứng
-dụng để né bước tạo login.
+Fails ⇒ **stop; user must request rights on that server**. Never run `CREATE DATABASE` to probe; never grant `db_datareader` to the app account to avoid creating a login.
 
-### Cổng A — quyền trên nền tảng FUI
+### Gate A — FUI platform
 
-Tạo project FUI đòi **`SystemRight >= 3`** trên hệ thống `fp`. Đây là cổng **server-side**, nằm trong
-thân `spAPI_FUI_Dev_ProjectEdit` — không né được bằng cách gọi API trực tiếp:
+Creating a project needs **`SystemRight >= 3`** on `fp`, enforced server-side in `spAPI_FUI_Dev_ProjectEdit` (direct API calls can't bypass):
 
 ```sql
 if @jID is null                 -- không có id ⇒ đang TẠO MỚI
@@ -74,137 +51,98 @@ Begin
         RAISERROR(N'Bạn không có quyền tạo dự án', 16, 1)
 ```
 
-**Không có quyền thì DỪNG NGAY và báo lại user — đừng làm bước nào khác.** Lý do đặt `project_new`
-trước phần database: `INSERT INTO tblA_Project` chỉ cần
-`ProjectID`/`ProjectName`/`GroupName`/`Framework`/`pDomain`/`Router`, **không tham chiếu database nào**
-— nên tạo project *không* cần DB có trước. Làm DB trước rồi mới phát hiện bị từ chối là để lại một
-database thật, hai SQL login và một bản ghi `acc` mồ côi; mà `DROP DATABASE` thì MCP chặn cứng, dọn
-phải làm tay.
-
-Gọi `project_new` chính là phép kiểm cổng A — vừa là việc phải làm, không tốn thêm lượt gọi nào. Bị từ
-chối thì chưa có gì được tạo ra (với điều kiện cổng B đã kiểm trước, đúng thứ tự ở trên).
-
-Ba mức quyền khác nhau cho ba thao tác, đừng nhầm (đọc từ thân SP thật):
+**No right ⇒ STOP, report, do nothing else.** Project goes before the DB because `INSERT INTO tblA_Project` needs only `ProjectID`/`ProjectName`/`GroupName`/`Framework`/`pDomain`/`Router` — no database. DB-first then rejection leaves a real DB, two SQL logins and an orphan `acc` record; fui hard-blocks `DROP DATABASE`, so cleanup is manual. `fui project new` _is_ the gate A check (no extra call); rejected ⇒ nothing created (if B was checked first).
 
-| Thao tác | SP | Điều kiện |
-|---|---|---|
-| **Tạo** project (`project_new`) | `spAPI_FUI_Dev_ProjectEdit` (`id` rỗng) | `SystemRight >= 3` |
-| **Sửa** project (`project_update`) | `spAPI_FUI_Dev_ProjectEdit` (có `id`) | `SystemRight >= 2` **và** `UserRight > 2` |
-| Publish `project.json` (`project_publish_config`) | `spAPI_FUI_Dev_EditorUpdate` (`Mode = 'project'`) | `SystemRight >= 2` **và** `UserRight > 2` |
-| Tạo/sửa **module**, publish module | `spAPI_FUI_Dev_ModuleEdit` · `spAPI_FUI_Dev_EditorUpdate` | `SystemRight >= 2` **và** `UserRight > 1` |
+| Operation                                             | SP                                                        | Condition                                  |
+| ----------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------ |
+| **Create** project (`fui project new`)                | `spAPI_FUI_Dev_ProjectEdit` (empty `id`)                  | `SystemRight >= 3`                         |
+| **Edit** project (`fui project update`)               | `spAPI_FUI_Dev_ProjectEdit` (with `id`)                   | `SystemRight >= 2` **and** `UserRight > 2` |
+| Publish `project.json` (`fui project publish-config`) | `spAPI_FUI_Dev_EditorUpdate` (`Mode = 'project'`)         | `SystemRight >= 2` **and** `UserRight > 2` |
+| Create/edit/publish **module**                        | `spAPI_FUI_Dev_ModuleEdit` · `spAPI_FUI_Dev_EditorUpdate` | `SystemRight >= 2` **and** `UserRight > 1` |
 
-`SystemRight` là điều kiện **cần** (toàn hệ thống `fp`), `UserRight` là điều kiện **đủ** (trên đúng
-project đó) — hai trục AND với nhau. Chỉ riêng *tạo* project là không xét `UserRight`, vì project chưa
-tồn tại thì chưa có dòng nào trong `tblA_UserProject`.
+`SystemRight` (whole `fp`) is necessary, `UserRight` (that project) sufficient — ANDed. Only _create_ skips `UserRight` (no `tblA_UserProject` row yet).
 
-> ⚠️ `pDomain` được kiểm **trước** cổng quyền (`CheckDomain`): domain trùng với project khác sẽ báo lỗi
-> domain chứ không phải lỗi quyền. Đừng đọc nhầm thông báo rồi đi xin cấp quyền.
+> ⚠️ `pDomain` is checked **before** the permission gate (`CheckDomain`): a duplicate domain gives a domain error, not a permission error. Don't go request rights over it.
 
 ---
 
-## Chỉ mục — dựng một dự án mới đi qua những file nào
+## Index — phases of a new project
 
-File này **chỉ sở hữu giai đoạn 1**. Một dự án mới đi trọn 7 giai đoạn; đây là bản đồ để biết đang ở đâu
-và đọc tiếp file nào, thay vì mò từng file một.
+This file owns **phase 1 only**.
 
-| # | Giai đoạn | File sở hữu | Làm gì |
-|---|---|---|---|
-| 0 | Làm rõ phạm vi với user | [system-design.md](system-design.md) §Bước 0 | Ai dùng, quy trình nghiệp vụ, entity chính |
-| **1** | **Hạ tầng ← BẠN ĐANG Ở ĐÂY** | **file này** (Bước 0 + 1–6) | Kiểm 2 cổng quyền → `project_new` → DB + 2 tài khoản SQL + alias `acc` → quyền quản trị |
-| 2 | Phân rã hệ thống thành module | [system-design.md](system-design.md) §Bước 1 | Danh sách module, vai trò truy cập |
-| 3 | Thiết kế schema | [db-table-design.md](db-table-design.md) | Quy ước đặt tên bảng, PK/FK, cột audit. `CREATE TABLE` do **lập trình viên tự chạy** |
-| 4 | Định nghĩa quyền **người dùng cuối** | [permission-system.md](permission-system.md) + [system-design.md](system-design.md) §Bước 4b | `right_system_new` / `right_function_new` — làm TRƯỚC khi module nào gác quyền |
-| 5 | Cấu hình runtime project | [project-config.md](project-config.md) | `project.json`: menu, menuLeft, điều hướng, domainSetting |
-| 6 | Module đầu tiên | `module_new` → [fullstack-workflow.md](fullstack-workflow.md) | Quy trình 6 bước UI-first cho từng module |
+| #     | Phase                     | Owner                                                                                        | Do                                                                                  |
+| ----- | ------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| 0     | Clarify scope             | [system-design.md](system-design.md) §Step 0                                                 | Users, process, main entities                                                       |
+| **1** | **Infrastructure ← HERE** | **this file**                                                                                | 2 gates → `fui project new` → DB + 2 SQL accounts + `acc` alias → admin rights      |
+| 2     | Split into modules        | [system-design.md](system-design.md) §Step 1                                                 | Module list, access roles                                                           |
+| 3     | Schema                    | [db-table-design.md](db-table-design.md)                                                     | Naming, PK/FK, audit columns. `CREATE TABLE` **run by the developer**               |
+| 4     | **End-user** rights       | [permission-system.md](permission-system.md) + [system-design.md](system-design.md) §Step 4b | `fui right system new` / `fui right function new` — BEFORE any module gates on them |
+| 5     | Runtime config            | [project-config.md](project-config.md)                                                       | `project.json`: menu, menuLeft, navigation, domainSetting                           |
+| 6     | First module              | `fui module new` → [fullstack-workflow.md](fullstack-workflow.md)                            | 6-step UI-first flow                                                                |
 
-**Không thuộc file này** (đừng tìm ở đây, cũng đừng chép vào đây): quy ước đặt tên bảng · cấu hình menu ·
-quyền người dùng cuối · cách viết SP ([tapi-reference.md](tapi-reference.md)) · kết nối/schema/SP hằng
-ngày ([db-workflow.md](db-workflow.md)).
+Not in this file (don't look or copy here): table naming · menus · end-user rights · SP writing ([tapi-reference.md](tapi-reference.md)) · daily connection/schema/SP ([db-workflow.md](db-workflow.md)).
 
 ---
 
-## 🔴 Hai mặt phẳng quyền — đọc trước, đừng trộn
+## 🔴 Two permission planes — don't mix
 
-Từ "quyền" trong FUI trỏ tới **hai hệ thống khác hẳn nhau**. Nhầm hai cái này là đi cấp quyền ở sai nơi
-rồi kết luận "cấp rồi mà không có tác dụng".
+|           | `SystemRight` (system `acc`)                                       | `UserRight` (`tblA_UserProject`)        |
+| --------- | ------------------------------------------------------------------ | --------------------------------------- |
+| Scope     | **System-wide** — one number per user per app                      | **Per project**                         |
+| Answers   | "What can this user do in app X?"                                  | "What can this user do with project Y?" |
+| Stored in | `acc.tblSysRight` + `acc` assignment tables                        | `tblA_UserProject` (FUI platform DB)    |
+| Commands  | `fui right ...` (8) → [permission-system.md](permission-system.md) | `fui user ...` (5) → Step 6             |
 
-| | `SystemRight` (hệ thống `acc`) | `UserRight` (bảng `tblA_UserProject`) |
-|---|---|---|
-| Phạm vi | **Toàn hệ thống** — một con số cho một user trên một app | **Từng project một** |
-| Trả lời câu hỏi | "User này làm được gì trong app X nói chung?" | "User này làm được gì với project Y cụ thể?" |
-| Lưu ở | `acc.tblSysRight` + bảng gán quyền của `acc` | `tblA_UserProject` (DB nền tảng FUI) |
-| Tool | 8 tool `right_*` → [permission-system.md](permission-system.md) | 5 tool `project_user_*` → Bước 6 dưới đây |
+Mixing them = granting in the wrong place, then "granted but no effect". The FUI IDE _is itself a FUI app_ (project `fp`), so `SystemRight` on `fp` = developer rights in the IDE:
 
-**Chỗ dễ nhầm nhất:** IDE FUI *bản thân nó cũng là một app FUI* (project `fp`). Nên `SystemRight` trên
-`fp` chính là "quyền của lập trình viên trong IDE" — **không** phải chỉ là quyền của người dùng cuối
-như bảng cũ của file này từng ghi. Cụ thể:
+- `SystemRight` on `fp` = **may create projects** (≥ 3); necessary for every edit.
+- `UserRight` on project Y = **may touch Y**; sufficient.
+- ANDed: `UserRight = 3` with `SystemRight = 1` can't edit anything.
 
-- `SystemRight` trên `fp` = **được phép tạo project hay không** (≥ 3), và là điều kiện *cần* cho mọi
-  thao tác sửa.
-- `UserRight` trên project Y = **được đụng vào project Y hay không**. Điều kiện *đủ*.
-- Hai cái **AND với nhau**, xem bảng ba thao tác ở mục trên. Có `UserRight = 3` mà `SystemRight = 1`
-  thì vẫn không sửa được gì.
-
-Còn `SystemRight`/`FunctionRight` trên **project nghiệp vụ của bạn** (không phải `fp`) thì đúng là quyền
-của người dùng cuối trong app đó — việc đó làm sau, theo
-[system-design.md](system-design.md) Bước 4b.
+`SystemRight`/`FunctionRight` on **your business project** (not `fp`) are end-user rights — later, per [system-design.md](system-design.md) Step 4b.
 
 ---
 
-## Bước 1 — Tạo project FUI (đây là cổng A, làm trước phần database)
+## Step 1 — Create the FUI project (gate A, before the DB)
 
 ```
-project_new({ projectData: {
-  ProjectID: "...", ProjectName: "...", GroupName: "...", Framework: "V3",
-  pDomain: "...",            // tuỳ chọn — tên miền riêng của project
-  Router: ""                 // tuỳ chọn, mặc định ""
-}})
+fui project new --data '{
+  "ProjectID": "...", "ProjectName": "...", "GroupName": "...", "Framework": "V3",
+  "pDomain": "...",
+  "Router": ""
+}'
 ```
 
-- **Chỉ SÁU field này được đọc.** `spAPI_FUI_Dev_ProjectEdit` lấy đúng `ProjectID`, `ProjectName`,
-  `GroupName`, `Framework`, `pDomain`, `Router` từ `@jsonObj` rồi thôi.
-- 🔴 **Đừng truyền `title`/`login`/`apiDomain`/`fileDomain`/`userInfo`/`menu` vào đây — chúng bị BỎ
-  QUA, lặng lẽ.** SP ghi cột `projectData` bằng một hằng số rỗng cứng trong thân nó:
+`pDomain` optional (project's own domain); `Router` optional, default `""`.
+
+- **Only these SIX fields are read** from `@jsonObj`.
+- 🔴 **`title`/`login`/`apiDomain`/`fileDomain`/`userInfo`/`menu` are silently IGNORED.** The SP writes `projectData` from a hardcoded constant:
   ```sql
   declare @jProjectdata nvarchar(1000) = '{"title":"","apiDomain":"","login":"","menu":[]}'
   ```
-  Truyền vào thì API vẫn trả ✅ và project vẫn được tạo — chỉ là cấu hình runtime **không nằm ở đâu
-  cả**. Đúng kiểu hỏng-âm-thầm: mọi dấu hiệu đều nói thành công.
-- **Cấu hình runtime đặt ở bước riêng sau đó**: sửa file `{projectId}/project.json` rồi
-  `project_publish_config` — xem [project-config.md](project-config.md). Đây là đường **duy nhất** để
-  `menu`/`apiDomain`/`login` thật sự vào được project.
-- **`projectData` phải PHẲNG** — không bọc trong `"data"`.
-- **`Framework`: dự án mới dùng `V3`** trừ khi user nêu lý do khác (thường là phải đồng bộ với các
-  project cũ cùng nhóm). Đây là lựa chọn **không đổi lại được rẻ**: nó quyết định tầng import, vocabulary
-  component, và cả cú pháp grid — V2 là Vuetify 1.5 (`v-container/v-layout/v-flex`), V3 là Vuetify 3
-  (`v-container/v-row/v-col`), và ngưỡng `w` px của hai bên cũng khác nhau. Phần lớn ví dụ module.json
-  trong skill viết theo cú pháp **V2** (đa số project đang chạy), nên khi làm project V3 phải đối chiếu
-  → [controls-patterns.md](controls-patterns.md) §6 (chủ sở hữu bảng khác biệt V2/V3). Nêu rõ lựa chọn
-  này với user, đừng để nó thành mặc định ngầm.
-
-**Người gọi API tự động được `UserRight = 3` trên project vừa tạo — chỉ người tạo, không ai khác**
-(SP tự `INSERT INTO tblA_UserProject ... 3`). Đó chính là lý do phải có Bước 6.
-
-Bị từ chối `Bạn không có quyền tạo dự án` → **dừng hẳn, báo user xin `SystemRight >= 3` trên hệ thống
-`fp`**. Không đi tiếp các bước dưới: lúc này chưa có gì được tạo ra, và nên giữ nguyên như vậy.
+  API still returns ✅, project created, config lost — silent failure.
+- Runtime config: edit `{projectId}/project.json` then `fui project publish-config` ([project-config.md](project-config.md)) — the **only** way `menu`/`apiDomain`/`login` get in.
+- `projectData` must be **FLAT** — not wrapped in `"data"`.
+- **`Framework`: `V3` for new projects** unless the user has a reason (usually matching older projects in the group). Expensive to change: decides import layer, component vocabulary, grid syntax — V2 = Vuetify 1.5 (`v-container/v-layout/v-flex`), V3 = Vuetify 3 (`v-container/v-row/v-col`), and `w` px thresholds differ. Most skill module.json examples are **V2**; for V3 cross-check [controls-patterns.md](controls-patterns.md) §6 (V2/V3 diff owner). State the choice to the user; never implicit.
+
+**Only the caller gets `UserRight = 3` on the new project** (SP `INSERT INTO tblA_UserProject ... 3`) — hence Step 6.
+
+Rejected with `Bạn không có quyền tạo dự án` ⇒ **stop; user must request `SystemRight >= 3` on `fp`**. Nothing created yet — keep it so.
 
 ---
 
-## Bước 2 — Tạo database
+## Step 2 — Create the database
 
-> Điều kiện tiên quyết: **cổng B ở Bước 0 đã xanh** (`sysadmin`, hoặc `CREATE ANY DATABASE` +
-> `ALTER ANY LOGIN`). Chưa kiểm thì quay lại kiểm — đừng chạy `CREATE DATABASE` để dò xem có lỗi không.
+> Prerequisite: gate B green. Never run `CREATE DATABASE` to probe.
 
-**Hỏi server đích xem các database khác đang để file vật lý ở đâu trước, không hardcode đường dẫn.**
-Mỗi server một quy ước; đoán sai thì file nằm lạc chỗ và không ai phát hiện cho tới lúc backup.
+**Query where the server keeps other DB files; never hardcode paths** (wrong guess = misplaced files, unnoticed until backup):
 
 ```sql
 SELECT DISTINCT LEFT(physical_name, LEN(physical_name) - CHARINDEX('\', REVERSE(physical_name)))
 FROM sys.master_files WHERE database_id > 4;
 ```
 
-`database_id > 4` để bỏ `master`/`model`/`msdb`/`tempdb` — chúng nằm ở thư mục cài đặt SQL Server, không
-phải nơi đặt DB nghiệp vụ. Kết quả thường gặp: `C:\Application\Database\`. Dùng chung đúng quy ước đó:
+`database_id > 4` skips `master`/`model`/`msdb`/`tempdb` (install dir). Typical: `C:\Application\Database\`. Follow it:
 
 ```sql
 CREATE DATABASE [TenDB]
@@ -212,15 +150,13 @@ ON PRIMARY (NAME = N'TenDB',     FILENAME = N'C:\Application\Database\TenDB.mdf'
 LOG ON      (NAME = N'TenDB_log', FILENAME = N'C:\Application\Database\TenDB_log.ldf');
 ```
 
-**Vòng gà–trứng:** DB mới chưa có kết nối nào, nên chạy câu này qua một kết nối **đã có sẵn tới chính
-SQL Server đó** — `db_alias_list()` cho biết alias nào đang nằm trên server nào, rồi
-`db_connect_by_name({ apiName })` để mượn. Chạy bằng `db_sql_execute_nonquery({ confirmWrite: true })`.
+Chicken-and-egg: the new DB has no connection — borrow an **existing connection on the same server** (`fui db alias list`, then `fui db add-by-name <apiName>`) and run `fui exec "<sql>" --confirm-write`.
 
 ---
 
-## Bước 3 — Tài khoản ỨNG DỤNG (execute-only)
+## Step 3 — APP account (execute-only)
 
-Login **trùng tên database**, mật khẩu ngẫu nhiên mạnh:
+Login **named after the DB**, strong random password:
 
 ```bash
 openssl rand -base64 12
@@ -234,19 +170,15 @@ CREATE USER [TenDB] FOR LOGIN [TenDB];
 GRANT EXECUTE ON SCHEMA::dbo TO [TenDB];
 ```
 
-**Chỉ `public` + `GRANT EXECUTE ON SCHEMA::dbo`. KHÔNG `db_datareader`, KHÔNG `db_datawriter`, KHÔNG
-cấp quyền trên bảng.** Lý do: tAPI chỉ chạy stored procedure, nên execute-only là **đủ dùng** — mọi SP
-mới tự động nằm trong `SCHEMA::dbo` nên không phải cấp lại từng cái. Cấp thêm quyền bảng không giúp app
-chạy tốt hơn, nó chỉ mở sẵn đường đọc/ghi thẳng bảng cho một lời gọi bị lợi dụng.
+**Only `public` + `GRANT EXECUTE ON SCHEMA::dbo`. NO `db_datareader`, NO `db_datawriter`, NO table grants.** tAPI only runs SPs; new SPs fall under `SCHEMA::dbo` automatically. Table rights don't help the app — they only open direct table access to an abused call.
 
-Đây là tài khoản **duy nhất** được nạp vào `acc` ở Bước 5.
+The **only** account loaded into `acc` (Step 5).
 
 ---
 
-## Bước 4 — Tài khoản DEV (db_owner)
+## Step 4 — DEV account (db_owner)
 
-**Mặc định dùng lại tài khoản dev dùng chung sẵn có** của hệ thống (ví dụ `xTuan`) — login đã tồn tại ở
-cấp server, chỉ cần cấp vào database mới:
+**Default: reuse the existing shared dev login** (e.g. `xTuan`) — just add it to the new DB:
 
 ```sql
 USE [TenDB];
@@ -254,130 +186,93 @@ CREATE USER [xTuan] FOR LOGIN [xTuan];
 ALTER ROLE db_owner ADD MEMBER [xTuan];
 ```
 
-**KHÔNG `CREATE LOGIN` mới** trừ khi user yêu cầu riêng một tài khoản dev cho project đó. Đẻ thêm login
-cho mỗi project là đẻ thêm một mật khẩu phải quản lý, trong khi tài khoản dùng chung đã có sẵn ở mọi
-DB anh em — và chính nó là cặp credential mà `db_connect_by_name` mượn được.
+**NO new `CREATE LOGIN`** unless the user asks for a project-specific dev account — each extra login is another password, while the shared one exists in every sibling DB and is the credential `fui db add-by-name` borrows.
 
 ---
 
-## Bước 5 — Đăng ký database thành alias tAPI
+## Step 5 — Register the DB as a tAPI alias
 
 ```
-db_alias_new({
-  apiName:    "tenalias",          // module.json sẽ gọi "/tenalias/TenAPI"
-  moduleName: "Tên hệ thống",
-  sqlServer:  "...",
-  database:   "TenDB",
-  username:   "TenDB",             // tài khoản ỨNG DỤNG ở Bước 3
-  password:   "<mật khẩu Bước 3>"
-})
+fui db alias new tenalias \
+  --module-name "Tên hệ thống" \
+  --sql-server "..." \
+  --database TenDB \
+  --username TenDB \
+  --password-env TENDB_PASSWORD
 ```
 
-Tool gọi `SM_Modules_Update` **hai lượt** — `UpdateConnection=0` tạo record, rồi `UpdateConnection=1`
-nạp connection — vì record phải tồn tại trước khi set connection lên nó.
+`tenalias` → module.json calls `"/tenalias/TenAPI"`. Password only via `--password -` (stdin) or `--password-env VAR`.
+
+fui calls `SM_Modules_Update` **twice**: `UpdateConnection=0` creates the record, `UpdateConnection=1` sets the connection (record must exist first).
 
-- 🔴 **`username`/`password` phải là tài khoản ỨNG DỤNG ở Bước 3, KHÔNG phải tài khoản dev.** Nạp nhầm tài khoản dev
-  thì **mọi lời gọi API của app chạy dưới quyền `db_owner`** — không có lỗi nào nổi lên, app chạy y hệt,
-  chỉ là hàng rào bảo mật biến mất.
-- `ModuleID` mới = `MAX(ModuleID)+1` trên **toàn bộ** `acc.tblModules` → tool cần một kết nối alias
-  `acc` (`db_connect_by_name({ apiName: "acc" })`). Không suy từ `db_alias_list` được: danh sách đó chỉ
-  gồm module **bạn** được quản lý, MAX trên tập con có thể đụng ID của người khác.
-- Alias đã tồn tại ⇒ lỗi cứng, tool không ghi đè.
+- 🔴 **Credentials = Step 3 APP account, NEVER the dev account.** Dev account ⇒ every app API call runs as `db_owner`, with no visible error.
+- New `ModuleID` = `MAX(ModuleID)+1` over **all** `acc.tblModules` ⇒ needs an `acc` connection (`fui db add-by-name acc`). Can't use `fui db alias list`: it lists only modules **you** manage; MAX over a subset may collide.
+- Existing alias ⇒ hard error, no overwrite.
 
-Xong bước này thì `db_connect_by_name({ apiName: "tenalias" })` dùng được — xem
-[db-workflow.md](db-workflow.md) §2b.
+Then `fui db add-by-name tenalias` works — [db-workflow.md](db-workflow.md) §2b.
 
 ---
 
-## Bước 6 — Cấp quyền quản trị project cho người khác
+## Step 6 — Grant project admin to others
 
-Ba bước, và thứ tự này là **bắt buộc** chứ không phải gợi ý:
+Order is **mandatory**:
 
 ```
-1. project_user_list()                              → ai đang có quyền
-2. project_user_search({ textsearch: "tên/username" }) → lấy UserID thật
-3. project_user_new({ userId: "DEV001", userRight: 3 })
+1. fui user list                     → who has rights now
+2. fui user search "tên/username"    → get the real UserID
+3. fui user add DEV001 --right 3
 ```
 
-**`project_user_new`/`_update`/`_delete` chỉ nhận `userId` chính xác, không nhận tên hay username.**
-Đây là cổng xác nhận danh tính, và nó là **cấu trúc chứ không phải lời nhắc**: muốn có `userId` thì bắt
-buộc đã chạy `project_user_search` và đã nhìn thấy bảng `UserID | Username | Họ tên`. **Đưa bảng đó cho
-user xem và để họ chọn trước khi cấp** — trùng tên là chuyện thường, và cấp nhầm quyền Admin cho người
-khác không lùi được bằng một lượt gọi.
-
-| Mức | Nghĩa |
-|---|---|
-| 1 | View only |
-| 2 | Develop |
-| 3 | **Admin** — mức cần cho người quản lý project (`project_publish_config` đòi `> 2`) |
-
-- Tạo và sửa là **hai tool riêng**: `project_user_new` lỗi cứng nếu user đã có quyền (trỏ sang
-  `_update`), và ngược lại. Không tool nào upsert ngầm.
-- Thu hồi quyền là `project_user_delete` — 🔴 tóm tắt hậu quả và chờ user xác nhận trước khi gọi.
-- **Quyền LUÔN là cấp project — không có biến thể cấp module.** Chữ ký SP có `@MID` và module
-  `fp/permission` của IDE cũng truyền nó, nhưng **thân SP không bao giờ đọc**: mọi thao tác lọc theo
-  `ProjectID`. Đừng suy ra một phạm vi không tồn tại từ việc thấy tham số đó.
-
-**Điều kiện để CHÍNH BẠN cấp được quyền** (thân `spAPI_FUI_Dev_UserRight_Update`):
-`SystemRight >= 2` **và** (`UserRight > 2` trên project đó **hoặc** `SystemRight >= 4`) — tức
-`SystemRight >= 4` cấp được cho mọi project mà không cần là admin của project đó. Chỉ *xem* danh sách
-(`project_user_list`) thì nhẹ hơn: `SystemRight >= 2` và (`UserRight > 1` hoặc `SystemRight >= 3`).
+**`fui user add`/`set`/`remove` take only the exact `UserID`** — a structural identity gate: you must run `fui user search` and see `UserID | Username | Họ tên`. **Show that table and let the user pick before granting** — duplicate names are common; a wrong Admin grant can't be undone in one call.
+
+| Level | Meaning                                                                                |
+| ----- | -------------------------------------------------------------------------------------- |
+| 1     | View only                                                                              |
+| 2     | Develop                                                                                |
+| 3     | **Admin** — needed to manage the project (`fui project publish-config` requires `> 2`) |
+
+- Create and edit are separate: `fui user add` hard-errors if rights exist (use `set`), and vice versa. No silent upsert.
+- Revoke = `fui user remove` — 🔴 summarize the consequence, wait for confirmation.
+- **Rights are ALWAYS project-level.** The SP has `@MID` and IDE module `fp/permission` passes it, but the body never reads it — all filtering is by `ProjectID`. Don't infer a module scope.
+
+**For YOU to grant** (`spAPI_FUI_Dev_UserRight_Update`): `SystemRight >= 2` **and** (`UserRight > 2` on the project **or** `SystemRight >= 4`) — `SystemRight >= 4` grants on any project. _Listing_ (`fui user list`): `SystemRight >= 2` and (`UserRight > 1` or `SystemRight >= 3`).
 
 ---
 
-## Xong hạ tầng rồi — đi tiếp đâu
+## After infrastructure
 
-Hết Bước 6 là **hết giai đoạn 1**, chưa phải hết việc: lúc này project **rỗng và chưa có cấu hình
-runtime** (`menu`/`apiDomain`/`login` vẫn là chuỗi rỗng do SP seed — xem Bước 1), chưa có bảng, chưa có
-module, chưa có mã quyền nào. Đừng dừng ở đây và báo "đã xong", cũng đừng nhảy thẳng vào viết module.json.
+Step 6 ends **phase 1 only**: the project is empty, runtime config still SP-seeded empty strings, no tables/modules/right codes. Don't report "done"; don't jump into module.json.
 
-1. `project_sync({ projectId })` + `session_set({ projectId })` — kéo project về workspace và đặt làm
-   target, khỏi phải truyền `projectId` ở mọi bước sau.
-2. **Cấu hình runtime**: sửa `{projectId}/project.json` (`apiDomain` trỏ vào alias vừa tạo, `title`,
-   `login`, `menu`) rồi `project_publish_config` — [project-config.md](project-config.md). **Bắt buộc**,
-   không phải tuỳ chọn: `project_new` không nhận những khoá này, nên bỏ qua bước này là project không
-   gọi được API nào.
-3. `db_connect_by_name({ apiName })` — kết nối alias vừa tạo ([db-workflow.md](db-workflow.md) §2c).
-   Đây cũng là **phép thử** rằng Bước 3 và Bước 5 đã đúng: nó chạy được nghĩa là tài khoản ứng dụng và
-   bản ghi `acc` đều ổn.
-4. Quay lại [system-design.md](system-design.md) từ **Bước 1** và đi tiếp theo thứ tự ở chỉ mục trên.
+1. `fui project sync` + `fui use <projectId>` — pull into workspace, set as target.
+2. **Runtime config (mandatory)**: edit `{projectId}/project.json` (`apiDomain` → new alias, `title`, `login`, `menu`), then `fui project publish-config` — [project-config.md](project-config.md). Skipped ⇒ the project can't call any API.
+3. `fui db add-by-name <apiName>` ([db-workflow.md](db-workflow.md) §2c) — also **proves** Steps 3 and 5 (app account + `acc` record OK).
+4. Resume [system-design.md](system-design.md) at **Step 1**, following the index.
 
-Dự án chỉ có **một** module đơn giản (không cần phân rã hệ thống) thì bỏ qua `system-design.md`, đi
-thẳng `module_new` → [fullstack-workflow.md](fullstack-workflow.md).
+Only **one** simple module ⇒ skip `system-design.md`: `fui module new` → [fullstack-workflow.md](fullstack-workflow.md).
 
 ---
 
 ## Checklist
 
-- [ ] **Cổng B (SQL Server)** đã kiểm bằng `SELECT` chỉ đọc, trên kết nối tới **đúng máy chủ đích**: `sysadmin = 1`, hoặc `CREATE ANY DATABASE` **và** `ALTER ANY LOGIN` đều `= 1`
-- [ ] **Cổng A (FUI)**: `project_new` chạy TRƯỚC phần database và đã thành công — không có `SystemRight >= 3` thì dừng ở đây, chưa tạo database nào
-- [ ] `projectData` PHẲNG, **chỉ 6 field** (`ProjectID`/`ProjectName`/`GroupName`/`Framework`/`pDomain`/`Router`); `Framework` đã chốt với user
-- [ ] Đã query `sys.master_files` để lấy đúng thư mục file vật lý, không hardcode
-- [ ] `CREATE DATABASE` với `FILENAME` theo đúng quy ước của server đó
-- [ ] Tài khoản ứng dụng: login trùng tên DB, mật khẩu ngẫu nhiên, **chỉ** `GRANT EXECUTE ON SCHEMA::dbo`
-- [ ] Tài khoản dev: **dùng lại login dùng chung**, chỉ `CREATE USER` + `db_owner`
-- [ ] `db_alias_new` đã nạp **tài khoản ứng dụng** (không phải tài khoản dev)
-- [ ] `db_connect_by_name({ apiName })` chạy được — chứng minh alias + credential đều đúng
-- [ ] `project_user_list` cho thấy đúng những người cần có quyền
-- [ ] Đã `project_sync` + `session_set` + **`project_publish_config`** (cấu hình runtime — `project_new` KHÔNG nhận `menu`/`apiDomain`/`login`)
-- [ ] Đã nói cho user biết **giai đoạn 2 là gì** (xem chỉ mục ở đầu file) — không dừng lại ở "hạ tầng xong"
-- [ ] **Kiểm chứng bảo mật**: đăng nhập bằng tài khoản ứng dụng, `SELECT TOP 1 * FROM <bảng bất kỳ>` phải
-      **bị từ chối** còn `EXEC` một SP thì chạy. Không kiểm thì không biết `GRANT` đã đúng hay chưa
+- [ ] Gate B: read-only `SELECT` on the **target server** — `sysadmin = 1`, or `CREATE ANY DATABASE` **and** `ALTER ANY LOGIN` = 1
+- [ ] Gate A: `fui project new` ran BEFORE the DB and succeeded — else stop, no DB
+- [ ] `projectData` FLAT, **only 6 fields**; `Framework` agreed with user
+- [ ] Physical folder from `sys.master_files`, not hardcoded; `CREATE DATABASE` `FILENAME` follows it
+- [ ] App account: login = DB name, random password, **only** `GRANT EXECUTE ON SCHEMA::dbo`
+- [ ] Dev account: **shared login reused**, only `CREATE USER` + `db_owner`
+- [ ] `fui db alias new` loaded the **app account**
+- [ ] `fui db add-by-name <apiName>` works
+- [ ] `fui user list` shows exactly the right people
+- [ ] `fui project sync` + `fui use` + **`fui project publish-config`** done
+- [ ] Told the user **what phase 2 is**
+- [ ] **Security check**: as the app account, `SELECT TOP 1 * FROM <any table>` is **denied** and `EXEC` of an SP works — otherwise the `GRANT` is unverified
 
 ---
 
-## Ba điều dễ hiểu sai
+## Three common misreadings
 
-**DDL ở đây khác luật DDL của schema nghiệp vụ.** `CREATE DATABASE` / `CREATE LOGIN` / `GRANT` là DDL
-**cấp server và đăng nhập**, chạy qua `db_sql_execute_nonquery({ confirmWrite: true })` như mô tả ở
-trên. Luật *"`CREATE TABLE`/`ALTER TABLE` do lập trình viên tự chạy"* của
-[system-design.md](system-design.md) Bước 2 vẫn nguyên vẹn và chỉ nói về **schema nghiệp vụ** — hai luật
-không mâu thuẫn, chúng nói về hai loại đối tượng khác nhau.
+**Server-level DDL ≠ business-schema DDL.** `CREATE DATABASE` / `CREATE LOGIN` / `GRANT` run via `fui exec "<sql>" --confirm-write`. The _"`CREATE TABLE`/`ALTER TABLE` run by the developer"_ rule ([system-design.md](system-design.md) Step 2) still stands for the **business schema** only — no conflict.
 
-**Mật khẩu tài khoản ứng dụng nằm nguyên văn trong transcript** ở Bước 3, vì câu `CREATE LOGIN` đi qua
-tham số tool. Đó là sự thật của quy trình, không giấu được: coi transcript của phiên dựng hạ tầng là
-nhạy cảm. Từ Bước 5 trở đi không tool nào in lại mật khẩu đó nữa (`db_alias_new` và `db_alias_list` đều cố
-ý không in trường `Password`).
+**The app password is in the transcript verbatim** (Step 3 `CREATE LOGIN` goes through the fui command) — treat the provisioning transcript as sensitive. From Step 5 on nothing prints it (`fui db alias new`/`fui db alias list` omit `Password`).
 
-**`UserRight` ở Bước 6 không phải `SystemRight` trên project nghiệp vụ.** Xem lại bảng hai mặt phẳng ở đầu file. Cấp `UserRight=3`
-cho một người **không** cho họ quyền gì trong app đang chạy, và ngược lại.
+**Step 6 `UserRight` ≠ `SystemRight` on the business project.** `UserRight=3` grants **nothing** in the running app, and vice versa.