init

plans/phase-1-requirement.md

@@ -0,0 +1,429 @@
+# ALLA-ITCENTER
+
+## Phase 1 - Asset Core MVP
+
+Version: 1.0
+
+Status: Approved Scope
+
+---
+
+# Objective
+
+สร้าง Asset Single Source of Truth
+
+ระบบต้องสามารถตอบได้ทันที
+
+* Asset คืออะไร
+* Asset อยู่ที่ไหน
+* ใครถือครอง
+* Asset เคยเปลี่ยน Code หรือไม่
+* Asset เคยย้ายฝ่ายหรือไม่
+
+---
+
+# Scope
+
+## Included
+
+### Asset Master
+
+### Assignment
+
+### Transfer
+
+### Return
+
+### Movement History
+
+### Dashboard
+
+---
+
+## Excluded
+
+### Warranty
+
+### EOS
+
+### EOL
+
+### EOP
+
+### Audit
+
+### Stock
+
+### License
+
+### Helpdesk
+
+---
+
+# Feature Structure
+
+```text
+src/features/
+
+assets/
+asset-assignments/
+asset-transfers/
+asset-movements/
+asset-dashboard/
+```
+
+---
+
+# Menu Structure
+
+```text
+Dashboard
+
+Assets
+ ├─ Asset List
+ ├─ Asset Assignment
+ ├─ Asset Transfer
+ └─ Asset Movements
+```
+
+---
+
+# Asset Module
+
+## Asset List
+
+Route
+
+```text
+/dashboard/assets
+```
+
+Primary View
+
+* Server-driven data table
+* This is the canonical list UI for Asset records in Phase 1
+* Must support desktop table layout and mobile-friendly responsive behavior
+
+Functions
+
+* Search
+* Filter
+* Sort
+* Pagination
+* Export
+
+Columns
+
+* Asset UID
+* Asset Code
+* Asset Name
+* Category
+* Company
+* Department
+* User
+* Asset Status
+* Asset Condition
+* Disposition / Process Status
+
+---
+
+## Asset Detail
+
+Route
+
+```text
+/dashboard/assets/[assetId]
+```
+
+Tabs
+
+### Overview
+
+### Assignment
+
+### Movement Timeline
+
+### Attachments
+
+---
+
+# Asset Assignment
+
+Route
+
+```text
+/dashboard/assets/[assetId]/assign
+```
+
+Required Fields
+
+* Asset
+* Employee
+* Department
+* Location
+* Assign Date
+* Document Attachment
+
+System Action
+
+* Update Current Assignment
+* Create Movement
+
+---
+
+# Asset Transfer
+
+Route
+
+```text
+/dashboard/assets/[assetId]/transfer
+```
+
+Required Fields
+
+* Old User
+* New User
+* Old Department
+* New Department
+* Old Location
+* New Location
+* Old Asset Code
+* New Asset Code
+* Transfer Date
+* Reference Document
+
+System Action
+
+* Update Asset
+* Create Movement
+
+---
+
+# Asset Return
+
+Route
+
+```text
+/dashboard/assets/[assetId]/return
+```
+
+Required Fields
+
+* Return Date
+* Asset Condition
+* Remark
+
+System Action
+
+* Asset Status = AVAILABLE
+* Create Movement
+
+---
+
+# Status Model
+
+Use these terms explicitly in UI, API contracts, database fields, filters, and dashboard labels.
+
+## Asset Status
+
+Current primary state of the asset.
+
+```text
+AVAILABLE
+ASSIGNED
+IN_REPAIR
+LOST
+RETIRED
+```
+
+## Asset Condition
+
+Current physical condition of the asset.
+
+```text
+NORMAL
+DAMAGED
+```
+
+## Disposition / Process Status
+
+Current repair or write-off process state.
+
+```text
+NONE
+WAITING_REPAIR
+WAITING_WRITE_OFF
+WRITE_OFF_COMPLETED
+```
+
+Status naming rules
+
+* Do not use the word `Status` alone in requirements or UI labels
+* `Asset Status` is the main status shown in the Asset Register Table
+* `Asset Condition` is a separate field and filter
+* `Disposition / Process Status` is a separate field and filter
+* `Movement Type` belongs to timeline/history, not to the current-state status model
+
+---
+
+# Asset Movement
+
+ทุก Event ต้องถูกบันทึก
+
+Event Types
+
+```text
+CREATE
+ASSIGN
+TRANSFER
+CHANGE_USER
+CHANGE_LOCATION
+CHANGE_DEPARTMENT
+CHANGE_CODE
+RETURN
+```
+
+---
+
+# Dashboard
+
+Route
+
+```text
+/dashboard
+```
+
+Cards
+
+* Total Assets
+* Assigned Assets
+* In Stock Assets
+* Transfer This Month
+* Assets Without User
+* Assets Without Location
+
+---
+
+# RBAC
+
+## IT Admin
+
+Full Access
+
+---
+
+## Helpdesk
+
+* Read Asset
+* Assign
+* Transfer
+* Return
+
+---
+
+## Infrastructure
+
+* Read Asset
+* Update Infrastructure Asset
+
+---
+
+## Viewer
+
+Read Only
+
+---
+
+# API Scope
+
+Assets
+
+```text
+GET    /api/assets
+GET    /api/assets/:id
+POST   /api/assets
+PUT    /api/assets/:id
+```
+
+Assignments
+
+```text
+POST   /api/assets/:id/assign
+```
+
+Transfers
+
+```text
+POST   /api/assets/:id/transfer
+```
+
+Returns
+
+```text
+POST   /api/assets/:id/return
+```
+
+Movements
+
+```text
+GET    /api/assets/:id/movements
+```
+
+---
+
+# UX Data Freshness Requirement
+
+ทุก operation ที่เป็น CRUD ต้องทำให้ข้อมูลบนหน้าจอ "สด" หลัง action สำเร็จทันที
+
+Rules
+
+* Create: ต้อง refresh หรือ invalidate รายการที่เกี่ยวข้อง และอัปเดต detail view ถ้ามีการ redirect ไปหน้ารายละเอียด
+* Update: ต้องอัปเดต detail cache และ refresh list cache ที่อาจได้รับผลกระทบจาก field ที่เปลี่ยน
+* Delete: ต้องลบ item ออกจาก cache หรือ refetch list เพื่อไม่ให้ผู้ใช้เห็นข้อมูลค้าง
+* Assignment, Transfer, Return: ต้อง refresh อย่างน้อย Asset Detail, Asset List, และ Movement Timeline
+* Dashboard metrics/cards ที่ได้รับผลกระทบจาก mutation ต้องถูก refresh หลัง operation สำเร็จ
+* ห้ามพึ่ง manual browser refresh เป็น flow ปกติของผู้ใช้
+
+Implementation intent
+
+* ใช้ TanStack Query `mutationOptions`
+* กำหนด cache invalidation ใน `src/features/<name>/api/mutations.ts`
+* ใช้ `invalidateQueries`, `setQueryData`, หรือ optimistic update ตามความเหมาะสม
+* ทุก mutation ต้องมีแผน post-success cache synchronization ที่ชัดเจนเพื่อ UX ที่ดี
+
+---
+
+# Database Scope
+
+Core Tables
+
+```text
+assets
+asset_assignments
+asset_movements
+attachments
+```
+
+Reference Tables
+
+```text
+companies
+sites
+departments
+locations
+employees
+```
+
+---
+
+# Success Criteria
+
+ผู้ใช้งานสามารถค้นหา Asset และทราบได้ภายใน 30 วินาทีว่า
+
+* Asset อยู่ที่ไหน
+* ใครถือครอง
+* เคยเปลี่ยนรหัสอะไร
+* เคยย้ายฝ่ายหรือไม่
+* เคยย้ายผู้ใช้หรือไม่
+
+โดยไม่ต้องเปิด Excel หรือเอกสารกระดาษเพิ่มเติม