[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7F47FCP2MP548SWCP0BJ6B1":3,"skill-same:01M7F47FCP2MP548SWCP0BJ6B1":61},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M7F47FCP2MP548SWCP0BJ6B1","writing-mysql-migrations",null,"Viết migration MySQL cho Cluvix (golang-migrate, Go + GORM): quy ước timestamp, idempotent ADD\u002FDROP COLUMN, FK constraint thật, decimal tiền, MySQL 9.7 LTS syntax mới\u002Fcũ, và luật CẤM tuyệt đối test\u002Fmigrate chạm DB dev\u002Fprod thật. Dùng skill này TRƯỚC KHI tạo file migration mới, sửa schema, thêm cột\u002FFK, backfill dữ liệu, hoặc trước khi chạy `cmd\u002Fmigrate`\u002Fintegration test đụng tới database — kể cả migration chỉ 1-2 dòng.","cluvix\u002Fcluvix-crm","cluvix","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F324537109?v=4","01M7F40XX639HYM8HRW4JW1TA5","Cluvix Solutions","01M7F40XYG6YMX0CD0QZNV61K4",21,"AGPL-3.0","https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fwriting-mysql-migrations\u002FSKILL.md",[],[],"2026-11-16 10:05:34",false,"---\nname: writing-mysql-migrations\ndescription: >-\n  Viết migration MySQL cho Cluvix (golang-migrate, Go + GORM): quy ước timestamp, idempotent\n  ADD\u002FDROP COLUMN, FK constraint thật, decimal tiền, MySQL 9.7 LTS syntax mới\u002Fcũ, và luật\n  CẤM tuyệt đối test\u002Fmigrate chạm DB dev\u002Fprod thật. Dùng skill này TRƯỚC KHI tạo file\n  migration mới, sửa schema, thêm cột\u002FFK, backfill dữ liệu, hoặc trước khi chạy\n  `cmd\u002Fmigrate`\u002Fintegration test đụng tới database — kể cả migration chỉ 1-2 dòng.\n---\n\n# Migration (Go + GORM)\n\n> Quy ước timestamp\u002Fdecimal\u002FFK\u002Ftemplate + luật CẤM chạm DB thật nằm ngay trong file này.\n> `reference\u002Fmigration-idempotent.md` — chi tiết pattern idempotent ADD\u002FDROP COLUMN\u002FFK\u002FINDEX.\n> `reference\u002Fmysql97.md` — cú pháp MySQL 9.7 LTS mới dùng được \u002F vẫn cấm \u002F cố ý không dùng.\n> `reference\u002Fupgrade-lts.md` — ghi chép quá trình upgrade lên MySQL 9.7 LTS.\n\n\n> **Server đang chạy MySQL 9.7 LTS (dev + prod).** Trước khi viết migration, đọc `skill\u002Fskills\u002Fwriting-mysql-migrations\u002Freference\u002Fmysql97.md` nếu\n> định dùng cú pháp\u002Ftính năng mà file này chưa nói tới — nó ghi rõ cái gì 9.7 **mới** dùng được\n> (functional unique index, `SIGNAL` trong procedure, hypergraph), cái gì **vẫn không** dùng được\n> (`ADD COLUMN IF NOT EXISTS` vẫn `ERROR 1064`), và cái gì 9.7 cho phép nhưng dự án **cố ý cấm**\n> (inline `REFERENCES` nay tạo FK thật nhưng tên `_ibfk_N` phá guard idempotent).\n> Quy ước hằng ngày (timestamp, decimal, FK, template) thì ở ngay file này — không cần đọc `mysql97.md`.\n\n## Tool\n- `golang-migrate`: `migrate -path migrations\u002F -database \"mysql:\u002F\u002F...\" up`\n- Tool luôn áp DB theo `DB_NAME` trong `.env` — verify bằng `mysql` cli thủ công phải connect ĐÚNG DB đó, không phải DB nào khác đang mở sẵn (dễ nhầm \"chưa lên\", \"không hit\")\n- Files: `backend\u002Fmigrations\u002F{timestamp}_{description}.up.sql` — **CHỈ tạo file `.up.sql`, KHÔNG tạo `.down.sql`**\n- Tạo file **bằng tay** — KHÔNG dùng `-cmd=create`: nó vẫn sinh kèm `.down.sql` (trái rule, phải xoá tay)\n- `-cmd=down` là code chết: repo không có `.down.sql` nào nên `m.Steps(-n)` luôn lỗi \"file does not exist\". Không có đường rollback bằng tool — sai thì viết migration mới bù\n- Timestamp: `YYYYMMDDHHmmss` — 14 ký tự đến giây (VD: `20260520150544`)\n- **Trước khi tạo**: `ls migrations\u002F | sort | tail -3` — timestamp mới phải lớn hơn file mới nhất\n- Dùng `date +%Y%m%d%H%M%S` nếu kết quả lớn hơn file mới nhất; nếu không thì tăng từ file mới nhất\n- Không dùng số tròn như `130000`, `000000` — dễ trùng\n- **Trước khi `migrate up`**: chạy lại `ls migrations | sort | tail -3` — nếu có file mới hơn timestamp của mình (agent\u002Fsession khác vừa tạo+apply song song), phải regenerate timestamp và rename file trước khi apply, nếu không `migrate up` sẽ báo \"không có migration mới\" và bỏ qua âm thầm (version DB đã vượt qua timestamp cũ của mình).\n- **Cổng thật là DB, không phải danh sách file**: `SELECT MAX(version) FROM schema_migrations` trên **DB đích** (mỗi DB khách một con số khác nhau). `ls` chỉ thấy file trong checkout của mình — DB có thể đã vượt qua timestamp đó do phiên\u002Fmáy khác apply. Tên file ≤ version hiện tại ⇒ golang-migrate **bỏ qua vĩnh viễn**: không lỗi, không cảnh báo, và nếu đó là migration dọn dữ liệu sai thì dữ liệu sai nằm lại mãi.\n- **KHÔNG hỏi được \"migration X đã apply chưa\" từ `schema_migrations`** — bảng chỉ có MỘT dòng (`version` + `dirty`), không phải nhật ký; `WHERE version IN (…)` trả 0 KHÔNG có nghĩa chưa apply. Kiểm bằng **hiện vật**: `information_schema.STATISTICS` \u002F `COLUMNS` xem chỉ mục\u002Fcột đã tồn tại và đủ cột chưa.\n- **Trước mỗi `-cmd=up`**: liệt kê file có version > `MAX(version)` của DB đích để biết chính xác sắp áp gì — `-cmd=up` áp TẤT CẢ file pending, gồm cả việc dang dở của phiên khác.\n- `migrations\u002F` (schema mới CRM standalone, story-62): mỗi bảng 1 file `20260928093138…_create_\u003Cbảng>.up.sql` (`CREATE TABLE IF NOT EXISTS`, idempotent) + `…_add_fk_appointment` + 4 file seed `2026092809471x_seed_{business_profile,location,lookup,admin}` + migration viết sau đó. KHÔNG còn baseline\u002Fsquash.\n- (Lịch sử, bộ ERP cũ — nay nằm ở `backend\u002Fmigrations_backup\u002F`, migrate KHÔNG đọc: `00000000000000_baseline` + `seed_data` + `fix_json_string_columns` + `20260814091602_squash_20260406_to_20260814` gộp 326 migration. Hai gạch đầu dưới chỉ áp cho DB còn chạy bộ cũ.)\n- **TUYỆT ĐỐI KHÔNG đổi version của file squash.** `schema_migrations` chỉ giữ MỘT con số: giữ `20260814091602` → DB ở head `ErrNoChange`; đổi sang timestamp mới → mọi DB ở head chạy lại toàn dải và chết ở đoạn `20260427120000` (`Error 1054 company_type_id`), để lại dirty\n- File squash KHÔNG idempotent (72\u002F326 migration gốc 04–07\u002F2026 dùng `CREATE TABLE` trần \u002F `ADD COLUMN` không guard) ⇒ `-auto-recover` vô dụng với nó. Provisioning DB mới hỏng giữa chừng → `DROP DATABASE` làm lại (~25s), KHÔNG force\n\n## ⛔ CẤM test\u002Fmigrate chạm DB thật — CATASTROPHIC (bài học 2026-07-18)\n\n**Sự cố:** trong 1 session BMAD dài fan-out nhiều subagent tự verify integration test, DB dev thật của 1 khách (`DB_NAME` trong .env) bị **wipe sạch về baseline** (mất toàn bộ bảng + data) rồi kẹt `schema_migrations` **dirty ở version 1** (chết khi apply `seed_data.up.sql`), chặn toàn bộ ~250 migration sau. Không dựng lại được thủ phạm chính xác vì migrate stderr không được log.\n\n**Nguyên nhân gốc (3 lớp, không phải 1 lệnh đơn):**\n1. **`testhelpers.New` (`internal\u002Ftesthelpers\u002Fsuite.go`) gọi `dropAllTables` = `DROP TABLE` MỌI bảng** trong DB mà `TEST_MYSQL_DSN` trỏ tới. Trỏ nhầm vào DB thật = mất sạch data ngay, không undo.\n2. **`seed_data.up.sql` KHÔNG idempotent** (raw dump `INSERT INTO ... VALUES(id cố định)`) → chạy lại lên DB đã có data → dup-key → migrate **dirty** → chặn deploy.\n3. **Plan\u002Fstory ghi thẳng tên DB dev thật (`DB_NAME` trong .env) làm target verify backfill** → cấp \"giấy phép\" cho agent trỏ migrate\u002Ftest vào DB thật. Cộng root creds trong memory + fan-out cô lập, mỗi subagent tự tạo DB → không ai đặt guard.\n\n**LUẬT (áp cho MỌI agent, kể cả fix nhỏ):**\n- Integration test \u002F `testhelpers.New` \u002F `cmd\u002Fmigrate` khi verify **CHỈ** chạy trên **DB dùng-một-lần** (`CREATE DATABASE ..._test\u002F_tmp` đầu → `DROP` cuối). **TUYỆT ĐỐI KHÔNG** trỏ `TEST_MYSQL_DSN` hay `-db` vào `DB_NAME` (DB dev\u002Fprod thật).\n- **Plan\u002Fstory KHÔNG BAO GIỜ ghi tên DB thật làm target verify.** Cần data thật để kiểm backfill → clone: `CREATE DATABASE cluvix_verify_tmp` + nạp dump → verify → `DROP`. Không đụng bản thật.\n- **Mọi migration idempotent** — kể cả seed: `INSERT IGNORE` \u002F `ON DUPLICATE KEY UPDATE`, không raw `INSERT` id cố định (xem mục Idempotent bên dưới).\n- Guard code đã cài (lưới cuối, KHÔNG thay kỷ luật): `testhelpers.New` **fatal nếu DB trong DSN == `DB_NAME`**; `seed_data` đã `INSERT IGNORE`; `cmd\u002Fmigrate` `force`\u002F`down` cần `-confirm`. **`-auto-recover` KHÔNG cần `-confirm`** — là flag opt-in tường minh cho deploy tự phục hồi dirty-state chạy nền; bắt `-confirm` sẽ phá pipeline deploy (regression 2026-07-18).\n\n**Nếu chuyện này xảy ra trên PRODUCTION (mô hình DB-per-customer):**\n- **Mất toàn bộ dữ liệu 1 khách hàng ngay lập tức**: `dropAllTables` xóa mọi bảng của DB đó — customer, hóa đơn, bệnh án EMR, sổ kế toán, bảng lương — **không có undo tầng app**. Blast radius = trọn 1 khách (không leak cross-tenant nhưng khách đó mất sạch). Nếu script \"migrate all tenants\" loop qua mọi DB → **mất TẤT CẢ khách**.\n- **Migration dirty = outage**: app không boot \u002F deploy kế bị chặn cho tới khi có người xử tay `force`.\n- **Không backup = mất vĩnh viễn**; có backup thì vẫn mất phần data từ mốc backup gần nhất (RPO gap).\n- **Bắt buộc trước khi bất cứ thứ gì chạm gần prod**: (a) creds\u002Fnetwork test tách hẳn prod — code test *không thể* mở nổi connection tới prod; (b) backup tự động + **đã test restore** (binlog\u002FPITR); (c) migration idempotent + cổng dry-run staging; (d) `dropAllTables` chỉ chạy được trên DB tên `*_test`. Guard `DB_NAME`-equality ở trên là điều kiện cần tối thiểu, chưa đủ cho prod.\n\n## Decimal columns\n- Số tiền lớn (payment, revenue, debt): `decimal(20,2)`\n- Số tiền nhỏ\u002Fgiá thuốc\u002Fgiá vật tư: `decimal(15,2)`\n- Lương: `decimal(15,0)`\n- Phần trăm\u002Ftỷ lệ: `decimal(5,2)`\n- Chỉ số sinh tồn (BMI, cân nặng): `decimal(5,2)`\n- Ngày công\u002Fgiờ: `decimal(5,1)` hoặc `decimal(6,1)`\n- KHÔNG dùng `float` hay `double` cho tiền\n\n## GORM tag phải khớp migration\n```go\n\u002F\u002F Tiền\u002Fdecimal: decimal.Decimal (shopspring), KHÔNG float64\nAmount decimal.Decimal `gorm:\"type:decimal(20,2);not null;default:0.00\" json:\"amount\"`\nImportPrice *decimal.Decimal `gorm:\"column:import_price;type:decimal(15,2);default:0.00\" json:\"import_price\"`\nPercentage *decimal.Decimal `gorm:\"type:decimal(5,2)\" json:\"percentage\"`\n```\n\n## Column conventions\n- FK nullable: `INT NULL` + `INDEX` + `FOREIGN KEY ... ON DELETE SET NULL` (hoặc `RESTRICT` nếu business không cho phép mất tham chiếu)\n- FK not null: `INT NOT NULL` + `INDEX` + `FOREIGN KEY ... ON DELETE RESTRICT` (mặc định — không cho xóa parent khi còn con; chỉ dùng `CASCADE` khi đã xác nhận business muốn xóa dây chuyền)\n- Timestamp: `BIGINT` (Unix), KHÔNG `DATETIME`\n- JSON: `JSON` type, KHÔNG `TEXT`\n- String có giới hạn: `VARCHAR(n)`, KHÔNG `TEXT` trừ khi cần\n- `created_at`, `updated_at`: `BIGINT` (Unix)\n- `status`: `TINYINT(1) DEFAULT 1`\n- KHÔNG thêm cột `version` — optimistic lock theo `updated_at` (D6\u002FD21, tập bảng ở `pkg\u002Foptlock`)\n- `sort_order`: `INT DEFAULT 0`\n- `branch_id`: `INT` + `INDEX` + FK tới `branch` (NULL = dùng chung mọi chi nhánh — Hard Rules). KHÔNG còn cột `company_id` (D15\u002Fstory-62: 1 thương hiệu\u002FDB).\n\n## FK phải khớp signed\u002Funsigned với id bảng cha (Error 3780)\n\n- Kiểu cột FK PHẢI khớp CHÍNH XÁC signed\u002Funsigned với id bảng cha — lệch → MySQL Error 3780 khi ADD FK, chặn toàn chuỗi migrate.\n- Schema hiện tại: `id` các bảng cha (`appointment`, `customer`, `branch`, `user`…) là `int` SIGNED; bảng mới hay quen tay `int unsigned` → kiểm trước: `grep -m1 '\\`id\\`' migrations\u002F*_create_\u003Cbảng cha>.up.sql`.\n- Kiểm ĐỦ mọi cột FK trong file (kể cả `measured_by`\u002F`created_by`) — sót 1 cột vẫn chặn migrate.\n\n## CREATE VIEW phải khai DEFINER tường minh\n\n`CREATE [OR REPLACE] VIEW` thiếu `DEFINER` → MySQL tự gán definer = user chạy migration lúc tạo lần đầu. Máy\u002FDB khác không có đúng user đó → mọi `SELECT` qua view lỗi `Error 1449 (HY000): The user specified as a definer ... does not exist`. Luôn khai `CREATE OR REPLACE DEFINER=CURRENT_USER VIEW ...` (không hardcode username, chạy đúng trên mọi máy).\n\n## Template up.sql\n```sql\nCREATE TABLE `table_name` (\n  `id` int unsigned NOT NULL AUTO_INCREMENT,\n  `branch_id` int DEFAULT NULL COMMENT 'Chi nhánh (NULL = dùng chung)',\n  `category_id` int unsigned DEFAULT NULL COMMENT 'FK ví dụ — tham chiếu bảng khác',\n  `status` tinyint(1) DEFAULT '1',\n  `amount` decimal(20,2) NOT NULL DEFAULT '0.00' COMMENT 'Số tiền',\n  `note` text COMMENT 'Ghi chú',\n  `created_at` bigint DEFAULT NULL,\n  `updated_at` bigint DEFAULT NULL,\n  `created_by` int DEFAULT NULL,\n  `updated_by` int DEFAULT NULL,\n  PRIMARY KEY (`id`),\n  KEY `idx_branch_id` (`branch_id`),\n  KEY `idx_category_id` (`category_id`),\n  CONSTRAINT `fk-table_name-branch_id` FOREIGN KEY (`branch_id`) REFERENCES `branch` (`id`) ON DELETE RESTRICT ON UPDATE CASCADE,\n  CONSTRAINT `fk-table_name-category_id` FOREIGN KEY (`category_id`) REFERENCES `category` (`id`) ON DELETE RESTRICT ON UPDATE CASCADE\n) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;\n```\n\n### FOREIGN KEY bắt buộc cho mọi cột tham chiếu bảng khác (CRITICAL)\n\nMọi cột dạng `xxx_id` tham chiếu tới 1 row cụ thể ở bảng khác — kể cả self-reference (`parent_id`) — **PHẢI có `FOREIGN KEY` thật trong CREATE TABLE** (không chỉ `KEY`\u002F`INDEX`). Áp dụng CẢ `branch_id` (schema mới story-62: các bảng có `branch_id` như `customer`, `appointment`… đều có FK tới `branch`; `branch_id` NULL = dùng chung — FK cho phép NULL). Ngoại lệ DUY NHẤT: `created_by`\u002F`updated_by` (xem CLAUDE.md). (Ngoại lệ `company_id` cũ đã bỏ cùng cột, D15.)\n\n**Lý do (CRITICAL — không phải style, là bug thật):** `models.DeleteWithCheck` (`internal\u002Fmodels\u002Fbase.go`) — cơ chế DUY NHẤT chặn xóa record đang bị bảng khác tham chiếu — chỉ đơn giản DELETE rồi bắt lỗi MySQL 1451 (FK violation). Bảng thiếu FK thật → hàm này không có gì để bắt lỗi → xóa \"thành công\" nhưng để lại con mồ côi (con vẫn giữ id đã bị xóa, không báo lỗi ở đâu cả). Case thật: `payment.cash_flow_category_id` tham chiếu `cash_flow_category.id` không có FK — phát hiện 2026-07-12.\n\nChọn `ON DELETE`:\n- `RESTRICT` (mặc định) — không cho xóa parent khi còn con, đúng nghĩa `DeleteWithCheck` đang cố làm.\n- `SET NULL` — chỉ khi cột nullable và business chấp nhận con \"mất tham chiếu\" khi cha bị xóa (vd optional category).\n- `CASCADE` — chỉ khi đã xác nhận rõ business muốn xóa dây chuyền (hiếm, rủi ro cao — cân nhắc kỹ trước khi dùng).\n\n**Bảng đã có data:** trước khi `ADD FOREIGN KEY` (ALTER trên bảng cũ, xem pattern \"Add FK nếu chưa tồn tại\" ở phần Idempotent bên dưới) — BẮT BUỘC query check orphan trước:\n```sql\nSELECT COUNT(*) FROM child_table c\nLEFT JOIN parent_table p ON c.parent_id = p.id\nWHERE c.parent_id IS NOT NULL AND p.id IS NULL;\n```\nCó orphan → xử lý theo business (SET NULL hàng loạt \u002F gán lại parent hợp lệ) trong CÙNG migration, TRƯỚC statement `ADD CONSTRAINT` — nếu không `ADD FOREIGN KEY` sẽ fail ngay khi migrate.\n\n- ⚠ `ADD FOREIGN KEY` khi `FOREIGN_KEY_CHECKS=1` = thuật toán COPY ⇒ **chặn ghi cả bảng** suốt thời gian chép (153k dòng: 24s). Dữ liệu đã chắc sạch (vừa dọn orphan ngay trước trong cùng file, hoặc cột vốn có FK tới đúng bảng cha) ⇒ bọc riêng lệnh ADD: `SET @old_fkc = @@SESSION.FOREIGN_KEY_CHECKS; SET SESSION FOREIGN_KEY_CHECKS = 0;` … `SET SESSION FOREIGN_KEY_CHECKS = @old_fkc;` ⇒ INPLACE 0.02s. **Chưa dọn orphan thì cấm** — MySQL không kiểm dữ liệu cũ.\n- Backfill `UPDATE … JOIN` bảng lớn: `SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED` (không khoá đọc dòng bảng được JOIN); lưu `@@SESSION.transaction_isolation` đầu file, trả lại cuối file.\n\n## Bỏ index thừa kiểu tiền-tố-trái — phải THỬ, không được suy luận\n\nIndex có tập cột là **tiền tố trái** của một index khác trên cùng bảng thì bỏ được, kể cả khi nó đang đỡ `FOREIGN KEY` (MySQL chấp nhận index có cột FK làm tiền tố trái). Đã bỏ 50 index như vậy ở `20260906114555` — 0 FK và 0 UNIQUE bị đụng. Loại bỏ mọi index **UNIQUE** khỏi danh sách: bỏ index unique là mất ràng buộc duy nhất, không phải tối ưu.\n\nBa cái bẫy, cả ba đều cho kết luận SAI mà không báo lỗi:\n\n- `GROUP_CONCAT(COLUMN_NAME)` trên `information_schema.STATISTICS` **BỎ QUA NULL**. Index biểu thức (functional index) có `COLUMN_NAME = NULL` nên các cột biểu thức tàng hình, khiến index trông như bắt đầu bằng cột khác ⇒ kết luận \"tiền tố trái\" sai ⇒ `ERROR 1553 … needed in a foreign key constraint` lúc drop. Câu quét PHẢI loại index có `SUM(COLUMN_NAME IS NULL) > 0` ở **CẢ hai vế**.\n- \"Tiền tố trái ⇒ chắc chắn drop được\" là suy luận. Chốt danh sách bằng cách **thử drop TỪNG CÁI** trên DB dùng-một-lần rồi chỉ giữ cái thành công.\n- ⚠ **\"Drop được\" ≠ \"nên drop\" — phép thử trên chỉ đo FK, KHÔNG đo hiệu năng.** InnoDB nối PK vào đuôi mọi chỉ mục phụ, nên `(company_id)` thực chất là `(company_id, id)` và phục vụ `ORDER BY id DESC` miễn phí; bỏ nó đo được phân trang sâu **869ms → 4.793ms**. Chỉ mục **một cột dẫn đầu bằng cột scope** (nay là `branch_id`; số đo gốc làm trên `company_id` trước D15) trên bảng list lớn ⇒ giữ, và ghi lý do ngay trong migration để lần quét sau không bỏ lại. Số đo + cách bench: `..\u002Fdebugging-backend-queries\u002Freference\u002Fperf-list-endpoints.md` §\"Đừng bỏ chỉ mục một cột `(company_id)`\".\n- `group_concat_max_len` mặc định 1024 làm script đối chứng cắt cụt danh sách id ⇒ báo lệch giả. Nâng ở đầu phiên đo.\n\nChi phí đáng bỏ: một bảng từng mang index 231MB trên data 48MB (gấp 4.8 lần) vì 32 index — mỗi INSERT ghi từng ấy entry, và index không nhét vừa `innodb_buffer_pool_size`.\n\n## Backfill phải khớp TỪNG guard của runtime, không khớp bản mô tả\n\nRuntime luôn có điều kiện NGẦM mà bản mô tả bằng lời không nêu. Backfill viết theo lời (\"tin staff sớm\nnhất\") **nghe đúng** mà quy kết sai — không lỗi, không cảnh báo.\n\n- AC của story backfill phải **trích thẳng câu persist** (`file:dòng`); reviewer đối chiếu `WHERE` của\n  backfill với **từng** guard runtime, không đối chiếu với câu mô tả.\n- Sự cố 2026-08-20 (`omi_conversation.first_responder_id`): runtime chỉ quy kết **sau khi gửi THÀNH\n  CÔNG** và **không tính tin chiến dịch** — 2 điều kiện không ai viết ra. Backfill thiếu cả 2 ⇒ **3\u002F6**\n  hội thoại trên DB dev quy kết bằng tin `status=1` (gửi lỗi). Lọt qua Dev lẫn SM, chỉ lộ khi QA đọc\n  code persist thay vì đọc mô tả.\n- Cùng lớp: tin của **nhiều luồng khác nhau** có thể trùng `src`\u002F`created_by`\u002F`status` — trước khi tin\n  vào một cột phân biệt, duyệt **mọi** điểm dựng row trong code sản phẩm rồi ghi lại kết luận.\n\n## Verify migration trên DB tạm — clone schema THẬT, không tự gõ lại bảng cha\n\n- Dựng DB dùng-một-lần bằng `mysqldump --no-data` từ DB dev, KHÔNG tự `CREATE TABLE` lại bảng cha rút gọn.\n- Bảng cha tự gõ luôn permissive hơn thật (thiếu NOT NULL\u002FUNIQUE\u002Fkiểu cột lệch) → migration \"pass\" trên DB tạm rồi fail lúc chạy thật.\n- Apply file migration **2 lần liên tiếp** để nghiệm thu idempotent; drop DB tạm ngay sau khi xong.\n- ⚠ **Bảng có chỉ mục FULLTEXT thì clone bằng `mysqldump` CHƯA XONG ở bước nạp schema.** Dump chỉ chép\n  lại *định nghĩa* index; nạp vào DB tạm là nó được dựng lại dưới `@@GLOBAL.innodb_ft_enable_stopword`\n  (mặc định = 1), trong khi migration thật dựng nó với `SET SESSION … = OFF`. Hệ quả: DB tạm tìm kiếm\n  **sót âm thầm** — 2026-09-07 một bench báo bản vá đúng là \"sót 1.088–2.744 dòng\", suýt loại nhầm.\n  Phải dựng lại FULLTEXT trong DB tạm cho đúng rồi đối chứng `MATCH` = `LIKE` với DB thật TRƯỚC khi\n  tin bất kỳ số nào. Quy trình dựng đúng (phải DROP HẾT fulltext trên bảng, không chỉ một cái):\n  `..\u002Fdebugging-backend-queries\u002Freference\u002Fpatterns-gotchas.md` §\"Chỉ mục ngram dựng sai stopword\".\n- Viết migration **tạo mới** FULLTEXT ⇒ đọc mục đó TRƯỚC: stopword gắn theo BẢNG (cố định bởi index\n  FULLTEXT đầu tiên), `SET GLOBAL` KHÔNG ăn, và chỉ mục dựng sai làm tìm kiếm sai mà không ném lỗi.\n- ⚠ **Đặt file vào `migrations\u002F` = APPLY LUÔN lên DB dev**: `air` chạy `run_dev.sh` → `migrate up` vài giây sau khi file xuất hiện, không hỏi gì. Migration nặng\u002Fkhoá bảng (`ADD FULLTEXT`, `ALTER` bảng lớn) phải soạn và verify ở `backend\u002Ftmp\u002F` TRƯỚC, chỉ chuyển vào `migrations\u002F` khi đã đạt trên DB dùng-một-lần.\n  Số đo để lập cửa sổ bảo trì: `ADD FULLTEXT … WITH PARSER ngram` trên cột **TEXT tự do dài** =\n  **3 phút 06 giây \u002F 524k dòng**, gấp ~4 lần mốc ~42,7s của cột ngắn — nhân theo số khách vì\n  DB-per-customer. Giảm rủi ro: code gọi `MATCH` phải tự lùi về `LIKE` khi gặp lỗi 1191, nhờ đó\n  endpoint không vỡ trong lúc `ALTER` chạy và thứ tự apply không quan trọng.\n\n## Idempotent migrations (CRITICAL)\n\n→ `migration-idempotent.md` — `PREPARE\u002FEXECUTE`, `CREATE PROCEDURE`, INFORMATION_SCHEMA lookup,\nNOT NULL + FK, golang-migrate gotchas, auto-recovery dirty state.\n\n## Lưu ý\n- KHÔNG dùng `AutoMigrate` cho production\n- GORM tag `type:decimal(x,y)` phải khớp migration\n- Sau thêm decimal column vào bảng dùng `map[string]interface{}`: query thủ công `.Find(&rows)` phải gọi `helpers.ParseDecimalFields(row, \"field\")` thủ công\n- Schema gốc: `backend\u002Fmigrations\u002F\u003Ctimestamp>_create_\u003Cbảng>.up.sql` (không còn file baseline — bản ERP cũ ở `migrations_backup\u002F`, migrate không đọc)\n\n## UNIQUE KEY + NULL column — dùng sentinel 0, không NULL (CRITICAL)\n\n`UNIQUE KEY (template_type, branch_id)` với `branch_id NULL` → MySQL cho phép nhiều row vì `NULL ≠ NULL` → `ON CONFLICT` không trigger → duplicate records âm thầm.\n\n```sql\n-- ❌ NEVER\nbranch_id BIGINT UNSIGNED NULL\nUNIQUE KEY uq (template_type, branch_id)  -- nhiều row (X, NULL) được phép\n\n-- ✅ ALWAYS — sentinel 0 = mẫu chung toàn thương hiệu (vd print_templates.branch_id)\nbranch_id BIGINT UNSIGNED NOT NULL DEFAULT 0\nUNIQUE KEY uq (template_type, branch_id)  -- (X, 0) enforce unique\n```\n\n**Migration chuyển NULL → sentinel 0:**\n```sql\nUPDATE table SET branch_id = 0 WHERE branch_id IS NULL;\nALTER TABLE table MODIFY branch_id BIGINT UNSIGNED NOT NULL DEFAULT 0;\n-- ADD UNIQUE KEY nếu chưa có\n```\n\n**Query:** `WHERE branch_id = 0` thay vì `WHERE branch_id IS NULL`.\n**Fallback (branch → mẫu chung toàn thương hiệu; trước D15 gọi là company-level):** `WHERE branch_id IN (?, 0) ORDER BY branch_id DESC LIMIT 1`.\n\n**Ngoại lệ — cột PHẢI giữ NULL (có FOREIGN KEY thật: sentinel 0 vỡ FK vì không có row id=0):** dùng functional key part (MySQL ≥ 8.0.13):\n```sql\nALTER TABLE account_balance ADD UNIQUE KEY uq_ab ((COALESCE(customer_id, 0)), account_id, period);\n```\nDedupe dữ liệu trước khi ADD — xem section \"Đổi unique key trên bảng có dữ liệu\". Đã áp (ERP, bảng kế toán — đã bỏ cùng D2\u002FD15): `uq_account_balance_dim0`, `uq_coa_company_code`.\n\n**Chiều NGƯỢC lại — cột CỐ Ý giữ NULL để UNIQUE cho phép nhiều row: phải chuẩn hoá `''` → NULL TRƯỚC khi ADD UNIQUE.** MySQL coi chuỗi rỗng là một GIÁ TRỊ, nên nhiều NULL thì hợp lệ còn nhiều `''` là `Error 1062`. Code ghi NULL không có nghĩa dữ liệu cũ\u002Fseed cũng NULL.\n```sql\nUPDATE t SET col = NULL WHERE col = '';   -- idempotent, chạy TRƯỚC\n-- rồi mới ADD UNIQUE KEY (col)\n```\nCa biên của một ràng buộc UNIQUE phải phủ **cả hai biểu diễn \"không có giá trị\"** (`NULL` và `''`) — thử mỗi NULL rồi kết luận an toàn là bỏ lọt. Thật (2026-08-31, `meta_page_config.ig_business_account_id`): verify chỉ thử NULL nên pass, tới khi test khác seed `''` mới lộ; nếu lọt lên DB khách thì migration fail và chặn cả đợt deploy.\n\n---\n\n## Atomic counter upsert — cột cộng dồn (balance\u002Fcounter)\n\n- KHÔNG `First → Save` cho cột cộng dồn — read-modify-write bị lost-update khi 2 request song song. Chuẩn: UPDATE tăng trực tiếp → `RowsAffected == 0` → INSERT → INSERT dính 1062 (thua đua) → retry UPDATE lần cuối.\n- MySQL đánh giá `SET` **trái→phải**: cột dẫn xuất đặt SAU dùng giá trị MỚI của các cột trước.\n\n```sql\nUPDATE account_balance\nSET debit_total = debit_total + ?, credit_total = credit_total + ?,\n    closing = IF(? = 2, credit_total - debit_total, debit_total - credit_total)  -- đã là giá trị MỚI\nWHERE ...;\n```\n\n- Nhánh INSERT cần unique index backstop (cột nullable → functional key part, xem section trên). Mẫu Go: `engine.ApplyBalanceDelta` (`accountant\u002Fledger\u002Fengine`).\n\n---\n\n## GORM Raw Query — args ordering (CRITICAL)\n\n`?` placeholder được bind **theo thứ tự xuất hiện trong SQL string, từ trên xuống, trái sang phải** — kể cả trong SELECT clause.\n\n```go\n\u002F\u002F ❌ SAI — tưởng WHERE trước, CASE WHEN sau\nargs = append(args, consultTypeIDs, from, to, CheckedIn, CheckedOut, IsAccepted)\n\n\u002F\u002F ✅ ĐÚNG — CASE WHEN trong SELECT xuất hiện TRƯỚC WHERE trong SQL\nargs = append(args,\n    CheckedIn, CheckedOut,  \u002F\u002F CASE WHEN a.status IN (?,?)     ← ở SELECT\n    IsAccepted,             \u002F\u002F CASE WHEN a.is_accepted = ?      ← ở SELECT\n    consultTypeIDs, from, to) \u002F\u002F WHERE type IN ?, BETWEEN ? AND ? ← ở WHERE\n```\n\n- Subquery lồng nhau: args của subquery phía trên được bind trước subquery phía dưới\n- `IN ?` với `[]int` slice: GORM tự expand thành `(1,2,3)` — không cần làm thủ công\n- `IN ?` với empty slice `[]int{}`: GORM sinh `IN (NULL)` — query không lỗi nhưng không match row nào\n\n## Đổi unique key trên bảng có dữ liệu\n\n- golang-migrate chạy MỌI migration pending liên tiếp trong 1 lần `-cmd=up` — KHÔNG thiết kế \"migration A → script ngoài → migration B\"; backfill bằng SQL thuần (`REPLACE`\u002F`UPPER` lồng nhau đủ mạnh) trong CÙNG file.\n- Trước `ADD UNIQUE KEY`: bắt buộc dedupe dữ liệu hiện có bằng SQL (giữ `MIN(id)`, row trùng đổi giá trị hậu tố `_DUP\u003Cid>` — không xóa cứng); bỏ sót → constraint fail → dirty state block deploy.\n\n## (đã bỏ, D15) Seed bảng scope theo company — per-company, không anchor 1 company duy nhất\n\n> Lịch sử: bảng `company` + cột `company_id` không còn (1 thương hiệu\u002FDB). Seed nay chỉ cần idempotent\n> `WHERE NOT EXISTS`\u002F`INSERT IGNORE` trong phạm vi 1 DB (Hard Rules); bài học còn giá trị: đừng\n> neo seed vào 1 dòng `MIN(id)` của bảng cha khi bảng cha có thể có nhiều dòng (vd `branch`).\n\n(Lịch sử, D15) Seed `config_code` (hay bảng nào cần 1 row\u002F`company_id`) KHÔNG dùng `SELECT MIN(id) FROM company` làm anchor — chỉ seed đúng 1 company, DB nhiều company (multi-brand cùng 1 khách) sẽ có company thiếu row, rơi vào fallback \"bất kể company\" sai tenant.\n\n```sql\n-- (lịch sử, D15) ❌ SAI — chỉ seed company nhỏ nhất\nINSERT INTO config_code (company_id, ...) SELECT (SELECT MIN(id) FROM company), ...  -- (lịch sử, D15)\nWHERE NOT EXISTS (SELECT 1 FROM config_code WHERE parent_table = 'service');\n\n-- ✅ ĐÚNG — seed đủ mọi company\nINSERT INTO config_code (company_id, ...)  -- (lịch sử, D15)\nSELECT c.id, ... FROM company c\nWHERE NOT EXISTS (SELECT 1 FROM config_code WHERE parent_table = 'service' AND company_id = c.id);  -- (lịch sử, D15)\n```\n- Cột nhận hậu tố dedupe phải khai đủ rộng (vd VARCHAR(20) thay vì VARCHAR(10)) — strict mode nổ `Data too long` ngay trong migration.\n\n## Kiểm \"đã seed chưa\" — dò theo KHOÁ SEED, KHÔNG theo `id`\n\nAudit \"record X đã có migration seed chưa\" phải dò theo **khoá seed thật** (`name`, `key`, `handler_key`), KHÔNG theo `id`.\n`INSERT IGNORE INTO t (name, ...)` không có cột `id` ⇒ mọi phép dò dựa trên `id` **mù hoàn toàn**: con số id không xuất hiện ở bất kỳ đâu trong file migration.\n`id` là `AUTO_INCREMENT` ⇒ **không ổn định giữa các DB khách** — cùng câu seed cho id 41 ở DB này, 45 ở DB khác.\n`INSERT IGNORE` trùng khoá **im lặng không làm gì** ⇒ \"chạy 2 lượt mà giá trị không đổi\" KHÔNG phân biệt được *idempotent* với *câu lệnh chưa bao giờ chạy*; xoá dòng rồi chạy lại để chứng minh lệnh có tác dụng.\n\n## Data-fix cột JSON array — additive, idempotent\n\nThêm phần tử vào cột JSON array (vd `departmentList`) để gỡ chặn nghiệp vụ: dùng\n`JSON_ARRAY_APPEND` bọc `NOT JSON_CONTAINS` — chạy lại không double-add, không đụng phần tử cũ.\n\n```sql\nUPDATE t SET col = JSON_ARRAY_APPEND(col, '$', \u003Cvalue>)\nWHERE id = ? AND NOT JSON_CONTAINS(col, '\u003Cvalue>');\n```\n\n## UNION ALL bảng cũ + bảng mới → MySQL 1271 \"Illegal mix of collations\"\n\nBảng cũ không khai `COLLATE` tường minh kế thừa collation mặc định server; bảng mới khai rõ\n(vd `utf8mb4_unicode_ci`) → UNION ALL 2 nhánh lẫn collation khác nhau, lỗi CHỈ lộ khi chạy\nquery thật (không phải lỗi Go\u002Fbuild). Fix: ép `COLLATE utf8mb4_unicode_ci` tường minh trên\nMỌI cột string (kể cả literal) ở TẤT CẢ nhánh UNION, không chỉ nhánh mới.\n\nKHÔNG `SET col = '[...]'` ghi đè nguyên mảng — mất phần tử cũ nếu tính base sai.\n\n## Cột SINH (generated column) + khoá ngoại: phải VIRTUAL, KHÔNG STORED\n\n**Đo thật trên MySQL 9.7.1 (2026-08-25, `omi_message_reaction`):** MySQL từ chối **MỌI** `FOREIGN KEY`\nđặt trên **cột nền** của một generated column **STORED** — thử đủ 3 tổ hợp\n`ON DELETE SET NULL\u002FCASCADE` × `ON UPDATE CASCADE\u002FRESTRICT`, tất cả đều `ERROR 1215 (HY000): Cannot\nadd foreign key constraint`. Cùng biểu thức đó để **VIRTUAL** thì FK tạo được bình thường, và UNIQUE\ntrên cột ảo VẪN chặn trùng thật (`ERROR 1062`) — InnoDB cho phép index phụ trên cột ảo.\n\nVì sao dễ mất thời gian ở đây: lỗi 1215 **không nói cột nào gây ra**, và `SHOW ENGINE INNODB STATUS`\ntrên MySQL 9.x không còn khối `LATEST FOREIGN KEY ERROR`. Cách chẩn đoán nhanh: tạo bảng thử với\ntừng FK riêng lẻ (đều chạy được) rồi thêm cột sinh vào → lộ ngay thủ phạm.\n\n**Khi nào cần cột sinh:** MySQL KHÔNG có partial\u002Ffiltered index. Muốn một `UNIQUE` phủ hai loại chủ\nthể loại trừ nhau (vd người thả cảm xúc: nhân viên nội bộ có FK `user_id` ↔ khách chỉ có chuỗi uid),\nhội tụ chúng về một cột sinh rồi UNIQUE trên đó:\n`reactor_key VARCHAR(120) GENERATED ALWAYS AS (IF(user_id IS NULL, channel_uid, CONCAT('u:', user_id))) VIRTUAL`\n⚠ **Tiền tố (`u:`) là bắt buộc** — thiếu nó thì `user_id = 123` và `channel_uid = \"123\"` đụng nhau.\n\nEntity GORM: cột sinh phải `gorm:\"->\"` (chỉ đọc). Thiếu tag ⇒ GORM đưa cột vào INSERT ⇒ **mọi**\n`Create` lỗi, và chỉ lộ ra khi có code thật dùng entity (tức là muộn).\n\n\n## ⚠ Ghi file vào `migrations\u002F` = ĐÃ APPLY lên DB dev trong vài giây (đo 2026-09-08)\n\n`backend\u002Fscripts\u002Frun_dev.sh` chạy `migrate up` **mỗi lần air rebuild**, và air rebuild ngay khi có\nfile mới. Nghĩa là: **không có bước \"viết xong rồi mới quyết định chạy\"** — vừa `Write` file\n`.up.sql` là nó đã chạy trên DB dev thật, trước khi kịp verify trên DB dùng-một-lần.\n\nBằng chứng (`backend\u002Ftmp\u002Frun.log`):\n\n```\n[16:33:36] run_dev.sh: migrate OK — migrate up: không có migration mới (version 20260908155444)\n[16:36:43] run_dev.sh: migrate OK — migrate up: 20260908155444 → 20260908163530 thành công\n```\n\nFile `20260908163530_*.up.sql` được ghi lúc 16:36 và tự apply lúc 16:36:44.\n\nHệ quả bắt buộc nhớ:\n\n1. **Verify TRƯỚC khi ghi vào `migrations\u002F`.** Soạn nội dung ở scratchpad của phiên, chạy thử trên\n   DB `*_tmp` (2 lần cho idempotency + 1 lần trên DB có dữ liệu vi phạm để xem cổng chặn có fail\n   thật không), rồi mới `Write` vào `migrations\u002F`. Làm ngược lại thì DB dev là nơi thử nghiệm đầu\n   tiên — đúng thứ luật ⛔ đầu file này cấm.\n2. **Migration hỏng ⇒ `dirty=1` và dev server của user chết** cho tới khi có người dọn tay. Kiểm\n   `SELECT dirty, version FROM schema_migrations` sau khi ghi file.\n3. Sửa nội dung một migration ĐÃ apply thì DB dev **không chạy lại** (golang-migrate chỉ nhớ\n   version, không có checksum) — nhưng DB khách khác sẽ nhận bản MỚI. Chỉ sửa khi nội dung mới\n   tương đương về ngữ nghĩa, và phải verify lại bản mới trên DB dùng-một-lần.\n\n## Rẽ nhánh có điều kiện: cách bắt migration DỪNG với thông báo đọc được\n\nCổng kiểm dữ liệu (vd \"còn bản sao thì đừng thêm UNIQUE\") mà chỉ `IF NOT EXISTS` rồi im lặng không\ntạo sẽ báo **thành công trên DB vẫn còn lỗ hổng** — xanh giả. Phải fail thật.\n\n- `SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = '…'` cho thông báo đẹp nhất và **chạy được ngoài\n  stored program**, NHƯNG **không dùng được ở đây**: `ERROR 1295 … not supported in the prepared\n  statement protocol`. Mà `PREPARE`\u002F`EXECUTE` lại là cách duy nhất để rẽ nhánh có điều kiện trong\n  file `.sql` không có stored program. Đã đo cả hai chiều 2026-09-08.\n- Cách còn lại: tham chiếu **một bảng không tồn tại mà TÊN chính là thông báo**:\n  `'SELECT 1 FROM \\`MIGRATION_ABORT_duplicate_customer_id_in_customer_warranty_code\\`'`\n  ⇒ `ERROR 1146 … Table 'db.migration_abort_duplicate_customer_id_in_customer_warranty_code'\n  doesn't exist`, exit code 1, và các câu lệnh sau KHÔNG chạy. Tên ≤64 ký tự (giới hạn identifier).\n\n⚠ Khi kiểm exit code trong shell: `mysql … | grep -v \"Using a password\"` trả exit code của **grep**,\nkhông phải của mysql. Đo đúng phải bỏ pipe (`mysql … > \u002Fdev\u002Fnull 2>&1; echo $?`) hoặc đọc\n`PIPESTATUS`. Đã suýt kết luận \"cổng chặn không fail\" vì đọc nhầm số 0 của grep.\n\n⚠ Cùng nguyên nhân, hậu quả khác: `mysql … | grep -v \"Using a password\" && \u003Clệnh kế>` — không dòng\nnào lọt qua grep ⇒ exit 1 ⇒ **lệnh kế bị bỏ qua im lặng**. Nối nhiều bước DB thì tách từng lệnh\nriêng, và luôn `SELECT COUNT(*)` xác nhận bước trước đã ghi được dữ liệu.\n\n## Thứ tự bắt buộc khi đổi chỉ mục mà FK đang dựa vào\n\n`ALTER TABLE … DROP INDEX` trên cột có FOREIGN KEY sẽ bị MySQL từ chối\n(`ERROR 1553 … needed in a foreign key constraint`) nếu không còn chỉ mục nào khác đỡ FK. Nên khi\nthay chỉ mục thường bằng UNIQUE trên CÙNG cột: **ADD UNIQUE trước, DROP index thường sau** — thứ tự\nngược lại fail. Kiểm sau khi chạy: FK phải còn trong `information_schema.KEY_COLUMN_USAGE`.\n","# Migration (Go + GORM)\n\n> Quy ước timestamp\u002Fdecimal\u002FFK\u002Ftemplate + luật CẤM chạm DB thật nằm ngay trong file này.\n> `reference\u002Fmigration-idempotent.md` — chi tiết pattern idempotent ADD\u002FDROP COLUMN\u002FFK\u002FINDEX.\n> `reference\u002Fmysql97.md` — cú pháp MySQL 9.7 LTS mới dùng được \u002F vẫn cấm \u002F cố ý không dùng.\n> `reference\u002Fupgrade-lts.md` — ghi chép quá trình upgrade lên MySQL 9.7 LTS.\n\n\n> **Server đang chạy MySQL 9.7 LTS (dev + prod).** Trước khi viết migration, đọc `skill\u002Fskills\u002Fwriting-mysql-migrations\u002Freference\u002Fmysql97.md` nếu\n> định dùng cú pháp\u002Ftính năng mà file này chưa nói tới — nó ghi rõ cái gì 9.7 **mới** dùng được\n> (functional unique index, `SIGNAL` trong procedure, hypergraph), cái gì **vẫn không** dùng được\n> (`ADD COLUMN IF NOT EXISTS` vẫn `ERROR 1064`), và cái gì 9.7 cho phép nhưng dự án **cố ý cấm**\n> (inline `REFERENCES` nay tạo FK thật nhưng tên `_ibfk_N` phá guard idempotent).\n> Quy ước hằng ngày (timestamp, decimal, FK, template) thì ở ngay file này — không cần đọc `mysql97.md`.\n\n## Tool\n- `golang-migrate`: `migrate -path migrations\u002F -database \"mysql:\u002F\u002F...\" up`\n- Tool luôn áp DB theo `DB_NAME` trong `.env` — verify bằng `mysql` cli thủ công phải connect ĐÚNG DB đó, không phải DB nào khác đang mở sẵn (dễ nhầm \"chưa lên\", \"không hit\")\n- Files: `backend\u002Fmigrations\u002F{timestamp}_{description}.up.sql` — **CHỈ tạo file `.up.sql`, KHÔNG tạo `.down.sql`**\n- Tạo file **bằng tay** — KHÔNG dùng `-cmd=create`: nó vẫn sinh kèm `.down.sql` (trái rule, phải xoá tay)\n- `-cmd=down` là code chết: repo không có `.down.sql` nào nên `m.Steps(-n)` luôn lỗi \"file does not exist\". Không có đường rollback bằng tool — sai thì viết migration mới bù\n- Timestamp: `YYYYMMDDHHmmss` — 14 ký tự đến giây (VD: `20260520150544`)\n- **Trước khi tạo**: `ls migrations\u002F | sort | tail -3` — timestamp mới phải lớn hơn file mới nhất\n- Dùng `date +%Y%m%d%H%M%S` nếu kết quả lớn hơn file mới nhất; nếu không thì tăng từ file mới nhất\n- Không dùng số tròn như `130000`, `000000` — dễ trùng\n- **Trước khi `migrate up`**: chạy lại `ls migrations | sort | tail -3` — nếu có file mới hơn timestamp của mình (agent\u002Fsession khác vừa tạo+apply song song), phải regenerate timestamp và rename file trước khi apply, nếu không `migrate up` sẽ báo \"không có migration mới\" và bỏ qua âm thầm (version DB đã vượt qua timestamp cũ của mình).\n- **Cổng thật là DB, không phải danh sách file**: `SELECT MAX(version) FROM schema_migrations` trên **DB đích** (mỗi DB khách một con số khác nhau). `ls` chỉ thấy file trong checkout của mình — DB có thể đã vượt qua timestamp đó do phiên\u002Fmáy khác apply. Tên file ≤ version hiện tại ⇒ golang-migrate **bỏ qua vĩnh viễn**: không lỗi, không cảnh báo, và nếu đó là migration dọn dữ liệu sai thì dữ liệu sai nằm lại mãi.\n- **KHÔNG hỏi được \"migration X đã apply chưa\" từ `schema_migrations`** — bảng chỉ có MỘT dòng (`version` + `dirty`), không phải nhật ký; `WHERE version IN (…)` trả 0 KHÔNG có nghĩa chưa apply. Kiểm bằng **hiện vật**: `information_schema.STATISTICS` \u002F `COLUMNS` xem chỉ mục\u002Fcột đã tồn tại và đủ cột chưa.\n- **Trước mỗi `-cmd=up`**: liệt kê file có version > `MAX(version)` của DB đích để biết chính xác sắp áp gì — `-cmd=up` áp TẤT CẢ file pending, gồm cả việc dang dở của phiên khác.\n- `migrations\u002F` (schema mới CRM standalone, story-62): mỗi bảng 1 file `20260928093138…_create_\u003Cbảng>.up.sql` (`CREATE TABLE IF NOT EXISTS`, idempotent) + `…_add_fk_appointment` + 4 file seed `2026092809471x_seed_{business_profile,location,lookup,admin}` + migration viết sau đó. KHÔNG còn baseline\u002Fsquash.\n- (Lịch sử, bộ ERP cũ — nay nằm ở `backend\u002Fmigrations_backup\u002F`, migrate KHÔNG đọc: `00000000000000_baseline` + `seed_data` + `fix_json_string_columns` + `20260814091602_squash_20260406_to_20260814` gộp 326 migration. Hai gạch đầu dưới chỉ áp cho DB còn chạy bộ cũ.)\n- **TUYỆT ĐỐI KHÔNG đổi version của file squash.** `schema_migrations` chỉ giữ MỘT con số: giữ `20260814091602` → DB ở head `ErrNoChange`; đổi sang timestamp mới → mọi DB ở head chạy lại toàn dải và chết ở đoạn `20260427120000` (`Error 1054 company_type_id`), để lại dirty\n- File squash KHÔNG idempotent (72\u002F326 migration gốc 04–07\u002F2026 dùng `CREATE TABLE` trần \u002F `ADD COLUMN` không guard) ⇒ `-auto-recover` vô dụng với nó. Provisioning DB mới hỏng giữa chừng → `DROP DATABASE` làm lại (~25s), KHÔNG force\n\n## ⛔ CẤM test\u002Fmigrate chạm DB thật — CATASTROPHIC (bài học 2026-07-18)\n\n**Sự cố:** trong 1 session BMAD dài fan-out nhiều subagent tự verify integration test, DB dev thật của 1 khách (`DB_NAME` trong .env) bị **wipe sạch về baseline** (mất toàn bộ bảng + data) rồi kẹt `schema_migrations` **dirty ở version 1** (chết khi apply `seed_data.up.sql`), chặn toàn bộ ~250 migration sau. Không dựng lại được thủ phạm chính xác vì migrate stderr không được log.\n\n**Nguyên nhân gốc (3 lớp, không phải 1 lệnh đơn):**\n1. **`testhelpers.New` (`internal\u002Ftesthelpers\u002Fsuite.go`) gọi `dropAllTables` = `DROP TABLE` MỌI bảng** trong DB mà `TEST_MYSQL_DSN` trỏ tới. Trỏ nhầm vào DB thật = mất sạch data ngay, không undo.\n2. **`seed_data.up.sql` KHÔNG idempotent** (raw dump `INSERT INTO ... VALUES(id cố định)`) → chạy lại lên DB đã có data → dup-key → migrate **dirty** → chặn deploy.\n3. **Plan\u002Fstory ghi thẳng tên DB dev thật (`DB_NAME` trong .env) làm target verify backfill** → cấp \"giấy phép\" cho agent trỏ migrate\u002Ftest vào DB thật. Cộng root creds trong memory + fan-out cô lập, mỗi subagent tự tạo DB → không ai đặt guard.\n\n**LUẬT (áp cho MỌI agent, kể cả fix nhỏ):**\n- Integration test \u002F `testhelpers.New` \u002F `cmd\u002Fmigrate` khi verify **CHỈ** chạy trên **DB dùng-một-lần** (`CREATE DATABASE ..._test\u002F_tmp` đầu → `DROP` cuối). **TUYỆT ĐỐI KHÔNG** trỏ `TEST_MYSQL_DSN` hay `-db` vào `DB_NAME` (DB dev\u002Fprod thật).\n- **Plan\u002Fstory KHÔNG BAO GIỜ ghi tên DB thật làm target verify.** Cần data thật để kiểm backfill → clone: `CREATE DATABASE cluvix_verify_tmp` + nạp dump → verify → `DROP`. Không đụng bản thật.\n- **Mọi migration idempotent** — kể cả seed: `INSERT IGNORE` \u002F `ON DUPLICATE KEY UPDATE`, không raw `INSERT` id cố định (xem mục Idempotent bên dưới).\n- Guard code đã cài (lưới cuối, KHÔNG thay kỷ luật): `testhelpers.New` **fatal nếu DB trong DSN == `DB_NAME`**; `seed_data` đã `INSERT IGNORE`; `cmd\u002Fmigrate` `force`\u002F`down` cần `-confirm`. **`-auto-recover` KHÔNG cần `-confirm`** — là flag opt-in tường minh cho deploy tự phục hồi dirty-state chạy nền; bắt `-confirm` sẽ phá pipeline deploy (regression 2026-07-18).\n\n**Nếu chuyện này xảy ra trên PRODUCTION (mô hình DB-per-customer):**\n- **Mất toàn bộ dữ liệu 1 khách hàng ngay lập tức**: `dropAllTables` xóa mọi bảng của DB đó — customer, hóa đơn, bệnh án EMR, sổ kế toán, bảng lương — **không có undo tầng app**. Blast radius = trọn 1 khách (không leak cross-tenant nhưng khách đó mất sạch). Nếu script \"migrate all tenants\" loop qua mọi DB → **mất TẤT CẢ khách**.\n- **Migration dirty = outage**: app không boot \u002F deploy kế bị chặn cho tới khi có người xử tay `force`.\n- **Không backup = mất vĩnh viễn**; có backup thì vẫn mất phần data từ mốc backup gần nhất (RPO gap).\n- **Bắt buộc trước khi bất cứ thứ gì chạm gần prod**: (a) creds\u002Fnetwork test tách hẳn prod — code test *không thể* mở nổi connection tới prod; (b) backup tự động + **đã test restore** (binlog\u002FPITR); (c) migration idempotent + cổng dry-run staging; (d) `dropAllTables` chỉ chạy được trên DB tên `*_test`. Guard `DB_NAME`-equality ở trên là điều kiện cần tối thiểu, chưa đủ cho prod.\n\n## Decimal columns\n- Số tiền lớn (payment, revenue, debt): `decimal(20,2)`\n- Số tiền nhỏ\u002Fgiá thuốc\u002Fgiá vật tư: `decimal(15,2)`\n- Lương: `decimal(15,0)`\n- Phần trăm\u002Ftỷ lệ: `decimal(5,2)`\n- Chỉ số sinh tồn (BMI, cân nặng): `decimal(5,2)`\n- Ngày công\u002Fgiờ: `decimal(5,1)` hoặc `decimal(6,1)`\n- KHÔNG dùng `float` hay `double` cho tiền\n\n## GORM tag phải khớp migration\n```go\n\u002F\u002F Tiền\u002Fdecimal: decimal.Decimal (shopspring), KHÔNG float64\nAmount decimal.Decimal `gorm:\"type:decimal(20,2);not null;default:0.00\" json:\"amount\"`\nImportPrice *decimal.Decimal `gorm:\"column:import_price;type:decimal(15,2);default:0.00\" json:\"import_price\"`\nPercentage *decimal.Decimal `gorm:\"type:decimal(5,2)\" json:\"percentage\"`\n```\n\n## Column conventions\n- FK nullable: `INT NULL` + `INDEX` + `FOREIGN KEY ... ON DELETE SET NULL` (hoặc `RESTRICT` nếu business không cho phép mất tham chiếu)\n- FK not null: `INT NOT NULL` + `INDEX` + `FOREIGN KEY ... ON DELETE RESTRICT` (mặc định — không cho xóa parent khi còn con; chỉ dùng `CASCADE` khi đã xác nhận business muốn xóa dây chuyền)\n- Timestamp: `BIGINT` (Unix), KHÔNG `DATETIME`\n- JSON: `JSON` type, KHÔNG `TEXT`\n- String có giới hạn: `VARCHAR(n)`, KHÔNG `TEXT` trừ khi cần\n- `created_at`, `updated_at`: `BIGINT` (Unix)\n- `status`: `TINYINT(1) DEFAULT 1`\n- KHÔNG thêm cột `version` — optimistic lock theo `updated_at` (D6\u002FD21, tập bảng ở `pkg\u002Foptlock`)\n- `sort_order`: `INT DEFAULT 0`\n- `branch_id`: `INT` + `INDEX` + FK tới `branch` (NULL = dùng chung mọi chi nhánh — Hard Rules). KHÔNG còn cột `company_id` (D15\u002Fstory-62: 1 thương hiệu\u002FDB).\n\n## FK phải khớp signed\u002Funsigned với id bảng cha (Error 3780)\n\n- Kiểu cột FK PHẢI khớp CHÍNH XÁC signed\u002Funsigned với id bảng cha — lệch → MySQL Error 3780 khi ADD FK, chặn toàn chuỗi migrate.\n- Schema hiện tại: `id` các bảng cha (`appointment`, `customer`, `branch`, `user`…) là `int` SIGNED; bảng mới hay quen tay `int unsigned` → kiểm trước: `grep -m1 '\\`id\\`' migrations\u002F*_create_\u003Cbảng cha>.up.sql`.\n- Kiểm ĐỦ mọi cột FK trong file (kể cả `measured_by`\u002F`created_by`) — sót 1 cột vẫn chặn migrate.\n\n## CREATE VIEW phải khai DEFINER tường minh\n\n`CREATE [OR REPLACE] VIEW` thiếu `DEFINER` → MySQL tự gán definer = user chạy migration lúc tạo lần đầu. Máy\u002FDB khác không có đúng user đó → mọi `SELECT` qua view lỗi `Error 1449 (HY000): The user specified as a definer ... does not exist`. Luôn khai `CREATE OR REPLACE DEFINER=CURRENT_USER VIEW ...` (không hardcode username, chạy đúng trên mọi máy).\n\n## Template up.sql\n```sql\nCREATE TABLE `table_name` (\n  `id` int unsigned NOT NULL AUTO_INCREMENT,\n  `branch_id` int DEFAULT NULL COMMENT 'Chi nhánh (NULL = dùng chung)',\n  `category_id` int unsigned DEFAULT NULL COMMENT 'FK ví dụ — tham chiếu bảng khác',\n  `status` tinyint(1) DEFAULT '1',\n  `amount` decimal(20,2) NOT NULL DEFAULT '0.00' COMMENT 'Số tiền',\n  `note` text COMMENT 'Ghi chú',\n  `created_at` bigint DEFAULT NULL,\n  `updated_at` bigint DEFAULT NULL,\n  `created_by` int DEFAULT NULL,\n  `updated_by` int DEFAULT NULL,\n  PRIMARY KEY (`id`),\n  KEY `idx_branch_id` (`branch_id`),\n  KEY `idx_category_id` (`category_id`),\n  CONSTRAINT `fk-table_name-branch_id` FOREIGN KEY (`branch_id`) REFERENCES `branch` (`id`) ON DELETE RESTRICT ON UPDATE CASCADE,\n  CONSTRAINT `fk-table_name-category_id` FOREIGN KEY (`category_id`) REFERENCES `category` (`id`) ON DELETE RESTRICT ON UPDATE CASCADE\n) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;\n```\n\n### FOREIGN KEY bắt buộc cho mọi cột tham chiếu bảng khác (CRITICAL)\n\nMọi cột dạng `xxx_id` tham chiếu tới 1 row cụ thể ở bảng khác — kể cả self-reference (`parent_id`) — **PHẢI có `FOREIGN KEY` thật trong CREATE TABLE** (không chỉ `KEY`\u002F`INDEX`). Áp dụng CẢ `branch_id` (schema mới story-62: các bảng có `branch_id` như `customer`, `appointment`… đều có FK tới `branch`; `branch_id` NULL = dùng chung — FK cho phép NULL). Ngoại lệ DUY NHẤT: `created_by`\u002F`updated_by` (xem CLAUDE.md). (Ngoại lệ `company_id` cũ đã bỏ cùng cột, D15.)\n\n**Lý do (CRITICAL — không phải style, là bug thật):** `models.DeleteWithCheck` (`internal\u002Fmodels\u002Fbase.go`) — cơ chế DUY NHẤT chặn xóa record đang bị bảng khác tham chiếu — chỉ đơn giản DELETE rồi bắt lỗi MySQL 1451 (FK violation). Bảng thiếu FK thật → hàm này không có gì để bắt lỗi → xóa \"thành công\" nhưng để lại con mồ côi (con vẫn giữ id đã bị xóa, không báo lỗi ở đâu cả). Case thật: `payment.cash_flow_category_id` tham chiếu `cash_flow_category.id` không có FK — phát hiện 2026-07-12.\n\nChọn `ON DELETE`:\n- `RESTRICT` (mặc định) — không cho xóa parent khi còn con, đúng nghĩa `DeleteWithCheck` đang cố làm.\n- `SET NULL` — chỉ khi cột nullable và business chấp nhận con \"mất tham chiếu\" khi cha bị xóa (vd optional category).\n- `CASCADE` — chỉ khi đã xác nhận rõ business muốn xóa dây chuyền (hiếm, rủi ro cao — cân nhắc kỹ trước khi dùng).\n\n**Bảng đã có data:** trước khi `ADD FOREIGN KEY` (ALTER trên bảng cũ, xem pattern \"Add FK nếu chưa tồn tại\" ở phần Idempotent bên dưới) — BẮT BUỘC query check orphan trước:\n```sql\nSELECT COUNT(*) FROM child_table c\nLEFT JOIN parent_table p ON c.parent_id = p.id\nWHERE c.parent_id IS NOT NULL AND p.id IS NULL;\n```\nCó orphan → xử lý theo business (SET NULL hàng loạt \u002F gán lại parent hợp lệ) trong CÙNG migration, TRƯỚC statement `ADD CONSTRAINT` — nếu không `ADD FOREIGN KEY` sẽ fail ngay khi migrate.\n\n- ⚠ `ADD FOREIGN KEY` khi `FOREIGN_KEY_CHECKS=1` = thuật toán COPY ⇒ **chặn ghi cả bảng** suốt thời gian chép (153k dòng: 24s). Dữ liệu đã chắc sạch (vừa dọn orphan ngay trước trong cùng file, hoặc cột vốn có FK tới đúng bảng cha) ⇒ bọc riêng lệnh ADD: `SET @old_fkc = @@SESSION.FOREIGN_KEY_CHECKS; SET SESSION FOREIGN_KEY_CHECKS = 0;` … `SET SESSION FOREIGN_KEY_CHECKS = @old_fkc;` ⇒ INPLACE 0.02s. **Chưa dọn orphan thì cấm** — MySQL không kiểm dữ liệu cũ.\n- Backfill `UPDATE … JOIN` bảng lớn: `SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED` (không khoá đọc dòng bảng được JOIN); lưu `@@SESSION.transaction_isolation` đầu file, trả lại cuối file.\n\n## Bỏ index thừa kiểu tiền-tố-trái — phải THỬ, không được suy luận\n\nIndex có tập cột là **tiền tố trái** của một index khác trên cùng bảng thì bỏ được, kể cả khi nó đang đỡ `FOREIGN KEY` (MySQL chấp nhận index có cột FK làm tiền tố trái). Đã bỏ 50 index như vậy ở `20260906114555` — 0 FK và 0 UNIQUE bị đụng. Loại bỏ mọi index **UNIQUE** khỏi danh sách: bỏ index unique là mất ràng buộc duy nhất, không phải tối ưu.\n\nBa cái bẫy, cả ba đều cho kết luận SAI mà không báo lỗi:\n\n- `GROUP_CONCAT(COLUMN_NAME)` trên `information_schema.STATISTICS` **BỎ QUA NULL**. Index biểu thức (functional index) có `COLUMN_NAME = NULL` nên các cột biểu thức tàng hình, khiến index trông như bắt đầu bằng cột khác ⇒ kết luận \"tiền tố trái\" sai ⇒ `ERROR 1553 … needed in a foreign key constraint` lúc drop. Câu quét PHẢI loại index có `SUM(COLUMN_NAME IS NULL) > 0` ở **CẢ hai vế**.\n- \"Tiền tố trái ⇒ chắc chắn drop được\" là suy luận. Chốt danh sách bằng cách **thử drop TỪNG CÁI** trên DB dùng-một-lần rồi chỉ giữ cái thành công.\n- ⚠ **\"Drop được\" ≠ \"nên drop\" — phép thử trên chỉ đo FK, KHÔNG đo hiệu năng.** InnoDB nối PK vào đuôi mọi chỉ mục phụ, nên `(company_id)` thực chất là `(company_id, id)` và phục vụ `ORDER BY id DESC` miễn phí; bỏ nó đo được phân trang sâu **869ms → 4.793ms**. Chỉ mục **một cột dẫn đầu bằng cột scope** (nay là `branch_id`; số đo gốc làm trên `company_id` trước D15) trên bảng list lớn ⇒ giữ, và ghi lý do ngay trong migration để lần quét sau không bỏ lại. Số đo + cách bench: `..\u002Fdebugging-backend-queries\u002Freference\u002Fperf-list-endpoints.md` §\"Đừng bỏ chỉ mục một cột `(company_id)`\".\n- `group_concat_max_len` mặc định 1024 làm script đối chứng cắt cụt danh sách id ⇒ báo lệch giả. Nâng ở đầu phiên đo.\n\nChi phí đáng bỏ: một bảng từng mang index 231MB trên data 48MB (gấp 4.8 lần) vì 32 index — mỗi INSERT ghi từng ấy entry, và index không nhét vừa `innodb_buffer_pool_size`.\n\n## Backfill phải khớp TỪNG guard của runtime, không khớp bản mô tả\n\nRuntime luôn có điều kiện NGẦM mà bản mô tả bằng lời không nêu. Backfill viết theo lời (\"tin staff sớm\nnhất\") **nghe đúng** mà quy kết sai — không lỗi, không cảnh báo.\n\n- AC của story backfill phải **trích thẳng câu persist** (`file:dòng`); reviewer đối chiếu `WHERE` của\n  backfill với **từng** guard runtime, không đối chiếu với câu mô tả.\n- Sự cố 2026-08-20 (`omi_conversation.first_responder_id`): runtime chỉ quy kết **sau khi gửi THÀNH\n  CÔNG** và **không tính tin chiến dịch** — 2 điều kiện không ai viết ra. Backfill thiếu cả 2 ⇒ **3\u002F6**\n  hội thoại trên DB dev quy kết bằng tin `status=1` (gửi lỗi). Lọt qua Dev lẫn SM, chỉ lộ khi QA đọc\n  code persist thay vì đọc mô tả.\n- Cùng lớp: tin của **nhiều luồng khác nhau** có thể trùng `src`\u002F`created_by`\u002F`status` — trước khi tin\n  vào một cột phân biệt, duyệt **mọi** điểm dựng row trong code sản phẩm rồi ghi lại kết luận.\n\n## Verify migration trên DB tạm — clone schema THẬT, không tự gõ lại bảng cha\n\n- Dựng DB dùng-một-lần bằng `mysqldump --no-data` từ DB dev, KHÔNG tự `CREATE TABLE` lại bảng cha rút gọn.\n- Bảng cha tự gõ luôn permissive hơn thật (thiếu NOT NULL\u002FUNIQUE\u002Fkiểu cột lệch) → migration \"pass\" trên DB tạm rồi fail lúc chạy thật.\n- Apply file migration **2 lần liên tiếp** để nghiệm thu idempotent; drop DB tạm ngay sau khi xong.\n- ⚠ **Bảng có chỉ mục FULLTEXT thì clone bằng `mysqldump` CHƯA XONG ở bước nạp schema.** Dump chỉ chép\n  lại *định nghĩa* index; nạp vào DB tạm là nó được dựng lại dưới `@@GLOBAL.innodb_ft_enable_stopword`\n  (mặc định = 1), trong khi migration thật dựng nó với `SET SESSION … = OFF`. Hệ quả: DB tạm tìm kiếm\n  **sót âm thầm** — 2026-09-07 một bench báo bản vá đúng là \"sót 1.088–2.744 dòng\", suýt loại nhầm.\n  Phải dựng lại FULLTEXT trong DB tạm cho đúng rồi đối chứng `MATCH` = `LIKE` với DB thật TRƯỚC khi\n  tin bất kỳ số nào. Quy trình dựng đúng (phải DROP HẾT fulltext trên bảng, không chỉ một cái):\n  `..\u002Fdebugging-backend-queries\u002Freference\u002Fpatterns-gotchas.md` §\"Chỉ mục ngram dựng sai stopword\".\n- Viết migration **tạo mới** FULLTEXT ⇒ đọc mục đó TRƯỚC: stopword gắn theo BẢNG (cố định bởi index\n  FULLTEXT đầu tiên), `SET GLOBAL` KHÔNG ăn, và chỉ mục dựng sai làm tìm kiếm sai mà không ném lỗi.\n- ⚠ **Đặt file vào `migrations\u002F` = APPLY LUÔN lên DB dev**: `air` chạy `run_dev.sh` → `migrate up` vài giây sau khi file xuất hiện, không hỏi gì. Migration nặng\u002Fkhoá bảng (`ADD FULLTEXT`, `ALTER` bảng lớn) phải soạn và verify ở `backend\u002Ftmp\u002F` TRƯỚC, chỉ chuyển vào `migrations\u002F` khi đã đạt trên DB dùng-một-lần.\n  Số đo để lập cửa sổ bảo trì: `ADD FULLTEXT … WITH PARSER ngram` trên cột **TEXT tự do dài** =\n  **3 phút 06 giây \u002F 524k dòng**, gấp ~4 lần mốc ~42,7s của cột ngắn — nhân theo số khách vì\n  DB-per-customer. Giảm rủi ro: code gọi `MATCH` phải tự lùi về `LIKE` khi gặp lỗi 1191, nhờ đó\n  endpoint không vỡ trong lúc `ALTER` chạy và thứ tự apply không quan trọng.\n\n## Idempotent migrations (CRITICAL)\n\n→ `migration-idempotent.md` — `PREPARE\u002FEXECUTE`, `CREATE PROCEDURE`, INFORMATION_SCHEMA lookup,\nNOT NULL + FK, golang-migrate gotchas, auto-recovery dirty state.\n\n## Lưu ý\n- KHÔNG dùng `AutoMigrate` cho production\n- GORM tag `type:decimal(x,y)` phải khớp migration\n- Sau thêm decimal column vào bảng dùng `map[string]interface{}`: query thủ công `.Find(&rows)` phải gọi `helpers.ParseDecimalFields(row, \"field\")` thủ công\n- Schema gốc: `backend\u002Fmigrations\u002F\u003Ctimestamp>_create_\u003Cbảng>.up.sql` (không còn file baseline — bản ERP cũ ở `migrations_backup\u002F`, migrate không đọc)\n\n## UNIQUE KEY + NULL column — dùng sentinel 0, không NULL (CRITICAL)\n\n`UNIQUE KEY (template_type, branch_id)` với `branch_id NULL` → MySQL cho phép nhiều row vì `NULL ≠ NULL` → `ON CONFLICT` không trigger → duplicate records âm thầm.\n\n```sql\n-- ❌ NEVER\nbranch_id BIGINT UNSIGNED NULL\nUNIQUE KEY uq (template_type, branch_id)  -- nhiều row (X, NULL) được phép\n\n-- ✅ ALWAYS — sentinel 0 = mẫu chung toàn thương hiệu (vd print_templates.branch_id)\nbranch_id BIGINT UNSIGNED NOT NULL DEFAULT 0\nUNIQUE KEY uq (template_type, branch_id)  -- (X, 0) enforce unique\n```\n\n**Migration chuyển NULL → sentinel 0:**\n```sql\nUPDATE table SET branch_id = 0 WHERE branch_id IS NULL;\nALTER TABLE table MODIFY branch_id BIGINT UNSIGNED NOT NULL DEFAULT 0;\n-- ADD UNIQUE KEY nếu chưa có\n```\n\n**Query:** `WHERE branch_id = 0` thay vì `WHERE branch_id IS NULL`.\n**Fallback (branch → mẫu chung toàn thương hiệu; trước D15 gọi là company-level):** `WHERE branch_id IN (?, 0) ORDER BY branch_id DESC LIMIT 1`.\n\n**Ngoại lệ — cột PHẢI giữ NULL (có FOREIGN KEY thật: sentinel 0 vỡ FK vì không có row id=0):** dùng functional key part (MySQL ≥ 8.0.13):\n```sql\nALTER TABLE account_balance ADD UNIQUE KEY uq_ab ((COALESCE(customer_id, 0)), account_id, period);\n```\nDedupe dữ liệu trước khi ADD — xem section \"Đổi unique key trên bảng có dữ liệu\". Đã áp (ERP, bảng kế toán — đã bỏ cùng D2\u002FD15): `uq_account_balance_dim0`, `uq_coa_company_code`.\n\n**Chiều NGƯỢC lại — cột CỐ Ý giữ NULL để UNIQUE cho phép nhiều row: phải chuẩn hoá `''` → NULL TRƯỚC khi ADD UNIQUE.** MySQL coi chuỗi rỗng là một GIÁ TRỊ, nên nhiều NULL thì hợp lệ còn nhiều `''` là `Error 1062`. Code ghi NULL không có nghĩa dữ liệu cũ\u002Fseed cũng NULL.\n```sql\nUPDATE t SET col = NULL WHERE col = '';   -- idempotent, chạy TRƯỚC\n-- rồi mới ADD UNIQUE KEY (col)\n```\nCa biên của một ràng buộc UNIQUE phải phủ **cả hai biểu diễn \"không có giá trị\"** (`NULL` và `''`) — thử mỗi NULL rồi kết luận an toàn là bỏ lọt. Thật (2026-08-31, `meta_page_config.ig_business_account_id`): verify chỉ thử NULL nên pass, tới khi test khác seed `''` mới lộ; nếu lọt lên DB khách thì migration fail và chặn cả đợt deploy.\n\n---\n\n## Atomic counter upsert — cột cộng dồn (balance\u002Fcounter)\n\n- KHÔNG `First → Save` cho cột cộng dồn — read-modify-write bị lost-update khi 2 request song song. Chuẩn: UPDATE tăng trực tiếp → `RowsAffected == 0` → INSERT → INSERT dính 1062 (thua đua) → retry UPDATE lần cuối.\n- MySQL đánh giá `SET` **trái→phải**: cột dẫn xuất đặt SAU dùng giá trị MỚI của các cột trước.\n\n```sql\nUPDATE account_balance\nSET debit_total = debit_total + ?, credit_total = credit_total + ?,\n    closing = IF(? = 2, credit_total - debit_total, debit_total - credit_total)  -- đã là giá trị MỚI\nWHERE ...;\n```\n\n- Nhánh INSERT cần unique index backstop (cột nullable → functional key part, xem section trên). Mẫu Go: `engine.ApplyBalanceDelta` (`accountant\u002Fledger\u002Fengine`).\n\n---\n\n## GORM Raw Query — args ordering (CRITICAL)\n\n`?` placeholder được bind **theo thứ tự xuất hiện trong SQL string, từ trên xuống, trái sang phải** — kể cả trong SELECT clause.\n\n```go\n\u002F\u002F ❌ SAI — tưởng WHERE trước, CASE WHEN sau\nargs = append(args, consultTypeIDs, from, to, CheckedIn, CheckedOut, IsAccepted)\n\n\u002F\u002F ✅ ĐÚNG — CASE WHEN trong SELECT xuất hiện TRƯỚC WHERE trong SQL\nargs = append(args,\n    CheckedIn, CheckedOut,  \u002F\u002F CASE WHEN a.status IN (?,?)     ← ở SELECT\n    IsAccepted,             \u002F\u002F CASE WHEN a.is_accepted = ?      ← ở SELECT\n    consultTypeIDs, from, to) \u002F\u002F WHERE type IN ?, BETWEEN ? AND ? ← ở WHERE\n```\n\n- Subquery lồng nhau: args của subquery phía trên được bind trước subquery phía dưới\n- `IN ?` với `[]int` slice: GORM tự expand thành `(1,2,3)` — không cần làm thủ công\n- `IN ?` với empty slice `[]int{}`: GORM sinh `IN (NULL)` — query không lỗi nhưng không match row nào\n\n## Đổi unique key trên bảng có dữ liệu\n\n- golang-migrate chạy MỌI migration pending liên tiếp trong 1 lần `-cmd=up` — KHÔNG thiết kế \"migration A → script ngoài → migration B\"; backfill bằng SQL thuần (`REPLACE`\u002F`UPPER` lồng nhau đủ mạnh) trong CÙNG file.\n- Trước `ADD UNIQUE KEY`: bắt buộc dedupe dữ liệu hiện có bằng SQL (giữ `MIN(id)`, row trùng đổi giá trị hậu tố `_DUP\u003Cid>` — không xóa cứng); bỏ sót → constraint fail → dirty state block deploy.\n\n## (đã bỏ, D15) Seed bảng scope theo company — per-company, không anchor 1 company duy nhất\n\n> Lịch sử: bảng `company` + cột `company_id` không còn (1 thương hiệu\u002FDB). Seed nay chỉ cần idempotent\n> `WHERE NOT EXISTS`\u002F`INSERT IGNORE` trong phạm vi 1 DB (Hard Rules); bài học còn giá trị: đừng\n> neo seed vào 1 dòng `MIN(id)` của bảng cha khi bảng cha có thể có nhiều dòng (vd `branch`).\n\n(Lịch sử, D15) Seed `config_code` (hay bảng nào cần 1 row\u002F`company_id`) KHÔNG dùng `SELECT MIN(id) FROM company` làm anchor — chỉ seed đúng 1 company, DB nhiều company (multi-brand cùng 1 khách) sẽ có company thiếu row, rơi vào fallback \"bất kể company\" sai tenant.\n\n```sql\n-- (lịch sử, D15) ❌ SAI — chỉ seed company nhỏ nhất\nINSERT INTO config_code (company_id, ...) SELECT (SELECT MIN(id) FROM company), ...  -- (lịch sử, D15)\nWHERE NOT EXISTS (SELECT 1 FROM config_code WHERE parent_table = 'service');\n\n-- ✅ ĐÚNG — seed đủ mọi company\nINSERT INTO config_code (company_id, ...)  -- (lịch sử, D15)\nSELECT c.id, ... FROM company c\nWHERE NOT EXISTS (SELECT 1 FROM config_code WHERE parent_table = 'service' AND company_id = c.id);  -- (lịch sử, D15)\n```\n- Cột nhận hậu tố dedupe phải khai đủ rộng (vd VARCHAR(20) thay vì VARCHAR(10)) — strict mode nổ `Data too long` ngay trong migration.\n\n## Kiểm \"đã seed chưa\" — dò theo KHOÁ SEED, KHÔNG theo `id`\n\nAudit \"record X đã có migration seed chưa\" phải dò theo **khoá seed thật** (`name`, `key`, `handler_key`), KHÔNG theo `id`.\n`INSERT IGNORE INTO t (name, ...)` không có cột `id` ⇒ mọi phép dò dựa trên `id` **mù hoàn toàn**: con số id không xuất hiện ở bất kỳ đâu trong file migration.\n`id` là `AUTO_INCREMENT` ⇒ **không ổn định giữa các DB khách** — cùng câu seed cho id 41 ở DB này, 45 ở DB khác.\n`INSERT IGNORE` trùng khoá **im lặng không làm gì** ⇒ \"chạy 2 lượt mà giá trị không đổi\" KHÔNG phân biệt được *idempotent* với *câu lệnh chưa bao giờ chạy*; xoá dòng rồi chạy lại để chứng minh lệnh có tác dụng.\n\n## Data-fix cột JSON array — additive, idempotent\n\nThêm phần tử vào cột JSON array (vd `departmentList`) để gỡ chặn nghiệp vụ: dùng\n`JSON_ARRAY_APPEND` bọc `NOT JSON_CONTAINS` — chạy lại không double-add, không đụng phần tử cũ.\n\n```sql\nUPDATE t SET col = JSON_ARRAY_APPEND(col, '$', \u003Cvalue>)\nWHERE id = ? AND NOT JSON_CONTAINS(col, '\u003Cvalue>');\n```\n\n## UNION ALL bảng cũ + bảng mới → MySQL 1271 \"Illegal mix of collations\"\n\nBảng cũ không khai `COLLATE` tường minh kế thừa collation mặc định server; bảng mới khai rõ\n(vd `utf8mb4_unicode_ci`) → UNION ALL 2 nhánh lẫn collation khác nhau, lỗi CHỈ lộ khi chạy\nquery thật (không phải lỗi Go\u002Fbuild). Fix: ép `COLLATE utf8mb4_unicode_ci` tường minh trên\nMỌI cột string (kể cả literal) ở TẤT CẢ nhánh UNION, không chỉ nhánh mới.\n\nKHÔNG `SET col = '[...]'` ghi đè nguyên mảng — mất phần tử cũ nếu tính base sai.\n\n## Cột SINH (generated column) + khoá ngoại: phải VIRTUAL, KHÔNG STORED\n\n**Đo thật trên MySQL 9.7.1 (2026-08-25, `omi_message_reaction`):** MySQL từ chối **MỌI** `FOREIGN KEY`\nđặt trên **cột nền** của một generated column **STORED** — thử đủ 3 tổ hợp\n`ON DELETE SET NULL\u002FCASCADE` × `ON UPDATE CASCADE\u002FRESTRICT`, tất cả đều `ERROR 1215 (HY000): Cannot\nadd foreign key constraint`. Cùng biểu thức đó để **VIRTUAL** thì FK tạo được bình thường, và UNIQUE\ntrên cột ảo VẪN chặn trùng thật (`ERROR 1062`) — InnoDB cho phép index phụ trên cột ảo.\n\nVì sao dễ mất thời gian ở đây: lỗi 1215 **không nói cột nào gây ra**, và `SHOW ENGINE INNODB STATUS`\ntrên MySQL 9.x không còn khối `LATEST FOREIGN KEY ERROR`. Cách chẩn đoán nhanh: tạo bảng thử với\ntừng FK riêng lẻ (đều chạy được) rồi thêm cột sinh vào → lộ ngay thủ phạm.\n\n**Khi nào cần cột sinh:** MySQL KHÔNG có partial\u002Ffiltered index. Muốn một `UNIQUE` phủ hai loại chủ\nthể loại trừ nhau (vd người thả cảm xúc: nhân viên nội bộ có FK `user_id` ↔ khách chỉ có chuỗi uid),\nhội tụ chúng về một cột sinh rồi UNIQUE trên đó:\n`reactor_key VARCHAR(120) GENERATED ALWAYS AS (IF(user_id IS NULL, channel_uid, CONCAT('u:', user_id))) VIRTUAL`\n⚠ **Tiền tố (`u:`) là bắt buộc** — thiếu nó thì `user_id = 123` và `channel_uid = \"123\"` đụng nhau.\n\nEntity GORM: cột sinh phải `gorm:\"->\"` (chỉ đọc). Thiếu tag ⇒ GORM đưa cột vào INSERT ⇒ **mọi**\n`Create` lỗi, và chỉ lộ ra khi có code thật dùng entity (tức là muộn).\n\n\n## ⚠ Ghi file vào `migrations\u002F` = ĐÃ APPLY lên DB dev trong vài giây (đo 2026-09-08)\n\n`backend\u002Fscripts\u002Frun_dev.sh` chạy `migrate up` **mỗi lần air rebuild**, và air rebuild ngay khi có\nfile mới. Nghĩa là: **không có bước \"viết xong rồi mới quyết định chạy\"** — vừa `Write` file\n`.up.sql` là nó đã chạy trên DB dev thật, trước khi kịp verify trên DB dùng-một-lần.\n\nBằng chứng (`backend\u002Ftmp\u002Frun.log`):\n\n```\n[16:33:36] run_dev.sh: migrate OK — migrate up: không có migration mới (version 20260908155444)\n[16:36:43] run_dev.sh: migrate OK — migrate up: 20260908155444 → 20260908163530 thành công\n```\n\nFile `20260908163530_*.up.sql` được ghi lúc 16:36 và tự apply lúc 16:36:44.\n\nHệ quả bắt buộc nhớ:\n\n1. **Verify TRƯỚC khi ghi vào `migrations\u002F`.** Soạn nội dung ở scratchpad của phiên, chạy thử trên\n   DB `*_tmp` (2 lần cho idempotency + 1 lần trên DB có dữ liệu vi phạm để xem cổng chặn có fail\n   thật không), rồi mới `Write` vào `migrations\u002F`. Làm ngược lại thì DB dev là nơi thử nghiệm đầu\n   tiên — đúng thứ luật ⛔ đầu file này cấm.\n2. **Migration hỏng ⇒ `dirty=1` và dev server của user chết** cho tới khi có người dọn tay. Kiểm\n   `SELECT dirty, version FROM schema_migrations` sau khi ghi file.\n3. Sửa nội dung một migration ĐÃ apply thì DB dev **không chạy lại** (golang-migrate chỉ nhớ\n   version, không có checksum) — nhưng DB khách khác sẽ nhận bản MỚI. Chỉ sửa khi nội dung mới\n   tương đương về ngữ nghĩa, và phải verify lại bản mới trên DB dùng-một-lần.\n\n## Rẽ nhánh có điều kiện: cách bắt migration DỪNG với thông báo đọc được\n\nCổng kiểm dữ liệu (vd \"còn bản sao thì đừng thêm UNIQUE\") mà chỉ `IF NOT EXISTS` rồi im lặng không\ntạo sẽ báo **thành công trên DB vẫn còn lỗ hổng** — xanh giả. Phải fail thật.\n\n- `SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = '…'` cho thông báo đẹp nhất và **chạy được ngoài\n  stored program**, NHƯNG **không dùng được ở đây**: `ERROR 1295 … not supported in the prepared\n  statement protocol`. Mà `PREPARE`\u002F`EXECUTE` lại là cách duy nhất để rẽ nhánh có điều kiện trong\n  file `.sql` không có stored program. Đã đo cả hai chiều 2026-09-08.\n- Cách còn lại: tham chiếu **một bảng không tồn tại mà TÊN chính là thông báo**:\n  `'SELECT 1 FROM \\`MIGRATION_ABORT_duplicate_customer_id_in_customer_warranty_code\\`'`\n  ⇒ `ERROR 1146 … Table 'db.migration_abort_duplicate_customer_id_in_customer_warranty_code'\n  doesn't exist`, exit code 1, và các câu lệnh sau KHÔNG chạy. Tên ≤64 ký tự (giới hạn identifier).\n\n⚠ Khi kiểm exit code trong shell: `mysql … | grep -v \"Using a password\"` trả exit code của **grep**,\nkhông phải của mysql. Đo đúng phải bỏ pipe (`mysql … > \u002Fdev\u002Fnull 2>&1; echo $?`) hoặc đọc\n`PIPESTATUS`. Đã suýt kết luận \"cổng chặn không fail\" vì đọc nhầm số 0 của grep.\n\n⚠ Cùng nguyên nhân, hậu quả khác: `mysql … | grep -v \"Using a password\" && \u003Clệnh kế>` — không dòng\nnào lọt qua grep ⇒ exit 1 ⇒ **lệnh kế bị bỏ qua im lặng**. Nối nhiều bước DB thì tách từng lệnh\nriêng, và luôn `SELECT COUNT(*)` xác nhận bước trước đã ghi được dữ liệu.\n\n## Thứ tự bắt buộc khi đổi chỉ mục mà FK đang dựa vào\n\n`ALTER TABLE … DROP INDEX` trên cột có FOREIGN KEY sẽ bị MySQL từ chối\n(`ERROR 1553 … needed in a foreign key constraint`) nếu không còn chỉ mục nào khác đỡ FK. Nên khi\nthay chỉ mục thường bằng UNIQUE trên CÙNG cột: **ADD UNIQUE trước, DROP index thường sau** — thứ tự\nngược lại fail. Kiểm sau khi chạy: FK phải còn trong `information_schema.KEY_COLUMN_USAGE`.\n",{"name":5,"description":7},"main","ea9f5ed9bd4eaf32e9489bcbe9603955c1462a63","skill\u002Fskills\u002Fwriting-mysql-migrations",20,"https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm","https:\u002F\u002Fgithub.com\u002Fcluvix","cluvixsolutions.com","Cluvix Solutions is a technology outsourcing company specializing in custom software development for growing businesses. We build end-to-end enterprise solution","2026-11-02 19:55:39",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add cluvix\u002Fcluvix-crm --skill writing-mysql-migrations",{"tool":39,"command":40},"bunx","bunx skills add cluvix\u002Fcluvix-crm --skill writing-mysql-migrations",{"tool":42,"command":43},"pnpm","pnpm dlx skills add cluvix\u002Fcluvix-crm --skill writing-mysql-migrations","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fwriting-mysql-migrations\u002FSKILL.md",true,[47,53,57],{"path":48,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":51,"sourceHtmlUrl":52},"reference\u002Fmigration-idempotent.md","REFERENCE","参考文档",11491,"https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fwriting-mysql-migrations\u002Freference\u002Fmigration-idempotent.md",{"path":54,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":55,"sourceHtmlUrl":56},"reference\u002Fmysql97.md",15294,"https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fwriting-mysql-migrations\u002Freference\u002Fmysql97.md",{"path":58,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":59,"sourceHtmlUrl":60},"reference\u002Fupgrade-lts.md",6951,"https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fwriting-mysql-migrations\u002Freference\u002Fupgrade-lts.md",[62,69,76,83,90,97],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M7F475VEPATD0D8KP8V2HHYV","writing-backend-resources","Hướng dẫn quy trình 6 bước TẠO MỚI resource backend Go (entity, dao, repository, service, handler, router, DTO, module layout) cho ERP Cluvix. Dùng skill này TRƯỚC KHI tạo resource CRUD mới hoặc module mới trong internal\u002Fmodules\u002F, khi cần biết Handler DI\u002FRouter\u002FRepository Reader\u002FDTO pattern chuẩn, hoặc trước khi đụng module service (status filter 2 tầng, cascade, optimistic lock). KHÔNG dùng skill này để debug\u002Fsửa query đang sai — xem debugging-backend-queries cho việc đó.","https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fwriting-backend-resources\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M7F46Z6MMBQ0AP2ZA5HW5R4X","working-on-ops","Hướng dẫn nghiệp vụ dashboard CRM, export, và import dữ liệu trong module ops của backend Cluvix. Dùng skill này KHI đụng report\u002Fdashboard CRM, thêm cột export (`?columns=`), hoặc import khách hàng (migration onboard SAAS client) — đọc trước khi đổi bất kỳ hành vi nào trong các luồng này.","https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fworking-on-ops\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M7F46PPNCK976F4SYWVHXAHC","working-on-hr","Quy tắc và pattern nghiệp vụ HR Cluvix trong CRM standalone: user nội bộ, role\u002FRBAC, đổi\u002Fđặt lại mật khẩu, import user. Dùng skill này KHI làm feature\u002Fsửa bug đụng module hr (chỉ còn `hr\u002Fuser`) — trước khi đọc code.","https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fworking-on-hr\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M7F468VEARVSRRYBJ8VHJSJ3","working-on-crm","Quy tắc và pattern nghiệp vụ CRM Cluvix: khách hàng, lịch hẹn, liệu trình, đơn hàng, thanh toán. Dùng skill này KHI làm feature\u002Fsửa bug đụng module crm (customer, appointment, order, treatment, payment) — trước khi đọc code, để tránh phá vỡ business rule đã có (tái khai thác, customer status IN(...)).","https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fworking-on-crm\u002FSKILL.md",[],[],{"skillNo":91,"name":92,"nameZh":6,"description":93,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":19},"01M7F45Y15Q0CBEP06CFF2AAEY","working-on-config","Quy tắc và pattern nghiệp vụ Config Cluvix còn sống trong CRM standalone: mẫu in (print_template), control field trong bảng (control_field_in_table), IndexedDB sync của config. Dùng skill này KHI làm feature\u002Fsửa bug đụng các module đó — trước khi đọc code. Tổng đài\u002Fchữ ký số\u002FAI config đã bỏ (chỉ còn mô tả lịch sử trong skill, KHÔNG áp dụng).","https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fworking-on-config\u002FSKILL.md",[],[],{"skillNo":98,"name":99,"nameZh":6,"description":100,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":101,"categories":102,"keywords":103,"publishedAt":19},"01M7F45FK4E7YJ0MENAWJT9NGY","testing-backend","Hạ tầng test Go: unit test, integration test với TEST_MYSQL_DSN (MySQL disposable thật, KHÔNG dockertest), FreshTenant helper, HTTP handler test qua httptest, và mutation test (`go test -overlay`) để chứng minh test thật sự neo hành vi. Dùng skill này TRƯỚC KHI viết test mới cho backend Go, khi cần biết cách dựng DB test sạch mỗi lần chạy, trước khi báo một AC dạng phủ định\u002Fmặc định là Done, hoặc trước khi verify build\u002Ftest theo Development Protocol bước 4 (Validate).","https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Ftesting-backend\u002FSKILL.md",[],[]]