[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7F4181C1M91P53TWDMDF4S4":3,"skill-same:01M7F4181C1M91P53TWDMDF4S4":65},{"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},"01M7F4181C1M91P53TWDMDF4S4","building-list-and-export-views",null,"BaseListV2 (filterFields, state trên URL, fetchList), BaseDetail\u002FBaseReport\u002FBasePrint, và export\u002Fimport Excel trong Cluvix FE. Dùng skill này KHI làm màn hình danh sách mới, migrate list V1→V2, thêm report có export, hoặc thêm chức năng in — trước khi đụng colDef\u002FExportOptionsDialog hoặc PrintLayout.","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\u002Ffrontend\u002Fskill\u002Fskills\u002Fbuilding-list-and-export-views\u002FSKILL.md",[],[],"2026-11-16 10:05:34",false,"---\nname: building-list-and-export-views\ndescription: >-\n  BaseListV2 (filterFields, state trên URL, fetchList), BaseDetail\u002FBaseReport\u002FBasePrint,\n  và export\u002Fimport Excel trong Cluvix FE. Dùng skill này KHI làm màn hình danh sách\n  mới, migrate list V1→V2, thêm report có export, hoặc thêm chức năng in — trước khi\n  đụng colDef\u002FExportOptionsDialog hoặc PrintLayout.\n---\n\n# Building list and export views\n\n> Print flow chi tiết (PrintLayout, PrintContext, window.print() gotchas): `reference\u002Ffe-print.md`\n> Import\u002FExport Excel chi tiết: `reference\u002Ffe-patterns-import-export.md`\n> Gotchas Search\u002FAutoComplete\u002FList display: `reference\u002Ffe-patterns-gotchas-search.md`\n> Khuôn `.ts` + `.html` cho list config mới (toolbar lọc, bộ chọn cột, cột thao tác cố định): `reference\u002Ffe-list-config-template.md`\n\n\n\nDùng cho list mới, hoặc list cần giữ filter khi bấm vào bản ghi → xem chi tiết → Back.\n`BaseList` (V1) giữ nguyên — KHÔNG migrate hàng loạt, chuyển từng list khi có nhu cầu.\n\n## Bật V2\n\n```ts\nexport class XxxList extends BaseListV2\u003CXxxModel> implements OnInit {\n  @ViewChild('dt') dt!: Table\u003CXxxModel>;\n  protected override URL_STATE_PREFIX = 'xx';   \u002F\u002F 2–3 ký tự, khác nhau giữa 2 list cùng 1 route\n  protected filterFields(): FilterFieldDef[] { return [ \u002F* ... *\u002F ]; }\n  ngOnInit() { this.initListV2(); }\n}\n```\n\n```html\n\u003Cp-table #dt [lazy]=\"true\" [lazyLoadOnInit]=\"false\" (onLazyLoad)=\"loadRecords($event)\"\n         [filters]=\"initialFilters()\" [first]=\"first()\" [loading]=\"showSkeleton()\" [filterDelay]=\"0\">\n  \u003Cng-template #caption>\n    \u003Cdiv class=\"h-[2px] mb-1\">\n      @if (refreshing()) { \u003Cp-progressbar [showValue]=\"false\" [style]=\"{height:'2px'}\" mode=\"indeterminate\"\u002F> }\n    \u003C\u002Fdiv>\n```\n\n- 5 binding bắt buộc: `[lazyLoadOnInit]=\"false\"` · `[filters]` · `[first]` · `[loading]=\"showSkeleton()\"` · `[filterDelay]=\"0\"`.\n- Thanh báo tải lại đặt trong hộp cao cố định (`h-[2px]`) — tự nó không được gây CLS.\n- KHÔNG override `initFilter()`, `getDefaultFilterValues()`, `clearFilter()`, `searchHandler()` — base lo hết.\n\n## filterFields()\n\n- 1 field = 1 dòng: `{name, kind, default?, urlKey?, debounce?, itemType?, toFilter?, urlSync?}`.\n- `kind`: `text` (contains) · `in` (multiselect, LUÔN mảng) · `equals` (select 1, LUÔN scalar) · `dateRange` (between, cặp unix) · `dateSingle` (chọn 1 ngày, gửi BE chuỗi `yyyy-MM-dd`, matchMode mặc định `custom`) · `monthDayRange` (khoảng ngày-tháng KHÔNG năm, between, cặp chuỗi `MM-DD` — vd lọc sinh nhật) · `dateRangeSplit` (khoảng ngày mà BE đọc bằng **2 param tên riêng**, vd `_dueDateGte`\u002F`_dueDateLte`) · `custom` (tự lo qua `toFilter`).\n- BE nhận **khoảng ngày-tháng không năm** (`MM-DD`, vd `birthday_md`) → `kind: 'monthDayRange'`. KHÔNG dùng `custom`: `custom` không parse ngược URL→`Date` nên filter không sống sót qua Back\u002FF5 (cùng bài học với `dateSingle`). Ngày chỉ tồn tại ở năm nhuận (`02-29`) được giữ bằng cách lùi về năm nhuận cố định — panel lịch sẽ hiện năm đó, ô input `dateFormat=\"dd\u002Fmm\"` không lộ.\n- BE nhận khoảng ngày qua **2 tên param khác nhau** (không phải 1 param `[gte]\u002F[lte]`) → `kind: 'dateRangeSplit'` (accountant 2026-08-04, `InstallmentDebts._dueDateGte`\u002F`_dueDateLte`). Một `FilterMetadata` chỉ sinh được 1 tên param nên base **không sinh gì** (`toFilterMeta` trả `null`) — chỉ lo FormControl + URL sync; component tự ghép 2 param trong `fetchList()`. Nhờ vậy filter này **sống sót qua Back\u002FF5**, khác hẳn cách cũ (`custom` + `urlSync:false`) không làm được.\n- Select chọn-một: template KHÔNG `[multiple]`, PHẢI `[showClear]=\"true\"` (thiếu → không xoá được filter), def `kind: 'equals'`.\n- **`p-datepicker` filter với `(onClear)=\"clearXxx()\"` — PHẢI có `[showClear]=\"true\"` trên CÙNG thẻ, nếu không handler CÂM LẶNG mãi mãi** (PrimeNG v22: `clearIconEnabled = showClear() && !disabled()`, mặc định `showClear=false` → icon xoá không bao giờ render → `clear()` không ai gọi được → `onClear.emit` không bao giờ chạy). Không phải lỗi cú pháp, `tsc`\u002F`ng build` đều sạch — chỉ lộ ra khi bấm thật trên UI. Đo được ở accountant: 70\u002F71 chỗ dính lỗi này từ trước khi có epic migrate.\n- `default` phụ thuộc thời điểm → truyền factory: `default: () => [this.timezoneService.todayStart(), this.timezoneService.todayEnd()]`.\n- Sentinel\u002Fluật riêng → `toFilter`, vd `revenue_id` id=0 nghĩa là chưa có → `{value: '1', matchMode: 'is'}`.\n- `urlKey` bỏ trống = tự suy: bỏ `_` đầu + camelCase→snake_case (`_groupLocal`→`group_local`, `customerType`→`customer_type`). Chỉ khai khi muốn khác quy ước (`appointment_date`→`date`) hoặc khi bị trùng (`_status` vs `status`).\n- Control tên có ký tự `[`\u002F`]` (kind `'custom'`, BE đọc raw `c.Query(\"field[x]\")`) → BẮT BUỘC khai `urlKey` tường minh (vd `urlKey:'status'`) — mặc định giữ nguyên ký tự lạ, `URLSearchParams` percent-encode thành `%5B%5D` trên address bar (round-trip đúng, chỉ xấu URL). `assertFilterDefs()` không chặn được ca này.\n- `assertFilterDefs()` ném lỗi lúc mở trang (dev) khi trùng `name`, trùng urlKey, hoặc đụng khoá dành riêng `_f`\u002F`_page`\u002F`_size`\u002F`_sort`.\n- Lọc từ code: `this.setFilterValue(name, value)` — KHÔNG `patchValue()` + `resetPage()` (đẻ 2 request).\n- Field BE chưa có `query.ApplyFilter` thì KHÔNG khai def và KHÔNG để nút bấm lọc — nút sẽ đổi URL mà kết quả không đổi (sai âm thầm).\n- `kind: 'text'` value đi thẳng vào query string GET, KHÔNG giới hạn độ dài mặc định — gõ\u002Fpaste vài nghìn ký tự làm request vượt giới hạn dòng request của backend\u002Fproxy → HTTP 414, list trắng im lặng. Base đã tự chặn ở `MAX_TEXT_FILTER_LENGTH = 200` (`list-filter.model.ts`) — mọi `kind:'text'` tự cắt còn 200 ký tự + toast cảnh báo (`base-list-v2.ts` `wireFilterControls()`), áp dụng mọi list dùng `BaseListV2`, không cần khai gì thêm.\n\n## State trên URL\n\n- Param phẳng, không mang matchMode: `?ap_f=1&ap_date=1785690000,1785776399&ap_status=1&ap_page=2`.\n- `ap_f=1` = cờ \"URL đang giữ state\": có cờ → URL là nguồn sự thật, param vắng mặt = người dùng đã xoá filter đó; không cờ → dùng default.\n- Ghi URL bằng `Location.replaceState`, **KHÔNG** `router.navigate` — navigate chạy trọn chu kỳ điều hướng (ActivationEnd ×N + Scroll) làm `p-table` vẽ lại đè lên popover filter đang mở.\n- Query dựng từ `location.path()`, chỉ `set`\u002F`delete` key mình sở hữu — KHÔNG `createUrlTree({queryParamsHandling: 'merge'})`; `replaceState` không báo cho router nên cây URL của router luôn cũ.\n- Trả `%2C` → `,` sau `URLSearchParams.toString()`.\n- Đồng bộ lại khi điều hướng: nghe `NavigationEnd` **và `NavigationSkipped`** — bấm lại chính menu đang đứng thì router skip, `queryParams` KHÔNG phát. Đọc state từ `e.url`, KHÔNG từ `activatedRoute.snapshot` (skip không cập nhật snapshot).\n- Khi đồng bộ lại phải gán LUÔN `page`\u002F`per-page`\u002F`sort` (param vắng = về mặc định), KHÔNG gán theo `if (page > 1)`.\n- `writeUrlState()` gọi trong `setTimeout` + guard cờ `destroyed` — router commit URL ở cuối chu kỳ, và component có thể đã huỷ trong khoảng đó.\n- Chặn theo path (`e.url` vs path lúc init) trước khi xử — không ghi đè URL của trang khác.\n\n## Tải dữ liệu\n\n- Override `fetchList()` trả `Observable\u003CListApiResponse\u003CT>>`; KHÔNG override `searchHandler`, KHÔNG tự set `loading`\u002F`models`\u002F`paginationInfo`.\n- Base đẩy mọi lần tải qua `Subject + switchMap` → huỷ request cũ, hết cảnh response cũ về sau ghi đè kết quả mới.\n- `getList()` KHÔNG xoá `models` (stale-while-revalidate). Skeleton chỉ ở lần tải đầu (`showSkeleton` = `loading && !loadedOnce`); các lần sau dùng `refreshing`.\n- List có `#loadingbody` dùng `colsIt()` PHẢI gán `effect(() => this.padCols.set(this.selectedColumns().length + \u003Csố cột luôn hiện>))` trong constructor — `padCols` mặc định 0 ⇒ hàng skeleton không có `\u003Ctd>` nào, `tsc`\u002F`ngc` không bắt.\n- Endpoint không theo convention `filter[field][matchMode]` (vd query phẳng riêng) → vẫn khai `filterFields()` bình thường (để có URL state + wiring), nhưng `fetchList()` đọc thẳng `rfFilterModel.getRawValue()` và tự dựng param như V1 — KHÔNG dùng `searchParams()`. Ghi comment tại chỗ giải thích lý do, kẻo người sau \"dọn\" nhầm về `searchParams()`.\n- List có field tổng\u002Fside-effect ngoài `items`\u002F`_meta` gán trong `fetchList()` (vd `total`\u002F`discount` hiển thị footer) → PHẢI tự thêm sequence guard (`private xxFetchSeq = 0`, tăng ở đầu `fetchList()`, chỉ gán khi `seq === this.xxFetchSeq` lúc response về) nếu paginator\u002Fsort không debounce — `wireReloadPipeline` (base) chỉ huỷ được việc GIAO `models`\u002F`paginationInfo` cho request cũ, KHÔNG huỷ side-effect tự viết chạy trong thân `switchMap(async...)` của chính `fetchList()`.\n- `effect()` re-tính state \"theo trang mới\" (vd cơ chế chọn-dòng tự viết cần `currentPageItems` khớp trang hiện tại) phải watch `this.paginationInfo()`, KHÔNG watch `this.models()` — `models` còn bị mutate NGOÀI luồng fetch bởi `updateRow()` (base, dùng khi cập nhật 1 dòng tại chỗ vd toggle status), `paginationInfo` chỉ đổi khi có fetch thật.\n- List nhúng nhận `@Input customer` từ parent có `model()` khởi tạo rỗng-nhưng-truthy (vd `customer-detail.ts` dùng `signal({} as T)`) → `fetchList()` có thể chạy với `customer.id === undefined` lúc parent chưa load xong HTTP, rõ nhất khi Back\u002FForward remount toàn trang (không phải chỉ đổi tab). Guard đầu `fetchList()`: `if (!this.customer?.id) return this.emptyListResult();` — helper có sẵn trên `BaseListV2`, trả `{items:[], _meta:{totalCount:0}}` hợp lệ (không phải lỗi); `ngOnChanges` sẵn có sẽ tự refetch khi customer load xong. Cùng lý do gây interceptor văng cả app nếu BE endpoint coi id rỗng là 404 — xem `frontend\u002Fskill\u002Fskills\u002Fworking-on-fe-modules\u002Freference\u002Ffe-patterns-gotchas.md`.\n\n## Gotcha PrimeNG v22\n\n- Input `[filters]` đồng bộ vào `dt.filters` qua `effect()` → chạy SAU `ngOnInit` của bảng, tức sau lần `onLazyLoad` đầu tiên. Bảng tự bắn thì request đầu đi với filter RỖNG → bắt buộc `[lazyLoadOnInit]=\"false\"`, base tự bắn trong `afterNextRender`.\n- `filterDelay` mặc định đã là 300 → gỡ binding vô ích, phải `[filterDelay]=\"0\"` (base đã debounce 300\u002F500ms).\n- `p-select [multiple]=\"true\"` trông y hệt dropdown chọn-một (không checkbox, không chip) — dễ tưởng single trong khi nó cộng dồn.\n- Control inline trong `p-table` (`p-toggleswitch`, checkbox) bind `[ngModel]` một chiều **KHÔNG tự quay lại giá trị cũ khi API lỗi**: control ghi thẳng vào state nội bộ lúc bấm, Angular chỉ `writeValue` khi giá trị binding ĐỔI, và `rowTrackBy` mặc định track theo THAM CHIẾU dòng → tạo mảng mới mà giữ nguyên reference từng dòng thì view được tái dùng, không revert. Revert đúng = **thay reference dòng**: `models.update(rows => rows.map(r => r.id === id ? {...r, status: cũ} : r))`, kèm set lạc quan trước khi gọi API.\n\n## Điều kiện đủ để migrate 1 list sang V2\n\nKiểm 3 thứ TRƯỚC khi bắt tay, thiếu bất kỳ cái nào thì **giữ nguyên V1**:\n- Template có `\u003Cp-table>` **và** `[lazy]=\"true\"` — mọi giá trị của V2 (URL state, SWR, huỷ request cũ) đi qua `onLazyLoad` → `loadRecords()`. Bảng không lazy thì V2 chỉ đổi base class, không được gì.\n- Có `@ViewChild('dt')` (thiếu thì thêm — `BaseListV2` khai `abstract dt`).\n- Component có nơi dùng thật (route hoặc được nhúng) — grep selector trước, đừng migrate component chết.\n\n## Checklist migrate V1 → V2 (đúc từ 45 lần làm, epic `crm-list-v2`)\n\n- `defaultSearch.set(...)` trong `ngOnInit` → **xoá**, chuyển sang `default: () => ...` (factory) của field tương ứng. `[monthStart, todayStart]` và `[monthStart, todayEnd]` cho ra CÙNG range vì `buildFilterTimestamp` chuẩn hoá end về cuối ngày.\n- `sort.set(...)` nằm trong `searchHandler()` → chuyển lên **constructor**. Để nguyên chỗ cũ thì mỗi lần tải nó đá sort người dùng chọn về mặc định (bug thật ở `ContactList`), và `initialSort` của base cũng sai.\n- Control khai trong `fb.group` nhưng **không có `formControlName` nào trong template** = control chết → không khai def. Grep template trước khi chép cả danh sách control sang `filterFields()`.\n- Field mà BE **không có** `query.ApplyFilter` lẫn `c.Query` → không khai def, gỡ luôn control lọc chết đó (nó đổi URL mà không đổi kết quả — sai âm thầm).\n- BE đọc raw `c.Query(\"\u003Cfield>\")` thay vì `ApplyFilter` → `kind: 'custom'` + `toFilter` trả `matchMode: 'custom'`; tên control phải TRÙNG tên param BE. `buildFilter()` gửi raw `field=value` cho MỌI field có matchMode `'custom'` — bất kể tên có `_` hay không (đã fix 2026-08-04, trước đó chỉ đúng với field bắt đầu bằng `_`).\n- BE nhận **1 ngày** dạng chuỗi `yyyy-MM-dd` (không unix, không khoảng) → `kind: 'dateSingle'`. KHÔNG dùng `kind: 'custom'` cho ca này: `custom` không có đường parse ngược URL→`Date` nên filter ngày sẽ không sống sót qua Back\u002FF5. `dateSingle` format theo **wall-clock cục bộ** của Date (giống `formatDate(d,'yyyy-MM-dd','en-US')` của V1), KHÔNG chuyển timezone lần nữa — `p-datePicker` và `BaseApp.today` đều đã là Date theo giờ cần dùng.\n- 2 bảng khác nhau có thể lưu Unix ở 2 đơn vị khác nhau (vd `log_call.started_at`=ms, `zalo_zns_log.sent_time`=giây) — `kind: 'dateRange'` LUÔN sinh giây. Đọc `comment` của cột trong `dao\u002Fentity.go` TRƯỚC khi khai `dateRange`; cột ms → override `toFilterMeta()` nhân 1000 tại component (KHÔNG dùng `kind:'custom'` — mất khả năng sống qua Back\u002FF5).\n- Response shape khác chuẩn (vd `{sumPoint, object:{items,_meta}}`) → bóc trong `fetchList()`, đừng sửa base.\n- Đổi tên form control thì phải sửa `formControlName` trong template — **`tsc` không bắt được lệch tên**, reactive form chỉ vỡ lúc chạy.\n- Component tự `inject(ActivatedRoute)` vào field `private activatedRoute` → **TS2415** khi lên V2 (\"Types have separate declarations of a private property 'activatedRoute'\") vì `BaseListV2` đã khai field private cùng tên. Đổi tên field local (vd `printTemplateRoute`), **KHÔNG** sửa base. Gặp thật 2 lần: `config-print-template`, `hr\u002Fcertificate`.\n- Lọc cứng theo query param của route (vd `?type=...`, không nằm trong panel filter) → `this.requiredSearch.set({...})`, KHÔNG nhét vào `filterFields()`: `requiredSearch` luôn được gộp vào `searchParams()` và không cho người dùng chỉnh.\n- **Quên `URL_STATE_PREFIX` = tắt URL sync CÂM LẶNG.** Prefix rỗng là giá trị mặc định hợp lệ (dành cho list nhúng) nên `watchUrlNavigation`\u002F`writeUrlState`\u002F`restoreFromUrl` đều return sớm, không một lời cảnh báo: `tsc` xanh, list chạy bình thường, code review \"đạt\" đủ AC — mà FR-1\u002FFR-2 mất trắng. Gặp thật 1\u002F6 list ở epic `care-list-v2` (2026-08-03), agent còn tự khai trong báo cáo là đã đặt. ✅ Cuối mỗi wave, Planner grep đối chiếu **toàn bộ** list vừa migrate: `grep -rn \"URL_STATE_PREFIX = \" src\u002Fapp\u002Fmodules\u002F\u003Cmodule>\u002F` — đếm phải khớp số list *routed*, và list nhúng phải KHÔNG có dòng này. Đừng tin báo cáo của Dev.\n- **Ô lọc không gắn được `formControlName`** (`app-user-select`, `\u003Cinput type=\"month\">`, hay signal mà nghiệp vụ đọc) → dựng giá trị hiển-thị-lại bằng `computed(() => this.initialFilters()['\u003Cfield>']?.value ?? \u003Crỗng>)`, **KHÔNG** sync bằng `control.valueChanges`: base patch\u002Freset form bằng `emitEvent:false` ở `restoreFromUrl()` và `clearFilter()` nên `valueChanges` bỏ lỡ 2 ca đó. Từ 2026-08-04 `wireFilterControls()` cũng cập nhật `initialFilters` nên nó là **gương trung thực của form ở cả 4 đường** (init · người dùng đổi · điều hướng · xoá lọc). Hệ quả kèm theo: field lọc qua `p-columnFilter` (không có trong `filterFields()`) sẽ bị **rơi khỏi `dt.filters`** mỗi lần user đổi filter panel — cần giữ thì phải khai nó thành `FilterFieldDef`.\n- Component tự khai `private activatedRoute = inject(ActivatedRoute)` (vd để đọc deep-link `?user_id=`) sẽ **đụng field `private activatedRoute` của `BaseListV2`** → `TS2415\u002FTS2515` \"incorrectly extends base class... separate declarations of a private property\". Đổi tên field của component (vd `ceActivatedRoute`), **KHÔNG** sửa base. Gặp thật ở `hr\u002Fcertificate\u002Flist` (epic `hr-list-v2`, 2026-08-03); V1 không dính vì `BaseList` không inject `ActivatedRoute`.\n- Control lọc có thể nằm **ngoài** `rfFilterModel`: gọi thẳng `dt.filter(v, '\u003Cfield>', ...)` từ một `[ngModel]` standalone. Quét `dt.filter(` toàn module trước khi chốt danh sách field, đừng chỉ đọc `fb.group` — sót kiểu này làm khảo sát thiếu hẳn 1 filter (`LeaveBalanceList.year`, epic `hr-list-v2`).\n- V1 gọi `this.defaultSearch.set({})` (không phải `.set({field: ...})`) trong 1 hàm `clearXxx()` → đang xoá NHIỀU field cùng lúc (side-effect chéo), không chỉ field trong tên hàm. Migrate 1-1 sang `setFilterValue(field, null)` cho đúng 1 field sẽ thu hẹp phạm vi xoá — đối chiếu kỹ hàm `clearXxx()` V1 xem `defaultSearch`\u002F`search` bị reset bao nhiêu key trước khi migrate.\n- Base trung gian (Component → `MiddleBase` → `BaseListV2`) tự khai method tên `fetchList`\u002F`filterFields`\u002Ftên khác trùng với thành viên mới của `BaseListV2` → phải đổi tên method cũ (vd `fetchApi`) ở TẤT CẢ subclass TRƯỚC khi đổi `MiddleBase` sang `extends BaseListV2`. Không đổi base rồi để subclass \"sửa dần sau\": `ngOnInit` của base đổi hành vi cho MỌI subclass đồng thời — build vẫn xanh nhưng runtime vỡ ngay (bảng bắn request trước khi filter từ URL kịp áp) tới khi từng subclass migrate xong. Gặp thật: `WorkspaceRevenueListBase`\u002F`WorkspaceCommissionListBase`, epic `workspace-list-v2`.\n- `(input)=\"searchKeyword($event)\"` cạnh `formControlName` cùng field = lọc 2 đường (gõ 1 ký tự bắn 2 request) — bug có sẵn nhiều epic, không phải riêng vài list. Gỡ `(input)=...` khi migrate, giữ `formControlName` (base tự debounce). Grep TOÀN module bằng lệnh riêng cho từng file, KHÔNG gộp 1 vòng lặp shell — dễ lỗi quote silent-fail khiến kết luận nhầm \"không dính\" trong khi thực tế 100% list dính (epic `workspace-list-v2`, 14\u002F14).\n- `default:` trong `filterFields()` CHỈ áp lúc mở màn và khi bấm lại mục menu (URL trần). Nút \"Xoá bộ lọc\" (`clearFilter()`) xoá MỌI field về RỖNG, kể cả field có `default` (user chốt 2026-11-01) — đúng hành vi `defaultSearch.set({})` của V1, migrate field \"tháng này\" V1 sang `default:` factory là đủ. Ngoại lệ: field mà BE trả 422 khi thiếu (báo cáo bắt buộc dải ngày + trần 1 năm) → khai `required: true` (bắt buộc kèm `default`, `assertFilterDefs()` chặn) — xoá bộ lọc và URL đã-lọc-thiếu-param trả field đó về `default`. Field nặng khi bỏ ngày nhưng BE không chặn → hỏi user, KHÔNG tự gắn `required`.\n- List nhúng dùng `requiredSearch` (vd theo `customer.id`) — thứ tự gọi `initXxxFilter()` (set `requiredSearch`) trước hay sau `initListV2()` trong `ngOnInit` KHÔNG quyết định request đầu có đủ param: request đầu bắn trong `afterNextRender()` (macrotask, sau khi `ngOnInit` đã chạy xong hoàn toàn), và `requiredSearch` là signal đọc live trong `searchParams`, không bị chụp snapshot. Đặt trước chỉ vì đọc tự nhiên hơn, không phải vì đúng\u002Fsai kỹ thuật — đừng suy diễn thành \"rò dữ liệu chéo\" nếu đặt sau.\n- List có field drill-down ngoài `filterFields()` (đọc\u002Fghi qua route queryParam) mà tự `rfFilterModel.reset(..., {emitEvent:false})` cho field khác trong `filterFields()` → KHÔNG được tự `this.initialFilters.set({}); this.search.set({})` để \"đồng bộ lại\" — 2 dòng đó xoá SẠCH mọi filter kể cả default theo điều kiện (vd `payment_user_id` theo role), và chạy ngay ở lần emit ĐẦU TIÊN (đồng bộ, trong `ngOnInit()`, TRƯỚC `scheduleFirstLoad()` async) nên bug lộ ra NGAY LẦN TẢI TRANG ĐẦU, không cần thao tác gì (epic `sale-list-v2`, user telesale mất filter theo role, thấy khách toàn phòng). Rebuild đúng: chỉ khi field trong `filterFields()` THẬT SỰ đổi, dùng `this.toFilterMeta(def, value)` cho từng field + `this.search.set(this.utilsService.buildFilter(filters))` (cả 2 đều `protected`, gọi được từ subclass) — KHÔNG blank về `{}`.\n- Pattern \"cờ boolean chặn 1 lần fetch kế tiếp\" đặt TRƯỚC `route.navigate()` (async) → phải reset cờ về `false` ngay trong `valueChanges` của MỌI control tự kích điều hướng mới (vd chọn drill-down khác) — Angular Router huỷ navigation đang chờ khi có navigation mới, nên navigation cũ (đã set cờ) có thể KHÔNG BAO GIỜ emit lại để tự tiêu thụ cờ, làm rò rỉ chặn nhầm request hợp lệ kế tiếp (epic `sale-list-v2`, phát hiện qua `\u002Fbmad-review`).\n- Trước khi đổi 1 endpoint list sang phân trang server-side (điều kiện để migrate lên V2), grep HẾT consumer của service\u002Fendpoint đó — không chỉ component đang migrate. Consumer khác có thể cần TOÀN BỘ dữ liệu (vd popup autocomplete tự lọc client-side) và sẽ bị BE mặc định cắt còn `per-page` mặc định (thường 20), mất dữ liệu im lặng không lỗi. Gặp thật: `\u002Fomi\u002Fquick-reply` (`QuickReplyList` cần trang, `OmnichatQuickreplyPopup` cần hết) — fix bằng tham số `?all=1` bỏ qua Paginate (epic `list-v2-final-cleanup`).\n\n## CRITICAL: bảng KHÔNG phân trang thì đừng dùng `searchParams()`\n\n`searchParams()` của base luôn kèm `page`\u002F`sort`\u002F`per-page`. Bảng không có `[rows]`\u002Fpaginator → `dt.rows()` là `undefined` → `per-page=undefined` → BE trả **404** (gặp thật ở `NoteStatistics`).\n\n```ts\n\u002F\u002F Bảng thống kê không phân trang — giữ đúng bộ params V1:\nconst params = { ...this.defaultSearch(), ...this.search(), ...this.requiredSearch() };\nreturn this.modelService.list({ params }).pipe(...);\n```\nQuét nhanh cả module: component `extends BaseListV2` mà template có `\u003Cp-table>` nhưng **không** có `[rows]` → soi lại `fetchList()`.\n\n## p-table full-height (footer\u002Fpaginator dính đáy) — `[appFillHeight]`, KHÔNG `TableLayoutService`\n\n`TableLayoutService.tableNormal()`\u002F`tableDetail()` (breakpoint cứng theo `window.innerWidth`) bind vào `[style]=\"{minHeight\u002FmaxHeight: calc(100vh - Npx)}\"` là cách CŨ, sai khi p-table lồng trong layout riêng của trang (con số breakpoint không trừ đúng phần header\u002Ftoolbar phía trên — bug thật \"treo lơ lửng\" ở `emr\u002Fexamination`, epic `p-table-full-height`). Dùng directive `[appFillHeight]` (`share\u002Fdirective\u002Ffill-height.directive.ts`) thay thế:\n\n```html\n\u003Cp-table appFillHeight [scrollHeight]=\"'flex'\" ...>\n```\n\n- Directive chỉ tự thêm `flex-1 min-h-0` cho CHÍNH `\u003Cp-table>` — KHÔNG tự sửa ancestor. `[scrollHeight]=\"'flex'\"` PHẢI tự khai tường minh (PrimeNG v22 `Table.scrollHeight` là `InputSignal` chỉ đọc, directive không gán được).\n- **Ancestor PHẢI tự lo** — chain flex LIÊN TỤC từ khung bị chặn (viewport\u002Ftab bounded) xuống tận `\u003Cp-table>`, mỗi tầng `display:flex;flex-direction:column;min-height:0`. 2 case thật đã làm:\n  - **Ancestor CÓ SẴN flex-bounded** (`emr\u002Fexamination` — `.cx-workspace`\u002F`.cx-sec-anchor--fill`): không cần `calc()` nào, `appFillHeight` là đủ.\n  - **Ancestor CHỈ CÓ `min-height`, không phải khung chặn thật, VÀ dùng chung giữa nhiều tab** (`customer-detail.html` — `\u003Cp-tabpanels>` PrimeNG chỉ `[style.min-height]`, 11+ tab dùng CHUNG 1 `\u003Cp-tabpanels>`) — **KHÔNG style thẳng element `p-tabpanel`\u002F`p-tabs`\u002F`p-tablist` bằng CSS blanket cho TOÀN BỘ tabpanel** (đã thử, revert 2026-08-07 — xem lịch sử `bmad\u002Fp-table-full-height\u002Fstories\u002Fstory-02-*.md`). 2 lỗi thật khi làm vậy: (1) `p-tabpanel { display:flex }` (author CSS) đè mất `[hidden]{display:none}` (UA stylesheet, author LUÔN thắng UA bất kể specificity) → mọi tabpanel (kể cả tab không active) cùng hiện, chia đều flex-space; (2) tab CHƯA migrate (list thường, cao tự nhiên, có paginator ở cuối) bị kẹp cứng theo `overflow-y:auto` của tabpanel dùng chung → paginator rớt xuống dưới vùng cuộn nội bộ thay vì hiện ngay, khác hẳn hành vi cũ (trang ngoài tự cuộn); (3) riêng tab có `display:grid` layout nhiều cột (vd tab \"Thông tin\" 2 cột) còn bị `p-tabpanel > * { display:flex }` đè mất `display:grid` do specificity `p-tabpanel > *` (0,1,1) cao hơn class `.grid` của Tailwind (0,1,0). **Đúng cách: SCOPE riêng 1 class (`.cx-tabpanel-fill`) cho ĐÚNG `\u003Cp-tabpanel>` đã migrate, KHÔNG đụng `\u003Cp-tabpanels>` gốc hay các `\u003Cp-tabpanel>` khác** — style thẳng element `p-tabpanel`\u002F`p-tablist` CHỈ an toàn khi TOÀN BỘ các tab dùng chung `\u003Cp-tabpanels>` đó đều đã migrate (không còn tab \"tự nhiên\" nào trong nhóm).\n```html\n\u003Cdiv class=\"cx-tabpanel-fill\" [style.--cx-table-detail]=\"tableDetail() + 'px'\">\n  \u003Capp-list-appointment-in-contact class=\"flex-1 min-h-0 flex flex-col\" ...\u002F>\n\u003C\u002Fdiv>\n```\n```scss\n.cx-tabpanel-fill {\n  height: calc(100vh - var(--cx-table-detail, 265px));\n  display: flex;\n  flex-direction: column;\n  overflow: hidden;\n}\n```\n- **KHÔNG áp dụng được** khi 1 tab\u002Fsection có ≥2 khối cạnh tranh chiều cao (vd tab \"orders\" của `examination`: `service-order` + `cls-results` xếp chồng) — ép `flex:1` đồng loạt sẽ vỡ layout (không tự chia được không gian). Cần thiết kế riêng, không dùng `appFillHeight` mù quáng.\n- Ancestor có `overflow-y:auto` riêng (vd `.cx-workspace`) + p-table tự scroll nội bộ (`scrollHeight=\"flex\"`) → 2 lớp scroll chồng nhau, sai số làm tròn dưới-pixel làm thanh cuộn NGOÀI chớp hiện rồi ẩn. Tắt hẳn `overflow` ở ancestor đó khi tab đang active là list full-height (xem `.cx-workspace--fill` trong `examination.scss`).\n- **Cuộn ngoài trang dư vài px SAU KHI đã đo đúng KHÔNG chắc do bảng** — xác nhận bằng cách đo tab\u002Ftrang KHÁC hoàn toàn không đụng gì (`document.scrollingElement.scrollHeight - window.innerHeight`), nếu vẫn dư y hệt thì đó là bug GLOBAL không liên quan p-table. Gặp thật: `src\u002Fassets\u002Foverrides\u002Fcustom.scss` có 2 rule TRÙNG selector `.layout-content-wrapper .layout-content` (padding khác nhau, cả 2 `!important`, rule sau âm thầm thắng) — sửa ở `custom.scss`, KHÔNG cố bù bằng cách co bảng lại (sai chỗ, blast radius sai).\n\n## `appFillHeight=\"page\"` — trang list ROUTED top-level (thay `tableNormal()`)\n\nMode KHÁC với `[appFillHeight]` trần ở trên (đó là cụm `tableDetail()`, p-table NHÚNG trong tab\u002Ftrang\nkhác). Mode `page` dành cho trang list ROUTED TOP-LEVEL trước đây dùng\n`TableLayoutService.tableNormal()` bind `[style]=\"{minHeight\u002FmaxHeight: calc(100vh - tableNormal()px)}\"`\n— cùng lớp lỗi hằng số cứng theo `window.innerWidth`, xác nhận qua đo thật (epic\n`p-table-full-height-list-pages`, 310 file, `bmad\u002Fp-table-full-height-list-pages\u002Fpilot-findings.md`):\n\n```html\n\u003Cp-table appFillHeight=\"page\" [scrollHeight]=\"'flex'\" [style]=\"{ width: '100%' }\" ...>\n```\n\n- Vì sao hằng số sai: **`1rem = 12px` trong app này** (KHÔNG phải 16px mặc định trình duyệt — mọi\n  tính rem phải dựa vào số đo thật, không suy từ 16px), breadcrumb (`flex-wrap: wrap`) có thể xuống\n  2 dòng ở màn hẹp, và mode menu ngang (`_sidebar_horizontal.scss`) đổi `padding-top` của\n  `.layout-content-wrapper` 4rem→7rem — không có 1 hằng số nào đúng cho mọi viewport\u002Fmode.\n- Directive (`share\u002Fdirective\u002Ffill-height.directive.ts`) tự đi ngược DOM từ `\u003Cp-table>` lên\n  `.layout-content-wrapper` (shell dùng chung MỌI route, `AppLayout`), gắn `display:flex;\n  flex-direction:column` cho MỌI tầng trung gian nó đi qua (class `.cx-fill-chain`) + chính wrapper\n  (`.cx-fill-page`) ở `ngAfterViewInit` — **và BẮT BUỘC tự gỡ ở `ngOnDestroy`**. `.layout-content-\n  wrapper` KHÔNG tái tạo khi đổi route (SPA) — không gỡ ⇒ trang KẾ TIẾP (form dài, dashboard) bị\n  khoá `height:100vh` bởi tính năng của trang TRƯỚC, cắt cụt nội dung mà không có lỗi console nào.\n- **Gate chống \"quên import\" — BẮT BUỘC chạy, KHÔNG có gate build nào khác bắt được lỗi này**:\n  `appFillHeight=\"page\"` là attribute TĨNH, không phải `[appFillHeight]=\"'page'\"`. Thiếu\n  `FillHeightDirective` trong `imports: [...]` của `@Component` ⇒ Angular bỏ qua attribute lạ CÂM\n  LẶNG — đã đo thực nghiệm: `tsc --noEmit`\u002F`ngc --noEmit`\u002F`ng build` đều KHÔNG lệch 1 lỗi nào. Chạy\n  `frontend\u002Fscripts\u002Fverify-fill-height-page.sh` sau MỌI lần thêm\u002Fsửa `appFillHeight=\"page\"`.\n- 12 file có ≥2 `\u003Cp-table>` trong cùng host — soi tay TRƯỚC khi áp mặc định (11\u002F12 trường hợp thật\n  ở epic này là bảng thứ 2 lồng trong `\u003Cng-template #expandedrow>` — PrimeNG row-expansion, KHÔNG\n  cạnh tranh chiều cao, áp `appFillHeight=\"page\"` cho bảng NGOÀI bình thường; chỉ 1\u002F12 là 3 bảng\n  cạnh nhau thật trong `\u003Cp-tabs>`, xem 2 gotcha dưới).\n- **Directive KHÔNG chỉ dùng cho `\u003Cp-table>`** — `[appFillHeight]` là generic (`Renderer2` thao tác\n  `ElementRef` bất kỳ). Trang dùng `\u003Cdiv [style]=\"{height:calc(...)}}\">` bọc cả report\u002Fform (KHÔNG\n  có `\u003Cp-table>` nào) vẫn áp được y hệt, chỉ bỏ `[scrollHeight]=\"'flex'\"` (thuộc tính riêng\n  `p-table`). Đừng kết luận \"không áp dụng được\" chỉ vì file không có `\u003Cp-table>`.\n- **Ancestor đã tự là flex-row hoặc CSS Grid** (PrimeFlex `.grid` — `display:flex;flex-wrap:wrap`,\n  dùng cho layout 2+ CỘT CẠNH NHAU; hoặc Tailwind `.grid`\u002F`grid-cols-*` — CSS Grid thật, dùng cho\n  layout lưới nhiều cột như `emr\u002Fexamination` cấp trang): directive TỰ đo `getComputedStyle(node)\n  .display` trước khi quyết định — ancestor đã là `flex`\u002F`inline-flex`\u002F`grid`\u002F`inline-grid` thì CHỈ\n  thêm sizing (`cx-fill-chain`), KHÔNG ép `flex-direction:column` (`cx-fill-chain-stack`) đè lên,\n  tránh phá layout ngang\u002Flưới đang có. **Bẫy đặt tên trùng**: PrimeFlex và Tailwind CÙNG định nghĩa\n  class tên `.grid` với Ý NGHĨA KHÁC NHAU (PrimeFlex: `display:flex`; Tailwind: `display:grid`) —\n  đo `getComputedStyle` thật để biết cái nào đang thắng trong file cụ thể, ĐỪNG suy từ tên class.\n- **Ancestor có thể mang attribute `hidden`** (PrimeNG `\u003Cp-tabpanel [hidden]=\"!active()\">`, xem\n  `node_modules\u002Fprimeng\u002F...\u002Fprimeng-tabs.mjs`): CSS tác giả LUÔN thắng UA stylesheet với declaration\n  thường (không `!important`) BẤT KỂ specificity — set `display:flex` không điều kiện sẽ làm tab đã\n  ẩn vẫn hiện đè (bug thật đã phải revert 2026-08-07). 2 class CSS đều guard `:not([hidden])` trong\n  `_content.scss` — ancestor `[hidden]` thì không rule author nào khớp, UA `[hidden]{display:none}`\n  áp dụng bình thường. Áp dụng được cho MỌI `\u003Cp-tabpanel>` chứa `appFillHeight=\"page\"`, không cần xử\n  lý riêng từng file.\n\n## Giới hạn đã biết\n\n- Lối vào DUY NHẤT của một hành động (nút \"Chi tiết\", link mở panel) đặt trong `@if (isColVisible('x')())` sẽ biến mất hẳn khi `x` không nằm trong `selectedColumns` mặc định — build xanh, không lỗi. Trước khi neo nút vào cột nào: đối chiếu `selectedColumns` của CHÍNH list đó; cột có mặt ở mọi list là tên khách hàng.\n- Filter đặt ở header cột (`p-columnFilter`) vẫn lọc nhưng KHÔNG lên URL — cần giữ qua URL thì khai thành `FilterFieldDef` trong panel.\n- Mũi tên sort trên header không sáng lại sau khôi phục (sort vẫn đúng); bind `[sortField]` trên bảng lazy đẻ thêm request lúc init.\n- URL nội bộ của router lệch thanh địa chỉ (hệ quả của `replaceState`) — chỗ nào so URL đầy đủ cần biết điều này.\n\n\n\n---\n\n## 1. `BaseDetail\u003CT>` — single record view (routed)\n\n**File:** `src\u002Fapp\u002Fshare\u002Fbase\u002Fbase-detail.ts`\n**Pattern:** extend + inject modelService + override `afterModelLoaded` nếu cần\n\n```typescript\nexport class CustomerDetail extends BaseDetail\u003CCustomerModel> implements OnInit {\n    modelService = inject(CustomerService);\n\n    ngOnInit() {\n        \u002F\u002F BaseDetail tự đọc route param :id + gọi modelService.get(id)\n        super.ngOnInit();\n    }\n\n    \u002F\u002F Override hook\n    override afterModelLoaded(model: CustomerModel): void {\n        this.title.setTitle(model.fullname);\n    }\n}\n```\n\nTemplate: `{{ model().fullname }}`, `{{ model().phone }}`, etc.\n\n---\n\n## 2. `BaseReport\u003CT>` — report với export Excel\n\n**File:** `src\u002Fapp\u002Fshare\u002Fbase\u002Fbase-report.ts`\n**Pattern:** extend + implement 3 abstract members\n\n```typescript\nexport class RevenueReport extends BaseReport\u003CRevenueItem> implements OnInit {\n    modelService = inject(RevenueService);\n\n    \u002F\u002F BẮT BUỘC implement\n    rfFilter = this.fb.group({\n        dateFrom: [this.timezoneService.monthStartDate()],\n        dateTo: [this.timezoneService.todayDate()],\n    });\n\n    fetchData(): Observable\u003Cany> {\n        return this.modelService.getRevenue({ params: this.searchParams() });\n    }\n\n    fetchExport(): Observable\u003Cstring> {\n        return this.modelService.exportRevenue({ params: this.searchParams() });\n    }\n}\n```\n\nBaseReport tự handle: `loadReport()`, `exportExcel()`, pagination, quick date select, keyword search.\n\n`rfFilter` phải là single source of truth: → Xem `frontend\u002Fskill\u002Fskills\u002Ffrontend-hard-rules\u002FSKILL.md` B.16.\n\n---\n\n## 3. `BasePrint` — print pages\n\n**File:** `src\u002Fapp\u002Fshare\u002Fbase\u002Fbase-print.ts`\n**@Injectable** — KHÔNG phải @Directive, KHÔNG extend BaseApp.\n\n```typescript\nexport class PrintXxx extends BasePrint implements OnInit {\n    \u002F\u002F KHÔNG có sẵn BaseApp services — inject thủ công nếu cần\n    modelService = inject(XxxService);\n    private destroyRef = inject(DestroyRef);\n\n    ngOnInit(): void {\n        \u002F\u002F Pattern chuẩn: tryLoadFromCache → API fallback\n        this.activatedRoute.params\n            .pipe(takeUntilDestroyed(this.destroyRef))\n            .subscribe((params: any) => {\n                const cacheKey = this.activatedRoute.snapshot.queryParams['cacheKey'];\n                const cached = this.tryLoadFromCache(cacheKey);\n                if (cached) { this.applyData(cached); return; }\n                this.modelService.getXxx(params.id).subscribe((d) => this.applyData(d));\n            });\n    }\n\n    applyData(data: any): void {\n        this.model.set(data);\n        this.printData.setModel({ company: ..., layoutType: ... });\n        setTimeout(() => void this.handlePrintAfterInit());\n    }\n}\n```\n\n→ Xem `fe-print.md` cho toàn bộ print flow.\n\n\n## ExportOptionsDialog (reusable)\n\n**File:** `src\u002Fapp\u002Fmodules\u002Futilities\u002Fexport-options-dialog\u002Fexport-options-dialog.ts`\n\nMở trước khi gọi API export, cho user chọn:\n- `'selected'` — chỉ export cột đang bật trong `selectedColumns`\n- `'all'` — export toàn bộ cột\n\n```typescript\n\u002F\u002F Trong component có export:\nimport { ExportOptionsDialog, ExportMode } from '@\u002Fmodules\u002Futilities\u002Fexport-options-dialog\u002Fexport-options-dialog';\n\nexportExcel() {\n  const ref = this.dialogWrapperService.open(ExportOptionsDialog, {\n    header: this.translate.instant('utilities.export_options_dialog.header'),\n    width: '480px',\n    data: {\n      selectedCount: this.selectedColumns().length,\n      totalCount: this.displayCols.length,   \u002F\u002F tổng cột trong availableColumns\u002FdisplayCols\n    },\n  });\n\n  ref.onClose.subscribe((mode: ExportMode | null) => {\n    if (!mode) return;\n    const params: any = { ...this.searchParams() };\n    if (mode === 'selected') {\n      params['columns'] = this.selectedColumns().join(',');\n    }\n    \u002F\u002F gọi API export với params\n  });\n}\n```\n\n**i18n keys** (đã có đủ 4 locale): `utilities.export_options_dialog.header\u002Fselected_label\u002Fselected_desc\u002Fall_label\u002Fall_desc`\n\n---\n\n## BE — colDef pattern cho export có column filter\n\nKhi BE cần support `?columns=...` param, dùng `colDef` slice thay vì hardcode headers\u002Fmapper.\n\n**Xem pattern đầy đủ:** `(repo cha) ..\u002Fskill\u002Fskills\u002Fworking-on-ops\u002Freference\u002Fexport.md § colDef pattern`\n\n---\n\n## Quy tắc áp dụng\n\n- `displayCols` (array tất cả cột) và `selectedColumns` (signal) phải có cùng `value` key với BE `colDef[i].key`\n- `mode === 'all'` → KHÔNG gửi `columns` param → BE fallback export all\n- `mode === 'selected'` → gửi `columns=val1,val2,...` → BE filter theo thứ tự `colDef`\n- Default mode trong dialog = `'selected'` (UX: user thường muốn export những gì đang thấy)\n- **Param export LUÔN lấy từ `this.exportParams()` của `BaseListV2` — KHÔNG tự dựng lại** (bug 2026-08-13, dính 58 màn):\n\n  ```ts\n  \u002F\u002F ĐÚNG\n  const params = {...this.exportParams()} as any;\n  \u002F\u002F SAI — thiếu `sort`, file export ra thứ tự khác bảng user đang nhìn\n  const params = {...this.defaultSearch(), ...this.search(), ...this.requiredSearch()} as any;\n  ```\n\n  Lý do: BE dùng CHUNG một query cho list và export (nhánh `_export=1` nằm trong list handler), thiếu `sort` là BE rơi về defaultOrder (thường `id DESC`). `exportParams()` = `searchParams()` bỏ `page`\u002F`per-page` (export lấy trọn kết quả) nhưng giữ `sort`.\n  Kiểm tra kèm: cột cho `pSortableColumn` phải là cột DB thật có trong whitelist `ApplySort` của handler BE — sort cột hiển thị\u002Ftính toán (vd `appointment_time` chỉ là format của `appointment_date`) thì BE reject âm thầm, list và export đều không sort được như user tưởng.\n","# Building list and export views\n\n> Print flow chi tiết (PrintLayout, PrintContext, window.print() gotchas): `reference\u002Ffe-print.md`\n> Import\u002FExport Excel chi tiết: `reference\u002Ffe-patterns-import-export.md`\n> Gotchas Search\u002FAutoComplete\u002FList display: `reference\u002Ffe-patterns-gotchas-search.md`\n> Khuôn `.ts` + `.html` cho list config mới (toolbar lọc, bộ chọn cột, cột thao tác cố định): `reference\u002Ffe-list-config-template.md`\n\n\n\nDùng cho list mới, hoặc list cần giữ filter khi bấm vào bản ghi → xem chi tiết → Back.\n`BaseList` (V1) giữ nguyên — KHÔNG migrate hàng loạt, chuyển từng list khi có nhu cầu.\n\n## Bật V2\n\n```ts\nexport class XxxList extends BaseListV2\u003CXxxModel> implements OnInit {\n  @ViewChild('dt') dt!: Table\u003CXxxModel>;\n  protected override URL_STATE_PREFIX = 'xx';   \u002F\u002F 2–3 ký tự, khác nhau giữa 2 list cùng 1 route\n  protected filterFields(): FilterFieldDef[] { return [ \u002F* ... *\u002F ]; }\n  ngOnInit() { this.initListV2(); }\n}\n```\n\n```html\n\u003Cp-table #dt [lazy]=\"true\" [lazyLoadOnInit]=\"false\" (onLazyLoad)=\"loadRecords($event)\"\n         [filters]=\"initialFilters()\" [first]=\"first()\" [loading]=\"showSkeleton()\" [filterDelay]=\"0\">\n  \u003Cng-template #caption>\n    \u003Cdiv class=\"h-[2px] mb-1\">\n      @if (refreshing()) { \u003Cp-progressbar [showValue]=\"false\" [style]=\"{height:'2px'}\" mode=\"indeterminate\"\u002F> }\n    \u003C\u002Fdiv>\n```\n\n- 5 binding bắt buộc: `[lazyLoadOnInit]=\"false\"` · `[filters]` · `[first]` · `[loading]=\"showSkeleton()\"` · `[filterDelay]=\"0\"`.\n- Thanh báo tải lại đặt trong hộp cao cố định (`h-[2px]`) — tự nó không được gây CLS.\n- KHÔNG override `initFilter()`, `getDefaultFilterValues()`, `clearFilter()`, `searchHandler()` — base lo hết.\n\n## filterFields()\n\n- 1 field = 1 dòng: `{name, kind, default?, urlKey?, debounce?, itemType?, toFilter?, urlSync?}`.\n- `kind`: `text` (contains) · `in` (multiselect, LUÔN mảng) · `equals` (select 1, LUÔN scalar) · `dateRange` (between, cặp unix) · `dateSingle` (chọn 1 ngày, gửi BE chuỗi `yyyy-MM-dd`, matchMode mặc định `custom`) · `monthDayRange` (khoảng ngày-tháng KHÔNG năm, between, cặp chuỗi `MM-DD` — vd lọc sinh nhật) · `dateRangeSplit` (khoảng ngày mà BE đọc bằng **2 param tên riêng**, vd `_dueDateGte`\u002F`_dueDateLte`) · `custom` (tự lo qua `toFilter`).\n- BE nhận **khoảng ngày-tháng không năm** (`MM-DD`, vd `birthday_md`) → `kind: 'monthDayRange'`. KHÔNG dùng `custom`: `custom` không parse ngược URL→`Date` nên filter không sống sót qua Back\u002FF5 (cùng bài học với `dateSingle`). Ngày chỉ tồn tại ở năm nhuận (`02-29`) được giữ bằng cách lùi về năm nhuận cố định — panel lịch sẽ hiện năm đó, ô input `dateFormat=\"dd\u002Fmm\"` không lộ.\n- BE nhận khoảng ngày qua **2 tên param khác nhau** (không phải 1 param `[gte]\u002F[lte]`) → `kind: 'dateRangeSplit'` (accountant 2026-08-04, `InstallmentDebts._dueDateGte`\u002F`_dueDateLte`). Một `FilterMetadata` chỉ sinh được 1 tên param nên base **không sinh gì** (`toFilterMeta` trả `null`) — chỉ lo FormControl + URL sync; component tự ghép 2 param trong `fetchList()`. Nhờ vậy filter này **sống sót qua Back\u002FF5**, khác hẳn cách cũ (`custom` + `urlSync:false`) không làm được.\n- Select chọn-một: template KHÔNG `[multiple]`, PHẢI `[showClear]=\"true\"` (thiếu → không xoá được filter), def `kind: 'equals'`.\n- **`p-datepicker` filter với `(onClear)=\"clearXxx()\"` — PHẢI có `[showClear]=\"true\"` trên CÙNG thẻ, nếu không handler CÂM LẶNG mãi mãi** (PrimeNG v22: `clearIconEnabled = showClear() && !disabled()`, mặc định `showClear=false` → icon xoá không bao giờ render → `clear()` không ai gọi được → `onClear.emit` không bao giờ chạy). Không phải lỗi cú pháp, `tsc`\u002F`ng build` đều sạch — chỉ lộ ra khi bấm thật trên UI. Đo được ở accountant: 70\u002F71 chỗ dính lỗi này từ trước khi có epic migrate.\n- `default` phụ thuộc thời điểm → truyền factory: `default: () => [this.timezoneService.todayStart(), this.timezoneService.todayEnd()]`.\n- Sentinel\u002Fluật riêng → `toFilter`, vd `revenue_id` id=0 nghĩa là chưa có → `{value: '1', matchMode: 'is'}`.\n- `urlKey` bỏ trống = tự suy: bỏ `_` đầu + camelCase→snake_case (`_groupLocal`→`group_local`, `customerType`→`customer_type`). Chỉ khai khi muốn khác quy ước (`appointment_date`→`date`) hoặc khi bị trùng (`_status` vs `status`).\n- Control tên có ký tự `[`\u002F`]` (kind `'custom'`, BE đọc raw `c.Query(\"field[x]\")`) → BẮT BUỘC khai `urlKey` tường minh (vd `urlKey:'status'`) — mặc định giữ nguyên ký tự lạ, `URLSearchParams` percent-encode thành `%5B%5D` trên address bar (round-trip đúng, chỉ xấu URL). `assertFilterDefs()` không chặn được ca này.\n- `assertFilterDefs()` ném lỗi lúc mở trang (dev) khi trùng `name`, trùng urlKey, hoặc đụng khoá dành riêng `_f`\u002F`_page`\u002F`_size`\u002F`_sort`.\n- Lọc từ code: `this.setFilterValue(name, value)` — KHÔNG `patchValue()` + `resetPage()` (đẻ 2 request).\n- Field BE chưa có `query.ApplyFilter` thì KHÔNG khai def và KHÔNG để nút bấm lọc — nút sẽ đổi URL mà kết quả không đổi (sai âm thầm).\n- `kind: 'text'` value đi thẳng vào query string GET, KHÔNG giới hạn độ dài mặc định — gõ\u002Fpaste vài nghìn ký tự làm request vượt giới hạn dòng request của backend\u002Fproxy → HTTP 414, list trắng im lặng. Base đã tự chặn ở `MAX_TEXT_FILTER_LENGTH = 200` (`list-filter.model.ts`) — mọi `kind:'text'` tự cắt còn 200 ký tự + toast cảnh báo (`base-list-v2.ts` `wireFilterControls()`), áp dụng mọi list dùng `BaseListV2`, không cần khai gì thêm.\n\n## State trên URL\n\n- Param phẳng, không mang matchMode: `?ap_f=1&ap_date=1785690000,1785776399&ap_status=1&ap_page=2`.\n- `ap_f=1` = cờ \"URL đang giữ state\": có cờ → URL là nguồn sự thật, param vắng mặt = người dùng đã xoá filter đó; không cờ → dùng default.\n- Ghi URL bằng `Location.replaceState`, **KHÔNG** `router.navigate` — navigate chạy trọn chu kỳ điều hướng (ActivationEnd ×N + Scroll) làm `p-table` vẽ lại đè lên popover filter đang mở.\n- Query dựng từ `location.path()`, chỉ `set`\u002F`delete` key mình sở hữu — KHÔNG `createUrlTree({queryParamsHandling: 'merge'})`; `replaceState` không báo cho router nên cây URL của router luôn cũ.\n- Trả `%2C` → `,` sau `URLSearchParams.toString()`.\n- Đồng bộ lại khi điều hướng: nghe `NavigationEnd` **và `NavigationSkipped`** — bấm lại chính menu đang đứng thì router skip, `queryParams` KHÔNG phát. Đọc state từ `e.url`, KHÔNG từ `activatedRoute.snapshot` (skip không cập nhật snapshot).\n- Khi đồng bộ lại phải gán LUÔN `page`\u002F`per-page`\u002F`sort` (param vắng = về mặc định), KHÔNG gán theo `if (page > 1)`.\n- `writeUrlState()` gọi trong `setTimeout` + guard cờ `destroyed` — router commit URL ở cuối chu kỳ, và component có thể đã huỷ trong khoảng đó.\n- Chặn theo path (`e.url` vs path lúc init) trước khi xử — không ghi đè URL của trang khác.\n\n## Tải dữ liệu\n\n- Override `fetchList()` trả `Observable\u003CListApiResponse\u003CT>>`; KHÔNG override `searchHandler`, KHÔNG tự set `loading`\u002F`models`\u002F`paginationInfo`.\n- Base đẩy mọi lần tải qua `Subject + switchMap` → huỷ request cũ, hết cảnh response cũ về sau ghi đè kết quả mới.\n- `getList()` KHÔNG xoá `models` (stale-while-revalidate). Skeleton chỉ ở lần tải đầu (`showSkeleton` = `loading && !loadedOnce`); các lần sau dùng `refreshing`.\n- List có `#loadingbody` dùng `colsIt()` PHẢI gán `effect(() => this.padCols.set(this.selectedColumns().length + \u003Csố cột luôn hiện>))` trong constructor — `padCols` mặc định 0 ⇒ hàng skeleton không có `\u003Ctd>` nào, `tsc`\u002F`ngc` không bắt.\n- Endpoint không theo convention `filter[field][matchMode]` (vd query phẳng riêng) → vẫn khai `filterFields()` bình thường (để có URL state + wiring), nhưng `fetchList()` đọc thẳng `rfFilterModel.getRawValue()` và tự dựng param như V1 — KHÔNG dùng `searchParams()`. Ghi comment tại chỗ giải thích lý do, kẻo người sau \"dọn\" nhầm về `searchParams()`.\n- List có field tổng\u002Fside-effect ngoài `items`\u002F`_meta` gán trong `fetchList()` (vd `total`\u002F`discount` hiển thị footer) → PHẢI tự thêm sequence guard (`private xxFetchSeq = 0`, tăng ở đầu `fetchList()`, chỉ gán khi `seq === this.xxFetchSeq` lúc response về) nếu paginator\u002Fsort không debounce — `wireReloadPipeline` (base) chỉ huỷ được việc GIAO `models`\u002F`paginationInfo` cho request cũ, KHÔNG huỷ side-effect tự viết chạy trong thân `switchMap(async...)` của chính `fetchList()`.\n- `effect()` re-tính state \"theo trang mới\" (vd cơ chế chọn-dòng tự viết cần `currentPageItems` khớp trang hiện tại) phải watch `this.paginationInfo()`, KHÔNG watch `this.models()` — `models` còn bị mutate NGOÀI luồng fetch bởi `updateRow()` (base, dùng khi cập nhật 1 dòng tại chỗ vd toggle status), `paginationInfo` chỉ đổi khi có fetch thật.\n- List nhúng nhận `@Input customer` từ parent có `model()` khởi tạo rỗng-nhưng-truthy (vd `customer-detail.ts` dùng `signal({} as T)`) → `fetchList()` có thể chạy với `customer.id === undefined` lúc parent chưa load xong HTTP, rõ nhất khi Back\u002FForward remount toàn trang (không phải chỉ đổi tab). Guard đầu `fetchList()`: `if (!this.customer?.id) return this.emptyListResult();` — helper có sẵn trên `BaseListV2`, trả `{items:[], _meta:{totalCount:0}}` hợp lệ (không phải lỗi); `ngOnChanges` sẵn có sẽ tự refetch khi customer load xong. Cùng lý do gây interceptor văng cả app nếu BE endpoint coi id rỗng là 404 — xem `frontend\u002Fskill\u002Fskills\u002Fworking-on-fe-modules\u002Freference\u002Ffe-patterns-gotchas.md`.\n\n## Gotcha PrimeNG v22\n\n- Input `[filters]` đồng bộ vào `dt.filters` qua `effect()` → chạy SAU `ngOnInit` của bảng, tức sau lần `onLazyLoad` đầu tiên. Bảng tự bắn thì request đầu đi với filter RỖNG → bắt buộc `[lazyLoadOnInit]=\"false\"`, base tự bắn trong `afterNextRender`.\n- `filterDelay` mặc định đã là 300 → gỡ binding vô ích, phải `[filterDelay]=\"0\"` (base đã debounce 300\u002F500ms).\n- `p-select [multiple]=\"true\"` trông y hệt dropdown chọn-một (không checkbox, không chip) — dễ tưởng single trong khi nó cộng dồn.\n- Control inline trong `p-table` (`p-toggleswitch`, checkbox) bind `[ngModel]` một chiều **KHÔNG tự quay lại giá trị cũ khi API lỗi**: control ghi thẳng vào state nội bộ lúc bấm, Angular chỉ `writeValue` khi giá trị binding ĐỔI, và `rowTrackBy` mặc định track theo THAM CHIẾU dòng → tạo mảng mới mà giữ nguyên reference từng dòng thì view được tái dùng, không revert. Revert đúng = **thay reference dòng**: `models.update(rows => rows.map(r => r.id === id ? {...r, status: cũ} : r))`, kèm set lạc quan trước khi gọi API.\n\n## Điều kiện đủ để migrate 1 list sang V2\n\nKiểm 3 thứ TRƯỚC khi bắt tay, thiếu bất kỳ cái nào thì **giữ nguyên V1**:\n- Template có `\u003Cp-table>` **và** `[lazy]=\"true\"` — mọi giá trị của V2 (URL state, SWR, huỷ request cũ) đi qua `onLazyLoad` → `loadRecords()`. Bảng không lazy thì V2 chỉ đổi base class, không được gì.\n- Có `@ViewChild('dt')` (thiếu thì thêm — `BaseListV2` khai `abstract dt`).\n- Component có nơi dùng thật (route hoặc được nhúng) — grep selector trước, đừng migrate component chết.\n\n## Checklist migrate V1 → V2 (đúc từ 45 lần làm, epic `crm-list-v2`)\n\n- `defaultSearch.set(...)` trong `ngOnInit` → **xoá**, chuyển sang `default: () => ...` (factory) của field tương ứng. `[monthStart, todayStart]` và `[monthStart, todayEnd]` cho ra CÙNG range vì `buildFilterTimestamp` chuẩn hoá end về cuối ngày.\n- `sort.set(...)` nằm trong `searchHandler()` → chuyển lên **constructor**. Để nguyên chỗ cũ thì mỗi lần tải nó đá sort người dùng chọn về mặc định (bug thật ở `ContactList`), và `initialSort` của base cũng sai.\n- Control khai trong `fb.group` nhưng **không có `formControlName` nào trong template** = control chết → không khai def. Grep template trước khi chép cả danh sách control sang `filterFields()`.\n- Field mà BE **không có** `query.ApplyFilter` lẫn `c.Query` → không khai def, gỡ luôn control lọc chết đó (nó đổi URL mà không đổi kết quả — sai âm thầm).\n- BE đọc raw `c.Query(\"\u003Cfield>\")` thay vì `ApplyFilter` → `kind: 'custom'` + `toFilter` trả `matchMode: 'custom'`; tên control phải TRÙNG tên param BE. `buildFilter()` gửi raw `field=value` cho MỌI field có matchMode `'custom'` — bất kể tên có `_` hay không (đã fix 2026-08-04, trước đó chỉ đúng với field bắt đầu bằng `_`).\n- BE nhận **1 ngày** dạng chuỗi `yyyy-MM-dd` (không unix, không khoảng) → `kind: 'dateSingle'`. KHÔNG dùng `kind: 'custom'` cho ca này: `custom` không có đường parse ngược URL→`Date` nên filter ngày sẽ không sống sót qua Back\u002FF5. `dateSingle` format theo **wall-clock cục bộ** của Date (giống `formatDate(d,'yyyy-MM-dd','en-US')` của V1), KHÔNG chuyển timezone lần nữa — `p-datePicker` và `BaseApp.today` đều đã là Date theo giờ cần dùng.\n- 2 bảng khác nhau có thể lưu Unix ở 2 đơn vị khác nhau (vd `log_call.started_at`=ms, `zalo_zns_log.sent_time`=giây) — `kind: 'dateRange'` LUÔN sinh giây. Đọc `comment` của cột trong `dao\u002Fentity.go` TRƯỚC khi khai `dateRange`; cột ms → override `toFilterMeta()` nhân 1000 tại component (KHÔNG dùng `kind:'custom'` — mất khả năng sống qua Back\u002FF5).\n- Response shape khác chuẩn (vd `{sumPoint, object:{items,_meta}}`) → bóc trong `fetchList()`, đừng sửa base.\n- Đổi tên form control thì phải sửa `formControlName` trong template — **`tsc` không bắt được lệch tên**, reactive form chỉ vỡ lúc chạy.\n- Component tự `inject(ActivatedRoute)` vào field `private activatedRoute` → **TS2415** khi lên V2 (\"Types have separate declarations of a private property 'activatedRoute'\") vì `BaseListV2` đã khai field private cùng tên. Đổi tên field local (vd `printTemplateRoute`), **KHÔNG** sửa base. Gặp thật 2 lần: `config-print-template`, `hr\u002Fcertificate`.\n- Lọc cứng theo query param của route (vd `?type=...`, không nằm trong panel filter) → `this.requiredSearch.set({...})`, KHÔNG nhét vào `filterFields()`: `requiredSearch` luôn được gộp vào `searchParams()` và không cho người dùng chỉnh.\n- **Quên `URL_STATE_PREFIX` = tắt URL sync CÂM LẶNG.** Prefix rỗng là giá trị mặc định hợp lệ (dành cho list nhúng) nên `watchUrlNavigation`\u002F`writeUrlState`\u002F`restoreFromUrl` đều return sớm, không một lời cảnh báo: `tsc` xanh, list chạy bình thường, code review \"đạt\" đủ AC — mà FR-1\u002FFR-2 mất trắng. Gặp thật 1\u002F6 list ở epic `care-list-v2` (2026-08-03), agent còn tự khai trong báo cáo là đã đặt. ✅ Cuối mỗi wave, Planner grep đối chiếu **toàn bộ** list vừa migrate: `grep -rn \"URL_STATE_PREFIX = \" src\u002Fapp\u002Fmodules\u002F\u003Cmodule>\u002F` — đếm phải khớp số list *routed*, và list nhúng phải KHÔNG có dòng này. Đừng tin báo cáo của Dev.\n- **Ô lọc không gắn được `formControlName`** (`app-user-select`, `\u003Cinput type=\"month\">`, hay signal mà nghiệp vụ đọc) → dựng giá trị hiển-thị-lại bằng `computed(() => this.initialFilters()['\u003Cfield>']?.value ?? \u003Crỗng>)`, **KHÔNG** sync bằng `control.valueChanges`: base patch\u002Freset form bằng `emitEvent:false` ở `restoreFromUrl()` và `clearFilter()` nên `valueChanges` bỏ lỡ 2 ca đó. Từ 2026-08-04 `wireFilterControls()` cũng cập nhật `initialFilters` nên nó là **gương trung thực của form ở cả 4 đường** (init · người dùng đổi · điều hướng · xoá lọc). Hệ quả kèm theo: field lọc qua `p-columnFilter` (không có trong `filterFields()`) sẽ bị **rơi khỏi `dt.filters`** mỗi lần user đổi filter panel — cần giữ thì phải khai nó thành `FilterFieldDef`.\n- Component tự khai `private activatedRoute = inject(ActivatedRoute)` (vd để đọc deep-link `?user_id=`) sẽ **đụng field `private activatedRoute` của `BaseListV2`** → `TS2415\u002FTS2515` \"incorrectly extends base class... separate declarations of a private property\". Đổi tên field của component (vd `ceActivatedRoute`), **KHÔNG** sửa base. Gặp thật ở `hr\u002Fcertificate\u002Flist` (epic `hr-list-v2`, 2026-08-03); V1 không dính vì `BaseList` không inject `ActivatedRoute`.\n- Control lọc có thể nằm **ngoài** `rfFilterModel`: gọi thẳng `dt.filter(v, '\u003Cfield>', ...)` từ một `[ngModel]` standalone. Quét `dt.filter(` toàn module trước khi chốt danh sách field, đừng chỉ đọc `fb.group` — sót kiểu này làm khảo sát thiếu hẳn 1 filter (`LeaveBalanceList.year`, epic `hr-list-v2`).\n- V1 gọi `this.defaultSearch.set({})` (không phải `.set({field: ...})`) trong 1 hàm `clearXxx()` → đang xoá NHIỀU field cùng lúc (side-effect chéo), không chỉ field trong tên hàm. Migrate 1-1 sang `setFilterValue(field, null)` cho đúng 1 field sẽ thu hẹp phạm vi xoá — đối chiếu kỹ hàm `clearXxx()` V1 xem `defaultSearch`\u002F`search` bị reset bao nhiêu key trước khi migrate.\n- Base trung gian (Component → `MiddleBase` → `BaseListV2`) tự khai method tên `fetchList`\u002F`filterFields`\u002Ftên khác trùng với thành viên mới của `BaseListV2` → phải đổi tên method cũ (vd `fetchApi`) ở TẤT CẢ subclass TRƯỚC khi đổi `MiddleBase` sang `extends BaseListV2`. Không đổi base rồi để subclass \"sửa dần sau\": `ngOnInit` của base đổi hành vi cho MỌI subclass đồng thời — build vẫn xanh nhưng runtime vỡ ngay (bảng bắn request trước khi filter từ URL kịp áp) tới khi từng subclass migrate xong. Gặp thật: `WorkspaceRevenueListBase`\u002F`WorkspaceCommissionListBase`, epic `workspace-list-v2`.\n- `(input)=\"searchKeyword($event)\"` cạnh `formControlName` cùng field = lọc 2 đường (gõ 1 ký tự bắn 2 request) — bug có sẵn nhiều epic, không phải riêng vài list. Gỡ `(input)=...` khi migrate, giữ `formControlName` (base tự debounce). Grep TOÀN module bằng lệnh riêng cho từng file, KHÔNG gộp 1 vòng lặp shell — dễ lỗi quote silent-fail khiến kết luận nhầm \"không dính\" trong khi thực tế 100% list dính (epic `workspace-list-v2`, 14\u002F14).\n- `default:` trong `filterFields()` CHỈ áp lúc mở màn và khi bấm lại mục menu (URL trần). Nút \"Xoá bộ lọc\" (`clearFilter()`) xoá MỌI field về RỖNG, kể cả field có `default` (user chốt 2026-11-01) — đúng hành vi `defaultSearch.set({})` của V1, migrate field \"tháng này\" V1 sang `default:` factory là đủ. Ngoại lệ: field mà BE trả 422 khi thiếu (báo cáo bắt buộc dải ngày + trần 1 năm) → khai `required: true` (bắt buộc kèm `default`, `assertFilterDefs()` chặn) — xoá bộ lọc và URL đã-lọc-thiếu-param trả field đó về `default`. Field nặng khi bỏ ngày nhưng BE không chặn → hỏi user, KHÔNG tự gắn `required`.\n- List nhúng dùng `requiredSearch` (vd theo `customer.id`) — thứ tự gọi `initXxxFilter()` (set `requiredSearch`) trước hay sau `initListV2()` trong `ngOnInit` KHÔNG quyết định request đầu có đủ param: request đầu bắn trong `afterNextRender()` (macrotask, sau khi `ngOnInit` đã chạy xong hoàn toàn), và `requiredSearch` là signal đọc live trong `searchParams`, không bị chụp snapshot. Đặt trước chỉ vì đọc tự nhiên hơn, không phải vì đúng\u002Fsai kỹ thuật — đừng suy diễn thành \"rò dữ liệu chéo\" nếu đặt sau.\n- List có field drill-down ngoài `filterFields()` (đọc\u002Fghi qua route queryParam) mà tự `rfFilterModel.reset(..., {emitEvent:false})` cho field khác trong `filterFields()` → KHÔNG được tự `this.initialFilters.set({}); this.search.set({})` để \"đồng bộ lại\" — 2 dòng đó xoá SẠCH mọi filter kể cả default theo điều kiện (vd `payment_user_id` theo role), và chạy ngay ở lần emit ĐẦU TIÊN (đồng bộ, trong `ngOnInit()`, TRƯỚC `scheduleFirstLoad()` async) nên bug lộ ra NGAY LẦN TẢI TRANG ĐẦU, không cần thao tác gì (epic `sale-list-v2`, user telesale mất filter theo role, thấy khách toàn phòng). Rebuild đúng: chỉ khi field trong `filterFields()` THẬT SỰ đổi, dùng `this.toFilterMeta(def, value)` cho từng field + `this.search.set(this.utilsService.buildFilter(filters))` (cả 2 đều `protected`, gọi được từ subclass) — KHÔNG blank về `{}`.\n- Pattern \"cờ boolean chặn 1 lần fetch kế tiếp\" đặt TRƯỚC `route.navigate()` (async) → phải reset cờ về `false` ngay trong `valueChanges` của MỌI control tự kích điều hướng mới (vd chọn drill-down khác) — Angular Router huỷ navigation đang chờ khi có navigation mới, nên navigation cũ (đã set cờ) có thể KHÔNG BAO GIỜ emit lại để tự tiêu thụ cờ, làm rò rỉ chặn nhầm request hợp lệ kế tiếp (epic `sale-list-v2`, phát hiện qua `\u002Fbmad-review`).\n- Trước khi đổi 1 endpoint list sang phân trang server-side (điều kiện để migrate lên V2), grep HẾT consumer của service\u002Fendpoint đó — không chỉ component đang migrate. Consumer khác có thể cần TOÀN BỘ dữ liệu (vd popup autocomplete tự lọc client-side) và sẽ bị BE mặc định cắt còn `per-page` mặc định (thường 20), mất dữ liệu im lặng không lỗi. Gặp thật: `\u002Fomi\u002Fquick-reply` (`QuickReplyList` cần trang, `OmnichatQuickreplyPopup` cần hết) — fix bằng tham số `?all=1` bỏ qua Paginate (epic `list-v2-final-cleanup`).\n\n## CRITICAL: bảng KHÔNG phân trang thì đừng dùng `searchParams()`\n\n`searchParams()` của base luôn kèm `page`\u002F`sort`\u002F`per-page`. Bảng không có `[rows]`\u002Fpaginator → `dt.rows()` là `undefined` → `per-page=undefined` → BE trả **404** (gặp thật ở `NoteStatistics`).\n\n```ts\n\u002F\u002F Bảng thống kê không phân trang — giữ đúng bộ params V1:\nconst params = { ...this.defaultSearch(), ...this.search(), ...this.requiredSearch() };\nreturn this.modelService.list({ params }).pipe(...);\n```\nQuét nhanh cả module: component `extends BaseListV2` mà template có `\u003Cp-table>` nhưng **không** có `[rows]` → soi lại `fetchList()`.\n\n## p-table full-height (footer\u002Fpaginator dính đáy) — `[appFillHeight]`, KHÔNG `TableLayoutService`\n\n`TableLayoutService.tableNormal()`\u002F`tableDetail()` (breakpoint cứng theo `window.innerWidth`) bind vào `[style]=\"{minHeight\u002FmaxHeight: calc(100vh - Npx)}\"` là cách CŨ, sai khi p-table lồng trong layout riêng của trang (con số breakpoint không trừ đúng phần header\u002Ftoolbar phía trên — bug thật \"treo lơ lửng\" ở `emr\u002Fexamination`, epic `p-table-full-height`). Dùng directive `[appFillHeight]` (`share\u002Fdirective\u002Ffill-height.directive.ts`) thay thế:\n\n```html\n\u003Cp-table appFillHeight [scrollHeight]=\"'flex'\" ...>\n```\n\n- Directive chỉ tự thêm `flex-1 min-h-0` cho CHÍNH `\u003Cp-table>` — KHÔNG tự sửa ancestor. `[scrollHeight]=\"'flex'\"` PHẢI tự khai tường minh (PrimeNG v22 `Table.scrollHeight` là `InputSignal` chỉ đọc, directive không gán được).\n- **Ancestor PHẢI tự lo** — chain flex LIÊN TỤC từ khung bị chặn (viewport\u002Ftab bounded) xuống tận `\u003Cp-table>`, mỗi tầng `display:flex;flex-direction:column;min-height:0`. 2 case thật đã làm:\n  - **Ancestor CÓ SẴN flex-bounded** (`emr\u002Fexamination` — `.cx-workspace`\u002F`.cx-sec-anchor--fill`): không cần `calc()` nào, `appFillHeight` là đủ.\n  - **Ancestor CHỈ CÓ `min-height`, không phải khung chặn thật, VÀ dùng chung giữa nhiều tab** (`customer-detail.html` — `\u003Cp-tabpanels>` PrimeNG chỉ `[style.min-height]`, 11+ tab dùng CHUNG 1 `\u003Cp-tabpanels>`) — **KHÔNG style thẳng element `p-tabpanel`\u002F`p-tabs`\u002F`p-tablist` bằng CSS blanket cho TOÀN BỘ tabpanel** (đã thử, revert 2026-08-07 — xem lịch sử `bmad\u002Fp-table-full-height\u002Fstories\u002Fstory-02-*.md`). 2 lỗi thật khi làm vậy: (1) `p-tabpanel { display:flex }` (author CSS) đè mất `[hidden]{display:none}` (UA stylesheet, author LUÔN thắng UA bất kể specificity) → mọi tabpanel (kể cả tab không active) cùng hiện, chia đều flex-space; (2) tab CHƯA migrate (list thường, cao tự nhiên, có paginator ở cuối) bị kẹp cứng theo `overflow-y:auto` của tabpanel dùng chung → paginator rớt xuống dưới vùng cuộn nội bộ thay vì hiện ngay, khác hẳn hành vi cũ (trang ngoài tự cuộn); (3) riêng tab có `display:grid` layout nhiều cột (vd tab \"Thông tin\" 2 cột) còn bị `p-tabpanel > * { display:flex }` đè mất `display:grid` do specificity `p-tabpanel > *` (0,1,1) cao hơn class `.grid` của Tailwind (0,1,0). **Đúng cách: SCOPE riêng 1 class (`.cx-tabpanel-fill`) cho ĐÚNG `\u003Cp-tabpanel>` đã migrate, KHÔNG đụng `\u003Cp-tabpanels>` gốc hay các `\u003Cp-tabpanel>` khác** — style thẳng element `p-tabpanel`\u002F`p-tablist` CHỈ an toàn khi TOÀN BỘ các tab dùng chung `\u003Cp-tabpanels>` đó đều đã migrate (không còn tab \"tự nhiên\" nào trong nhóm).\n```html\n\u003Cdiv class=\"cx-tabpanel-fill\" [style.--cx-table-detail]=\"tableDetail() + 'px'\">\n  \u003Capp-list-appointment-in-contact class=\"flex-1 min-h-0 flex flex-col\" ...\u002F>\n\u003C\u002Fdiv>\n```\n```scss\n.cx-tabpanel-fill {\n  height: calc(100vh - var(--cx-table-detail, 265px));\n  display: flex;\n  flex-direction: column;\n  overflow: hidden;\n}\n```\n- **KHÔNG áp dụng được** khi 1 tab\u002Fsection có ≥2 khối cạnh tranh chiều cao (vd tab \"orders\" của `examination`: `service-order` + `cls-results` xếp chồng) — ép `flex:1` đồng loạt sẽ vỡ layout (không tự chia được không gian). Cần thiết kế riêng, không dùng `appFillHeight` mù quáng.\n- Ancestor có `overflow-y:auto` riêng (vd `.cx-workspace`) + p-table tự scroll nội bộ (`scrollHeight=\"flex\"`) → 2 lớp scroll chồng nhau, sai số làm tròn dưới-pixel làm thanh cuộn NGOÀI chớp hiện rồi ẩn. Tắt hẳn `overflow` ở ancestor đó khi tab đang active là list full-height (xem `.cx-workspace--fill` trong `examination.scss`).\n- **Cuộn ngoài trang dư vài px SAU KHI đã đo đúng KHÔNG chắc do bảng** — xác nhận bằng cách đo tab\u002Ftrang KHÁC hoàn toàn không đụng gì (`document.scrollingElement.scrollHeight - window.innerHeight`), nếu vẫn dư y hệt thì đó là bug GLOBAL không liên quan p-table. Gặp thật: `src\u002Fassets\u002Foverrides\u002Fcustom.scss` có 2 rule TRÙNG selector `.layout-content-wrapper .layout-content` (padding khác nhau, cả 2 `!important`, rule sau âm thầm thắng) — sửa ở `custom.scss`, KHÔNG cố bù bằng cách co bảng lại (sai chỗ, blast radius sai).\n\n## `appFillHeight=\"page\"` — trang list ROUTED top-level (thay `tableNormal()`)\n\nMode KHÁC với `[appFillHeight]` trần ở trên (đó là cụm `tableDetail()`, p-table NHÚNG trong tab\u002Ftrang\nkhác). Mode `page` dành cho trang list ROUTED TOP-LEVEL trước đây dùng\n`TableLayoutService.tableNormal()` bind `[style]=\"{minHeight\u002FmaxHeight: calc(100vh - tableNormal()px)}\"`\n— cùng lớp lỗi hằng số cứng theo `window.innerWidth`, xác nhận qua đo thật (epic\n`p-table-full-height-list-pages`, 310 file, `bmad\u002Fp-table-full-height-list-pages\u002Fpilot-findings.md`):\n\n```html\n\u003Cp-table appFillHeight=\"page\" [scrollHeight]=\"'flex'\" [style]=\"{ width: '100%' }\" ...>\n```\n\n- Vì sao hằng số sai: **`1rem = 12px` trong app này** (KHÔNG phải 16px mặc định trình duyệt — mọi\n  tính rem phải dựa vào số đo thật, không suy từ 16px), breadcrumb (`flex-wrap: wrap`) có thể xuống\n  2 dòng ở màn hẹp, và mode menu ngang (`_sidebar_horizontal.scss`) đổi `padding-top` của\n  `.layout-content-wrapper` 4rem→7rem — không có 1 hằng số nào đúng cho mọi viewport\u002Fmode.\n- Directive (`share\u002Fdirective\u002Ffill-height.directive.ts`) tự đi ngược DOM từ `\u003Cp-table>` lên\n  `.layout-content-wrapper` (shell dùng chung MỌI route, `AppLayout`), gắn `display:flex;\n  flex-direction:column` cho MỌI tầng trung gian nó đi qua (class `.cx-fill-chain`) + chính wrapper\n  (`.cx-fill-page`) ở `ngAfterViewInit` — **và BẮT BUỘC tự gỡ ở `ngOnDestroy`**. `.layout-content-\n  wrapper` KHÔNG tái tạo khi đổi route (SPA) — không gỡ ⇒ trang KẾ TIẾP (form dài, dashboard) bị\n  khoá `height:100vh` bởi tính năng của trang TRƯỚC, cắt cụt nội dung mà không có lỗi console nào.\n- **Gate chống \"quên import\" — BẮT BUỘC chạy, KHÔNG có gate build nào khác bắt được lỗi này**:\n  `appFillHeight=\"page\"` là attribute TĨNH, không phải `[appFillHeight]=\"'page'\"`. Thiếu\n  `FillHeightDirective` trong `imports: [...]` của `@Component` ⇒ Angular bỏ qua attribute lạ CÂM\n  LẶNG — đã đo thực nghiệm: `tsc --noEmit`\u002F`ngc --noEmit`\u002F`ng build` đều KHÔNG lệch 1 lỗi nào. Chạy\n  `frontend\u002Fscripts\u002Fverify-fill-height-page.sh` sau MỌI lần thêm\u002Fsửa `appFillHeight=\"page\"`.\n- 12 file có ≥2 `\u003Cp-table>` trong cùng host — soi tay TRƯỚC khi áp mặc định (11\u002F12 trường hợp thật\n  ở epic này là bảng thứ 2 lồng trong `\u003Cng-template #expandedrow>` — PrimeNG row-expansion, KHÔNG\n  cạnh tranh chiều cao, áp `appFillHeight=\"page\"` cho bảng NGOÀI bình thường; chỉ 1\u002F12 là 3 bảng\n  cạnh nhau thật trong `\u003Cp-tabs>`, xem 2 gotcha dưới).\n- **Directive KHÔNG chỉ dùng cho `\u003Cp-table>`** — `[appFillHeight]` là generic (`Renderer2` thao tác\n  `ElementRef` bất kỳ). Trang dùng `\u003Cdiv [style]=\"{height:calc(...)}}\">` bọc cả report\u002Fform (KHÔNG\n  có `\u003Cp-table>` nào) vẫn áp được y hệt, chỉ bỏ `[scrollHeight]=\"'flex'\"` (thuộc tính riêng\n  `p-table`). Đừng kết luận \"không áp dụng được\" chỉ vì file không có `\u003Cp-table>`.\n- **Ancestor đã tự là flex-row hoặc CSS Grid** (PrimeFlex `.grid` — `display:flex;flex-wrap:wrap`,\n  dùng cho layout 2+ CỘT CẠNH NHAU; hoặc Tailwind `.grid`\u002F`grid-cols-*` — CSS Grid thật, dùng cho\n  layout lưới nhiều cột như `emr\u002Fexamination` cấp trang): directive TỰ đo `getComputedStyle(node)\n  .display` trước khi quyết định — ancestor đã là `flex`\u002F`inline-flex`\u002F`grid`\u002F`inline-grid` thì CHỈ\n  thêm sizing (`cx-fill-chain`), KHÔNG ép `flex-direction:column` (`cx-fill-chain-stack`) đè lên,\n  tránh phá layout ngang\u002Flưới đang có. **Bẫy đặt tên trùng**: PrimeFlex và Tailwind CÙNG định nghĩa\n  class tên `.grid` với Ý NGHĨA KHÁC NHAU (PrimeFlex: `display:flex`; Tailwind: `display:grid`) —\n  đo `getComputedStyle` thật để biết cái nào đang thắng trong file cụ thể, ĐỪNG suy từ tên class.\n- **Ancestor có thể mang attribute `hidden`** (PrimeNG `\u003Cp-tabpanel [hidden]=\"!active()\">`, xem\n  `node_modules\u002Fprimeng\u002F...\u002Fprimeng-tabs.mjs`): CSS tác giả LUÔN thắng UA stylesheet với declaration\n  thường (không `!important`) BẤT KỂ specificity — set `display:flex` không điều kiện sẽ làm tab đã\n  ẩn vẫn hiện đè (bug thật đã phải revert 2026-08-07). 2 class CSS đều guard `:not([hidden])` trong\n  `_content.scss` — ancestor `[hidden]` thì không rule author nào khớp, UA `[hidden]{display:none}`\n  áp dụng bình thường. Áp dụng được cho MỌI `\u003Cp-tabpanel>` chứa `appFillHeight=\"page\"`, không cần xử\n  lý riêng từng file.\n\n## Giới hạn đã biết\n\n- Lối vào DUY NHẤT của một hành động (nút \"Chi tiết\", link mở panel) đặt trong `@if (isColVisible('x')())` sẽ biến mất hẳn khi `x` không nằm trong `selectedColumns` mặc định — build xanh, không lỗi. Trước khi neo nút vào cột nào: đối chiếu `selectedColumns` của CHÍNH list đó; cột có mặt ở mọi list là tên khách hàng.\n- Filter đặt ở header cột (`p-columnFilter`) vẫn lọc nhưng KHÔNG lên URL — cần giữ qua URL thì khai thành `FilterFieldDef` trong panel.\n- Mũi tên sort trên header không sáng lại sau khôi phục (sort vẫn đúng); bind `[sortField]` trên bảng lazy đẻ thêm request lúc init.\n- URL nội bộ của router lệch thanh địa chỉ (hệ quả của `replaceState`) — chỗ nào so URL đầy đủ cần biết điều này.\n\n\n\n---\n\n## 1. `BaseDetail\u003CT>` — single record view (routed)\n\n**File:** `src\u002Fapp\u002Fshare\u002Fbase\u002Fbase-detail.ts`\n**Pattern:** extend + inject modelService + override `afterModelLoaded` nếu cần\n\n```typescript\nexport class CustomerDetail extends BaseDetail\u003CCustomerModel> implements OnInit {\n    modelService = inject(CustomerService);\n\n    ngOnInit() {\n        \u002F\u002F BaseDetail tự đọc route param :id + gọi modelService.get(id)\n        super.ngOnInit();\n    }\n\n    \u002F\u002F Override hook\n    override afterModelLoaded(model: CustomerModel): void {\n        this.title.setTitle(model.fullname);\n    }\n}\n```\n\nTemplate: `{{ model().fullname }}`, `{{ model().phone }}`, etc.\n\n---\n\n## 2. `BaseReport\u003CT>` — report với export Excel\n\n**File:** `src\u002Fapp\u002Fshare\u002Fbase\u002Fbase-report.ts`\n**Pattern:** extend + implement 3 abstract members\n\n```typescript\nexport class RevenueReport extends BaseReport\u003CRevenueItem> implements OnInit {\n    modelService = inject(RevenueService);\n\n    \u002F\u002F BẮT BUỘC implement\n    rfFilter = this.fb.group({\n        dateFrom: [this.timezoneService.monthStartDate()],\n        dateTo: [this.timezoneService.todayDate()],\n    });\n\n    fetchData(): Observable\u003Cany> {\n        return this.modelService.getRevenue({ params: this.searchParams() });\n    }\n\n    fetchExport(): Observable\u003Cstring> {\n        return this.modelService.exportRevenue({ params: this.searchParams() });\n    }\n}\n```\n\nBaseReport tự handle: `loadReport()`, `exportExcel()`, pagination, quick date select, keyword search.\n\n`rfFilter` phải là single source of truth: → Xem `frontend\u002Fskill\u002Fskills\u002Ffrontend-hard-rules\u002FSKILL.md` B.16.\n\n---\n\n## 3. `BasePrint` — print pages\n\n**File:** `src\u002Fapp\u002Fshare\u002Fbase\u002Fbase-print.ts`\n**@Injectable** — KHÔNG phải @Directive, KHÔNG extend BaseApp.\n\n```typescript\nexport class PrintXxx extends BasePrint implements OnInit {\n    \u002F\u002F KHÔNG có sẵn BaseApp services — inject thủ công nếu cần\n    modelService = inject(XxxService);\n    private destroyRef = inject(DestroyRef);\n\n    ngOnInit(): void {\n        \u002F\u002F Pattern chuẩn: tryLoadFromCache → API fallback\n        this.activatedRoute.params\n            .pipe(takeUntilDestroyed(this.destroyRef))\n            .subscribe((params: any) => {\n                const cacheKey = this.activatedRoute.snapshot.queryParams['cacheKey'];\n                const cached = this.tryLoadFromCache(cacheKey);\n                if (cached) { this.applyData(cached); return; }\n                this.modelService.getXxx(params.id).subscribe((d) => this.applyData(d));\n            });\n    }\n\n    applyData(data: any): void {\n        this.model.set(data);\n        this.printData.setModel({ company: ..., layoutType: ... });\n        setTimeout(() => void this.handlePrintAfterInit());\n    }\n}\n```\n\n→ Xem `fe-print.md` cho toàn bộ print flow.\n\n\n## ExportOptionsDialog (reusable)\n\n**File:** `src\u002Fapp\u002Fmodules\u002Futilities\u002Fexport-options-dialog\u002Fexport-options-dialog.ts`\n\nMở trước khi gọi API export, cho user chọn:\n- `'selected'` — chỉ export cột đang bật trong `selectedColumns`\n- `'all'` — export toàn bộ cột\n\n```typescript\n\u002F\u002F Trong component có export:\nimport { ExportOptionsDialog, ExportMode } from '@\u002Fmodules\u002Futilities\u002Fexport-options-dialog\u002Fexport-options-dialog';\n\nexportExcel() {\n  const ref = this.dialogWrapperService.open(ExportOptionsDialog, {\n    header: this.translate.instant('utilities.export_options_dialog.header'),\n    width: '480px',\n    data: {\n      selectedCount: this.selectedColumns().length,\n      totalCount: this.displayCols.length,   \u002F\u002F tổng cột trong availableColumns\u002FdisplayCols\n    },\n  });\n\n  ref.onClose.subscribe((mode: ExportMode | null) => {\n    if (!mode) return;\n    const params: any = { ...this.searchParams() };\n    if (mode === 'selected') {\n      params['columns'] = this.selectedColumns().join(',');\n    }\n    \u002F\u002F gọi API export với params\n  });\n}\n```\n\n**i18n keys** (đã có đủ 4 locale): `utilities.export_options_dialog.header\u002Fselected_label\u002Fselected_desc\u002Fall_label\u002Fall_desc`\n\n---\n\n## BE — colDef pattern cho export có column filter\n\nKhi BE cần support `?columns=...` param, dùng `colDef` slice thay vì hardcode headers\u002Fmapper.\n\n**Xem pattern đầy đủ:** `(repo cha) ..\u002Fskill\u002Fskills\u002Fworking-on-ops\u002Freference\u002Fexport.md § colDef pattern`\n\n---\n\n## Quy tắc áp dụng\n\n- `displayCols` (array tất cả cột) và `selectedColumns` (signal) phải có cùng `value` key với BE `colDef[i].key`\n- `mode === 'all'` → KHÔNG gửi `columns` param → BE fallback export all\n- `mode === 'selected'` → gửi `columns=val1,val2,...` → BE filter theo thứ tự `colDef`\n- Default mode trong dialog = `'selected'` (UX: user thường muốn export những gì đang thấy)\n- **Param export LUÔN lấy từ `this.exportParams()` của `BaseListV2` — KHÔNG tự dựng lại** (bug 2026-08-13, dính 58 màn):\n\n  ```ts\n  \u002F\u002F ĐÚNG\n  const params = {...this.exportParams()} as any;\n  \u002F\u002F SAI — thiếu `sort`, file export ra thứ tự khác bảng user đang nhìn\n  const params = {...this.defaultSearch(), ...this.search(), ...this.requiredSearch()} as any;\n  ```\n\n  Lý do: BE dùng CHUNG một query cho list và export (nhánh `_export=1` nằm trong list handler), thiếu `sort` là BE rơi về defaultOrder (thường `id DESC`). `exportParams()` = `searchParams()` bỏ `page`\u002F`per-page` (export lấy trọn kết quả) nhưng giữ `sort`.\n  Kiểm tra kèm: cột cho `pSortableColumn` phải là cột DB thật có trong whitelist `ApplySort` của handler BE — sort cột hiển thị\u002Ftính toán (vd `appointment_time` chỉ là format của `appointment_date`) thì BE reject âm thầm, list và export đều không sort được như user tưởng.\n",{"name":5,"description":7},"main","ea9f5ed9bd4eaf32e9489bcbe9603955c1462a63","frontend\u002Fskill\u002Fskills\u002Fbuilding-list-and-export-views",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 building-list-and-export-views",{"tool":39,"command":40},"bunx","bunx skills add cluvix\u002Fcluvix-crm --skill building-list-and-export-views",{"tool":42,"command":43},"pnpm","pnpm dlx skills add cluvix\u002Fcluvix-crm --skill building-list-and-export-views","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Ffrontend\u002Fskill\u002Fskills\u002Fbuilding-list-and-export-views\u002FSKILL.md",true,[47,53,57,61],{"path":48,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":51,"sourceHtmlUrl":52},"reference\u002Ffe-list-config-template.md","REFERENCE","参考文档",8246,"https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Ffrontend\u002Fskill\u002Fskills\u002Fbuilding-list-and-export-views\u002Freference\u002Ffe-list-config-template.md",{"path":54,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":55,"sourceHtmlUrl":56},"reference\u002Ffe-patterns-gotchas-search.md",7216,"https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Ffrontend\u002Fskill\u002Fskills\u002Fbuilding-list-and-export-views\u002Freference\u002Ffe-patterns-gotchas-search.md",{"path":58,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":59,"sourceHtmlUrl":60},"reference\u002Ffe-patterns-import-export.md",13508,"https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Ffrontend\u002Fskill\u002Fskills\u002Fbuilding-list-and-export-views\u002Freference\u002Ffe-patterns-import-export.md",{"path":62,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":63,"sourceHtmlUrl":64},"reference\u002Ffe-print.md",20635,"https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Ffrontend\u002Fskill\u002Fskills\u002Fbuilding-list-and-export-views\u002Freference\u002Ffe-print.md",[66,73,80,87,94,101],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":19},"01M7F47FCP2MP548SWCP0BJ6B1","writing-mysql-migrations","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.","https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fwriting-mysql-migrations\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"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":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"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":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"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":95,"name":96,"nameZh":6,"description":97,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":98,"categories":99,"keywords":100,"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":102,"name":103,"nameZh":6,"description":104,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":105,"categories":106,"keywords":107,"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",[],[]]