init

2026-06-11 12:46:57 +07:00
parent 1993d88306
commit 7a390cf0df
720 changed files with 100919 additions and 0 deletions
--- a/plans/mvp-plan.md
+++ b/plans/mvp-plan.md
@@ -0,0 +1,200 @@
+# IT Asset Governance MVP Plan For This Dashboard Repo
+
+## Summary
+
+Implement the IT Center MVP as a new app-owned feature set inside the existing Next.js dashboard, using the current architecture:
+
+- `organizations` stays the tenant boundary and maps to `Company`
+- business roles (`IT Admin`, `Helpdesk`, `Infrastructure`, `Application`, `Auditor`, `Viewer`) are modeled as workspace-scoped permission bundles, not as replacements for `systemRole`
+- first release is a `Core Registry` MVP:
+  - master data
+  - asset register
+  - asset lifecycle transactions: assign, transfer, return, repair
+  - movement history
+  - basic dashboard summaries and risk widgets
+
+This should be built as a new feature family, following the migrated `products` and `users` patterns:
+`feature types -> service -> queries/mutations -> route handlers -> Drizzle`.
+
+## Key Changes
+
+### 1. Domain model and tenancy alignment
+
+- Treat `organization` as `Company`; keep the existing table and session/org-switcher model.
+- Add company-scoped master data tables under the selected organization:
+  - `sites`
+  - `departments`
+  - `locations`
+  - `employees`
+- Add asset domain tables:
+  - `assets`
+  - `asset_movements`
+  - `asset_repairs`
+- Keep `Asset UID` immutable and system-generated.
+- Keep `Asset Code` mutable and history-tracked through movement events.
+- Store current state on `assets`; store every lifecycle change as an append-only movement row.
+
+### 2. RBAC model for IT Center
+
+- Keep current auth layers:
+  - `users.systemRole` for global authority
+  - workspace membership and active workspace session context for tenant authority
+- Add a workspace-scoped business-role profile to membership-derived access:
+  - either a new membership field like `businessRole`
+  - or a dedicated per-organization user-access table linked to `user + organization`
+- Recommended canonical permissions:
+  - `master_data:manage`
+  - `asset:read`
+  - `asset:create`
+  - `asset:update`
+  - `asset:assign`
+  - `asset:transfer`
+  - `asset:return`
+  - `asset:repair`
+  - `asset:audit`
+  - `report:read`
+- Map business roles to permission bundles:
+  - `IT Admin`: full company-scoped access
+  - `Helpdesk`: assign/transfer/return/read
+  - `Infrastructure`: hardware, warranty, EOS/EOL/EOP, repair
+  - `Application`: software/license/subscription assets
+  - `Auditor`: read, audit, export/report read
+  - `Viewer`: read-only
+- Keep server-side enforcement in route handlers and page guards; nav remains UX-only.
+
+### 3. Feature/module structure in this repo
+
+Create a new feature family under `src/features/assets/` and sibling dashboard routes under `src/app/dashboard/`:
+
+- `src/features/assets/`
+  - `api/types.ts`
+  - `api/service.ts`
+  - `api/queries.ts`
+  - `api/mutations.ts`
+  - `components/`
+  - `schemas/`
+- Add dashboard routes:
+  - `/dashboard/assets`
+  - `/dashboard/assets/[assetId]`
+  - `/dashboard/assets/assign`
+  - `/dashboard/assets/transfer`
+  - `/dashboard/assets/return`
+  - `/dashboard/assets/repair`
+  - `/dashboard/assets/history`
+- Add master-data routes/pages, either grouped under `/dashboard/master-data/*` or `/dashboard/assets/settings/*`
+  - `sites`
+  - `departments`
+  - `locations`
+  - `employees`
+- Reuse existing patterns:
+  - `PageContainer`
+  - TanStack Table
+  - TanStack Form + Zod
+  - React Query prefetch + `HydrationBoundary`
+  - route handlers in `src/app/api/**`
+
+### 4. Backend and workflow design
+
+Implement route handlers for:
+
+- master data CRUD
+- asset CRUD
+- lifecycle actions as explicit endpoints, not generic updates:
+  - `POST /api/assets/[id]/assign`
+  - `POST /api/assets/[id]/transfer`
+  - `POST /api/assets/[id]/return`
+  - `POST /api/assets/[id]/repair`
+- movement history listing:
+  - `GET /api/assets/[id]/movements`
+- dashboard summary endpoints:
+  - totals by status
+  - warranty risk counts
+  - lifecycle risk counts
+  - data-quality counts
+
+Behavior rules to lock in:
+
+- `assign` updates current owner/location fields and inserts `ASSIGN` movement
+- `transfer` updates user/department/location/code as needed and inserts one `TRANSFER` movement with old/new values
+- `return` updates status to one of `IN_STOCK | REPAIR | RETIRED` and inserts `RETURN`
+- `repair` inserts repair history and optionally sets status `REPAIR`
+- every lifecycle mutation must write a movement record in the same server transaction
+
+### 5. UI/navigation and documentation alignment
+
+- Add new sidebar section for `Assets`, with visibility based on asset permissions.
+- Keep `Workspaces` semantics unchanged; they still represent company switching.
+- Add pages in this order for the MVP:
+  1. asset register/list
+  2. asset create/edit
+  3. assign
+  4. transfer
+  5. return
+  6. repair
+  7. movement history
+  8. dashboard summary widgets
+  9. master data CRUD pages
+- Update stale docs while implementing:
+  - `docs/nav-rbac.md` is legacy Clerk-oriented and should be rewritten to match Auth.js + current session fields
+  - add a new domain glossary doc, preferably `CONTEXT.md`, to define:
+    - Organization = Company
+    - Site
+    - Department
+    - Location
+    - Employee
+    - Asset UID
+    - Asset Code
+    - Movement
+    - Business Role
+
+## Public APIs / Types
+
+- Add new feature contracts in `src/features/assets/api/types.ts`:
+  - `Asset`
+  - `AssetFilters`
+  - `AssetsResponse`
+  - `AssetMutationPayload`
+  - `AssetAssignmentPayload`
+  - `AssetTransferPayload`
+  - `AssetReturnPayload`
+  - `AssetRepairPayload`
+  - `AssetMovement`
+  - `AssetDashboardSummary`
+- Add master data contracts:
+  - `Site`, `Department`, `Location`, `Employee`
+- Extend workspace-scoped access modeling so session-backed access checks can resolve:
+  - current workspace business role
+  - current workspace asset permissions
+- Do not overload `systemRole` with business roles.
+
+## Test Plan
+
+- Auth and tenancy:
+  - active organization scopes all master data and assets to one company
+  - switching organization changes visible assets and master data
+- RBAC:
+  - `IT Admin` can do all asset operations in the active workspace
+  - `Helpdesk` can assign/transfer/return but cannot manage system settings
+  - `Infrastructure` can repair and manage lifecycle data
+  - `Auditor` can read and audit but cannot mutate assets
+  - `Viewer` cannot access transactional pages
+- Asset lifecycle:
+  - create asset generates immutable `Asset UID`
+  - transfer can change owner, department, location, and asset code
+  - return updates status and writes movement
+  - repair writes repair history and status changes correctly
+- History and risk:
+  - every lifecycle action creates a movement row
+  - warranty/EOS/EOL/EOP widgets count the right assets
+  - data-quality widgets flag missing user/location/serial/warranty
+- UI:
+  - new nav items appear only for permitted roles
+  - asset list, detail, and transaction flows follow the repo’s React Query hydration pattern
+
+## Assumptions and Defaults
+
+- `organizations` remains the canonical tenant table and means `Company`.
+- MVP phase 1 is the `Core Registry` only; `Audit`, advanced `Reports`, mobile scanning, approvals, and external integrations stay phase 2+.
+- Business roles are workspace-scoped permission bundles layered on top of the current Auth.js + membership model.
+- Hardware and software assets can share one `assets` table in MVP, using `assetType` and `assetCategory` fields, unless later scale forces separation.
+- Movement history is the audit trail of lifecycle changes; it is not full event sourcing.