AGENT SKILL

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.

License 许可
AGPL-3.0
所属仓库
cluvix/cluvix-crm
最近更新
2026-11-02
Stars
★ 21
Forks
20

01 前言 Front Matter

name
working-on-hr
description
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.

03 SKILL.md 正文

Working on HR

Module quản lý user nội bộ: tài khoản, profile, role RBAC, EMR departments, import/export.


File map

Backend

internal/modules/webapp/hr/user/
├── route.go              # RegisterRoutes: gắn /hr/user/* + nested /user/:id/departments
├── handler/handler.go    # Tất cả handlers + BuildUserQuery + ImportUsers
├── service/service.go    # CRUD logic, cache, token revocation
└── dao/entity.go         # User, UserProfile structs + TableName

Frontend

src/app/modules/hr/user/
├── user-list/user-list.ts                              # Danh sách user, import, export, open form
├── user-list/user-import-result-dialog/                # Dialog kết quả import (danh sách tài khoản + password mới)
├── user-list/user-reset-password-dialog/               # Dialog đặt lại mật khẩu (FE chọn/generate pass, gửi lên BE)
├── form/user-form/user-form.ts                         # Admin tạo/sửa user (có EMR dept assignment)
├── form/user-update-profile/                           # User tự sửa profile cá nhân
└── form/change-password/                               # User tự đổi mật khẩu

Tenant scope — ĐẶCBIỆT cho bảng user và user_profile

user và user_profile KHÔNG nằm trong branchTables → ScopedDBNullBranch(c, h.DB, "user") / ScopedDBNullBranch(c, h.DB, "user_profile") đều là silent no-op (không thêm WHERE nào).

⚠ (đã bỏ, D15/story-58) Trước 1 thương hiệu/DB, BuildUserQuery còn tự thêm JSON_CONTAINS thủ công trên u.companyId (fallback companyActiveID → companyIDs). Đã bỏ hoàn toàn (D15) — mọi nhân viên trong DB thuộc thương hiệu duy nhất, KHÔNG cần lọc company nữa:

// ✅ BuildUserQuery hiện tại — không còn company filter, chỉ còn guard id <> 1
q := h.DB.Table("user u").
    Select(`u.id, u.id_old, u.username, u.status, u.branchId, ...`).
    Joins("LEFT JOIN user_profile p ON p.user_id = u.id").
    Where("u.id <> 1")
// filter branch (nếu cần) qua query.ApplyJSONContainsFilter(c, q, "branch_id", "u.branchId")
// — đây là filter THEO QUERY PARAM tường minh của FE, không phải auto-scope theo session.

Guard IDOR của Update/Delete/đổi mật khẩu (đi qua chính BuildUserQuery) nay là: tồn tại + u.id <> 1 + phạm vi chi nhánh + targetIsProtectedSuper — KHÔNG còn lớp company nào để verify thêm.

Phạm vi chi nhánh (2026-10-20): caller có branchIds ≠ rỗng và không phải super chỉ thấy/sửa nhân viên mà MỌI chi nhánh nằm trong phạm vi caller (JSON_LENGTH(u.branchId) > 0 AND JSON_CONTAINS(<branchIds caller>, u.branchId)). Nhâ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/sửa/import: branchListAllowed — caller giới hạn chi nhánh không được tạo hoặc để nhân viên có branchId rỗng.

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 chính caller (RbacSvc.PermissionsNotHeld); role super (define.SuperRoles) chỉ super gán. Cùng luật ở UpdatePermissionWithRole (rbac): non-super chỉ cấp cho role quyền mình đang có.

Single-record ops (GetUser, UpdateUser, DeleteUser) đều phải qua BuildUserQuery để prevent IDOR:

// ✅ Scope check trước khi sửa/xóa
var count int64
h.BuildUserQuery(c).Where("u.id = ?", uint(id)).Count(&count)
if count == 0 { response.NotFound(c); return }

Response structure — nested

FE nhận response dạng lồng userProfile + userRole (Yii2 compat):

{
  "id": 42,
  "username": "abc",
  "status": 10,
  "branchId": [1,2],
  "updated_at": 1760000000,
  "userProfile": {
    "user_id": 42,
    "fullname": "Nguyen Van A",
    "phone": "0901234567",
    "departmentList": [1, 2],
    ...
  },
  "userRole": { "name": "manager", "description": "Quản lý" }
}

parseGinH / 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:

helpers.ParseJSONFieldsForTables(items, "user")  // dùng cho GET /:id
parseJSONInItems(result.Items)                    // dùng cho list (sau khi nest)

Service — key patterns

Optimistic locking (UpdateUser) — theo updated_at (D6, pkg/optlock)

// 1. Pre-check trước transaction (fast fail)
if input.UpdatedAt != user.UpdatedAt {
    return nil, errs.ErrVersionConflict
}
// 2. Ghi có khoá: WHERE updated_at = ? + bump; 0 dòng ⇒ ErrVersionConflict
optlock.Updates(tx.Model(&hrUserDao.User{}).Where("id = ?", userID), input.UpdatedAt, updates)

Token revocation

Khi đổi status (và khi ChangePassword, DeleteUser) → revoke CẢ access token lẫn refresh token (đổi branch/role KHÔNG revoke — xem §Forced logout; vế companyId đã bỏ, D15):

if needRevoke && s.TokenSvc != nil {
    s.TokenSvc.RevokeAllSessions(userID)      // JTI blacklist
    s.TokenSvc.RevokeAllRefreshTokens(userID) // prevent silent re-auth
}

Tương tự khi ChangePassword, DeleteUser.

Role update (trong transaction)

// Dùng tx (không phải s.DB) khi query role bên trong transaction
tx.Table("rbac_auth_assignment").Select("item_name").Where("user_id = ?", userID).Scan(&currentRole)
if currentRole != *input.Role {
    tx.Exec("DELETE FROM rbac_auth_assignment WHERE user_id = ?", userID)
    tx.Exec("INSERT INTO rbac_auth_assignment (item_name, user_id, created_at) VALUES (?, ?, ?)", ...)
    needRevoke = true
}

GetAllUsers — cache scope

Luôn 1 khoá cache chung (story-58: bỏ lọc JSON u.companyId, 1 thương hiệu/DB — D15); invalidateCache xoá đúng khoá đó. (Lịch sử: trước đây useCache := len(companyIDs) == 0 — chỉ cache nhánh không lọc company; đã bỏ, D15.)

Forced logout — chỉ khi status thay đổi

  • RevokeAllSessions + RevokeAllRefreshTokens CHỈ khi status thay đổi (user bị vô hiệu hóa không được tiếp tục dùng app)
  • branch/role/dept: BE enforce per-request (UserScope + RBAC cache cleared) → KHÔNG cần revoke → user không bị logout
  • BumpUserAuthVersion chạy sau MỌI update (kể cả status) làm safety net

BumpUserAuthVersion — khi nào gọi

Gọi middleware.BumpUserAuthVersion(s.Cache, userID) sau khi commit profile update khi !needRevoke && input.UserProfile != nil.

  • KHÔNG gọi khi needRevoke=true (token refresh flow đã lo sync FE)
  • KHÔNG gọi khi đổi password (token bị revoke → FE tự fetchAndSyncMe sau refresh)
  • Hàm nằm trong internal/middleware/response_headers.go, cần import middleware package vào service

Handler — ChangePassword vs ResetPassword vs UpdatePassword

Endpoint Dùng khi Xác thực
PUT /hr/user/reset-password Admin đặt lại pass cho user — FE chọn/generate password Không cần old password; BE validate tenant scope qua BuildUserQuery (prevent IDOR); min 6 ký tự
POST /hr/user/change-password Admin reset pass (legacy endpoint, vẫn còn) Không cần old password, cần id target
POST /hr/user/update-password User tự đổi pass chính mình Phải nhập oldpassword + newpassword + newpasswordrepeat

Cả 3 đều: hash bcrypt cost 12, call ChangePassword(userID, newPass) trong service → auto revoke sessions.

IDOR check bắt buộc cho reset-password:

// Dùng BuildUserQuery (KHÔNG ScopedDBNullBranch trực tiếp) vì user table dùng JSON array scope
var exists int64
h.BuildUserQuery(c).Where("u.id = ?", body.ID).Count(&exists)
if exists == 0 { response.NotFound(c); return }

ImportUsers — N+1 fix

Trước khi bắt đầu transaction: pre-scan toàn bộ rows để batch load:

// 1. Batch load phone → userId (tránh per-row query "ai đang dùng phone này")
var phonePreRows []struct{ UserID uint; Phone string }
h.DB.Table("user_profile").Select("user_id, phone").Where("phone IN ?", phonesInFile).Find(&phonePreRows)
phoneOwner := make(map[string]uint)

// 2. Batch load profileExists (tránh per-row COUNT)
var pidPreRows []struct{ UserID uint }
h.DB.Table("user_profile").Select("user_id").Where("user_id IN ?", updateIDsInFile).Find(&pidPreRows)
profileExists := make(map[uint]bool)

// 3. Trong loop: sau khi CREATE profile mới → cập nhật map
profileExists[currentUserID] = true  // tránh duplicate key nếu cùng ID xuất hiện 2 lần

importEmrDepartments — tương tự: pre-load existing assignments trước khi vòng lặp insert.


Frontend — UserForm (admin)

user-form.ts — admin tạo/sửa user.

EMR department flow — ĐÃ BỎ (lịch sử)

Gán khoa EMR cho user (emrDeptRows, saveDepartments, "1 primary per company_id" — lịch sử, D15) đã xoá cùng module hr/user_emr_department (story-12) và company (D15). Form nay submit 1 lệnh updateUser/create.

onSubmit pattern

const payload = this.getPayload();
const saveOp = this.isEditMode()
  ? this.modelService.updateUser(modelId!, payload, {})
  : this.modelService.create(payload, {});
saveOp.pipe(finalize(() => this.isSubmitting.set(false))).subscribe({ ... });

Self-edit (admin sửa chính mình)

if (this.isEditMode() && modelId === userId()) {
  this.syncAuthUserIfSelf();  // sync branchId vào authUser signal + localStorage (companyId/departments đã bỏ, D15)
  sessionStorage.setItem('post_reload_toast', translate.instant('...'));
  location.reload();  // phải reload để JWT context refresh
  return;
}

Frontend — UserChangePassword

Validator cross-field mismatch cần kích hoạt lại khi newpassword thay đổi:

this.rfModel.get('newpassword')!.valueChanges
  .pipe(takeUntilDestroyed(this.destroyRef))
  .subscribe(() => this.rfModel.get('newpasswordrepeat')!.updateValueAndValidity());

newpassword phải có Validators.minLength(6) (match BE validation ≥6 chars).

Sau khi đổi password thành công → BE revoke all tokens → FE phải logout ngay:

setTimeout(() => this.authService.handleRefreshTokenExpired(), 1500);  // delay để user đọc toast

Frontend — UserUpdateProfile

birthday timezone trap:

// ❌ NEVER — new Date("2000-01-15") → UTC midnight → hiển thị 14/01 ở GMT+7
birthday: new Date(res.birthday)

// ✅ ALWAYS — append T00:00:00 để parse local time
birthday: new Date(res.birthday + 'T00:00:00')

srcImageUpload type — phải là string | null không phải !: any:

srcImageUpload: string | null = null;

Toast duplicates — KHÔNG dùng <p-toast> local

app.component.ts đã có 1 global <p-toast position="top-right" />.
PrimeNG MessageService broadcast tới tất cả <p-toast> instance trong DOM.
→ KHÔNG thêm <p-toast /> vào từng page/component con (attendance.html, schedule.html, ...).


i18n keys liên quan

Key Nội dung
user_updated Cập nhật người dùng thành công
password_changed Đổi mật khẩu thành công
password_min Mật khẩu tối thiểu 6 ký tự
password_confirm_mismatch Mật khẩu xác nhận không khớp
password_old_wrong Mật khẩu cũ không đúng
import_success Import thành công

Per-user IndexedDB auth session

Store userAuthSession trong IndexedDB cluvixData — lưu user data + permissions + authVersion riêng từng user.

Đặc điểm:

  • keyPath: userId (KHÔNG phải id) — isolated by user, multi-user cùng browser không xung đột
  • KHÔNG add vào Dexie global sync (X-Dexie-Versions) — chỉ sync khi BE báo version lệch
  • Migration: fallback localStorage auth_user key cho session cũ, tự migrate sau lần save kế tiếp
  • auth_user_id (localStorage, number) — lightweight boot marker để biết load IDB entry nào

2 sync triggers:

  1. Token revocation → FE nhận 401 → silent refresh → fetchAndSyncMe() (gọi /api/auth/me, cập nhật signals + IDB)
  2. Header X-User-Auth-Version: {userId}:{timestamp} lệch → isStale() → fetchAndSyncMe()

X-User-Auth-Version header flow:

  • BE set header này trong mọi response (từ AuthResponseHeaders middleware), giá trị = Redis key auth:user_auth_ver:{userID}
  • BumpUserAuthVersion(cache, userID) ghi Redis key với TTL 30 ngày — gọi khi profile update không revoke token
  • FE kiểm tra trong response-handler.interceptor.ts → chỉ trigger sync khi headerUserId === currentUserId
  • Cập nhật _cachedAuthVersion + userAuthSession.updateAuthVersion() trước khi gọi fetchAndSyncMe() để tránh loop

Endpoints summary

GET    /hr/user                     # list + filter + export
GET    /hr/user/get-all-users       # dropdown/sync (JSON array, no pagination)
GET    /hr/user/:id                 # single record
POST   /hr/user                     # create
PUT    /hr/user/:id                 # update (optimistic lock)
DELETE /hr/user/:id                 # soft delete (status = define.UserStatusDeleted = 1)
POST   /hr/user/change-password     # admin reset pass của user khác
POST   /hr/user/update-password     # user tự đổi pass (verify old pass)
PUT    /hr/user/reset-password      # admin đặt lại pass (FE gửi password, BE validate + apply)
POST   /hr/user/import-users        # import Excel
GET    /hr/user/get-template        # download import template

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.

04 同仓库更多 Skills

cluvix
cluvix/cluvix-crm

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.

★ 21
cluvix
cluvix/cluvix-crm

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 đó.

★ 21
cluvix
cluvix/cluvix-crm

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.

★ 21
cluvix
cluvix/cluvix-crm

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(...)).

★ 21
cluvix
cluvix/cluvix-crm

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).

★ 21
cluvix
cluvix/cluvix-crm

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/mặc định là Done, hoặc trước khi verify build/test theo Development Protocol bước 4 (Validate).

★ 21