building-list-and-export-views
BaseListV2 (filterFields, state trên URL, fetchList), BaseDetail/BaseReport/BasePrint, và export/import 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/ExportOptionsDialog hoặc PrintLayout.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-02
- Stars
- ★ 21
- Forks
- 20
01 前言 Front Matter
- name
- building-list-and-export-views
- description
- BaseListV2 (filterFields, state trên URL, fetchList), BaseDetail/BaseReport/BasePrint, và export/import 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/ExportOptionsDialog hoặc PrintLayout.
02 资源文件 4
- 参考文档reference/fe-list-config-template.md8.1 KB
- 参考文档reference/fe-patterns-gotchas-search.md7.0 KB
- 参考文档reference/fe-patterns-import-export.md13.2 KB
- 参考文档reference/fe-print.md20.2 KB
03 SKILL.md 正文
Building list and export views
Print flow chi tiết (PrintLayout, PrintContext, window.print() gotchas):
reference/fe-print.mdImport/Export Excel chi tiết:reference/fe-patterns-import-export.mdGotchas Search/AutoComplete/List display:reference/fe-patterns-gotchas-search.mdKhuôn.ts+.htmlcho list config mới (toolbar lọc, bộ chọn cột, cột thao tác cố định):reference/fe-list-config-template.md
Dù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.
BaseList (V1) giữ nguyên — KHÔNG migrate hàng loạt, chuyển từng list khi có nhu cầu.
Bật V2
export class XxxList extends BaseListV2<XxxModel> implements OnInit {
@ViewChild('dt') dt!: Table<XxxModel>;
protected override URL_STATE_PREFIX = 'xx'; // 2–3 ký tự, khác nhau giữa 2 list cùng 1 route
protected filterFields(): FilterFieldDef[] { return [ /* ... */ ]; }
ngOnInit() { this.initListV2(); }
}
<p-table #dt [lazy]="true" [lazyLoadOnInit]="false" (onLazyLoad)="loadRecords($event)"
[filters]="initialFilters()" [first]="first()" [loading]="showSkeleton()" [filterDelay]="0">
<ng-template #caption>
<div class="h-[2px] mb-1">
@if (refreshing()) { <p-progressbar [showValue]="false" [style]="{height:'2px'}" mode="indeterminate"/> }
</div>
- 5 binding bắt buộc:
[lazyLoadOnInit]="false"·[filters]·[first]·[loading]="showSkeleton()"·[filterDelay]="0". - Thanh báo tải lại đặt trong hộp cao cố định (
h-[2px]) — tự nó không được gây CLS. - KHÔNG override
initFilter(),getDefaultFilterValues(),clearFilter(),searchHandler()— base lo hết.
filterFields()
- 1 field = 1 dòng:
{name, kind, default?, urlKey?, debounce?, itemType?, toFilter?, urlSync?}. 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ỗiyyyy-MM-dd, matchMode mặc địnhcustom) ·monthDayRange(khoảng ngày-tháng KHÔNG năm, between, cặp chuỗiMM-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/_dueDateLte) ·custom(tự lo quatoFilter).- BE nhận khoảng ngày-tháng không năm (
MM-DD, vdbirthday_md) →kind: 'monthDayRange'. KHÔNG dùngcustom:customkhông parse ngược URL→Datenên filter không sống sót qua Back/F5 (cùng bài học vớidateSingle). 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 đó, ô inputdateFormat="dd/mm"không lộ. - BE nhận khoảng ngày qua 2 tên param khác nhau (không phải 1 param
[gte]/[lte]) →kind: 'dateRangeSplit'(accountant 2026-08-04,InstallmentDebts._dueDateGte/_dueDateLte). MộtFilterMetadatachỉ sinh được 1 tên param nên base không sinh gì (toFilterMetatrảnull) — chỉ lo FormControl + URL sync; component tự ghép 2 param trongfetchList(). Nhờ vậy filter này sống sót qua Back/F5, khác hẳn cách cũ (custom+urlSync:false) không làm được. - Select chọn-một: template KHÔNG
[multiple], PHẢI[showClear]="true"(thiếu → không xoá được filter), defkind: 'equals'. p-datepickerfilter 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 địnhshowClear=false→ icon xoá không bao giờ render →clear()không ai gọi được →onClear.emitkhông bao giờ chạy). Không phải lỗi cú pháp,tsc/ng buildđều sạch — chỉ lộ ra khi bấm thật trên UI. Đo được ở accountant: 70/71 chỗ dính lỗi này từ trước khi có epic migrate.defaultphụ thuộc thời điểm → truyền factory:default: () => [this.timezoneService.todayStart(), this.timezoneService.todayEnd()].- Sentinel/luật riêng →
toFilter, vdrevenue_idid=0 nghĩa là chưa có →{value: '1', matchMode: 'is'}. urlKeybỏ 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 (_statusvsstatus).- Control tên có ký tự
[/](kind'custom', BE đọc rawc.Query("field[x]")) → BẮT BUỘC khaiurlKeytường minh (vdurlKey:'status') — mặc định giữ nguyên ký tự lạ,URLSearchParamspercent-encode thành%5B%5Dtrên address bar (round-trip đúng, chỉ xấu URL).assertFilterDefs()không chặn được ca này. assertFilterDefs()ném lỗi lúc mở trang (dev) khi trùngname, trùng urlKey, hoặc đụng khoá dành riêng_f/_page/_size/_sort.- Lọc từ code:
this.setFilterValue(name, value)— KHÔNGpatchValue()+resetPage()(đẻ 2 request). - Field BE chưa có
query.ApplyFilterthì 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). kind: 'text'value đi thẳng vào query string GET, KHÔNG giới hạn độ dài mặc định — gõ/paste vài nghìn ký tự làm request vượt giới hạn dòng request của backend/proxy → HTTP 414, list trắng im lặng. Base đã tự chặn ởMAX_TEXT_FILTER_LENGTH = 200(list-filter.model.ts) — mọikind:'text'tự cắt còn 200 ký tự + toast cảnh báo (base-list-v2.tswireFilterControls()), áp dụng mọi list dùngBaseListV2, không cần khai gì thêm.
State trên URL
- Param phẳng, không mang matchMode:
?ap_f=1&ap_date=1785690000,1785776399&ap_status=1&ap_page=2. 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.- Ghi URL bằng
Location.replaceState, KHÔNGrouter.navigate— navigate chạy trọn chu kỳ điều hướng (ActivationEnd ×N + Scroll) làmp-tablevẽ lại đè lên popover filter đang mở. - Query dựng từ
location.path(), chỉset/deletekey mình sở hữu — KHÔNGcreateUrlTree({queryParamsHandling: 'merge'});replaceStatekhông báo cho router nên cây URL của router luôn cũ. - Trả
%2C→,sauURLSearchParams.toString(). - Đồng bộ lại khi điều hướng: nghe
NavigationEndvàNavigationSkipped— bấm lại chính menu đang đứng thì router skip,queryParamsKHÔNG phát. Đọc state từe.url, KHÔNG từactivatedRoute.snapshot(skip không cập nhật snapshot). - Khi đồng bộ lại phải gán LUÔN
page/per-page/sort(param vắng = về mặc định), KHÔNG gán theoif (page > 1). writeUrlState()gọi trongsetTimeout+ guard cờdestroyed— router commit URL ở cuối chu kỳ, và component có thể đã huỷ trong khoảng đó.- Chặn theo path (
e.urlvs path lúc init) trước khi xử — không ghi đè URL của trang khác.
Tải dữ liệu
- Override
fetchList()trảObservable<ListApiResponse<T>>; KHÔNG overridesearchHandler, KHÔNG tự setloading/models/paginationInfo. - 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. getList()KHÔNG xoámodels(stale-while-revalidate). Skeleton chỉ ở lần tải đầu (showSkeleton=loading && !loadedOnce); các lần sau dùngrefreshing.- List có
#loadingbodydùngcolsIt()PHẢI gáneffect(() => this.padCols.set(this.selectedColumns().length + <số cột luôn hiện>))trong constructor —padColsmặc định 0 ⇒ hàng skeleton không có<td>nào,tsc/ngckhông bắt. - Endpoint không theo convention
filter[field][matchMode](vd query phẳng riêng) → vẫn khaifilterFields()bình thường (để có URL state + wiring), nhưngfetchList()đọc thẳngrfFilterModel.getRawValue()và tự dựng param như V1 — KHÔNG dùngsearchParams(). Ghi comment tại chỗ giải thích lý do, kẻo người sau "dọn" nhầm vềsearchParams(). - List có field tổng/side-effect ngoài
items/_metagán trongfetchList()(vdtotal/discounthiển thị footer) → PHẢI tự thêm sequence guard (private xxFetchSeq = 0, tăng ở đầufetchList(), chỉ gán khiseq === this.xxFetchSeqlúc response về) nếu paginator/sort không debounce —wireReloadPipeline(base) chỉ huỷ được việc GIAOmodels/paginationInfocho request cũ, KHÔNG huỷ side-effect tự viết chạy trong thânswitchMap(async...)của chínhfetchList(). effect()re-tính state "theo trang mới" (vd cơ chế chọn-dòng tự viết cầncurrentPageItemskhớp trang hiện tại) phải watchthis.paginationInfo(), KHÔNG watchthis.models()—modelscòn bị mutate NGOÀI luồng fetch bởiupdateRow()(base, dùng khi cập nhật 1 dòng tại chỗ vd toggle status),paginationInfochỉ đổi khi có fetch thật.- List nhúng nhận
@Input customertừ parent cómodel()khởi tạo rỗng-nhưng-truthy (vdcustomer-detail.tsdùngsignal({} as T)) →fetchList()có thể chạy vớicustomer.id === undefinedlúc parent chưa load xong HTTP, rõ nhất khi Back/Forward remount toàn trang (không phải chỉ đổi tab). Guard đầufetchList():if (!this.customer?.id) return this.emptyListResult();— helper có sẵn trênBaseListV2, trả{items:[], _meta:{totalCount:0}}hợp lệ (không phải lỗi);ngOnChangessẵ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 — xemfrontend/skill/skills/working-on-fe-modules/reference/fe-patterns-gotchas.md.
Gotcha PrimeNG v22
- Input
[filters]đồng bộ vàodt.filtersquaeffect()→ chạy SAUngOnInitcủa bảng, tức sau lầnonLazyLoadđầ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 trongafterNextRender. filterDelaymặc định đã là 300 → gỡ binding vô ích, phải[filterDelay]="0"(base đã debounce 300/500ms).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.- 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ỉwriteValuekhi giá trị binding ĐỔI, vàrowTrackBymặ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.
Điều kiện đủ để migrate 1 list sang V2
Kiểm 3 thứ TRƯỚC khi bắt tay, thiếu bất kỳ cái nào thì giữ nguyên V1:
- Template có
<p-table>và[lazy]="true"— mọi giá trị của V2 (URL state, SWR, huỷ request cũ) đi quaonLazyLoad→loadRecords(). Bảng không lazy thì V2 chỉ đổi base class, không được gì. - Có
@ViewChild('dt')(thiếu thì thêm —BaseListV2khaiabstract dt). - Component có nơi dùng thật (route hoặc được nhúng) — grep selector trước, đừng migrate component chết.
Checklist migrate V1 → V2 (đúc từ 45 lần làm, epic crm-list-v2)
defaultSearch.set(...)trongngOnInit→ xoá, chuyển sangdefault: () => ...(factory) của field tương ứng.[monthStart, todayStart]và[monthStart, todayEnd]cho ra CÙNG range vìbuildFilterTimestampchuẩn hoá end về cuối ngày.sort.set(...)nằm trongsearchHandler()→ 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àinitialSortcủa base cũng sai.- Control khai trong
fb.groupnhưng không cóformControlNamenào trong template = control chết → không khai def. Grep template trước khi chép cả danh sách control sangfilterFields(). - Field mà BE không có
query.ApplyFilterlẫnc.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). - BE đọc raw
c.Query("<field>")thay vìApplyFilter→kind: 'custom'+toFiltertrảmatchMode: 'custom'; tên control phải TRÙNG tên param BE.buildFilter()gửi rawfield=valuecho 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_). - 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ùngkind: 'custom'cho ca này:customkhông có đường parse ngược URL→Datenên filter ngày sẽ không sống sót qua Back/F5.dateSingleformat theo wall-clock cục bộ của Date (giốngformatDate(d,'yyyy-MM-dd','en-US')của V1), KHÔNG chuyển timezone lần nữa —p-datePickervàBaseApp.todayđều đã là Date theo giờ cần dùng. - 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. Đọccommentcủa cột trongdao/entity.goTRƯỚC khi khaidateRange; cột ms → overridetoFilterMeta()nhân 1000 tại component (KHÔNG dùngkind:'custom'— mất khả năng sống qua Back/F5). - Response shape khác chuẩn (vd
{sumPoint, object:{items,_meta}}) → bóc trongfetchList(), đừng sửa base. - Đổi tên form control thì phải sửa
formControlNametrong template —tsckhông bắt được lệch tên, reactive form chỉ vỡ lúc chạy. - Component tự
inject(ActivatedRoute)vào fieldprivate 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 (vdprintTemplateRoute), KHÔNG sửa base. Gặp thật 2 lần:config-print-template,hr/certificate. - 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àofilterFields():requiredSearchluôn được gộp vàosearchParams()và không cho người dùng chỉnh. - 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ênwatchUrlNavigation/writeUrlState/restoreFromUrlđều return sớm, không một lời cảnh báo:tscxanh, list chạy bình thường, code review "đạt" đủ AC — mà FR-1/FR-2 mất trắng. Gặp thật 1/6 list ở epiccare-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/app/modules/<module>/— đế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. - Ô lọc không gắn được
formControlName(app-user-select,<input type="month">, hay signal mà nghiệp vụ đọc) → dựng giá trị hiển-thị-lại bằngcomputed(() => this.initialFilters()['<field>']?.value ?? <rỗng>), KHÔNG sync bằngcontrol.valueChanges: base patch/reset form bằngemitEvent:falseởrestoreFromUrl()vàclearFilter()nênvalueChangesbỏ lỡ 2 ca đó. Từ 2026-08-04wireFilterControls()cũng cập nhậtinitialFiltersnê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 quap-columnFilter(không có trongfilterFields()) sẽ bị rơi khỏidt.filtersmỗi lần user đổi filter panel — cần giữ thì phải khai nó thànhFilterFieldDef. - Component tự khai
private activatedRoute = inject(ActivatedRoute)(vd để đọc deep-link?user_id=) sẽ đụng fieldprivate activatedRoutecủaBaseListV2→TS2415/TS2515"incorrectly extends base class... separate declarations of a private property". Đổi tên field của component (vdceActivatedRoute), KHÔNG sửa base. Gặp thật ởhr/certificate/list(epichr-list-v2, 2026-08-03); V1 không dính vìBaseListkhông injectActivatedRoute. - Control lọc có thể nằm ngoài
rfFilterModel: gọi thẳngdt.filter(v, '<field>', ...)từ một[ngModel]standalone. Quétdt.filter(toàn module trước khi chốt danh sách field, đừng chỉ đọcfb.group— sót kiểu này làm khảo sát thiếu hẳn 1 filter (LeaveBalanceList.year, epichr-list-v2). - V1 gọi
this.defaultSearch.set({})(không phải.set({field: ...})) trong 1 hàmclearXxx()→ đ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 sangsetFilterValue(field, null)cho đúng 1 field sẽ thu hẹp phạm vi xoá — đối chiếu kỹ hàmclearXxx()V1 xemdefaultSearch/searchbị reset bao nhiêu key trước khi migrate. - Base trung gian (Component →
MiddleBase→BaseListV2) tự khai method tênfetchList/filterFields/tên khác trùng với thành viên mới củaBaseListV2→ phải đổi tên method cũ (vdfetchApi) ở TẤT CẢ subclass TRƯỚC khi đổiMiddleBasesangextends BaseListV2. Không đổi base rồi để subclass "sửa dần sau":ngOnInitcủ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/WorkspaceCommissionListBase, epicworkspace-list-v2. (input)="searchKeyword($event)"cạnhformControlNamecù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 (epicworkspace-list-v2, 14/14).default:trongfilterFields()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 videfaultSearch.set({})của V1, migrate field "tháng này" V1 sangdefault: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) → khairequired: true(bắt buộc kèmdefault,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ắnrequired.- List nhúng dùng
requiredSearch(vd theocustomer.id) — thứ tự gọiinitXxxFilter()(setrequiredSearch) trước hay sauinitListV2()trongngOnInitKHÔNG quyết định request đầu có đủ param: request đầu bắn trongafterNextRender()(macrotask, sau khingOnInitđã chạy xong hoàn toàn), vàrequiredSearchlà signal đọc live trongsearchParams, không bị chụp snapshot. Đặt trước chỉ vì đọc tự nhiên hơn, không phải vì đúng/sai kỹ thuật — đừng suy diễn thành "rò dữ liệu chéo" nếu đặt sau. - List có field drill-down ngoài
filterFields()(đọc/ghi qua route queryParam) mà tựrfFilterModel.reset(..., {emitEvent:false})cho field khác trongfilterFields()→ 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 (vdpayment_user_idtheo role), và chạy ngay ở lần emit ĐẦU TIÊN (đồng bộ, trongngOnInit(), TRƯỚCscheduleFirstLoad()async) nên bug lộ ra NGAY LẦN TẢI TRANG ĐẦU, không cần thao tác gì (epicsale-list-v2, user telesale mất filter theo role, thấy khách toàn phòng). Rebuild đúng: chỉ khi field trongfilterFields()THẬT SỰ đổi, dùngthis.toFilterMeta(def, value)cho từng field +this.search.set(this.utilsService.buildFilter(filters))(cả 2 đềuprotected, gọi được từ subclass) — KHÔNG blank về{}. - Pattern "cờ boolean chặn 1 lần fetch kế tiếp" đặt TRƯỚC
route.navigate()(async) → phải reset cờ vềfalsengay trongvalueChangescủ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 (epicsale-list-v2, phát hiện qua/bmad-review). - 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/endpoint đó — 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-pagemặc định (thường 20), mất dữ liệu im lặng không lỗi. Gặp thật:/omi/quick-reply(QuickReplyListcần trang,OmnichatQuickreplyPopupcần hết) — fix bằng tham số?all=1bỏ qua Paginate (epiclist-v2-final-cleanup).
CRITICAL: bảng KHÔNG phân trang thì đừng dùng searchParams()
searchParams() của base luôn kèm page/sort/per-page. Bảng không có [rows]/paginator → dt.rows() là undefined → per-page=undefined → BE trả 404 (gặp thật ở NoteStatistics).
// Bảng thống kê không phân trang — giữ đúng bộ params V1:
const params = { ...this.defaultSearch(), ...this.search(), ...this.requiredSearch() };
return this.modelService.list({ params }).pipe(...);
Quét nhanh cả module: component extends BaseListV2 mà template có <p-table> nhưng không có [rows] → soi lại fetchList().
p-table full-height (footer/paginator dính đáy) — [appFillHeight], KHÔNG TableLayoutService
TableLayoutService.tableNormal()/tableDetail() (breakpoint cứng theo window.innerWidth) bind vào [style]="{minHeight/maxHeight: 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/toolbar phía trên — bug thật "treo lơ lửng" ở emr/examination, epic p-table-full-height). Dùng directive [appFillHeight] (share/directive/fill-height.directive.ts) thay thế:
<p-table appFillHeight [scrollHeight]="'flex'" ...>
- Directive chỉ tự thêm
flex-1 min-h-0cho CHÍNH<p-table>— KHÔNG tự sửa ancestor.[scrollHeight]="'flex'"PHẢI tự khai tường minh (PrimeNG v22Table.scrollHeightlàInputSignalchỉ đọc, directive không gán được). - Ancestor PHẢI tự lo — chain flex LIÊN TỤC từ khung bị chặn (viewport/tab bounded) xuống tận
<p-table>, mỗi tầngdisplay:flex;flex-direction:column;min-height:0. 2 case thật đã làm:- Ancestor CÓ SẴN flex-bounded (
emr/examination—.cx-workspace/.cx-sec-anchor--fill): không cầncalc()nào,appFillHeightlà đủ. - 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—<p-tabpanels>PrimeNG chỉ[style.min-height], 11+ tab dùng CHUNG 1<p-tabpanels>) — KHÔNG style thẳng elementp-tabpanel/p-tabs/p-tablistbằng CSS blanket cho TOÀN BỘ tabpanel (đã thử, revert 2026-08-07 — xem lịch sửbmad/p-table-full-height/stories/story-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 theooverflow-y:autocủ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:gridlayout nhiều cột (vd tab "Thông tin" 2 cột) còn bịp-tabpanel > * { display:flex }đè mấtdisplay:griddo specificityp-tabpanel > *(0,1,1) cao hơn class.gridcủa Tailwind (0,1,0). Đúng cách: SCOPE riêng 1 class (.cx-tabpanel-fill) cho ĐÚNG<p-tabpanel>đã migrate, KHÔNG đụng<p-tabpanels>gốc hay các<p-tabpanel>khác — style thẳng elementp-tabpanel/p-tablistCHỈ an toàn khi TOÀN BỘ các tab dùng chung<p-tabpanels>đó đều đã migrate (không còn tab "tự nhiên" nào trong nhóm).
- Ancestor CÓ SẴN flex-bounded (
<div class="cx-tabpanel-fill" [style.--cx-table-detail]="tableDetail() + 'px'">
<app-list-appointment-in-contact class="flex-1 min-h-0 flex flex-col" .../>
</div>
.cx-tabpanel-fill {
height: calc(100vh - var(--cx-table-detail, 265px));
display: flex;
flex-direction: column;
overflow: hidden;
}
- KHÔNG áp dụng được khi 1 tab/section có ≥2 khối cạnh tranh chiều cao (vd tab "orders" của
examination:service-order+cls-resultsxếp chồng) — épflex: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ùngappFillHeightmù quáng. - Ancestor có
overflow-y:autoriê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ẳnoverflowở ancestor đó khi tab đang active là list full-height (xem.cx-workspace--filltrongexamination.scss). - 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/trang 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/assets/overrides/custom.scsscó 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).
appFillHeight="page" — trang list ROUTED top-level (thay tableNormal())
Mode KHÁC với [appFillHeight] trần ở trên (đó là cụm tableDetail(), p-table NHÚNG trong tab/trang
khác). Mode page dành cho trang list ROUTED TOP-LEVEL trước đây dùng
TableLayoutService.tableNormal() bind [style]="{minHeight/maxHeight: calc(100vh - tableNormal()px)}"
— cùng lớp lỗi hằng số cứng theo window.innerWidth, xác nhận qua đo thật (epic
p-table-full-height-list-pages, 310 file, bmad/p-table-full-height-list-pages/pilot-findings.md):
<p-table appFillHeight="page" [scrollHeight]="'flex'" [style]="{ width: '100%' }" ...>
- Vì sao hằng số sai:
1rem = 12pxtrong app này (KHÔNG phải 16px mặc định trình duyệt — mọi 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 2 dòng ở màn hẹp, và mode menu ngang (_sidebar_horizontal.scss) đổipadding-topcủa.layout-content-wrapper4rem→7rem — không có 1 hằng số nào đúng cho mọi viewport/mode. - Directive (
share/directive/fill-height.directive.ts) tự đi ngược DOM từ<p-table>lên.layout-content-wrapper(shell dùng chung MỌI route,AppLayout), gắndisplay:flex; flex-direction:columncho MỌI tầng trung gian nó đi qua (class.cx-fill-chain) + chính wrapper (.cx-fill-page) ởngAfterViewInit— và BẮT BUỘC tự gỡ ởngOnDestroy..layout-content- wrapperKHÔNG tái tạo khi đổi route (SPA) — không gỡ ⇒ trang KẾ TIẾP (form dài, dashboard) bị khoáheight:100vhbở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. - 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:
appFillHeight="page"là attribute TĨNH, không phải[appFillHeight]="'page'". ThiếuFillHeightDirectivetrongimports: [...]của@Component⇒ Angular bỏ qua attribute lạ CÂM LẶNG — đã đo thực nghiệm:tsc --noEmit/ngc --noEmit/ng buildđều KHÔNG lệch 1 lỗi nào. Chạyfrontend/scripts/verify-fill-height-page.shsau MỌI lần thêm/sửaappFillHeight="page". - 12 file có ≥2
<p-table>trong cùng host — soi tay TRƯỚC khi áp mặc định (11/12 trường hợp thật ở epic này là bảng thứ 2 lồng trong<ng-template #expandedrow>— PrimeNG row-expansion, KHÔNG cạnh tranh chiều cao, ápappFillHeight="page"cho bảng NGOÀI bình thường; chỉ 1/12 là 3 bảng cạnh nhau thật trong<p-tabs>, xem 2 gotcha dưới). - Directive KHÔNG chỉ dùng cho
<p-table>—[appFillHeight]là generic (Renderer2thao tácElementRefbất kỳ). Trang dùng<div [style]="{height:calc(...)}}">bọc cả report/form (KHÔNG có<p-table>nào) vẫn áp được y hệt, chỉ bỏ[scrollHeight]="'flex'"(thuộc tính riêngp-table). Đừng kết luận "không áp dụng được" chỉ vì file không có<p-table>. - Ancestor đã tự là flex-row hoặc CSS Grid (PrimeFlex
.grid—display:flex;flex-wrap:wrap, dùng cho layout 2+ CỘT CẠNH NHAU; hoặc Tailwind.grid/grid-cols-*— CSS Grid thật, dùng cho layout lưới nhiều cột nhưemr/examinationcấp trang): directive TỰ đogetComputedStyle(node) .displaytrước khi quyết định — ancestor đã làflex/inline-flex/grid/inline-gridthì CHỈ thêm sizing (cx-fill-chain), KHÔNG épflex-direction:column(cx-fill-chain-stack) đè lên, tránh phá layout ngang/lưới đang có. Bẫy đặt tên trùng: PrimeFlex và Tailwind CÙNG định nghĩa class tên.gridvới Ý NGHĨA KHÁC NHAU (PrimeFlex:display:flex; Tailwind:display:grid) — đogetComputedStylethật để biết cái nào đang thắng trong file cụ thể, ĐỪNG suy từ tên class. - Ancestor có thể mang attribute
hidden(PrimeNG<p-tabpanel [hidden]="!active()">, xemnode_modules/primeng/.../primeng-tabs.mjs): CSS tác giả LUÔN thắng UA stylesheet với declaration thường (không!important) BẤT KỂ specificity — setdisplay:flexkhông điều kiện sẽ làm tab đã ẩn vẫn hiện đè (bug thật đã phải revert 2026-08-07). 2 class CSS đều guard:not([hidden])trong_content.scss— ancestor[hidden]thì không rule author nào khớp, UA[hidden]{display:none}áp dụng bình thường. Áp dụng được cho MỌI<p-tabpanel>chứaappFillHeight="page", không cần xử lý riêng từng file.
Giới hạn đã biết
- 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 khixkhông nằm trongselectedColumnsmặc định — build xanh, không lỗi. Trước khi neo nút vào cột nào: đối chiếuselectedColumnscủa CHÍNH list đó; cột có mặt ở mọi list là tên khách hàng. - 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ànhFilterFieldDeftrong panel. - 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. - 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.
1. BaseDetail<T> — single record view (routed)
File: src/app/share/base/base-detail.ts
Pattern: extend + inject modelService + override afterModelLoaded nếu cần
export class CustomerDetail extends BaseDetail<CustomerModel> implements OnInit {
modelService = inject(CustomerService);
ngOnInit() {
// BaseDetail tự đọc route param :id + gọi modelService.get(id)
super.ngOnInit();
}
// Override hook
override afterModelLoaded(model: CustomerModel): void {
this.title.setTitle(model.fullname);
}
}
Template: {{ model().fullname }}, {{ model().phone }}, etc.
2. BaseReport<T> — report với export Excel
File: src/app/share/base/base-report.ts
Pattern: extend + implement 3 abstract members
export class RevenueReport extends BaseReport<RevenueItem> implements OnInit {
modelService = inject(RevenueService);
// BẮT BUỘC implement
rfFilter = this.fb.group({
dateFrom: [this.timezoneService.monthStartDate()],
dateTo: [this.timezoneService.todayDate()],
});
fetchData(): Observable<any> {
return this.modelService.getRevenue({ params: this.searchParams() });
}
fetchExport(): Observable<string> {
return this.modelService.exportRevenue({ params: this.searchParams() });
}
}
BaseReport tự handle: loadReport(), exportExcel(), pagination, quick date select, keyword search.
rfFilter phải là single source of truth: → Xem frontend/skill/skills/frontend-hard-rules/SKILL.md B.16.
3. BasePrint — print pages
File: src/app/share/base/base-print.ts
@Injectable — KHÔNG phải @Directive, KHÔNG extend BaseApp.
export class PrintXxx extends BasePrint implements OnInit {
// KHÔNG có sẵn BaseApp services — inject thủ công nếu cần
modelService = inject(XxxService);
private destroyRef = inject(DestroyRef);
ngOnInit(): void {
// Pattern chuẩn: tryLoadFromCache → API fallback
this.activatedRoute.params
.pipe(takeUntilDestroyed(this.destroyRef))
.subscribe((params: any) => {
const cacheKey = this.activatedRoute.snapshot.queryParams['cacheKey'];
const cached = this.tryLoadFromCache(cacheKey);
if (cached) { this.applyData(cached); return; }
this.modelService.getXxx(params.id).subscribe((d) => this.applyData(d));
});
}
applyData(data: any): void {
this.model.set(data);
this.printData.setModel({ company: ..., layoutType: ... });
setTimeout(() => void this.handlePrintAfterInit());
}
}
→ Xem fe-print.md cho toàn bộ print flow.
ExportOptionsDialog (reusable)
File: src/app/modules/utilities/export-options-dialog/export-options-dialog.ts
Mở trước khi gọi API export, cho user chọn:
'selected'— chỉ export cột đang bật trongselectedColumns'all'— export toàn bộ cột
// Trong component có export:
import { ExportOptionsDialog, ExportMode } from '@/modules/utilities/export-options-dialog/export-options-dialog';
exportExcel() {
const ref = this.dialogWrapperService.open(ExportOptionsDialog, {
header: this.translate.instant('utilities.export_options_dialog.header'),
width: '480px',
data: {
selectedCount: this.selectedColumns().length,
totalCount: this.displayCols.length, // tổng cột trong availableColumns/displayCols
},
});
ref.onClose.subscribe((mode: ExportMode | null) => {
if (!mode) return;
const params: any = { ...this.searchParams() };
if (mode === 'selected') {
params['columns'] = this.selectedColumns().join(',');
}
// gọi API export với params
});
}
i18n keys (đã có đủ 4 locale): utilities.export_options_dialog.header/selected_label/selected_desc/all_label/all_desc
BE — colDef pattern cho export có column filter
Khi BE cần support ?columns=... param, dùng colDef slice thay vì hardcode headers/mapper.
Xem pattern đầy đủ: (repo cha) ../skill/skills/working-on-ops/reference/export.md § colDef pattern
Quy tắc áp dụng
-
displayCols(array tất cả cột) vàselectedColumns(signal) phải có cùngvaluekey với BEcolDef[i].key -
mode === 'all'→ KHÔNG gửicolumnsparam → BE fallback export all -
mode === 'selected'→ gửicolumns=val1,val2,...→ BE filter theo thứ tựcolDef -
Default mode trong dialog =
'selected'(UX: user thường muốn export những gì đang thấy) -
Param export LUÔN lấy từ
this.exportParams()củaBaseListV2— KHÔNG tự dựng lại (bug 2026-08-13, dính 58 màn):// ĐÚNG const params = {...this.exportParams()} as any; // SAI — thiếu `sort`, file export ra thứ tự khác bảng user đang nhìn const params = {...this.defaultSearch(), ...this.search(), ...this.requiredSearch()} as any;Lý do: BE dùng CHUNG một query cho list và export (nhánh
_export=1nằm trong list handler), thiếusortlà BE rơi về defaultOrder (thườngid DESC).exportParams()=searchParams()bỏpage/per-page(export lấy trọn kết quả) nhưng giữsort. Kiểm tra kèm: cột chopSortableColumnphải là cột DB thật có trong whitelistApplySortcủa handler BE — sort cột hiển thị/tính toán (vdappointment_timechỉ là format củaappointment_date) thì BE reject âm thầm, list và export đều không sort được như user tưởng.
04 同仓库更多 Skills
writing-mysql-migrations
Viết migration MySQL cho Cluvix (golang-migrate, Go + GORM): quy ước timestamp, idempotent ADD/DROP COLUMN, FK constraint thật, decimal tiền, MySQL 9.7 LTS syntax mới/cũ, và luật CẤM tuyệt đối test/migrate chạm DB dev/prod thật. Dùng skill này TRƯỚC KHI tạo file migration mới, sửa schema, thêm cột/FK, backfill dữ liệu, hoặc trước khi chạy `cmd/migrate`/integration test đụng tới database — kể cả migration chỉ 1-2 dòng.
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/modules/, khi cần biết Handler DI/Router/Repository Reader/DTO 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/sửa query đang sai — xem debugging-backend-queries cho việc đó.
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/dashboard 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.
working-on-hr
Quy tắc và pattern nghiệp vụ HR Cluvix trong CRM standalone: user nội bộ, role/RBAC, đổi/đặt lại mật khẩu, import user. Dùng skill này KHI làm feature/sửa bug đụng module hr (chỉ còn `hr/user`) — trước khi đọc code.
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/sử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(...)).
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/sửa bug đụng các module đó — trước khi đọc code. Tổng đài/chữ ký số/AI config đã bỏ (chỉ còn mô tả lịch sử trong skill, KHÔNG áp dụng).