ubi-dan-itam/docs/asset-license-management.md

Quản lý Tài sản IT & License

Trạng thái hiện tại

• Chưa có hệ thống tập trung — request xử lý rời rạc qua email/docx (vd Firefly_License_Request.docx, Eric Pelatan.docx ở gốc workspace ubisoft/, ngoài repo này). Không tracking được ai đang giữ gì, license nào sắp hết hạn/hết seat, tài sản nào sắp hết bảo hành.
• Đã chốt: kiến trúc monolith Next.js, không tách backend/frontend ở giai đoạn này (xem trigger để tách ở dưới).
• Đã chốt: Postgres (2026-07-29) — lý do: đảm bảo scale sau này + Power BI connect native, và bạn đã có kinh nghiệm dùng Postgres. Migrate task 1 (entity Request, state Draft) từ SQLite sang Postgres đã xong, CONFIRMED pass.
• Đã chốt: Prisma (ORM) + Zod (validation) (2026-07-30) — lý do Prisma over Drizzle cho solo dev: Prisma Studio (xem/sửa data qua GUI, khỏi viết psql query khi không có teammate hỏi), migration workflow tự động (prisma migrate dev), docs/community lớn hơn hẳn khi cần tự tra cứu một mình. Đánh đổi: nặng hơn Drizzle (query engine binary riêng, cần bước generate client), "magic" hơn raw SQL. Zod đi kèm để tận dụng type inference thay vì viết tay interface + hàm validate riêng.
• Retrofit Request sang Prisma+Zod xong (2026-07-30) — CONFIRMED qua test-runner độc lập: 6 test pass trên Postgres thật (qua prisma migrate deploy), type-check sạch, lint sạch. type chuyển từ TEXT + CHECK sang Postgres enum (RequestType) — tương đương semantics, không phải divergence. id/createdAt giữ nguyên hành vi cũ. Chi tiết đầy đủ ở ../CLAUDE.md.
• Project scaffold (multi-agent dev workflow) đặt ngay tại repo này — xem ../CLAUDE.md.
• File này trước đây nằm ở ubisoft/processes/asset-license-management.md (workspace chung, không phải git repo) — đã move vào đây (2026-07-30) vì nó gắn chặt với app này và cần update song song với code. ubisoft/processes/README.md vẫn giữ 1 dòng trỏ tới đây cho ai tìm từ đó.

Mục tiêu

Theo dõi toàn bộ vòng đời tài sản/license: Request → Approval → Procurement → Receiving → Delivery → Tracking → Thu hồi/Retire, và trả lời nhanh được:

• Ai đang giữ máy/license nào?
• License nào sắp hết hạn hoặc hết seat?
• Tài sản nào sắp hết bảo hành?
• Chi phí/license theo phòng ban là bao nhiêu?

Data model (sơ bộ)

Entity	Ý nghĩa
Employee	id, tên, phòng ban, manager
Vendor	id, name, contactEmail, contactPhone, address, taxCode (nullable — mã số thuế VN), notes (nullable) — nhà cung cấp/reseller mua hàng qua, khác AssetModel.manufacturer (hãng sản xuất/OEM). Xem "Vendor" bên dưới
AssetItem	hardware high-value (serial hóa bắt buộc) — serial number, model (FK → AssetModel, bắt buộc — không còn string tự do), ngày mua, bảo hành, trạng thái (in stock / assigned / repair / retired), purchaseOrderId (FK → PurchaseOrder, nullable — chiều cung, xem "PurchaseOrder" bên dưới). Category không còn gán trực tiếp trên AssetItem — suy ra qua AssetModel.categoryId. Xem "Phân loại tài sản" bên dưới
License	phần mềm — tên, vendorId (FK → Vendor, retrofit từ string tự do — xem "Vendor" bên dưới), tổng seat, seat đã dùng, ngày hết hạn, loại (perpetual/subscription), purchaseOrderId (FK → PurchaseOrder, nullable — chiều cung, xem "PurchaseOrder" bên dưới)
Request	người yêu cầu, loại (asset/license), lý do, trạng thái, purchaseOrderId (FK → PurchaseOrder, nullable — chiều cầu, xem "PurchaseOrder" bên dưới) — chỉ áp dụng cho asset high-value/license, không dùng cho consumable (xem "Phân loại tài sản" bên dưới)
PurchaseOrder	id, vendorId (FK → Vendor), orderDate, expectedDate, receivedAt (nullable — null nghĩa là chưa nhận), receivedBy (FK → Employee, nullable, set cùng lúc với receivedAt). Gộp luôn Receipt (không còn là entity riêng — nhận hàng là 1 phần trạng thái của chính PO), all-or-nothing theo cả PO (không nhận từng phần), không track giá/chi phí, không có status riêng (suy ra từ Request liên kết). Xem "PurchaseOrder" bên dưới
Assignment	id, employeeId (FK → Employee), assetItemId (FK → AssetItem, nullable) / licenseId (FK → License, nullable — đúng 1 trong 2, XOR), assignedAt, returnedAt (nullable — null nghĩa đang giữ), signedAt (nullable — chỉ là timestamp đánh dấu đã ký, không upload file). Gán AssetItem (high-value)/License cho 1 Employee cụ thể. Không áp dụng cho consumable (consumable track theo tồn kho, không gắn 1 người cụ thể). Xem "Assignment" bên dưới
Request.servicenow_ticket	field text, nhập tay số ticket ServiceNow liên quan (không tích hợp API ServiceNow ngay — volume thấp, nhập tay đủ dùng; để ngỏ cho auto-sync sau nếu cần)
AssetCategory	id, tên (vd "Laptop", "Cáp HDMI"), nhóm giá trị cố định (high_value | low_value) — danh mục category cụ thể do IT admin tự định nghĩa, không hardcode. Xem "Phân loại tài sản" bên dưới
AssetModel	id, category (FK → AssetCategory, bắt buộc, phải thuộc nhóm high_value), manufacturer (vd "Dell"), name (vd "Latitude 5420"), specs (JSONB — giá trị thật của các thuộc tính động, xem AssetCategoryAttributeDef) — tách riêng 2 field manufacturer/name, không gộp chung 1 string, để filter/report theo hãng. Nằm giữa AssetCategory và AssetItem (1 model có nhiều AssetItem serial khác nhau). Xem "Phân loại tài sản" bên dưới
AssetCategoryAttributeDef	id, categoryId (FK → AssetCategory), key (slug, vd ram_gb), label (tên hiển thị, vd "RAM (GB)"), dataType (enum đóng: string/number/boolean/date), required (bool), sortOrder (int) — định nghĩa thuộc tính riêng theo từng category, giá trị thật nằm ở AssetModel.specs. Unique (categoryId, key). Xem "Phân loại tài sản" bên dưới
ConsumableItem	phụ kiện low-value/consumable — tên, category (bắt buộc, phải thuộc nhóm low_value, trỏ thẳng AssetCategory — không qua AssetModel, khái niệm "model" chỉ áp dụng cho asset serial hóa), số lượng tồn kho (quantityOnHand). KHÔNG serial hóa, KHÔNG gắn Assignment cá nhân — chỉ track theo số lượng. Xem "Phân loại tài sản" bên dưới
MaintenanceRecord	(spec BA 2026-08-04, đã chốt đủ với stakeholder — sẵn sàng cho pm) khai báo sửa chữa/bảo hành cho 1 AssetItem cụ thể — assetItemId (FK, bắt buộc), issueDescription, resolutionNotes (nullable), startDate, endDate (nullable — null = đang sửa), type (enum: repair/warranty/preventive), vendorId (FK → Vendor, nullable — null = tự sửa nội bộ). Không track cost. Xem "MaintenanceRecord" bên dưới

Luồng trạng thái Request

Draft → Pending Approval → Approved → Ordered → Received → Delivered → Closed
                 ↓                                  
             Rejected / Cancelled

Phân loại tài sản: High-value vs Low-value/Consumable (chốt 2026-08-02)

Quyết định đã chốt với stakeholder: tài sản được phân nhóm theo category cố định, KHÔNG theo ngưỡng giá tiền. Mỗi AssetCategory thuộc đúng 1 trong 2 nhóm giá trị (high_value hoặc low_value), category cụ thể do IT admin tự định nghĩa/mở rộng — danh sách dưới đây chỉ là ví dụ minh hoạ, không phải danh sách đóng:

• Nhóm high_value → đi qua luồng AssetItem hiện có nguyên vẹn (serial hóa bắt buộc, track cá nhân qua Assignment, đi qua state machine đầy đủ của Request). Ví dụ category: Laptop, Màn hình, Máy in, Điện thoại công ty.
• Nhóm low_value (consumable) → entity mới ConsumableItem, không serial hóa, chỉ track theo số lượng tồn kho (quantityOnHand), không gắn Assignment cho 1 người cụ thể. Ví dụ category: Cáp (HDMI/USB-C/LAN), Chuột, Bàn phím, Túi đựng laptop, Sạc dự phòng.

Cập nhật 2026-08-02 (2): thêm phân cấp AssetModel giữa AssetCategory và AssetItem. Lý do: nhiều model khác nhau trong cùng 1 category (vd category "Laptop" có nhiều model "Dell Latitude 5420", "MacBook Pro 14"...), cần report/thống kê theo model (vd "đang có bao nhiêu Dell Latitude 5420"), tránh lỗi gõ tay khi model là string tự do như trước. Phân cấp: AssetCategory ("Laptop") → AssetModel ("Dell Latitude 5420") → từng AssetItem (1 serial cụ thể thuộc model đó). AssetModel.manufacturer/AssetModel.name tách riêng (không gộp 1 string) để filter/report riêng theo hãng. Khái niệm "model" chỉ có ý nghĩa cho asset serial hóa (high_value) — ConsumableItem không có model, vẫn trỏ thẳng AssetCategory (low_value) như cũ.

Cập nhật 2026-08-02 (3): thêm AssetCategoryAttributeDef — thuộc tính đặc thù theo từng category. Lý do: từng category có bộ thuộc tính riêng cần track (vd RAM/CPU cho category "Laptop", độ phân giải cho "Màn hình") mà không phải asset high-value nào cũng giống nhau — cần định nghĩa động theo category, không hardcode cột cứng cho từng loại thuộc tính.

• Entity mới AssetCategoryAttributeDef: categoryId (FK → AssetCategory), key (slug, vd ram_gb), label (tên hiển thị, vd "RAM (GB)"), dataType (enum đóng: string/number/boolean/date — đây là tập giá trị kỹ thuật cố định do dev định nghĩa, khác với AssetCategory là tập mở IT admin tự mở rộng), required (bool), sortOrder (int, thứ tự hiển thị trên form). Unique (categoryId, key).
• Mỗi AssetCategory có bộ attribute riêng, độc lập — cố tình không phải thư viện thuộc tính dùng chung giữa các category. Nếu 2 category cùng muốn 1 thuộc tính kiểu "khối lượng (kg)", mỗi category tự tạo 1 row AssetCategoryAttributeDef riêng — trùng tên key giữa 2 category là bình thường và được chấp nhận, đây là 2 row không liên quan tới nhau. Lý do: ở quy mô hiện tại (ít category), thiết kế thư viện thuộc tính dùng chung (tách riêng bảng AttributeDef + bảng join CategoryAttribute) cộng thêm độ phức tạp thật (thêm 1 bảng, UX phải chọn "gắn thuộc tính có sẵn hay tạo mới", sửa 1 def ảnh hưởng dây chuyền nhiều category) để đổi lấy lợi ích (sửa 1 chỗ áp dụng khắp nơi, query cross-category an toàn) mà hiện chưa cần tới — stakeholder đã từ chối rõ ràng thiết kế dùng chung để giữ đơn giản.
• Giá trị thật nằm ở AssetModel.specs (cột JSONB) — không nằm trên AssetItem, vì đây là thuộc tính theo spec-sheet dùng chung cho mọi serial thuộc cùng 1 model (mọi AssetItem "Dell Latitude 5420" đều cùng RAM), không phải dữ liệu riêng theo từng instance. Validate động lúc ghi: app build Zod schema runtime từ các AssetCategoryAttributeDef thuộc category của model đó (map dataType → z.string()/z.number()/z.boolean()/z.coerce.date()), từ chối key lạ chưa được định nghĩa cho category, bắt buộc các key có required = true phải có mặt.
• Known gap chấp nhận được, chưa chặn: nếu admin sửa/xoá 1 AssetCategoryAttributeDef sau khi đã có AssetModel mang giá trị dưới key đó trong specs, giá trị cũ trở thành orphaned/stale — chưa có cơ chế migration/cleanup. Ghi nhận là known gap để xử lý khi có UI quản lý attribute-def thật, không cần giải quyết ngay bây giờ.

Ràng buộc dữ liệu:

• AssetModel.categoryId bắt buộc, phải trỏ tới 1 AssetCategory có valueGroup = high_value.
• AssetItem.modelId bắt buộc, phải trỏ tới 1 AssetModel có thật (thay cho field model string tự do trước đây — đã đổi, không cần chiến lược backfill vì DB chưa có AssetItem thật). AssetItem không còn giữ categoryId trực tiếp — category được suy ra qua AssetItem.modelId → AssetModel.categoryId (tránh 2 nguồn sự thật có thể lệch nhau).
• ConsumableItem.categoryId bắt buộc, phải trỏ tới 1 AssetCategory có valueGroup = low_value — trỏ thẳng, không qua AssetModel.
• Request (state machine đầy đủ) tiếp tục chỉ áp dụng cho type: asset|license như hiện tại — không mở rộng RequestType thêm consumable.
• AssetCategoryAttributeDef.categoryId bắt buộc, phải trỏ tới 1 AssetCategory có thật. Unique (categoryId, key).
• AssetModel.specs (JSONB) chỉ được chứa các key đã có AssetCategoryAttributeDef tương ứng với category của model đó — validate ở tầng Zod (build động lúc runtime), không phải DB CHECK constraint (nhất quán với nguyên tắc "không raw SQL cho app logic" của codebase).

Luồng riêng cho consumable ("xin + nhận" đơn giản hoá): stakeholder đã xác nhận muốn 1 luồng gọn hơn state machine đầy đủ của Request, nhưng chưa chốt chi tiết state/approval/xử lý hết hàng — xem danh sách câu hỏi mở trong spec BA (2026-08-02, lưu ở lịch sử trao đổi/PR liên quan). Không build luồng này (entity ConsumableRequest hoặc tương đương) tới khi có câu trả lời — chỉ mới build phần catalog (AssetCategory, ConsumableItem).

Vendor (chốt 2026-08-02)

Entity mới, độc lập với AssetModel.

• Field: id, name, contactEmail, contactPhone, address, taxCode (nullable — mã số thuế VN), notes (nullable).
• Phân biệt quan trọng: Vendor (nơi mua hàng — vd nhà phân phối/reseller VN) là khái niệm khác AssetModel.manufacturer (hãng sản xuất/OEM, vd "Dell") — không phải lúc nào cũng cùng 1 công ty (vd mua laptop Dell qua reseller "FPT Trading", không mua thẳng từ Dell). Quyết định: giữ nguyên AssetModel.manufacturer là string tự do như hiện tại (không đổi gì); Vendor chỉ dùng cho quan hệ mua sắm (PurchaseOrder, License).
• Retrofit License.vendor (hiện là string tự do) → License.vendorId (FK → Vendor), theo đúng tiền lệ đã có trong codebase (Request.employeeId string→FK khi Employee ra đời, AssetItem.model string→FK khi AssetModel ra đời — xem "Trạng thái hiện tại" ở ../CLAUDE.md). Chưa có License thật nào trong DB production nên đây là đổi kiểu cột thuần tuý, không cần chiến lược backfill — giống các retrofit trước đó.

Ràng buộc dữ liệu:

• License.vendorId bắt buộc, phải trỏ tới 1 Vendor có thật (thay cho field vendor string tự do trước đây).

PurchaseOrder (gộp Receipt) (chốt 2026-08-02)

Quyết định: gộp Receipt vào PurchaseOrder, không giữ là entity riêng nữa — nhận hàng chỉ là 1 phần trạng thái của chính PO đó (receivedAt/receivedBy), không cần 1 bảng riêng để đối chiếu. Row Receipt trong bảng Data model ở trên đã được xoá, gộp vào row PurchaseOrder.

• Field: id, vendorId (FK → Vendor), orderDate, expectedDate, receivedAt (nullable DateTime — null nghĩa là chưa nhận), receivedBy (nullable FK → Employee, set cùng lúc với receivedAt).
• Cố tình không có field giá/chi phí — stakeholder nói rõ PurchaseOrder không cần track tiền, chỉ cần trả lời "asset/license nào thuộc PO nào".
• Cố tình không có field PurchaseOrder.status riêng — trạng thái suy ra từ trạng thái của các Request liên kết (Request đã có state machine Ordered → Received → Delivered riêng), tránh 2 nguồn sự thật.
• Nhận hàng là all-or-nothing theo từng PO ("nhận 1 lần đủ cho cả PO") — không hỗ trợ nhận nhiều đợt/từng phần. Đây là đánh đổi đơn giản hoá có chủ ý, stakeholder đã biết rõ và chấp nhận có thể cần đổi lại sau (paraphrase: "giờ làm đơn giản vậy trước, sau này cần đổi thì tính tiếp") — ghi lại rõ đây là tradeoff/assumption đã note, không phải bỏ sót khi viết spec.
• Traceability (đúng yêu cầu cốt lõi của stakeholder: "chỉ cần biết asset nằm trong PO nào"): thêm purchaseOrderId (nullable FK → PurchaseOrder) ở CẢ BA chỗ — AssetItem, License, và Request. Ba field này phục vụ mục đích khác nhau, không dư thừa:
  • Request.purchaseOrderId — chiều cầu (demand-side): request nào đã duyệt được gộp vào PO này (đây vốn là mục đích ban đầu đã note trong doc cho PurchaseOrder: "gộp nhiều Request đã duyệt").
  • AssetItem.purchaseOrderId và License.purchaseOrderId — chiều cung (supply-side): record tồn kho/thực tế nào tới qua PO này. Set lúc intake/tạo mới. Nullable vì không phải AssetItem/License nào cũng đi qua 1 PO chính thức (vd tồn kho lịch sử nhập trước khi có hệ thống).

Ràng buộc dữ liệu:

• PurchaseOrder.vendorId bắt buộc, trỏ tới 1 Vendor có thật.
• PurchaseOrder.receivedBy chỉ set cùng lúc với receivedAt (cả hai cùng null hoặc cùng có giá trị).
• AssetItem.purchaseOrderId, License.purchaseOrderId, Request.purchaseOrderId đều nullable, trỏ tới PurchaseOrder nếu có.
• PurchaseOrder không có field status — suy ra qua Request liên kết, không lưu trùng.

Assignment (chốt 2026-08-02)

• Field: id, employeeId (FK → Employee), assetItemId (FK → AssetItem, nullable), licenseId (FK → License, nullable), assignedAt, returnedAt (nullable — null nghĩa đang giữ), signedAt (nullable DateTime — null nghĩa biên bản chưa ký. Cố tình chỉ là 1 timestamp đánh dấu đã ký/chưa, KHÔNG phải upload file — stakeholder đã quyết định rõ không cần lưu file scan lúc này, "biên bản ký nhận" chỉ cần đánh dấu đã ký + ngày ký).
• Đúng 1 trong 2 (assetItemId/licenseId) phải được set — không cả hai, không cả hai đều rỗng (XOR) — validate ở tầng Zod qua .refine(), theo đúng cách codebase đã xử lý validate cross-field (không phải DB CHECK constraint, đúng nguyên tắc "không raw SQL cho app logic" — Prisma schema cũng không diễn tả được constraint XOR này natively).
• Không phải entity mới, nhưng có các business rule tầng application cần note lại rõ ở đây (đủ quan trọng để phát sinh bug nếu bỏ sót, nhưng là rule app phải tự enforce, không phải bản thân là 1 entity):
  • 1 AssetItem chỉ có tối đa 1 Assignment active (returnedAt IS NULL) tại 1 thời điểm — không thể bị giữ bởi 2 người cùng lúc. Enforce trước khi tạo Assignment mới.
  • Assign 1 License phải tăng License.seatsUsed, và phải bị từ chối nếu seatsUsed >= seatsTotal (không overbook). Trả lại (set returnedAt) giảm seatsUsed. Toàn bộ phải chạy trong 1 transaction — đây chính là rủi ro seat-count race condition mà code-reviewer đã note trước đó cho License (xem "Trạng thái hiện tại" ở ../CLAUDE.md, mục License) — Assignment là chỗ thực sự implement/exercise seat counting lần đầu tiên.
  • Chuyển tài sản giữa nhân viên (case đặc biệt đã note ở trên: "Tài sản luân chuyển giữa phòng ban / chi nhánh") = đóng Assignment cũ (returnedAt = now) + tạo Assignment mới, cả hai trong 1 transaction. Không cần entity "Transfer" riêng.
  • AssetItem.status phải đồng bộ theo trạng thái Assignment: tạo Assignment → status assigned; trả lại → status in_stock, trừ nhánh RMA/sửa chữa đã note ở "Case đặc biệt cần xử lý" (đó là case riêng, không đi qua path trả-lại-thông-thường này).
  • Chốt 2026-08-02 (trả lời 2 câu hỏi mở của pm): (a) createAssignment() phải chặn nếu AssetItem.status hiện tại khác in_stock (vd không cho assign 1 item đang repair/retired) — trả lỗi 400, không chỉ dựa vào điều kiện "chưa có Assignment active nào". (b) Route "update" (trả lại/chuyển giao Assignment, nhận hàng PurchaseOrder) dùng PATCH /api/<entity>/[id] — tiền lệ REST-shape đầu tiên cho update trong codebase, áp dụng thống nhất cho cả Assignment và PurchaseOrder, không dùng action-based sub-route.

Ràng buộc dữ liệu:

• Assignment.employeeId bắt buộc, trỏ tới 1 Employee có thật.
• Đúng 1 trong assetItemId/licenseId được set (XOR) — validate Zod .refine().
• Không được có > 1 Assignment active cho cùng 1 AssetItem tại 1 thời điểm (enforce ở tầng application, không phải DB constraint).
• Tạo Assignment bị chặn nếu AssetItem.status khác in_stock (400).
• License.seatsUsed tăng/giảm đồng bộ trong 1 transaction khi assign/return; assign bị chặn nếu seatsUsed >= seatsTotal.

MaintenanceRecord (spec BA + stakeholder, chốt 2026-08-04 — sẵn sàng cho pm)

Xuất phát từ yêu cầu stakeholder: "muốn thêm 1 menu maintenance — khai báo sửa chữa cho từng AssetItem, kể cả bảo hành." Đây là entity mới (không phải mở rộng field trên AssetItem), hiện thực hoá case đã note từ trước ở "Case đặc biệt cần xử lý" bên dưới: "Asset hỏng → gửi RMA/sửa chữa → cần state 'in repair' tách khỏi 'assigned'" — AssetItemStatus.repair đã có sẵn trong enum (prisma/schema.prisma) từ khi AssetItem được tạo, nhưng chưa có entity/flow nào thực sự dùng tới giá trị đó cho tới nay. MaintenanceRecord sẽ là mutator đầu tiên của AssetItem.status ngoài Assignment — AssetItem hiện chưa có update endpoint nào cả, nên phần đồng bộ status dưới đây cũng ngầm là spec cho phần ghi AssetItem.status từ MaintenanceRecord (không phải 1 update endpoint chung chung cho AssetItem).

Field:

• id, assetItemId (FK → AssetItem, bắt buộc), type (Postgres enum: repair | warranty | preventive), vendorId (FK → Vendor, nullable — null nghĩa là tự sửa nội bộ, không qua vendor ngoài), issueDescription (text, bắt buộc — mô tả vấn đề/lý do gửi sửa), resolutionNotes (text, nullable — set khi đóng record, mô tả kết quả xử lý), startDate (Date, bắt buộc — ngày gửi đi sửa/bắt đầu), endDate (Date, nullable — ngày nhận lại/hoàn tất; null = đang sửa), createdAt.
• Không track cost — theo đúng tiền lệ PurchaseOrder (đã chốt trước đó không track tiền, xem mục "PurchaseOrder").
• Không có field status riêng trên MaintenanceRecord — suy ra "đang sửa" (endDate IS NULL) vs "đã xong" (endDate có giá trị) từ chính endDate, đúng tiền lệ PurchaseOrder.receivedAt (không track trạng thái trùng lặp).
• Chỉ áp dụng cho AssetItem (hardware) — License không có khái niệm sửa chữa vật lý, nên không cần cơ chế XOR như Assignment (assetItemId là target duy nhất, luôn bắt buộc).
• vendorId tái dùng entity Vendor hiện có (nơi mua hàng) — chấp nhận gộp chung khái niệm "đối tác ngoài" cho cả mua hàng lẫn sửa chữa, không tạo bảng riêng.
• 1 AssetItem chỉ có tối đa 1 MaintenanceRecord đang mở (endDate IS NULL) tại 1 thời điểm — không thể gửi cùng lúc 2 nơi sửa. Đủ hiển nhiên về mặt vật lý (1 item vật lý không thể ở 2 nơi sửa cùng lúc) để chốt thẳng, không cần hỏi — mirror invariant "tối đa 1 Assignment active" đã có.
• endDate (nếu có) phải >= startDate — validate ở tầng Zod ngay từ đầu, tránh lặp lại gap đã note ở "Việc còn dở" của ../CLAUDE.md (Assignment.returnedAt hiện chưa validate >= assignedAt).
• Không track "người tạo/ghi nhận" qua User — không có tiền lệ nào trong codebase hiện tại gắn business entity với User (chỉ dùng User cho login). Nếu sau này cần biết "ai gửi đi sửa", đó là field bổ sung riêng, không phải phần MVP này.

Đồng bộ AssetItem.status:

• Mở MaintenanceRecord (POST, chưa có endDate): tự động chuyển AssetItem.status sang repair trong cùng transaction (mirror cách Assignment đồng bộ AssetItem.status/License.seatsUsed).
• Nếu AssetItem đó đang có 1 Assignment active (returnedAt IS NULL) → chặn tạo MaintenanceRecord, trả 400 — bắt buộc phải return Assignment trước, giống cách createAssignment() hiện chặn tạo mới nếu AssetItem.status khác in_stock.
• Nếu AssetItem đang ở status retired sẵn → chặn tạo MaintenanceRecord, trả 400 (item đã thanh lý thì gửi sửa không còn ý nghĩa).
• Đóng MaintenanceRecord (set endDate + resolutionNotes qua PATCH /api/maintenance-records/[id], cùng REST-shape tiền lệ đã chốt cho Assignment/PurchaseOrder — "chốt 2026-08-02 (b)" ở mục Assignment): body nhận thêm targetStatus bắt buộc (vd in_stock nếu sửa xong, retired nếu sửa không thành công) — không tự động mặc định về in_stock, vì sửa không phải lúc nào cũng thành công.
• Các field khác ngoài hành động "đóng" record không có update endpoint riêng — set 1 lần lúc tạo, không sửa lại sau, theo đúng pattern hiện có (vd PurchaseOrder.orderDate không có update endpoint).

Module tương lai: Rack/Slot management + IoT (chưa build, chỉ note kiến trúc)

Mục tiêu xa hơn: biết chính xác asset nằm ở ô/slot nào trên tủ rack, và hướng dẫn người lấy đúng ô bằng đèn (pick-to-light).

Data model thêm:

• Rack (id, tên, vị trí — map với rack-1/2/3 đã có ảnh ở ../../server-racks/, thư mục ngoài repo này trong workspace ubisoft/)
• RackSlot (rack_id, vị trí U, sensor_status [empty/occupied — ghi bởi cảm biến vật lý], assigned_asset_id [nullable — ghi khi người dùng quét QR gán asset vào slot])
• Mismatch giữa sensor_status và assigned_asset_id (vd sensor báo occupied nhưng không có asset nào được assign) = tín hiệu cần kiểm tra thủ công (phát hiện thất thoát/quên cập nhật)

Kiến trúc: tách stack IoT riêng (broker MQTT hoặc tận dụng Home Assistant đã định dùng cho KNX ở văn phòng mới, xem ../../processes/new-office-fitout.md) khỏi app chính — lý do là giao thức (MQTT/CoAP), data shape (time-series), và network/bảo mật (nên tách VLAN như camera/access control) đều khác hẳn CRUD web app. Tích hợp qua 1 bridge job đọc/ghi trạng thái vào Postgres của app chính (RackSlot.sensor_status) — app chính không cần biết MQTT/HASS, Postgres vẫn là nguồn sự thật duy nhất.

Luồng pick-to-light (tương lai):

1. Request duyệt → nhận hàng → asset gán vào 1 RackSlot cụ thể → trạng thái Request thêm state mới "Ready for Pickup"
2. Người tới quét số ticket (ServiceNow, nhập tay ở trên) tại trạm quét QR gắn cạnh tủ rack → gọi API tra RackSlot tương ứng
3. Trạm quét = consumer độc lập thứ 2 của app (ngoài web frontend) → endpoint này cần thiết kế như API thật (auth riêng cho thiết bị, không dựa session web) — đây là trigger hợp lệ đầu tiên để có 1 API boundary rõ ràng, dù chưa cần tách hẳn backend
4. App → bridge → publish lệnh bật đèn đúng slot qua IoT stack
5. Người lấy xong → xác nhận (quét lại hoặc sensor tự phát hiện chuyển empty) → tắt đèn, đóng Assignment/Request

QR gán asset vào slot (bước 1, thủ công hàng ngày) không phải IoT — chỉ là quét mã bằng camera trình duyệt/máy quét cầm tay, ghi thẳng qua API hiện có của app chính, không cần MQTT.

Case đặc biệt cần xử lý

• Nhân viên nghỉ việc → checklist thu hồi asset + license (offboarding)
• License seat-based dùng chung (vd Adobe CC theo pool chung của phòng ban)
• Tài sản luân chuyển giữa phòng ban / chi nhánh (không phải "delivery" mới, mà là re-assign)
• Asset hỏng → gửi RMA/sửa chữa → cần state "in repair" tách khỏi "assigned" — giải quyết bởi MaintenanceRecord, spec chốt 2026-08-04, xem mục "MaintenanceRecord" bên dưới, sẵn sàng cho pm

Quyết định kiến trúc

• Quy mô hiện tại <100 người, IT team nhỏ → web app tự build gọn nhẹ, monolith (Next.js full-stack, frontend + API routes chung 1 app) — self-hosted, tương tự pattern app "IT Knowledge Base + Ticket Analyzer" đã build cho it-support.md (workspace ngoài repo này), theo nguyên tắc chung của workspace là ưu tiên self-host hơn cloud (xem ../../processes/new-office-fitout.md). Không tách backend/frontend riêng ở giai đoạn này — xem lý do & trigger để tách ở dưới.
• DB: Postgres, đã chốt (2026-07-29). Lý do: đảm bảo scale sau này, Power BI connect native/ổn định tới Postgres (còn SQLite cần ODBC driver gượng ép + không hợp để BI query đồng thời lúc app đang ghi), và đã có kinh nghiệm sẵn với Postgres. Cách lộ dữ liệu cho Power BI: tạo Postgres views riêng cho report (vd v_requests_report, v_license_utilization) + 1 read-only DB user trỏ Power BI vào, không cần expose API riêng cho việc này.
• Cron job (vd gửi email cảnh báo license sắp hết hạn hàng ngày) không cần tách backend riêng — làm 1 script độc lập (scripts/send-license-expiry-emails.ts) query thẳng Postgres, lịch chạy qua Windows Task Scheduler (đã có tiền lệ ở xibo-signage.md, workspace ngoài repo này) hoặc container cron riêng trong Docker. Cần chốt sau: SMTP nào, ngưỡng cảnh báo bao nhiêu ngày, gửi cho ai.
• Cân nhắc thay thế cho MVP: Airtable/Google Form nếu muốn test quy trình trước khi build — nhưng approval workflow nhiều bước + audit trail sẽ gượng ép nếu để lâu dài trên low-code.
• Reverse proxy khi deploy: Nginx Proxy Manager (đã chốt 2026-07-30) — tự host, có UI quản lý + tự động Let's Encrypt. Chưa dựng ngay vì app còn ở local dev, chưa tới bước deploy production. Khi deploy, app này khả năng sẽ dùng chung 1 NPM instance với các service self-host khác trong workspace (vd Xibo) thay vì mỗi app 1 reverse proxy riêng — cần xác nhận lại lúc thực sự deploy.
• Postgres: không expose ra internet qua domain (đã chốt 2026-07-31) — dù kỹ thuật làm được giống các cloud DB (domain + TLS + password mạnh), việc đó bắt tự vận hành toàn bộ phần bảo mật mà cloud provider thường lo (firewall theo IP, TLS, fail2ban, vá lỗi định kỳ) trong khi DB chứa data công ty thật. Quyết định: dev/test dùng Postgres local riêng từng máy (Docker, không expose). Khi deploy production ở nhà (Proxmox), Postgres prod chạy riêng biệt, không public — nếu cần connect từ máy khác (vd máy công ty) thì qua VPN/SSH tunnel, không mở port DB ra ngoài.
• Docker-compose: giữ chung 1 stack (app + db cùng 1 docker-compose.yml) thay vì tách file riêng cho DB — đã note tên network/volume/container tường minh (asset-license-mgmt-net, asset-license-mgmt-db-data, asset-license-mgmt-db) sẵn từ đầu nên tách sau này (nếu có consumer thứ 2 độc lập cần DB — vd cron container, IoT bridge) vẫn rẻ: chỉ cần đổi network thành external: true ở cả 2 file, volume tự nhận lại theo tên, gần như không downtime.

Khi nào nên tách backend riêng (chưa áp dụng, chỉ ghi lại trigger)

1. Có consumer thứ 2 thật sự cần gọi API độc lập ngoài web frontend (vd trạm quét QR pick-to-light — xem module Rack/Slot ở dưới; hoặc tích hợp ServiceNow sau này)
2. Có job cần chạy tách biệt khỏi request-response của web (cron email đã quyết là chưa cần tách, chỉ cần script + scheduler)
3. Cần hạ tầng/bảo mật khác biệt (vd module IoT rack — xem dưới, lý do khác hẳn: giao thức, data shape, network)
4. Team lớn tới mức có người riêng phụ trách backend

"Muốn tích hợp với hệ thống khác" tự nó không phải lý do để tách — ngược lại, tích hợp chặt (vd Rack/Slot dùng chung AssetItem) là lý do để gộp chung app/DB thay vì làm hệ thống riêng rồi nối lại qua API.

Process / SOP

(Chưa có — sẽ bổ sung khi bắt đầu implement: quy trình tạo request mới, checklist nhận hàng, checklist bàn giao có ký nhận, checklist offboarding thu hồi thiết bị)

Việc còn dở

• Thiết kế ERD chi tiết + wireframe màn hình
• Vendor, PurchaseOrder (gộp Receipt), Assignment, AssetCategoryAttributeDef (2026-08-02): đã có spec đầy đủ (BA), sẵn sàng cho pm chia task — xem các mục "Vendor", "PurchaseOrder (gộp Receipt)", "Assignment" và "Cập nhật 2026-08-02 (3)" trong "Phân loại tài sản" ở trên. Bao gồm cả retrofit License.vendor (string) → License.vendorId (FK → Vendor, không cần backfill vì chưa có License thật trong DB) và thêm purchaseOrderId (nullable FK) vào AssetItem/License/Request. Thứ tự phụ thuộc gợi ý cho pm: Vendor → retrofit License.vendorId → PurchaseOrder (+ purchaseOrderId trên 3 entity) → Assignment; AssetCategoryAttributeDef độc lập, có thể làm song song.
• Consumable (2026-08-02): phần phân loại (AssetCategory, ConsumableItem) đã có spec đầy đủ (BA), sẵn sàng cho pm chia task. Luồng "xin + nhận" (ConsumableRequest hoặc tương đương) BỊ CHẶN — cần stakeholder trả lời các câu hỏi mở: (1) có cần approval không, ai duyệt; (2) ai được tạo request xin (tự xin cho mình hay xin hộ được); (3) có giới hạn số lượng tối đa/lần xin không; (4) hết hàng thì chặn hẳn / cho "nợ" chờ nhập thêm / fulfill một phần; (5) trừ tồn kho lúc tạo request hay lúc fulfill; (6) restock tồn kho qua luồng nào, ai được làm; (7) có cần ghi nhận người phát hàng/ký nhận không. Không tự đoán — xem chi tiết đầy đủ trong spec BA.
• Migrate 2 request đang có (Firefly_License_Request.docx, Eric Pelatan.docx, ở workspace ubisoft/ ngoài repo này) vào hệ thống mới sau khi có DB
• MaintenanceRecord (spec BA + stakeholder, chốt 2026-08-04): đã có spec đầy đủ, sẵn sàng cho pm chia task — xem mục "MaintenanceRecord" phía trên. Field cơ bản + type (repair/warranty/preventive) + vendorId (tái dùng Vendor, nullable) đã chốt; đồng bộ AssetItem.status đã chốt rõ (auto → repair lúc mở, chặn nếu có Assignment active hoặc đã retired, targetStatus bắt buộc lúc đóng); không track cost.
• (Xa hơn, chưa ưu tiên) Rack/Slot + IoT pick-to-light, cron email cảnh báo license hết hạn, Power BI report views
• Setup Gitea tự host ở nhà (2026-07-31) — dự định làm remote chính sau này, giữ GitHub làm backup off-site (đây là "sản phẩm dùng cả đời" của user, không nên chỉ có 1 bản duy nhất). Tạm thời vẫn push GitHub như hiện tại, chưa làm gấp.

Ghi chú & bài học

• Migrate entity Request từ SQLite sang Postgres (2026-07-30) và setup ESLint đều đã CONFIRMED xong qua lượt verify độc lập (test-runner riêng, không phải agent vừa code tự chấm) — 6 test pass trên Postgres thật, lint sạch, type-check sạch. Chi tiết trạng thái nằm ở ../CLAUDE.md, không duplicate ở đây.

---

Cập nhật lần cuối: 2026-08-04 (spec MaintenanceRecord chốt đủ với stakeholder — sẵn sàng cho pm, xem "Việc còn dở")