201 lines
7.3 KiB
Markdown
201 lines
7.3 KiB
Markdown
# 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.
|