handling-auth-and-workspace
Dual authentication CRM/Client (JWT chỉ chứa uid, 2FA TOTP, device limit qua rts:{uid} zset) và các module config liên quan (IndexedDB master-data sync). Dùng skill này KHI đụng login/logout/refresh-token/2FA, session/device management, trước khi tái tạo helper đọc company/username từ JWT (đã xoá 2026-07-04 — PHẢI dùng GetBranchActiveID; company đã xoá hoàn toàn D15/story-41), hoặc khi thêm bảng IndexedDB mới ở FE.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-02
- Stars
- ★ 21
- Forks
- 20
01 前言 Front Matter
- name
- handling-auth-and-workspace
- description
- Dual authentication CRM/Client (JWT chỉ chứa uid, 2FA TOTP, device limit qua rts:{uid} zset) và các module config liên quan (IndexedDB master-data sync). Dùng skill này KHI đụng login/logout/refresh-token/2FA, session/device management, trước khi tái tạo helper đọc company/username từ JWT (đã xoá 2026-07-04 — PHẢI dùng GetBranchActiveID; company đã xoá hoàn toàn D15/story-41), hoặc khi thêm bảng IndexedDB mới ở FE.
02 资源文件 1
- 参考文档reference/indexeddb.md6.3 KB
03 SKILL.md 正文
Auth & Workspace
reference/indexeddb.md: IndexedDB master-data sync phía BE.
Tổng quan
2 hệ thống auth hoàn toàn tách biệt: CRM (nhân viên) và Client (đối tác bên ngoài).
CRM Auth (Nhân viên)
Flow
POST /api/crm/auth/login { username, password, device_fingerprint }
→ BE: validates credentials
→ BE: upsert user_device (device binding — xem §Device binding); đóng fingerprint vào refresh token
→ BE: Set-Cookie: refresh_token=<opaque>; HttpOnly; Secure; SameSite=None; Path=/api/auth; Max-Age=...
(HTTP dev: SameSite=Lax + Secure=false — None yêu cầu Secure=true)
→ Response body: { accessToken, expiresAt, refreshExpiresAt } ← NO refreshToken in body
→ FE: TokenService.setTokens(accessToken, expiresAt, refreshExpiresAt)
stores encrypted access_token (AES-GCM) + refresh_token_expires_at in localStorage
refresh_token cookie managed entirely by browser
POST /api/crm/auth/refresh-token { device_fingerprint }
→ Browser auto-sends refresh_token cookie (withCredentials: true, default in ApiService)
→ BE: reads c.Cookie("refresh_token"), verify device fingerprint theo DEVICE_BINDING_MODE, rotates, sets new cookie
→ Response body: { accessToken, expiresAt, refreshExpiresAt } ← NO refreshToken in body
POST /api/crm/auth/logout ← PUBLIC route (không qua JWTAuth)
→ Hoạt động cả khi access token đã hết hạn — bắt buộc để consume refresh cookie
→ Prod: reject Sec-Fetch-Site: cross-site (403) — chống CSRF forced-logout; dev skip (FE/BE khác site)
→ BE: revoke access jti (best-effort nếu có Bearer, truyền c.ClientIP() cho IP binding) + consume refresh + clear cookie (Max-Age=-1)
→ FE: TokenService.clearToken() wipes localStorage timestamps
POST /api/crm/auth/logout-all (authed)
→ RevokeAllSessions + RevokeAllRefreshTokens — PHẢI revoke cả 2 (xem §Security)
Request → middleware.JWTAuth(tokenSvc) → decode JWT + check revoked:{jti} (Redis) → set userID
→ middleware.AuthResponseHeaders() → loadUserScope() → set branchActiveId, branchIds, locale
JWT Claims
type Claims struct {
UID uint `json:"uid"`
}
// KHÔNG có branch_id/username trong JWT — branch scope lấy từ UserScope
// (GetBranchActiveID). GetCompanyID đã xóa 2026-07-04, KHÔNG tái tạo. D15/story-41:
// company đã xoá hoàn toàn khỏi hệ thống (1 thương hiệu/DB) — không còn company_id/
// companyActiveId/companyIds ở bất kỳ tầng nào.
Context getters
GetUserID(c)→ uintGetBranchActiveID(c)→ uintGetBranchIDs(c)→ []uint
UserScope (cached Redis 5 phút)
- Load từ
user(driving) LEFT JOINuser_profile→ branchActive_id, branchIds (JSON), locale, status InvalidateUserScope(userID)— gọi khi user đổi branch/statusbranchActive_idchỉ được tin khi còn ∈branchIds(effectiveActiveBranch, 2026-10-20) — lệch ⇒ về chi nhánh đầu tiên được phép;branchIdsrỗng = không giới hạn ⇒ giữ nguyênAuthResponseHeadersabort 401 nếuscope.Status != define.UserStatusActive— enforce per-request, không chỉ lúc login- Cache cleared khi admin update user → request ngay sau re-read DB → enforce ngay không cần logout
Security
- Device limit thật = giới hạn refresh token (2026-07-04): zset
rts:{uid}(rid → expiry) index refresh token/user; login vượtTOKEN_MAX_SESSIONS(default 3) → evict refresh của thiết bị ít-refresh-nhất (LRU) → thiết bị đó chết trong ≤ AccessTTL. Giới hạn access-session một mình VÔ NGHĨA (bị revoke thì silent-refresh sống lại) - Logout dùng
ConsumeRefreshKHÔNGVerifyAndRotateRefresh— rotate lúc logout tạo orphan token chiếm 1 slot device đến hết RefreshTTL - Rotation nguyên tử + phát hiện dùng lại (2026-10-20):
claimRefresh(Lua: DELrt+ ghirtused:{rid}= uid:hash:unix) — 2 request cùng token chỉ 1 cái thắng; thua ⇒ErrRefreshRaced⇒ handler trả 409, KHÔNG xoá cookie (FE coi là lỗi thoáng qua). Token đã xoay vòng bị trình lại saurefreshReuseGrace(30s) ⇒ErrRefreshReused: thu hồi MỌI refresh + access của user, seclogrefresh_reuse_detected - Token revocation (jti blacklist), IP binding (optional)
- Revocation enforce tại
JWTAuth(tokenSvc)(2026-07-04): checkrevoked:{jti}mỗi request — fail-open khi Redis lỗi - TTL blacklist = phần đời còn lại của token (lấy từ
sess:{uid}zset score) — TTL cố định ngắn hơn AccessTTL sẽ mở resurrection window (token revoke xong sống lại) - Revoke access PHẢI kèm revoke refresh (CRITICAL): chỉ
RevokeAllSessions→ thiết bị khác 401 thoáng qua rồi silent-refresh lấy token mới → revoke vô dụng. LUÔN gọi cặpRevokeAllSessions(uid)+RevokeAllRefreshTokens(uid)(logout-all, đổi mật khẩu, đổi role/status) - refresh_token: HttpOnly Secure SameSite=None cookie (Lax trên HTTP dev), Path=/api/auth (Cấp 2, implemented 2026-04-26)
- access_token: AES-GCM encrypted at rest in localStorage (Cấp 1)
- Login rate limit: 10 req/IP/5min via Redis INCR
- Trusted proxies (CRITICAL):
r.SetTrustedProxies(cfg.TrustedProxies)— gin default tin MỌI proxy →ClientIP()spoof được qua X-Forwarded-For. SetTRUSTED_PROXIESđúng khi sau reverse proxy, nếu không rate-limit/IP-binding/seclog đều dựa IP giả. Chiều ngược lại cũng chết: sau nginx mà.envTRỐNG ⇒ClientIP()= 127.0.0.1 cho MỌI request ⇒ rate limit key theo IP thành 1 bucket toàn cục (livechat 2026-09-03). Rate limit mới theo IP phải key thêm tenant/site và ghi tiền điều kiện này - IP binding (
TOKEN_IP_BINDING=true):buildAccessJWTnhétipHash=sha256(ip)vào access token;JWTAuthso vớisha256(ClientIP)mỗi request → 401 khi lệch. User di động đổi IP → 401 → interceptor silent-refresh → token rebind IP mới (không logout). Opt-in, default off - Token khác access (challenge 2FA, one-time...) PHẢI ký key riêng (vd
sha256(Secret+":purpose")) —JWTAuthverify chữ ký + expiry +revoked:{jti}+ issuer/audience (token.ClaimsMatchTenant, issuer/aud chứa DB_NAME từ 2026-10-18 — chặn token chéo khách) nhưng KHÔNG phân biệt mục đích token; ký chungTOKEN_SECRET→ token đó dùng được làm Bearer access token (challenge không có jti → bỏ qua cả revocation check) = bypass. Test guard:pkg/token/challenge_isolation_test.go
IP allowlist nhân viên (Hướng 2A — khác IP binding)
IP_ALLOWLIST_MODE=off|log|enforce(SetIPAllowlistModeở boot). Chặn nhân viên theoallowed_ips(IP/CIDR) — KHÁC IP binding (bind token vào 1 IP): allowlist là danh sách IP/dải được phép- Cột
allowed_ipsJSON trênbusiness_profile(D15/story-62, quapkg/brand; trước đây trêncompany) +user. Effective = user override > hồ sơ thương hiệu (user non-empty thắng; rỗng cả hai = không giới hạn). Load vàoUserScope.AllowedIPs(cache 5 phút → đổi allowed_ips propagate ≤5 phút hoặcInvalidateUserScope) - Enforce trong
AuthResponseHeaders(sau khi set branchActiveId):helpers.IPInAllowlist(ClientIP, list)(exact IP + CIDR). enforce → 403ip_not_allowed; log → chỉ seclog (throttle 1 lần/(user,ip)/5phút chống flood) - Super-user LUÔN bypass (
UserScope.IsSuper= EXISTS role trongdefine.SuperRoles) — cấu hình sai không tự khóa admin - PHỤ THUỘC trusted proxies — ClientIP phải thật
- FE: field
allowed_ips(textarea IP/CIDR mỗi dòng) trong form hồ sơ doanh nghiệp (authBusinessProfile) + user; cảnh báo lockout.helpers.IPInAllowlistcũng nângcheckPartnerIP(partner_auth) từ exact match lên CIDR - Test:
pkg/helpers/ipmatch_test.go(exact/CIDR/IPv6/edge)
Device binding (fingerprint)
- Bảng
user_device(auth-level, KHÔNG company_id):(user_id, fingerprint)UNIQUE, status trusted/pending/revoked. Nền cho 2FA/WebAuthn per-device sau này - FE gửi
device_fingerprint(SHA-256 base64url,fingerprint.ts, KHÔNG gồm screen — đổi khi cắm màn ngoài) ở login + refresh - Fingerprint đóng vào refresh token value:
rt:{uid}:{rid}=<hash>(legacy) hoặc<hash>:fp:<fingerprint> DEVICE_BINDING_MODE=off|log|enforce: enforce → refresh với fp lệch storedFP = 401; log → chỉ seclogrefresh_fp_mismatch(đo tỷ lệ trước khi bật enforce); token legacy (không fp) luôn bỏ qua, tự nâng cấp ở rotation kế- API self-service:
GET /auth/devices,POST /auth/devices/:id/revoke— CHỈ thiết bị của chính user (GetOwnedscope theo user_id); FE ở menu profile - Upsert throttle:
Dao.Upsert(..., minTouchInterval)— login truyền 0 (luôn ghi), refresh truyền 1h (bỏ qua write nếu last_seen còn mới) → giảm tải hot-path refresh - Dọn nền:
user_device_cleanup(helpers.RunBackgroundở bootstrap, 24h) xoá devicelast_seenquádefine.UserDeviceStaleDays(90) — chống phình bảng pkg/seclog: structured security events (sec_eventfield) — login_success/failed, new_device, refresh_fp_mismatch, access_ip_mismatch, device_evicted/revoked, revoked_token_reused, ip_not_allowed.Eventno-op khilogger.Lnil (test/boot sớm)- Test:
pkg/token/token_device_test.go(miniredis) — fingerprint binding enforce/log, legacy upgrade, device limit cap, ConsumeRefresh, RevokeRefreshByFingerprint, ActiveFingerprints, revocation blacklist
Audit log (Hướng 2B — persist seclog vào DB)
seclog.InitSink(buf, flush)(wire ở bootstrap):EventđẩyEntryvào buffered channel → goroutine batch-INSERT (CreateInBatches). Non-blocking: channel đầy → drop +seclog.Dropped()đếm, KHÔNG chặn request. Flush do module audit cấp (seclog không import DB/DAO)Eventpromote keyuser_id/usernamesang cột, còn lại vàodetailJSON.- Bảng
security_audit_log(auth-level, TOÀN DB — D15/story-58 đã bỏ hẳn cộtcompany_id, 1 thương hiệu/DB nên không cần scope company nữa): index(user_id,created_at),(event,created_at) - API
GET /auth/audit-log: super-user only (RbacSvc.IsSuperUser— config module không có perm middleware), KHÔNG scope gì thêm — xem hết log của DB. paginate + filteruser_id / event (1) / events (nhóm, phẩy) / from / to. - Dọn nền
security_audit_cleanup(helpers.RunBackground, 24h) xoá quádefine.AuditRetentionDays(180) - FE: trang
config/security-audit(audit tổng) +log/login(lịch sử đăng nhập, module history) — cả 2 super-user, p-table lazy.authService.getAuditLog() - Test:
pkg/seclog/seclog_test.go— sink batch flush + field promotion + nil-logger no-panic
Login history (chi tiết kiểm soát đăng nhập)
login_failedmangreasontrong detail:user_not_found | bad_password | inactive | rate_limited. Distinction chỉ ở audit (super-user), response luôn genericlogin_failed— chống user enumeration- Login query bỏ
WHERE status=Active→ query theo username rồi check status (phân biệt not_found vs inactive). Rate-limit (429) giờ cũng ghilogin_failed reason=rate_limited login_failed(user thật) +logoutresolvecompanyActive_idsớm → hiện trong view theo company (trước đây NULL → vô hình)logoutevent ghi khi decode được bearer (user_id + company). Login là public route → resolve company qua query user_profile- FE
log/login(modules/history/login): gộp login_success/failed/logout/new_device/login_no_fingerprint qua?events=; cột reason + device. Menu gateisSuperUser()(không gắn permission để non-super khỏi thấy rồi 403)
FE TokenService API (post Cấp-2 refactor)
// ✅ Current API
tokenService.setTokens(accessToken: string, expiresAt?: number, refreshExpiresAt?: number)
tokenService.getAccessToken(): string | null // decrypts AES-GCM from localStorage
tokenService.hasValidToken: boolean
tokenService.hasValidRefreshSession(): boolean // checks refresh_token_expires_at timestamp only
tokenService.isRefreshTokenExpired(): boolean
tokenService.clearToken() // clears localStorage, cookie cleared by BE on logout
// ❌ REMOVED — do NOT use
// tokenService.getRefreshToken() → no longer exists (cookie is HttpOnly, JS cannot read)
// tokenService.setTokens(a, b, c, d) → 4-arg form removed
doRefresh — clearToken chỉ khi 401/403 (CRITICAL)
doRefresh() catch block không được gọi clearToken() cho mọi lỗi. Chỉ clear khi BE xác nhận token thực sự invalid:
// ✅ CORRECT (hiện tại)
} catch (err: any) {
const status = (err as any)?.status;
if (status === 401 || status === 403) {
this.clearToken(); // token thực sự hết hạn ở Redis
}
return false; // network/5xx: không xóa refresh_token_expires_at
}
// ❌ NEVER — clearToken với mọi lỗi
} catch (err: any) {
this.clearToken(); // lỗi mạng thoáng qua xóa refresh_token_expires_at
return false; // → isRefreshTokenExpired() = true → "session expired" giả
}
Lý do: clearToken() xóa refresh_token_expires_at khỏi localStorage. isRefreshTokenExpired() trả true khi key bị thiếu. Nếu auto-refresh timer gặp lỗi mạng và clear session, điều hướng kế tiếp sẽ báo "Refresh session expired" dù refresh token trong Redis vẫn còn hiệu lực.
Phân biệt 3 path:
- auto-refresh timer → network error:
doRefresh()retry backoff (status 0/5xx) rồi mới trả false, không clearToken → state giữ nguyên - API request → 401 → refresh fail (interceptor): chỉ clearToken khi
hasValidRefreshSession()= false; transient → propagate error, không logout - authGuard → trySilentRefresh fail: transient (session còn) → cho điều hướng tiếp, interceptor refresh lại ở 401 kế tiếp; chỉ redirect login khi session hết
Chi tiết retry/discriminator: frontend/skill/skills/handling-fe-auth-and-i18n/reference/fe-patterns-gotchas-auth.md §"refresh fail ≠ logout"
authGuard (post Cấp-2)
FE cannot read the refresh_token cookie. Guard checks expiry via timestamp only:
// ✅ Correct check
if (tokenService.isRefreshTokenExpired()) { redirect to /login }
// ❌ Old pattern — removed
// const rt = tokenService.getRefreshToken(); if (!rt) { redirect }
authInitialized — race với withEnabledBlockingInitialNavigation (CRITICAL)
withEnabledBlockingInitialNavigation() đăng ký APP_INITIALIZER riêng chạy song song với initializeAuth — không phải sau. Khi access token còn hạn: initialize() (crypto ~1ms) xong trước → hasValidToken=true → authGuard pass ngay → requirePerm chạy synchronous — nhưng IDB read trong restoreAuthUser() (~10–50ms) chưa xong → userPermissions = Set() rỗng → redirect /auth/accessdenied trên mọi deep route khi F5.
Xảy ra khi: auth storage dùng IndexedDB (async) + SW cache chunk (fast import) — cả hai cộng lại làm race đủ lớn để xảy ra deterministic.
Fix pattern (đã implement):
// auth.state.ts
export const authInitialized = signal(false);
// auth.service.ts — restoreAuthUser()
try { /* ... restore logic ... */ } finally { authInitialized.set(true); }
// authGuard.ts — waitInitialized$ tạo trong injection context (toObservable không gọi được trong switchMap)
const waitInitialized$ = authInitialized()
? of(true as const)
: toObservable(authInitialized).pipe(filter(Boolean), take(1), map(() => true as const));
// Dùng ở CẢ 2 path: hasValidToken = true VÀ silent-refresh thành công
// (refresh xong nhưng restoreAuthUser Case 1a còn đang fetch /me → phải đợi)
Overhead: chỉ xảy ra lần đầu tiên (F5 với token còn hạn). Mọi navigation sau đó authInitialized() đã true → zero overhead.
withCredentials
ApiService.createHttpOptions() sets withCredentials: true by default — all requests
automatically include cookies. No need to pass it explicitly at call sites.
Cấp 3 (NOT implemented — deferred)
Moving access_token to HttpOnly cookie would trade XSS risk for CSRF risk (no CSRF protection in place). Triggers to re-evaluate: SOC2 Type II audit, PCI-DSS scope expansion, or pen-test finding.
(đã bỏ, D15/CRM standalone) Client Auth (Đối tác — Zalo Mini App, website)
Module internal/modules/client/ (PartnerAuth, partners.company_id/companyActiveId,
GetPartnerCompanyID) KHÔNG còn tồn tại trong repo CRM standalone này — verify 2026-09-28:
internal/modules/ chỉ còn webapp/ (không có client//mobile//public/), không có
internal/middleware/partner_auth.go. Nội dung dưới đây (flow OAuth partner, JWT PartnerClaims,
GetPartnerID/GetPartnerCompanyID) mô tả kiến trúc ERP cũ trước khi tách CRM standalone — giữ
làm lịch sử, KHÔNG áp dụng. Skill building-client-and-sync-apis đã xoá khỏi CRM standalone.
Response format khác nhau
CRM — pkg/response/response.go
Data(c, data),DataWithMessage(c, data, msg),Validate(c, msg),NotFound(c),ServerError(c, err)
Client — pkg/response/client.go
ClientSuccess(c, data, msg)→{success: true, code: 200, message, data, timestamp}ClientError(c, msg, code)→{success: false, code, message, data: null, timestamp}ClientValidate(c, msg)→{success: false, code: 422, message, data: null, timestamp}
Router
api := r.Group("/api")
api.POST("/client/oauth/token", h.OAuthToken) // public
// CRM public: /auth/login, /auth/refresh-token, /auth/logout (xem Flow)
authed := api.Group("", middleware.JWTAuth(d.TokenSvc), middleware.AuthResponseHeaders(db, d.Cache)) // CRM
clientGroup := api.Group("/client", middleware.PartnerAuth()) // Client
2FA — TOTP (Hướng 3)
- Login 2 bước:
POST /auth/login→ nếu user bật 2FA + thiết bị chưa trusted → trả{requires_2fa, challenge_token}(CHƯA cấp token).POST /auth/login/2fa {challenge_token, code, remember_device}→ verify TOTP/backup → cấp token.challenge_token= JWT 5 phút aud=2fa-challenge(proof đã qua password). - Device-aware skip: bỏ qua 2FA CHỈ khi
user_device.totp_trusted_until > nowVÀ client trình đúng token remember-device (cookie HttpOnlydevice_trust_<userID>path/api/auth; mobile transport: bodydevice_trust_token) khớpuser_device.totp_trust_hash(SHA-256, so constant-time), thiết bị chưa revoked.remember_device⇒ server sinh token ngẫu nhiên 32 byte, hạn = now +business_profile.totp_trust_days(0 = luôn hỏi, cho máy dùng chung). ⚠ KHÔNG bao giờ tin riêngdevice_fingerprint— client tự tính từ UA/ngôn ngữ/múi giờ/CPU, đoán được (lỗ hổng vá 2026-10-20). Revoke thiết bị xoá trust. - Secret mã hóa AES-GCM bằng
TOTP_ENC_KEY(env riêng); backup codes hash sha256, 1 lần. Rate-limit verify 5 lần/5 phút. - Endpoints (authed):
/auth/2fa/status|setup|verify-setup|disable,/auth/2fa/reset/:userId(super-user). - Policy per-company + per-role:
company.require_2fa=1HOẶC role ∈company.require_2fa_roles. Bắt buộc mà chưa enroll →UserScope.MustSetup2FA=true→ AuthResponseHeaders chặn mọi API (trừ/auth/2fa/*,/auth/me,/auth/permission) với 403 code=2fa_setup_required→ FE interceptor redirect/2fa-setup. AuthResponseHeaderschạy các gate nối tiếp sau khi setbranchActiveId/branchIds: 2FA (code=2fa_setup_required, chặn mọi API trừ endpoint setup 2FA +/me) rồi IP allowlist (ip_not_allowed, modeenforce). ⚠ (đã bỏ, D15) Trước đây còn gate thứ 3 chặn khiGetCompanyActiveID(c)==0(code=company_active_required, FE redirect/choose-company) — đã xoá cùng company (1 thương hiệu/DB không cần chọn thương hiệu active).- Hai gate loại trừ nhau về cấu trúc:
require_2fa/require_2fa_roleslấy quaLEFT JOIN company c ON c.id = p.companyActive_id⇒companyActive_idNULL thì join rỗng ⇒MustSetup2FAluôn false. Nghĩa là chính sách 2FA theo thương hiệu KHÔNG đọc được khi chưa chọn thương hiệu, và thứ tự thật là chọn thương hiệu trước → 2FA sau (không phải ngược lại). Không có lỗ hổng: giữa hai bước, mọi API nghiệp vụ đều bị một trong hai gate chặn. - Prefix
/api/config/onboarding/được MIỄN gate (DB trắng chưa có thương hiệu nào thìswitch-profilevô dụng). Cửa này KHÔNG tự bảo vệ — handler tự kiểm super-user + bảngcompanyrỗng toàn bảng (khôngScopedDB*), tự đóng vĩnh viễn khi đã có company.bootstraptạo company/branch + gán active trong 1 transaction, tuần tự hoá bằng named lock kèm tên DB. - Module:
internal/modules/webapp/auth/twofa(servicepquerna/otp+ handler). FE:login.ts(challenge),twofa-setup/(enroll/disable + QRng-qrcode), menu profile "Bảo mật 2 lớp". - seclog:
2fa_challenge,2fa_failed,2fa_enrolled,2fa_disabled,2fa_reset.
Env
TOKEN_SECRET=<secret> # CRM JWT key
PARTNER_JWT_KEY=<different> # Client JWT key — PHẢI khác nhau
TOTP_ENC_KEY=<hex 64 chars> # mã hóa TOTP secret 2FA (openssl rand -hex 32) — prod BẮT BUỘC
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).