[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7F46PPNCK976F4SYWVHXAHC":3,"skill-same:01M7F46PPNCK976F4SYWVHXAHC":47},{"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},"01M7F46PPNCK976F4SYWVHXAHC","working-on-hr",null,"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.","cluvix\u002Fcluvix-crm","cluvix","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F324537109?v=4","01M7F40XX639HYM8HRW4JW1TA5","Cluvix Solutions","01M7F40XYG6YMX0CD0QZNV61K4",21,"AGPL-3.0","https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fworking-on-hr\u002FSKILL.md",[],[],"2026-11-16 10:05:34",false,"---\nname: working-on-hr\ndescription: >-\n  Quy tắc và pattern nghiệp vụ HR Cluvix trong CRM standalone: user nội bộ, role\u002FRBAC,\n  đổ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\n  hr (chỉ còn `hr\u002Fuser`) — trước khi đọc code.\n---\n\n# Working on HR\n\n\n\n\nModule quản lý user nội bộ: tài khoản, profile, role RBAC, EMR departments, import\u002Fexport.\n\n---\n\n## File map\n\n### Backend\n```\ninternal\u002Fmodules\u002Fwebapp\u002Fhr\u002Fuser\u002F\n├── route.go              # RegisterRoutes: gắn \u002Fhr\u002Fuser\u002F* + nested \u002Fuser\u002F:id\u002Fdepartments\n├── handler\u002Fhandler.go    # Tất cả handlers + BuildUserQuery + ImportUsers\n├── service\u002Fservice.go    # CRUD logic, cache, token revocation\n└── dao\u002Fentity.go         # User, UserProfile structs + TableName\n```\n\n### Frontend\n```\nsrc\u002Fapp\u002Fmodules\u002Fhr\u002Fuser\u002F\n├── user-list\u002Fuser-list.ts                              # Danh sách user, import, export, open form\n├── user-list\u002Fuser-import-result-dialog\u002F                # Dialog kết quả import (danh sách tài khoản + password mới)\n├── user-list\u002Fuser-reset-password-dialog\u002F               # Dialog đặt lại mật khẩu (FE chọn\u002Fgenerate pass, gửi lên BE)\n├── form\u002Fuser-form\u002Fuser-form.ts                         # Admin tạo\u002Fsửa user (có EMR dept assignment)\n├── form\u002Fuser-update-profile\u002F                           # User tự sửa profile cá nhân\n└── form\u002Fchange-password\u002F                               # User tự đổi mật khẩu\n```\n\n---\n\n## Tenant scope — ĐẶCBIỆT cho bảng `user` và `user_profile`\n\n`user` và `user_profile` **KHÔNG nằm trong `branchTables`** → `ScopedDBNullBranch(c, h.DB, \"user\")` \u002F `ScopedDBNullBranch(c, h.DB, \"user_profile\")` đều là **silent no-op** (không thêm WHERE nào).\n\n⚠ **(đã bỏ, D15\u002Fstory-58)** Trước 1 thương hiệu\u002FDB, `BuildUserQuery` còn tự thêm `JSON_CONTAINS`\nthủ công trên `u.companyId` (fallback `companyActiveID` → `companyIDs`). Đã bỏ hoàn toàn (D15) — mọi nhân\nviên trong DB thuộc thương hiệu duy nhất, KHÔNG cần lọc company nữa:\n\n```go\n\u002F\u002F ✅ BuildUserQuery hiện tại — không còn company filter, chỉ còn guard id \u003C> 1\nq := h.DB.Table(\"user u\").\n    Select(`u.id, u.id_old, u.username, u.status, u.branchId, ...`).\n    Joins(\"LEFT JOIN user_profile p ON p.user_id = u.id\").\n    Where(\"u.id \u003C> 1\")\n\u002F\u002F filter branch (nếu cần) qua query.ApplyJSONContainsFilter(c, q, \"branch_id\", \"u.branchId\")\n\u002F\u002F — đây là filter THEO QUERY PARAM tường minh của FE, không phải auto-scope theo session.\n```\n\nGuard IDOR của Update\u002FDelete\u002Fđổi mật khẩu (đi qua chính `BuildUserQuery`) nay là: tồn tại +\n`u.id \u003C> 1` + **phạm vi chi nhánh** + `targetIsProtectedSuper` — KHÔNG còn lớp company nào để verify thêm.\n\n**Phạm vi chi nhánh (2026-10-20)**: caller có `branchIds` ≠ rỗng và không phải super chỉ thấy\u002Fsửa nhân viên mà\nMỌI chi nhánh nằm trong phạm vi caller (`JSON_LENGTH(u.branchId) > 0 AND JSON_CONTAINS(\u003CbranchIds caller>, u.branchId)`).\nNhân viên chưa gán chi nhánh (= không giới hạn chi nhánh) chỉ caller không giới hạn mới quản lý. Tạo\u002Fsửa\u002Fimport:\n`branchListAllowed` — caller giới hạn chi nhánh không được tạo hoặc để nhân viên có `branchId` rỗng.\n\n**Gán role (2026-10-20)**: `roleAssignBlocked` — non-super chỉ gán được role mà mọi quyền của role ⊆ quyền của\nchính caller (`RbacSvc.PermissionsNotHeld`); role super (`define.SuperRoles`) chỉ super gán. Cùng luật ở\n`UpdatePermissionWithRole` (rbac): non-super chỉ cấp cho role quyền mình đang có.\n\n**Single-record ops (GetUser, UpdateUser, DeleteUser) đều phải qua BuildUserQuery** để prevent IDOR:\n```go\n\u002F\u002F ✅ Scope check trước khi sửa\u002Fxóa\nvar count int64\nh.BuildUserQuery(c).Where(\"u.id = ?\", uint(id)).Count(&count)\nif count == 0 { response.NotFound(c); return }\n```\n\n---\n\n## Response structure — nested\n\nFE nhận response dạng lồng `userProfile` + `userRole` (Yii2 compat):\n```json\n{\n  \"id\": 42,\n  \"username\": \"abc\",\n  \"status\": 10,\n  \"branchId\": [1,2],\n  \"updated_at\": 1760000000,\n  \"userProfile\": {\n    \"user_id\": 42,\n    \"fullname\": \"Nguyen Van A\",\n    \"phone\": \"0901234567\",\n    \"departmentList\": [1, 2],\n    ...\n  },\n  \"userRole\": { \"name\": \"manager\", \"description\": \"Quản lý\" }\n}\n```\n\n**parseGinH \u002F parseJSONInItems** — sau khi GORM trả `[]map[string]interface{}`, các JSON column về dạng string. Phải gọi helpers để parse thành `json.RawMessage`:\n```go\nhelpers.ParseJSONFieldsForTables(items, \"user\")  \u002F\u002F dùng cho GET \u002F:id\nparseJSONInItems(result.Items)                    \u002F\u002F dùng cho list (sau khi nest)\n```\n\n---\n\n## Service — key patterns\n\n### Optimistic locking (UpdateUser) — theo `updated_at` (D6, `pkg\u002Foptlock`)\n```go\n\u002F\u002F 1. Pre-check trước transaction (fast fail)\nif input.UpdatedAt != user.UpdatedAt {\n    return nil, errs.ErrVersionConflict\n}\n\u002F\u002F 2. Ghi có khoá: WHERE updated_at = ? + bump; 0 dòng ⇒ ErrVersionConflict\noptlock.Updates(tx.Model(&hrUserDao.User{}).Where(\"id = ?\", userID), input.UpdatedAt, updates)\n```\n\n### Token revocation\nKhi đổi `status` (và khi ChangePassword, DeleteUser) → revoke CẢ access token lẫn refresh token (đổi branch\u002Frole KHÔNG revoke — xem §Forced logout; vế `companyId` đã bỏ, D15):\n```go\nif needRevoke && s.TokenSvc != nil {\n    s.TokenSvc.RevokeAllSessions(userID)      \u002F\u002F JTI blacklist\n    s.TokenSvc.RevokeAllRefreshTokens(userID) \u002F\u002F prevent silent re-auth\n}\n```\nTương tự khi ChangePassword, DeleteUser.\n\n### Role update (trong transaction)\n```go\n\u002F\u002F Dùng tx (không phải s.DB) khi query role bên trong transaction\ntx.Table(\"rbac_auth_assignment\").Select(\"item_name\").Where(\"user_id = ?\", userID).Scan(&currentRole)\nif currentRole != *input.Role {\n    tx.Exec(\"DELETE FROM rbac_auth_assignment WHERE user_id = ?\", userID)\n    tx.Exec(\"INSERT INTO rbac_auth_assignment (item_name, user_id, created_at) VALUES (?, ?, ?)\", ...)\n    needRevoke = true\n}\n```\n\n### GetAllUsers — cache scope\nLuôn 1 khoá cache chung (story-58: bỏ lọc JSON `u.companyId`, 1 thương hiệu\u002FDB — D15); `invalidateCache` xoá đúng khoá đó.\n(Lịch sử: trước đây `useCache := len(companyIDs) == 0` — chỉ cache nhánh không lọc company; đã bỏ, D15.)\n\n### Forced logout — chỉ khi `status` thay đổi\n- `RevokeAllSessions` + `RevokeAllRefreshTokens` CHỈ khi `status` thay đổi (user bị vô hiệu hóa không được tiếp tục dùng app)\n- branch\u002Frole\u002Fdept: BE enforce per-request (UserScope + RBAC cache cleared) → KHÔNG cần revoke → user không bị logout\n- `BumpUserAuthVersion` chạy sau MỌI update (kể cả status) làm safety net\n\n### BumpUserAuthVersion — khi nào gọi\nGọi `middleware.BumpUserAuthVersion(s.Cache, userID)` sau khi commit profile update khi `!needRevoke && input.UserProfile != nil`.\n- KHÔNG gọi khi `needRevoke=true` (token refresh flow đã lo sync FE)\n- KHÔNG gọi khi đổi password (token bị revoke → FE tự fetchAndSyncMe sau refresh)\n- Hàm nằm trong `internal\u002Fmiddleware\u002Fresponse_headers.go`, cần import middleware package vào service\n\n---\n\n## Handler — ChangePassword vs ResetPassword vs UpdatePassword\n\n| Endpoint | Dùng khi | Xác thực |\n|---|---|---|\n| `PUT \u002Fhr\u002Fuser\u002Freset-password` | Admin đặt lại pass cho user — **FE chọn\u002Fgenerate password** | Không cần old password; BE validate tenant scope qua `BuildUserQuery` (prevent IDOR); min 6 ký tự |\n| `POST \u002Fhr\u002Fuser\u002Fchange-password` | Admin reset pass (legacy endpoint, vẫn còn) | Không cần old password, cần `id` target |\n| `POST \u002Fhr\u002Fuser\u002Fupdate-password` | User tự đổi pass chính mình | Phải nhập `oldpassword` + `newpassword` + `newpasswordrepeat` |\n\nCả 3 đều: hash bcrypt cost 12, call `ChangePassword(userID, newPass)` trong service → auto revoke sessions.\n\n**IDOR check bắt buộc cho reset-password:**\n```go\n\u002F\u002F Dùng BuildUserQuery (KHÔNG ScopedDBNullBranch trực tiếp) vì user table dùng JSON array scope\nvar exists int64\nh.BuildUserQuery(c).Where(\"u.id = ?\", body.ID).Count(&exists)\nif exists == 0 { response.NotFound(c); return }\n```\n\n---\n\n## ImportUsers — N+1 fix\n\n**Trước khi bắt đầu transaction**: pre-scan toàn bộ rows để batch load:\n```go\n\u002F\u002F 1. Batch load phone → userId (tránh per-row query \"ai đang dùng phone này\")\nvar phonePreRows []struct{ UserID uint; Phone string }\nh.DB.Table(\"user_profile\").Select(\"user_id, phone\").Where(\"phone IN ?\", phonesInFile).Find(&phonePreRows)\nphoneOwner := make(map[string]uint)\n\n\u002F\u002F 2. Batch load profileExists (tránh per-row COUNT)\nvar pidPreRows []struct{ UserID uint }\nh.DB.Table(\"user_profile\").Select(\"user_id\").Where(\"user_id IN ?\", updateIDsInFile).Find(&pidPreRows)\nprofileExists := make(map[uint]bool)\n\n\u002F\u002F 3. Trong loop: sau khi CREATE profile mới → cập nhật map\nprofileExists[currentUserID] = true  \u002F\u002F tránh duplicate key nếu cùng ID xuất hiện 2 lần\n```\n\n`importEmrDepartments` — tương tự: pre-load existing assignments trước khi vòng lặp insert.\n\n---\n\n## Frontend — UserForm (admin)\n\n`user-form.ts` — admin tạo\u002Fsửa user.\n\n### EMR department flow — ĐÃ BỎ (lịch sử)\nGán khoa EMR cho user (`emrDeptRows`, `saveDepartments`, \"1 primary per `company_id`\" — lịch sử, D15) đã xoá cùng\nmodule `hr\u002Fuser_emr_department` (story-12) và company (D15). Form nay submit 1 lệnh `updateUser`\u002F`create`.\n\n### onSubmit pattern\n```typescript\nconst payload = this.getPayload();\nconst saveOp = this.isEditMode()\n  ? this.modelService.updateUser(modelId!, payload, {})\n  : this.modelService.create(payload, {});\nsaveOp.pipe(finalize(() => this.isSubmitting.set(false))).subscribe({ ... });\n```\n\n### Self-edit (admin sửa chính mình)\n```typescript\nif (this.isEditMode() && modelId === userId()) {\n  this.syncAuthUserIfSelf();  \u002F\u002F sync branchId vào authUser signal + localStorage (companyId\u002Fdepartments đã bỏ, D15)\n  sessionStorage.setItem('post_reload_toast', translate.instant('...'));\n  location.reload();  \u002F\u002F phải reload để JWT context refresh\n  return;\n}\n```\n\n---\n\n## Frontend — UserChangePassword\n\nValidator cross-field mismatch cần kích hoạt lại khi `newpassword` thay đổi:\n```typescript\nthis.rfModel.get('newpassword')!.valueChanges\n  .pipe(takeUntilDestroyed(this.destroyRef))\n  .subscribe(() => this.rfModel.get('newpasswordrepeat')!.updateValueAndValidity());\n```\n\n`newpassword` phải có `Validators.minLength(6)` (match BE validation ≥6 chars).\n\nSau khi đổi password thành công → BE revoke all tokens → FE phải logout ngay:\n```typescript\nsetTimeout(() => this.authService.handleRefreshTokenExpired(), 1500);  \u002F\u002F delay để user đọc toast\n```\n\n---\n\n## Frontend — UserUpdateProfile\n\n`birthday` timezone trap:\n```typescript\n\u002F\u002F ❌ NEVER — new Date(\"2000-01-15\") → UTC midnight → hiển thị 14\u002F01 ở GMT+7\nbirthday: new Date(res.birthday)\n\n\u002F\u002F ✅ ALWAYS — append T00:00:00 để parse local time\nbirthday: new Date(res.birthday + 'T00:00:00')\n```\n\n`srcImageUpload` type — phải là `string | null` không phải `!: any`:\n```typescript\nsrcImageUpload: string | null = null;\n```\n\n---\n\n## Toast duplicates — KHÔNG dùng `\u003Cp-toast>` local\n\n`app.component.ts` đã có 1 global `\u003Cp-toast position=\"top-right\" \u002F>`.  \nPrimeNG `MessageService` broadcast tới **tất cả** `\u003Cp-toast>` instance trong DOM.  \n→ KHÔNG thêm `\u003Cp-toast \u002F>` vào từng page\u002Fcomponent con (attendance.html, schedule.html, ...).\n\n---\n\n## i18n keys liên quan\n\n| Key | Nội dung |\n|---|---|\n| `user_updated` | Cập nhật người dùng thành công |\n| `password_changed` | Đổi mật khẩu thành công |\n| `password_min` | Mật khẩu tối thiểu 6 ký tự |\n| `password_confirm_mismatch` | Mật khẩu xác nhận không khớp |\n| `password_old_wrong` | Mật khẩu cũ không đúng |\n| `import_success` | Import thành công |\n\n---\n\n## Per-user IndexedDB auth session\n\nStore `userAuthSession` trong IndexedDB `cluvixData` — lưu user data + permissions + authVersion **riêng từng user**.\n\n**Đặc điểm:**\n- keyPath: `userId` (KHÔNG phải `id`) — isolated by user, multi-user cùng browser không xung đột\n- KHÔNG add vào Dexie global sync (`X-Dexie-Versions`) — chỉ sync khi BE báo version lệch\n- Migration: fallback localStorage `auth_user` key cho session cũ, tự migrate sau lần save kế tiếp\n- `auth_user_id` (localStorage, number) — lightweight boot marker để biết load IDB entry nào\n\n**2 sync triggers:**\n1. Token revocation → FE nhận 401 → silent refresh → `fetchAndSyncMe()` (gọi `\u002Fapi\u002Fauth\u002Fme`, cập nhật signals + IDB)\n2. Header `X-User-Auth-Version: {userId}:{timestamp}` lệch → `isStale()` → `fetchAndSyncMe()`\n\n**`X-User-Auth-Version` header flow:**\n- BE set header này trong mọi response (từ `AuthResponseHeaders` middleware), giá trị = Redis key `auth:user_auth_ver:{userID}`\n- `BumpUserAuthVersion(cache, userID)` ghi Redis key với TTL 30 ngày — gọi khi profile update không revoke token\n- FE kiểm tra trong `response-handler.interceptor.ts` → chỉ trigger sync khi `headerUserId === currentUserId`\n- Cập nhật `_cachedAuthVersion` + `userAuthSession.updateAuthVersion()` **trước** khi gọi `fetchAndSyncMe()` để tránh loop\n\n---\n\n## Endpoints summary\n\n```\nGET    \u002Fhr\u002Fuser                     # list + filter + export\nGET    \u002Fhr\u002Fuser\u002Fget-all-users       # dropdown\u002Fsync (JSON array, no pagination)\nGET    \u002Fhr\u002Fuser\u002F:id                 # single record\nPOST   \u002Fhr\u002Fuser                     # create\nPUT    \u002Fhr\u002Fuser\u002F:id                 # update (optimistic lock)\nDELETE \u002Fhr\u002Fuser\u002F:id                 # soft delete (status = define.UserStatusDeleted = 1)\nPOST   \u002Fhr\u002Fuser\u002Fchange-password     # admin reset pass của user khác\nPOST   \u002Fhr\u002Fuser\u002Fupdate-password     # user tự đổi pass (verify old pass)\nPUT    \u002Fhr\u002Fuser\u002Freset-password      # admin đặt lại pass (FE gửi password, BE validate + apply)\nPOST   \u002Fhr\u002Fuser\u002Fimport-users        # import Excel\nGET    \u002Fhr\u002Fuser\u002Fget-template        # download import template\n```\n\n**Status thật của `user`:** 10=Active, 9=Inactive (vô hiệu hóa tạm thời, KHÔNG phải nghỉ việc), 1=Deleted (soft-delete qua DeleteUser) — comment GORM cũ trong `entity.go` ghi sai (\"0=Inactive, 9=Deleted\"), đừng tin theo.\n","# Working on HR\n\n\n\n\nModule quản lý user nội bộ: tài khoản, profile, role RBAC, EMR departments, import\u002Fexport.\n\n---\n\n## File map\n\n### Backend\n```\ninternal\u002Fmodules\u002Fwebapp\u002Fhr\u002Fuser\u002F\n├── route.go              # RegisterRoutes: gắn \u002Fhr\u002Fuser\u002F* + nested \u002Fuser\u002F:id\u002Fdepartments\n├── handler\u002Fhandler.go    # Tất cả handlers + BuildUserQuery + ImportUsers\n├── service\u002Fservice.go    # CRUD logic, cache, token revocation\n└── dao\u002Fentity.go         # User, UserProfile structs + TableName\n```\n\n### Frontend\n```\nsrc\u002Fapp\u002Fmodules\u002Fhr\u002Fuser\u002F\n├── user-list\u002Fuser-list.ts                              # Danh sách user, import, export, open form\n├── user-list\u002Fuser-import-result-dialog\u002F                # Dialog kết quả import (danh sách tài khoản + password mới)\n├── user-list\u002Fuser-reset-password-dialog\u002F               # Dialog đặt lại mật khẩu (FE chọn\u002Fgenerate pass, gửi lên BE)\n├── form\u002Fuser-form\u002Fuser-form.ts                         # Admin tạo\u002Fsửa user (có EMR dept assignment)\n├── form\u002Fuser-update-profile\u002F                           # User tự sửa profile cá nhân\n└── form\u002Fchange-password\u002F                               # User tự đổi mật khẩu\n```\n\n---\n\n## Tenant scope — ĐẶCBIỆT cho bảng `user` và `user_profile`\n\n`user` và `user_profile` **KHÔNG nằm trong `branchTables`** → `ScopedDBNullBranch(c, h.DB, \"user\")` \u002F `ScopedDBNullBranch(c, h.DB, \"user_profile\")` đều là **silent no-op** (không thêm WHERE nào).\n\n⚠ **(đã bỏ, D15\u002Fstory-58)** Trước 1 thương hiệu\u002FDB, `BuildUserQuery` còn tự thêm `JSON_CONTAINS`\nthủ công trên `u.companyId` (fallback `companyActiveID` → `companyIDs`). Đã bỏ hoàn toàn (D15) — mọi nhân\nviên trong DB thuộc thương hiệu duy nhất, KHÔNG cần lọc company nữa:\n\n```go\n\u002F\u002F ✅ BuildUserQuery hiện tại — không còn company filter, chỉ còn guard id \u003C> 1\nq := h.DB.Table(\"user u\").\n    Select(`u.id, u.id_old, u.username, u.status, u.branchId, ...`).\n    Joins(\"LEFT JOIN user_profile p ON p.user_id = u.id\").\n    Where(\"u.id \u003C> 1\")\n\u002F\u002F filter branch (nếu cần) qua query.ApplyJSONContainsFilter(c, q, \"branch_id\", \"u.branchId\")\n\u002F\u002F — đây là filter THEO QUERY PARAM tường minh của FE, không phải auto-scope theo session.\n```\n\nGuard IDOR của Update\u002FDelete\u002Fđổi mật khẩu (đi qua chính `BuildUserQuery`) nay là: tồn tại +\n`u.id \u003C> 1` + **phạm vi chi nhánh** + `targetIsProtectedSuper` — KHÔNG còn lớp company nào để verify thêm.\n\n**Phạm vi chi nhánh (2026-10-20)**: caller có `branchIds` ≠ rỗng và không phải super chỉ thấy\u002Fsửa nhân viên mà\nMỌI chi nhánh nằm trong phạm vi caller (`JSON_LENGTH(u.branchId) > 0 AND JSON_CONTAINS(\u003CbranchIds caller>, u.branchId)`).\nNhân viên chưa gán chi nhánh (= không giới hạn chi nhánh) chỉ caller không giới hạn mới quản lý. Tạo\u002Fsửa\u002Fimport:\n`branchListAllowed` — caller giới hạn chi nhánh không được tạo hoặc để nhân viên có `branchId` rỗng.\n\n**Gán role (2026-10-20)**: `roleAssignBlocked` — non-super chỉ gán được role mà mọi quyền của role ⊆ quyền của\nchính caller (`RbacSvc.PermissionsNotHeld`); role super (`define.SuperRoles`) chỉ super gán. Cùng luật ở\n`UpdatePermissionWithRole` (rbac): non-super chỉ cấp cho role quyền mình đang có.\n\n**Single-record ops (GetUser, UpdateUser, DeleteUser) đều phải qua BuildUserQuery** để prevent IDOR:\n```go\n\u002F\u002F ✅ Scope check trước khi sửa\u002Fxóa\nvar count int64\nh.BuildUserQuery(c).Where(\"u.id = ?\", uint(id)).Count(&count)\nif count == 0 { response.NotFound(c); return }\n```\n\n---\n\n## Response structure — nested\n\nFE nhận response dạng lồng `userProfile` + `userRole` (Yii2 compat):\n```json\n{\n  \"id\": 42,\n  \"username\": \"abc\",\n  \"status\": 10,\n  \"branchId\": [1,2],\n  \"updated_at\": 1760000000,\n  \"userProfile\": {\n    \"user_id\": 42,\n    \"fullname\": \"Nguyen Van A\",\n    \"phone\": \"0901234567\",\n    \"departmentList\": [1, 2],\n    ...\n  },\n  \"userRole\": { \"name\": \"manager\", \"description\": \"Quản lý\" }\n}\n```\n\n**parseGinH \u002F parseJSONInItems** — sau khi GORM trả `[]map[string]interface{}`, các JSON column về dạng string. Phải gọi helpers để parse thành `json.RawMessage`:\n```go\nhelpers.ParseJSONFieldsForTables(items, \"user\")  \u002F\u002F dùng cho GET \u002F:id\nparseJSONInItems(result.Items)                    \u002F\u002F dùng cho list (sau khi nest)\n```\n\n---\n\n## Service — key patterns\n\n### Optimistic locking (UpdateUser) — theo `updated_at` (D6, `pkg\u002Foptlock`)\n```go\n\u002F\u002F 1. Pre-check trước transaction (fast fail)\nif input.UpdatedAt != user.UpdatedAt {\n    return nil, errs.ErrVersionConflict\n}\n\u002F\u002F 2. Ghi có khoá: WHERE updated_at = ? + bump; 0 dòng ⇒ ErrVersionConflict\noptlock.Updates(tx.Model(&hrUserDao.User{}).Where(\"id = ?\", userID), input.UpdatedAt, updates)\n```\n\n### Token revocation\nKhi đổi `status` (và khi ChangePassword, DeleteUser) → revoke CẢ access token lẫn refresh token (đổi branch\u002Frole KHÔNG revoke — xem §Forced logout; vế `companyId` đã bỏ, D15):\n```go\nif needRevoke && s.TokenSvc != nil {\n    s.TokenSvc.RevokeAllSessions(userID)      \u002F\u002F JTI blacklist\n    s.TokenSvc.RevokeAllRefreshTokens(userID) \u002F\u002F prevent silent re-auth\n}\n```\nTương tự khi ChangePassword, DeleteUser.\n\n### Role update (trong transaction)\n```go\n\u002F\u002F Dùng tx (không phải s.DB) khi query role bên trong transaction\ntx.Table(\"rbac_auth_assignment\").Select(\"item_name\").Where(\"user_id = ?\", userID).Scan(&currentRole)\nif currentRole != *input.Role {\n    tx.Exec(\"DELETE FROM rbac_auth_assignment WHERE user_id = ?\", userID)\n    tx.Exec(\"INSERT INTO rbac_auth_assignment (item_name, user_id, created_at) VALUES (?, ?, ?)\", ...)\n    needRevoke = true\n}\n```\n\n### GetAllUsers — cache scope\nLuôn 1 khoá cache chung (story-58: bỏ lọc JSON `u.companyId`, 1 thương hiệu\u002FDB — D15); `invalidateCache` xoá đúng khoá đó.\n(Lịch sử: trước đây `useCache := len(companyIDs) == 0` — chỉ cache nhánh không lọc company; đã bỏ, D15.)\n\n### Forced logout — chỉ khi `status` thay đổi\n- `RevokeAllSessions` + `RevokeAllRefreshTokens` CHỈ khi `status` thay đổi (user bị vô hiệu hóa không được tiếp tục dùng app)\n- branch\u002Frole\u002Fdept: BE enforce per-request (UserScope + RBAC cache cleared) → KHÔNG cần revoke → user không bị logout\n- `BumpUserAuthVersion` chạy sau MỌI update (kể cả status) làm safety net\n\n### BumpUserAuthVersion — khi nào gọi\nGọi `middleware.BumpUserAuthVersion(s.Cache, userID)` sau khi commit profile update khi `!needRevoke && input.UserProfile != nil`.\n- KHÔNG gọi khi `needRevoke=true` (token refresh flow đã lo sync FE)\n- KHÔNG gọi khi đổi password (token bị revoke → FE tự fetchAndSyncMe sau refresh)\n- Hàm nằm trong `internal\u002Fmiddleware\u002Fresponse_headers.go`, cần import middleware package vào service\n\n---\n\n## Handler — ChangePassword vs ResetPassword vs UpdatePassword\n\n| Endpoint | Dùng khi | Xác thực |\n|---|---|---|\n| `PUT \u002Fhr\u002Fuser\u002Freset-password` | Admin đặt lại pass cho user — **FE chọn\u002Fgenerate password** | Không cần old password; BE validate tenant scope qua `BuildUserQuery` (prevent IDOR); min 6 ký tự |\n| `POST \u002Fhr\u002Fuser\u002Fchange-password` | Admin reset pass (legacy endpoint, vẫn còn) | Không cần old password, cần `id` target |\n| `POST \u002Fhr\u002Fuser\u002Fupdate-password` | User tự đổi pass chính mình | Phải nhập `oldpassword` + `newpassword` + `newpasswordrepeat` |\n\nCả 3 đều: hash bcrypt cost 12, call `ChangePassword(userID, newPass)` trong service → auto revoke sessions.\n\n**IDOR check bắt buộc cho reset-password:**\n```go\n\u002F\u002F Dùng BuildUserQuery (KHÔNG ScopedDBNullBranch trực tiếp) vì user table dùng JSON array scope\nvar exists int64\nh.BuildUserQuery(c).Where(\"u.id = ?\", body.ID).Count(&exists)\nif exists == 0 { response.NotFound(c); return }\n```\n\n---\n\n## ImportUsers — N+1 fix\n\n**Trước khi bắt đầu transaction**: pre-scan toàn bộ rows để batch load:\n```go\n\u002F\u002F 1. Batch load phone → userId (tránh per-row query \"ai đang dùng phone này\")\nvar phonePreRows []struct{ UserID uint; Phone string }\nh.DB.Table(\"user_profile\").Select(\"user_id, phone\").Where(\"phone IN ?\", phonesInFile).Find(&phonePreRows)\nphoneOwner := make(map[string]uint)\n\n\u002F\u002F 2. Batch load profileExists (tránh per-row COUNT)\nvar pidPreRows []struct{ UserID uint }\nh.DB.Table(\"user_profile\").Select(\"user_id\").Where(\"user_id IN ?\", updateIDsInFile).Find(&pidPreRows)\nprofileExists := make(map[uint]bool)\n\n\u002F\u002F 3. Trong loop: sau khi CREATE profile mới → cập nhật map\nprofileExists[currentUserID] = true  \u002F\u002F tránh duplicate key nếu cùng ID xuất hiện 2 lần\n```\n\n`importEmrDepartments` — tương tự: pre-load existing assignments trước khi vòng lặp insert.\n\n---\n\n## Frontend — UserForm (admin)\n\n`user-form.ts` — admin tạo\u002Fsửa user.\n\n### EMR department flow — ĐÃ BỎ (lịch sử)\nGán khoa EMR cho user (`emrDeptRows`, `saveDepartments`, \"1 primary per `company_id`\" — lịch sử, D15) đã xoá cùng\nmodule `hr\u002Fuser_emr_department` (story-12) và company (D15). Form nay submit 1 lệnh `updateUser`\u002F`create`.\n\n### onSubmit pattern\n```typescript\nconst payload = this.getPayload();\nconst saveOp = this.isEditMode()\n  ? this.modelService.updateUser(modelId!, payload, {})\n  : this.modelService.create(payload, {});\nsaveOp.pipe(finalize(() => this.isSubmitting.set(false))).subscribe({ ... });\n```\n\n### Self-edit (admin sửa chính mình)\n```typescript\nif (this.isEditMode() && modelId === userId()) {\n  this.syncAuthUserIfSelf();  \u002F\u002F sync branchId vào authUser signal + localStorage (companyId\u002Fdepartments đã bỏ, D15)\n  sessionStorage.setItem('post_reload_toast', translate.instant('...'));\n  location.reload();  \u002F\u002F phải reload để JWT context refresh\n  return;\n}\n```\n\n---\n\n## Frontend — UserChangePassword\n\nValidator cross-field mismatch cần kích hoạt lại khi `newpassword` thay đổi:\n```typescript\nthis.rfModel.get('newpassword')!.valueChanges\n  .pipe(takeUntilDestroyed(this.destroyRef))\n  .subscribe(() => this.rfModel.get('newpasswordrepeat')!.updateValueAndValidity());\n```\n\n`newpassword` phải có `Validators.minLength(6)` (match BE validation ≥6 chars).\n\nSau khi đổi password thành công → BE revoke all tokens → FE phải logout ngay:\n```typescript\nsetTimeout(() => this.authService.handleRefreshTokenExpired(), 1500);  \u002F\u002F delay để user đọc toast\n```\n\n---\n\n## Frontend — UserUpdateProfile\n\n`birthday` timezone trap:\n```typescript\n\u002F\u002F ❌ NEVER — new Date(\"2000-01-15\") → UTC midnight → hiển thị 14\u002F01 ở GMT+7\nbirthday: new Date(res.birthday)\n\n\u002F\u002F ✅ ALWAYS — append T00:00:00 để parse local time\nbirthday: new Date(res.birthday + 'T00:00:00')\n```\n\n`srcImageUpload` type — phải là `string | null` không phải `!: any`:\n```typescript\nsrcImageUpload: string | null = null;\n```\n\n---\n\n## Toast duplicates — KHÔNG dùng `\u003Cp-toast>` local\n\n`app.component.ts` đã có 1 global `\u003Cp-toast position=\"top-right\" \u002F>`.  \nPrimeNG `MessageService` broadcast tới **tất cả** `\u003Cp-toast>` instance trong DOM.  \n→ KHÔNG thêm `\u003Cp-toast \u002F>` vào từng page\u002Fcomponent con (attendance.html, schedule.html, ...).\n\n---\n\n## i18n keys liên quan\n\n| Key | Nội dung |\n|---|---|\n| `user_updated` | Cập nhật người dùng thành công |\n| `password_changed` | Đổi mật khẩu thành công |\n| `password_min` | Mật khẩu tối thiểu 6 ký tự |\n| `password_confirm_mismatch` | Mật khẩu xác nhận không khớp |\n| `password_old_wrong` | Mật khẩu cũ không đúng |\n| `import_success` | Import thành công |\n\n---\n\n## Per-user IndexedDB auth session\n\nStore `userAuthSession` trong IndexedDB `cluvixData` — lưu user data + permissions + authVersion **riêng từng user**.\n\n**Đặc điểm:**\n- keyPath: `userId` (KHÔNG phải `id`) — isolated by user, multi-user cùng browser không xung đột\n- KHÔNG add vào Dexie global sync (`X-Dexie-Versions`) — chỉ sync khi BE báo version lệch\n- Migration: fallback localStorage `auth_user` key cho session cũ, tự migrate sau lần save kế tiếp\n- `auth_user_id` (localStorage, number) — lightweight boot marker để biết load IDB entry nào\n\n**2 sync triggers:**\n1. Token revocation → FE nhận 401 → silent refresh → `fetchAndSyncMe()` (gọi `\u002Fapi\u002Fauth\u002Fme`, cập nhật signals + IDB)\n2. Header `X-User-Auth-Version: {userId}:{timestamp}` lệch → `isStale()` → `fetchAndSyncMe()`\n\n**`X-User-Auth-Version` header flow:**\n- BE set header này trong mọi response (từ `AuthResponseHeaders` middleware), giá trị = Redis key `auth:user_auth_ver:{userID}`\n- `BumpUserAuthVersion(cache, userID)` ghi Redis key với TTL 30 ngày — gọi khi profile update không revoke token\n- FE kiểm tra trong `response-handler.interceptor.ts` → chỉ trigger sync khi `headerUserId === currentUserId`\n- Cập nhật `_cachedAuthVersion` + `userAuthSession.updateAuthVersion()` **trước** khi gọi `fetchAndSyncMe()` để tránh loop\n\n---\n\n## Endpoints summary\n\n```\nGET    \u002Fhr\u002Fuser                     # list + filter + export\nGET    \u002Fhr\u002Fuser\u002Fget-all-users       # dropdown\u002Fsync (JSON array, no pagination)\nGET    \u002Fhr\u002Fuser\u002F:id                 # single record\nPOST   \u002Fhr\u002Fuser                     # create\nPUT    \u002Fhr\u002Fuser\u002F:id                 # update (optimistic lock)\nDELETE \u002Fhr\u002Fuser\u002F:id                 # soft delete (status = define.UserStatusDeleted = 1)\nPOST   \u002Fhr\u002Fuser\u002Fchange-password     # admin reset pass của user khác\nPOST   \u002Fhr\u002Fuser\u002Fupdate-password     # user tự đổi pass (verify old pass)\nPUT    \u002Fhr\u002Fuser\u002Freset-password      # admin đặt lại pass (FE gửi password, BE validate + apply)\nPOST   \u002Fhr\u002Fuser\u002Fimport-users        # import Excel\nGET    \u002Fhr\u002Fuser\u002Fget-template        # download import template\n```\n\n**Status thật của `user`:** 10=Active, 9=Inactive (vô hiệu hóa tạm thời, KHÔNG phải nghỉ việc), 1=Deleted (soft-delete qua DeleteUser) — comment GORM cũ trong `entity.go` ghi sai (\"0=Inactive, 9=Deleted\"), đừng tin theo.\n",{"name":5,"description":7},"main","ea9f5ed9bd4eaf32e9489bcbe9603955c1462a63","skill\u002Fskills\u002Fworking-on-hr",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 working-on-hr",{"tool":39,"command":40},"bunx","bunx skills add cluvix\u002Fcluvix-crm --skill working-on-hr",{"tool":42,"command":43},"pnpm","pnpm dlx skills add cluvix\u002Fcluvix-crm --skill working-on-hr","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fworking-on-hr\u002FSKILL.md",true,[],[48,55,62,69,76,83],{"skillNo":49,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"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":56,"name":57,"nameZh":6,"description":58,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":61,"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":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"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":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"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":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M7F45Y15Q0CBEP06CFF2AAEY","working-on-config","Quy tắc và pattern nghiệp vụ Config Cluvix còn sống trong CRM standalone: mẫu in (print_template), control field trong bảng (control_field_in_table), IndexedDB sync của config. Dùng skill này KHI làm feature\u002Fsửa bug đụng các module đó — trước khi đọc code. Tổng đài\u002Fchữ ký số\u002FAI config đã bỏ (chỉ còn mô tả lịch sử trong skill, KHÔNG áp dụng).","https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Fworking-on-config\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M7F45FK4E7YJ0MENAWJT9NGY","testing-backend","Hạ tầng test Go: unit test, integration test với TEST_MYSQL_DSN (MySQL disposable thật, KHÔNG dockertest), FreshTenant helper, HTTP handler test qua httptest, và mutation test (`go test -overlay`) để chứng minh test thật sự neo hành vi. Dùng skill này TRƯỚC KHI viết test mới cho backend Go, khi cần biết cách dựng DB test sạch mỗi lần chạy, trước khi báo một AC dạng phủ định\u002Fmặc định là Done, hoặc trước khi verify build\u002Ftest theo Development Protocol bước 4 (Validate).","https:\u002F\u002Fgithub.com\u002Fcluvix\u002Fcluvix-crm\u002Fblob\u002Fmain\u002Fskill\u002Fskills\u002Ftesting-backend\u002FSKILL.md",[],[]]