alla-allaos-fullstack/plans/phase-1-requirement.md

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

src/features/

assets/
asset-assignments/
asset-transfers/
asset-movements/
asset-dashboard/

---

Menu Structure

Dashboard

Assets
 ├─ Asset List
 ├─ Asset Assignment
 ├─ Asset Transfer
 └─ Asset Movements

---

Asset Module

Asset List

Route

/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

/dashboard/assets/[assetId]

Tabs

Overview

Assignment

Movement Timeline

Attachments

---

Asset Assignment

Route

/dashboard/assets/[assetId]/assign

Required Fields

• Asset
• Employee
• Department
• Location
• Assign Date
• Document Attachment

System Action

• Update Current Assignment
• Create Movement

---

Asset Transfer

Route

/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

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

AVAILABLE
ASSIGNED
IN_REPAIR
LOST
RETIRED

Asset Condition

Current physical condition of the asset.

NORMAL
DAMAGED

Disposition / Process Status

Current repair or write-off process state.

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

CREATE
ASSIGN
TRANSFER
CHANGE_USER
CHANGE_LOCATION
CHANGE_DEPARTMENT
CHANGE_CODE
RETURN

---

Dashboard

Route

/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

GET    /api/assets
GET    /api/assets/:id
POST   /api/assets
PUT    /api/assets/:id

Assignments

POST   /api/assets/:id/assign

Transfers

POST   /api/assets/:id/transfer

Returns

POST   /api/assets/:id/return

Movements

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

assets
asset_assignments
asset_movements
attachments

Reference Tables

companies
sites
departments
locations
employees

---

Success Criteria

ผู้ใช้งานสามารถค้นหา Asset และทราบได้ภายใน 30 วินาทีว่า

• Asset อยู่ที่ไหน
• ใครถือครอง
• เคยเปลี่ยนรหัสอะไร
• เคยย้ายฝ่ายหรือไม่
• เคยย้ายผู้ใช้หรือไม่

โดยไม่ต้องเปิด Excel หรือเอกสารกระดาษเพิ่มเติม