@fui-org/fui-cli 1.3.2 → 2.1.0

package/skills/fui-skill/references/controls-styling-vocabulary.md

@@ -1,113 +1,145 @@
-# Controls Styling — Bộ từ vựng layout được duyệt (chỉ dùng thế này)
+# Controls Styling — Approved Layout Vocabulary (use only this)
 
-> File này sở hữu: **bộ class/prop/style được duyệt cho `controls` và `.vue`, thứ tự ưu tiên khi trình bày**. Chọn chế độ thẩm mỹ + giới hạn `border-radius` xem [design-modes.md](design-modes.md).
+> Owns: **approved class/prop/style set for `controls` and `.vue`, and presentation priority order**. Aesthetic mode + `border-radius` limits: [design-modes.md](design-modes.md).
 
-**Quy tắc số 1: KHÔNG tự thêm `style` và `class` để "làm đẹp" UI.** Chỉ dùng đúng bộ từ vựng dưới đây — được rút trích từ 78 file `module.json` thực tế của 5 dự án (contest-score, security-manager, fp, lhu-test, lhu-lib). Nếu người mô tả không yêu cầu một hiệu ứng/khoảng cách/màu cụ thể → **không thêm gì cả**. Layout của FUI (grid + Vuetify + theme project) đã đủ đẹp và nhất quán.
+**Rule #1: do NOT add `style` or `class` to "beautify" UI.** Use only the vocabulary below (extracted from 78 real `module.json` files across 5 projects: contest-score, security-manager, fp, lhu-test, lhu-lib). If the user didn't ask for a specific effect/spacing/color → **add nothing**. FUI layout (grid + Vuetify + project theme) is already consistent.
 
-> Thống kê thực tế: trong 1.284 control object, chỉ ~12% dùng `attr.style` (gần như chỉ để đặt `width`), và **không có class tùy chỉnh nào** — 100% là class tiện ích chuẩn của Vuetify. AI hay mắc lỗi thêm `style="padding/margin/border/box-shadow/border-radius/background"` và class tự chế → **đừng làm vậy.**
+> Stats: of 1,284 control objects only ~12% use `attr.style` (almost only for `width`), and **zero custom classes** — 100% standard Vuetify utilities. Common AI mistake: adding `style="padding/margin/border/box-shadow/border-radius/background"` and invented classes → **don't.**
 
 ---
 
-## Nguyên tắc
+## Principles
 
-1. **Mặc định: không style, không class.** Chỉ đặt `el`, `attr` (v-model/label/:items/:action…), `w`, `col` khi cần chia cột.
-2. Cần khoảng cách/căn lề → dùng **class tiện ích Vuetify** trong bảng dưới, KHÔNG viết `style`.
-3. `style` chỉ dùng cho **`width` cố định** của field lọc (`style: "width:200px"`) — không dùng cho padding/margin/border/color/background.
-4. Màu sắc: dùng prop component (`color="primary"`) hoặc class `primary--text`/`error--text` — không `style="color:#..."`.
-5. **Không** tự thêm `border`, `border-radius`, `box-shadow`, `background`, `padding`, custom class → trừ khi user yêu cầu rõ.
-6. **Padding gọn — mặc định `pa-2`.** Khi cần padding, dùng `pa-2` (hoặc `pa-1`/`pa-0`); **KHÔNG dùng padding lớn** (`pa-4`, `pa-6`, `pa-8`...) gây lãng phí không gian màn hình. Tương tự margin: ưu tiên `-1`/`-2`, tránh `-6`/`-8`.
-7. **Khi user *có* yêu cầu trình bày cụ thể — theo đúng thứ tự ưu tiên này**, chỉ xuống nấc sau khi nấc trước không đáp ứng được:
-   `prop của component` (`color`, `outlined`, `dense`, `elevation`) → `class tiện ích Vuetify` (`pa-*`, `ma-*`, `d-flex`, `text-*`, `primary--text`) → `mw-*` cho bề rộng → custom class → inline `style` (**cuối cùng**).
+1. **Default: no style, no class.** Set only `el`, `attr` (v-model/label/:items/:action…), `w`, and `col` when splitting columns.
+2. Spacing/alignment → **Vuetify utility classes** from the tables below, NOT `style`.
+3. `style` only for **fixed `width`** of a filter field (`style: "width:200px"`) — never padding/margin/border/color/background.
+4. Color: component prop (`color="primary"`) or class `primary--text`/`error--text` — no `style="color:#..."`.
+5. **Never** add `border`, `border-radius`, `box-shadow`, `background`, `padding`, custom classes unless the user explicitly asks.
+6. **Compact padding — default `pa-2`** (or `pa-1`/`pa-0`). **NO large padding** (`pa-4`, `pa-6`, `pa-8`...) — wastes screen space. Margin likewise: prefer `-1`/`-2`, avoid `-6`/`-8`.
+7. **When the user _does_ ask for specific presentation — follow this priority**, moving down only when the previous level can't do it:
+   `component prop` (`color`, `outlined`, `dense`, `elevation`) → `Vuetify utility class` (`pa-*`, `ma-*`, `d-flex`, `text-*`, `primary--text`) → `mw-*` for width → custom class → inline `style` (**last**).
 
 ---
 
-## 1. `prop` của container / row (grid wrapper)
-
-Container ngoài cùng và mỗi row chỉ dùng các token sau (theo tần suất thực tế):
-
-| Token | Dùng để | Tần suất |
-|---|---|---|
-| `grid-list-md` | Khoảng cách chuẩn giữa các cột (container) | rất cao |
-| `fluid` | Container rộng hết chiều ngang | cao |
-| `row` | Đánh dấu row | rất cao |
-| `align-center` | **Canh giữa theo chiều dọc** các control trong cùng một row, nhất là khi khác loại/khác chiều cao | cao |
-| `justify-center` | Căn giữa nội dung theo chiều ngang | rất cao |
-| `justify-left` / `justify-end` / `justify-start` | Căn trái / phải | vừa |
-| `text-center` / `text-left` | Căn text | vừa |
-| `mw-800` `mw-1000` `mw-1200` `mw-1400` | **Giới hạn bề rộng nội dung** (FUI class) — trang form/nhập liệu căn giữa | vừa |
-| `hidden-container` | Bọc dialog (v-dialog/f-dialog) — không chiếm layout | dùng cho dialog |
-| `grid-list-lg` | Khoảng cách rộng hơn grid-list-md | thấp |
-| `pa-0` / `py-0` | Bỏ padding container khi cần sát mép | thấp |
-| `page-container` / `page-navigation` | Layout filter-bar sticky (xem ui-layout-patterns.md) | hiếm |
-
-> **Công thức mặc định** cho một trang bình thường: container `"fluid grid-list-md"`, mỗi row `"row"`. Hàng có nhiều loại control/chiều cao khác nhau dùng `"row wrap align-center"` để cùng trục giữa theo chiều dọc; `justify-center` chỉ là căn giữa theo chiều ngang. Trang form nhập liệu: thêm `mw-1000`/`mw-1200` để giới hạn bề rộng.
-
-## 2. `col` (cột grid bao ngoài control)
-
-`col` chỉ dùng cho: chia độ rộng, hoặc căn/thu gọn cột. Token thực dùng:
-
-| Token | Dùng để |
-|---|---|
-| `shrink` | **Field lọc bề rộng cố định** (không giãn) — phổ biến nhất. **Bắt buộc mỗi khi `w` là px**; viết `"class": "shrink"`, KHÔNG phải `"shrink": true` (dạng sau trơ ở V3) |
-| `text-end` / `text-start` / `text-center` | Căn nội dung trong cột |
-| `pa-0` | Bỏ padding cột |
-| `align-self-center` | Căn giữa theo chiều dọc |
-
-`col` có thể viết dạng chuỗi ngắn `"text-end"` hoặc object `{ "class": "shrink" }`. Thêm `"v-if": "..."` vào `col` để ẩn/hiện cả cột theo quyền/điều kiện.
-
-> Ưu tiên `align-center` trên row để canh đồng bộ cả hàng. Chỉ dùng `align-self-center` trên `col`
-> khi duy nhất một control cần sửa trục. Không bù lệch dọc bằng margin hoặc inline style.
-
-## 3. `attr.class` (class trên chính control)
-
-Chỉ dùng class tiện ích Vuetify. Nhóm thực dùng:
-
-| Nhóm | Token |
-|---|---|
-| Margin | `mt-1 mt-2 mt-3` · `mb-1 mb-2 mb-4` · `my-2` · `ml-1 ml-2` · `mr-1 mr-2` |
-| Padding | `pa-0 pa-2` · `pt-3` · `py-1` — **tránh `pa-4/6/8`** (lãng phí không gian) |
-| Flex | `d-flex` · `flex-column` · `align-center` · `justify-center` · `justify-end` · `flex-grow-0` · `flex-wrap` · `flex-md-grow-0` |
-| Text | `text-center` · `text-left` · `text-right` |
-| Cỡ chữ / đậm | `text-h6` · `subtitle-1` · `body-2` · `caption` · `font-weight-bold` · `font-weight-medium` |
-| Màu chữ (V2) | `primary--text` · `error--text` · `grey--text` · `white--text` — **chỉ hoạt động trên FUI V2 (Vuetify 1.5)** (cú pháp `--text` suffix) |
-| Màu chữ (V3) | `text-primary` · `text-error` · `text-grey` · `text-white` — cú pháp utility class của **Vuetify 3** (`text-{color}`). Dùng sai version thì class không có effect, không báo lỗi |
-| Màu nền | prop `color="primary"` trên component, hoặc class nền Vuetify `primary` · `grey lighten-4` |
-| Bo góc | `rounded` · `rounded-lg` · `rounded-0` |
-| Đổ bóng / phẳng | prop `elevation="0"` / `flat` / `outlined` trên `v-card`/`v-btn` |
-| Ẩn/hiện theo breakpoint | `d-none d-md-flex`... |
-| Kích thước | prop component (`max-width`, `width`, `dense`, `small`, `x-large`) — không `style="width:..."` trừ khi cần px cố định. Riêng icon: giữ kích thước mặc định, **không tự thêm `small`/`:small`** |
-
-### Kích thước icon
-
-- Khi thiết kế UI, icon dùng kích thước mặc định của component và theme.
-- **Không tự ý đặt `small` hoặc `:small`** cho `v-icon`, nút icon, hay button có icon chỉ để làm giao diện “gọn” hơn.
-- Chỉ thu nhỏ icon khi user yêu cầu rõ, hoặc một component/pattern chuyên biệt đã quy định kích thước đó; khi ấy ghi đúng prop ở đúng component, không thu nhỏ cả button ngoài ý muốn.
-
-**Trước khi đặt một class mới → tra bảng trên.** Chỉ được định nghĩa class riêng khi cần thứ Vuetify
-không có sẵn: grid-template phức tạp, animation, pseudo-element (`::before`), selector con đặc thù.
-Khi đó đặt trong `header.html`, tên class có prefix rõ ràng, **số lượng tối thiểu** — không tái tạo
-lại card/badge/spacing mà Vuetify đã có.
-
-> `flex-md-grow-0` + `col: { class: "shrink" }` + `style: "width:200px"` = **field lọc bề rộng cố định** — pattern chuẩn cho toolbar (xem [ui-patterns.md](ui-patterns.md) §4). Đây là chỗ hợp lệ duy nhất để dùng `style` (chỉ `width`).
+## 1. Container / row `prop` (grid wrapper)
+
+Outer container and each row use only these tokens (by real frequency):
+
+| Token                                            | Purpose                                                               | Frequency |
+| ------------------------------------------------ | --------------------------------------------------------------------- | --------- |
+| `grid-list-md`                                   | Standard column gap (container)                                       | very high |
+| `fluid`                                          | Full-width container                                                  | high      |
+| `row`                                            | Marks a row                                                           | very high |
+| `align-center`                                   | **Vertically center** controls in a row, esp. different types/heights | high      |
+| `justify-center`                                 | Horizontal centering                                                  | very high |
+| `justify-left` / `justify-end` / `justify-start` | Left / right align                                                    | medium    |
+| `text-center` / `text-left`                      | Text align                                                            | medium    |
+| `mw-800` `mw-1000` `mw-1200` `mw-1400`           | **Limit content width** (FUI class) — centered form/data-entry pages  | medium    |
+| `hidden-container`                               | Wraps dialogs (v-dialog/f-dialog) — takes no layout space             | dialogs   |
+| `grid-list-lg`                                   | Wider gap than grid-list-md                                           | low       |
+| `pa-0` / `py-0`                                  | Remove container padding to touch edges                               | low       |
+| `page-container` / `page-navigation`             | Sticky filter-bar layout (see ui-layout-patterns.md)                  | rare      |
+
+> **Default formula**: container `"fluid grid-list-md"`, each row `"row"`. Rows mixing control types/heights: `"row wrap align-center"` for a shared vertical axis; `justify-center` is horizontal only. Form pages: add `mw-1000`/`mw-1200`.
+
+## 2. `col` (grid column wrapping a control)
+
+`col` only for width splitting or aligning/shrinking the column:
+
+| Token                                     | Purpose                                                                                                                                                   |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `shrink`                                  | **Fixed-width filter field** (doesn't grow) — most common. **Required whenever `w` is px**; write `"class": "shrink"`, NOT `"shrink": true` (inert on V3) |
+| `text-end` / `text-start` / `text-center` | Align content in column                                                                                                                                   |
+| `pa-0`                                    | Remove column padding                                                                                                                                     |
+| `align-self-center`                       | Vertical centering                                                                                                                                        |
+
+Short string `"text-end"` or object `{ "class": "shrink" }`. Add `"v-if": "..."` to `col` to show/hide the whole column by right/condition.
+
+> Prefer `align-center` on the row to align the whole row. Use `align-self-center` on `col` only when a single control needs fixing. Never compensate vertical offset with margin or inline style.
+
+## 3. `attr.class` (on the control itself)
+
+Vuetify utility classes only:
+
+| Group                 | Tokens                                                                                                                                                                        |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Margin                | `mt-1 mt-2 mt-3` · `mb-1 mb-2 mb-4` · `my-2` · `ml-1 ml-2` · `mr-1 mr-2`                                                                                                      |
+| Padding               | `pa-0 pa-2` · `pt-3` · `py-1` — **avoid `pa-4/6/8`**                                                                                                                          |
+| Flex                  | `d-flex` · `flex-column` · `align-center` · `justify-center` · `justify-end` · `flex-grow-0` · `flex-wrap` · `flex-md-grow-0`                                                 |
+| Text                  | `text-center` · `text-left` · `text-right`                                                                                                                                    |
+| Size / weight         | `text-h6` · `subtitle-1` · `body-2` · `caption` · `font-weight-bold` · `font-weight-medium`                                                                                   |
+| Text color (V2)       | `primary--text` · `error--text` · `grey--text` · `white--text` — **FUI V2 (Vuetify 1.5) only** (`--text` suffix)                                                              |
+| Text color (V3)       | `text-primary` · `text-error` · `text-grey` · `text-white` — **Vuetify 3** `text-{color}`. Wrong version = no effect, no error                                                |
+| Background            | prop `color="primary"`, or Vuetify bg classes `primary` · `grey lighten-4`                                                                                                    |
+| Rounding              | `rounded` · `rounded-lg` · `rounded-0`                                                                                                                                        |
+| Shadow / flat         | prop `elevation="0"` / `flat` / `outlined` on `v-card`/`v-btn`                                                                                                                |
+| Breakpoint visibility | `d-none d-md-flex`...                                                                                                                                                         |
+| Size                  | component props (`max-width`, `width`, `dense`, `small`, `x-large`) — no `style="width:..."` unless fixed px needed. Icons: keep default size, **don't add `small`/`:small`** |
+| Scrollbar             | `fpScrollbar` — **the only class** for any area with its own scrollbar; see §Scrollbar right below                                                                            |
+
+### Scrollbar — always the built-in `fpScrollbar`
+
+`fpScrollbar` is predefined in the platform's `projectdefaultstyle.css` (V2 and V3): a thin bar, **hidden until hover**, fading in ~300ms on hover and out ~600ms on leave (thumb `rgba(0,0,0,.25)`, transparent track), working in Firefox and Chrome/Edge/Safari. The class sets `overflow-y: auto` itself. The width is the browser's `thin` (~10px on Chrome ≥121, which ignores `::-webkit-scrollbar` once `scrollbar-color` is set), not the 5px the webkit rule says. The left menu of `HeaderBar` (`.v-navigation-drawer__content`) **already has** this rule; add nothing there.
+
+**Default — the element that REALLY scrolls gets `fpScrollbar`**, without the user asking: a list box with `max-height`, a side panel, the content area of a card/dialog, a long tag/chip list...
+
+**Exactly ONE layer — never nest `fpScrollbar`.** Hovering the innermost area also `:hover`s every outer layer and runs their effect too ⇒ the bar shows late and drops frames (measured on a real project: 2 nested layers slowed show/hide from ~300/600ms to ~850/2000ms). Before adding it, ask:
+
+- Does this element **have a height limit and content that exceeds it**? If not, don't add it; a panel/splitter that only divides the layout (height follows content) is not a scroll area.
+- Does an ancestor already scroll (another `fpScrollbar`, **or `.v-navigation-drawer__content`**)? Then pick one layer: usually recompute the inner layer's height to fit (subtracting the tab bar/toolbar above) so the outer layer no longer overflows, and drop scrolling on the outer layer. An outer layer overflowing by a few dozen px means the inner height is miscalculated, not a reason to keep two scroll layers.
+
+```json
+{ "el": "div", "attr": { "class": "fpScrollbar", "style": "max-height: 400px" }, "innerHTML": [ ... ] }
+{ "el": "v-list", "attr": { "class": "fpScrollbar", "max-height": "300" }, "innerHTML": [ ... ] }
+```
+
+- The class only styles **the scrollbar**; the element still needs a height limit (`max-height`/`height`, preferably a component prop like `max-height` of `v-list`/`v-card`) to have anything to scroll. No need to add `overflow-y: auto`.
+- Same in `.vue`: `class="fpScrollbar"` on the scrolling element.
+
+**User asks to "redo / prettify / restyle the scrollbar"** → still `fpScrollbar`; **NEVER** hand-write `::-webkit-scrollbar`, `scrollbar-width`, `scrollbar-color`. Each module drawing its own style breaks consistency, and hand-made rules easily break the shared class's show/hide effect. Only when the user explicitly asks for **another color** (e.g. a scrollbar on a dark background) override it, and only the **color variable**, in `header.html`:
+
+```css
+/* dark background: translucent white thumb, keeps fpScrollbar's show/hide effect */
+.my-dark-panel.fpScrollbar:hover {
+  --fp-scrollbar: rgba(255, 255, 255, 0.3);
+}
+```
+
+The override does **not** touch `transition`. In particular, never add `scrollbar-color` to the transition: the color already goes through the `--fp-scrollbar` variable (which is transitioning), and transitioning `scrollbar-color` too restarts it every frame ⇒ the color changes in steps, 2-3 times slower.
+
+Do not use `fpScrollbar` for:
+
+- **`f-table`/`f-sheet`**: the table scrolls internally by `:height` (see [ui-table-cell-patterns.md](ui-table-cell-patterns.md)); putting it on an outer wrapper only adds a nested scrollbar.
+- **`HTMLOnly: true` modules**: they do not load `projectdefaultstyle.css`, so the class does not exist (see [module-structure.md](module-structure.md) §HTMLOnly=true). There, writing scrollbar CSS in the module is fine.
+
+### Icon size
+
+- Icons use the component/theme default size.
+- **Don't set `small` or `:small`** on `v-icon`, icon buttons, or buttons with icons just to look "compact".
+- Shrink only when the user explicitly asks or a specialised component/pattern prescribes it; then set the prop on exactly that component — don't shrink the whole button unintentionally.
+
+**Before adding a class → check the table above.** Define a custom class only for what Vuetify lacks: complex grid-template, animation, pseudo-element (`::before`), specific child selectors. Put it in `header.html`, clearly prefixed, **minimal count** — don't recreate card/badge/spacing Vuetify already has.
+
+> `flex-md-grow-0` + `col: { class: "shrink" }` + `style: "width:200px"` = **fixed-width filter field** — standard toolbar pattern ([ui-patterns.md](ui-patterns.md) §4). The only valid place for `style` (width only).
 
 ---
 
-## 4. Cách chia độ rộng: `w` (KHÔNG dùng style/class cho việc này)
+## 4. Width: `w` (NOT style/class)
 
-| `w` | Ý nghĩa |
-|---|---|
-| `1`–`12` | Số cột grid (12 = full row) |
-| `>= 25` (vd `250`) | Bề rộng cố định theo px — **bắt buộc kèm `col: { "class": "shrink" }`**, thiếu thì con số px vô tác dụng |
-| `13`–`24` | **Không dùng** — vùng chết, V2 ra px còn V3 ra class không tồn tại |
-| `""` (rỗng) | Tự co theo nội dung |
+| `w`                  | Meaning                                                                                |
+| -------------------- | -------------------------------------------------------------------------------------- |
+| `1`–`12`             | Grid columns (12 = full row)                                                           |
+| `>= 25` (e.g. `250`) | Fixed px width — **requires `col: { "class": "shrink" }`**, otherwise px has no effect |
+| `13`–`24`            | **Don't use** — dead zone: V2 yields px, V3 yields a non-existent class                |
+| `""` (empty)         | Size to content                                                                        |
 
-Chia cột **luôn dùng `w`**, không dùng `style="width:..%"` hay class `col-6` tự chế.
+Always split columns with `w` — no `style="width:..%"`, no invented `col-6`.
 
-Số đo và lý do đầy đủ: [controls-patterns.md](controls-patterns.md) §`w` dạng pixel.
+Measurements and reasons: [controls-patterns.md](controls-patterns.md) §Pixel `w`.
 
 ---
 
-## 5. Đối chiếu ĐÚNG / SAI
+## 5. RIGHT / WRONG
 
 ```json
 // ✅ ĐÚNG — gọn, dùng w + prop chuẩn, không style thừa
@@ -130,11 +162,12 @@ Số đo và lý do đầy đủ: [controls-patterns.md](controls-patterns.md)
 
 ---
 
-## 6. Khi nào ĐƯỢC thêm style/class
+## 6. When style/class IS allowed
+
+Only when the user **explicitly requests** specific presentation (e.g. "grey background for this block", "limit width to 800px", "this text red"). Even then:
 
-Chỉ khi **người mô tả yêu cầu rõ** một yêu cầu trình bày cụ thể (ví dụ "cho khối này nền xám", "giới hạn bề rộng 800px", "chữ này màu đỏ"). Kể cả khi đó:
-- Ưu tiên prop component → class tiện ích Vuetify → `mw-*` cho bề rộng → cuối cùng mới `style`.
-- Nếu áp `border-radius` theo yêu cầu: tuân giới hạn trong [design-modes.md](design-modes.md) (khung lớn ≤12px, vừa ≤8px, nhỏ ≤6px).
-- Không viết `<style>` trong `.vue`; CSS đặt ở `header.html`.
+- Prop → Vuetify utility class → `mw-*` for width → `style` last.
+- `border-radius` on request: obey limits in [design-modes.md](design-modes.md) (large frame ≤12px, medium ≤8px, small ≤6px).
+- No `<style>` in `.vue`; CSS goes in `header.html`.
 
-> Tóm lại: **thấy mình sắp gõ `style` hoặc đặt tên class mới → dừng lại và hỏi "user có yêu cầu cái này không?". Nếu không → bỏ đi.**
+> **About to type `style` or name a new class → stop and ask "did the user request this?". If not → drop it.**

package/skills/fui-skill/references/db-table-design.md

@@ -1,60 +1,56 @@
-# Quy tắc thiết kế bảng (Table Design Conventions)
+# Table Design Conventions
 
-> File này sở hữu: **quy tắc thiết kế bảng: đặt tên, PK/FK, cột audit, kiểu dữ liệu**. Workflow kết nối/SP xem [db-workflow.md](db-workflow.md).
+> Owns: **table design rules: naming, PK/FK, audit columns, data types**. Connection/SP workflow: [db-workflow.md](db-workflow.md). Load when designing a new schema.
 
-Quy ước đặt tên bảng, khóa chính, và cột audit khi thiết kế database cho FUI. Load file này khi thiết kế schema mới.
-
-> **Lưu ý về DDL — sửa cấu trúc thì được, mất dữ liệu thì không:** `ALTER TABLE ... ADD` (thêm cột/ràng buộc) và `DROP CONSTRAINT` **chạy thẳng qua tool**; `ALTER COLUMN` (đổi kiểu) chạy được nhưng **cần `confirmWrite: true`** vì thu hẹp độ chính xác số/thời gian mất dữ liệu âm thầm. `CREATE TABLE`, `DROP COLUMN`, `DROP TABLE` thì **chặn cứng**, phải do lập trình viên tự chạy. Quy ước đặt tên dưới đây là tài liệu — AI trình bày DDL để user duyệt trước khi chạy.
+> **DDL — structure changes OK, data loss not:** `ALTER TABLE ... ADD` (column/constraint) and `DROP CONSTRAINT` run directly via fui. `ALTER COLUMN` (type change) runs but **needs `--confirm-write`** — narrowing numeric/time precision silently loses data. `CREATE TABLE`, `DROP COLUMN`, `DROP TABLE` are **hard-blocked**; the developer runs them. Conventions below are documentation — present DDL to the user for approval before running.
 >
-> Kết nối DB, dbToken, schema, workflow SP: xem [db-workflow.md](db-workflow.md). Thiết kế app nhiều bảng/module: xem [system-design.md](system-design.md).
+> DB connection, dbToken, schema, SP workflow: [db-workflow.md](db-workflow.md). Multi-table/multi-module app design: [system-design.md](system-design.md).
 
 ---
 
-## Đặt tên bảng
+## Table names
 
-| Nhóm | Quy tắc | Ví dụ |
-|---|---|---|
-| Bảng hệ thống / danh mục bổ trợ | Chữ thường, không tiền tố | `syslog`, `syslogtype`, `syspermission` |
-| Bảng nghiệp vụ / thực thể chính | Tiền tố `tbl` + PascalCase | `tblUsers`, `tblDepartments`, `tblSession` |
+| Group                            | Rule                      | Example                                    |
+| -------------------------------- | ------------------------- | ------------------------------------------ |
+| System / auxiliary lookup tables | Lowercase, no prefix      | `syslog`, `syslogtype`, `syspermission`    |
+| Business / main entity tables    | `tbl` prefix + PascalCase | `tblUsers`, `tblDepartments`, `tblSession` |
 
-**Khóa chính:** `[TênThựcThể]ID` — ghép tên thực thể + `ID`
+**Primary key:** `[EntityName]ID`
 
-| Bảng | Khóa chính |
-|---|---|
-| `tblUsers` | `UserID` |
+| Table            | PK             |
+| ---------------- | -------------- |
+| `tblUsers`       | `UserID`       |
 | `tblDepartments` | `DepartmentID` |
-| `tblSession` | `SessionID` |
+| `tblSession`     | `SessionID`    |
 
-> Nhất quán: FK ở bảng con dùng cùng tên với PK bảng cha — `UserID` không đổi thành `CreatorID` hay `OwnerID`.
+> FK in a child table uses the same name as the parent PK — `UserID`, never `CreatorID` or `OwnerID`.
 
 ---
 
-## Trường thời gian (Timestamp)
+## Timestamp columns
 
-Mỗi bảng nên có ít nhất một trường timestamp để truy vết mốc thời gian:
+Every table should have at least one timestamp:
 
 ```sql
 [CreateTime]  [datetime]  DEFAULT (getdate())
 [UpdateTime]  [datetime]  DEFAULT (getdate())
 ```
 
-- Kiểu dữ liệu: `datetime`  
-- `DEFAULT (getdate())` — SQL Server **tự điền** khi INSERT, không cần truyền từ code  
-- Dùng `CreateTime` cho bảng chỉ ghi một lần; `UpdateTime` cho bảng cập nhật thường xuyên; cả hai khi cần phân biệt ngày tạo vs ngày sửa cuối
+- Type `datetime`; `DEFAULT (getdate())` — SQL Server **fills it** on INSERT, no need to pass from code.
+- `CreateTime` for write-once tables; `UpdateTime` for frequently updated ones; both when created vs last-modified must differ.
 
 ---
 
-## Trường định danh người thực hiện (User Tracking)
+## User tracking columns
 
 ```sql
 [CreateUser]  [char](9)  NULL
 [UpdateUser]  [char](9)  NULL
 ```
 
-- Kiểu dữ liệu: `char(9)` hoặc `varchar(20)` — **đồng bộ với kiểu dữ liệu của `UserID` trong `tblUsers`**
-- **Không có DEFAULT** — ứng dụng bắt buộc phải truyền `UserID` của user đang đăng nhập
-- SQL Server không tự biết user nào đang thao tác qua FUI/tAPI — trách nhiệm thuộc về code
-- Trong SP: nhận qua `@sys_UserID` (tAPI auto-inject), lưu vào `[CreateUser]` / `[UpdateUser]`
+- Type `char(9)` or `varchar(20)` — **match the type of `UserID` in `tblUsers`**.
+- **No DEFAULT** — the app must pass the logged-in `UserID`. SQL Server can't know the FUI/tAPI user; code is responsible.
+- In SPs: receive via `@sys_UserID` (tAPI auto-injects), store into `[CreateUser]` / `[UpdateUser]`.
 
 ```sql
 CREATE PROCEDURE spAPI_EntityInsert
@@ -67,7 +63,7 @@ AS
 
 ---
 
-## Template cột audit — copy-paste khi tạo bảng mới
+## Audit column template — paste into new tables
 
 ```sql
 [CreateUser]  [char](9)   NULL,