updated skills
This commit is contained in:
@@ -0,0 +1,128 @@
|
||||
---
|
||||
name: sp-api-plugin-asset-register
|
||||
description: Fixed-asset lifecycle plugin for the Fetch-native @suaveplan/api platform. Authored with @suaveplan/api-plugin-kit definePlugin, contributes 15 typed RouteDescriptors under /assets, persisting to its own SurrealDB tables via four SurrealDB-backed repositories from one injected SurrealAdapter (plugin OWNS its persistence). Computes depreciation (straight-line, reducing-balance, units-of-activity), renders asset-tag QR labels with @suaveplan/qrcode, manages maintenance records and cost-centre assignments. Server-tier.
|
||||
---
|
||||
|
||||
# @suaveplan/api-plugin-asset-register
|
||||
|
||||
## Purpose
|
||||
|
||||
Fixed-asset lifecycle plugin for the Fetch-native `@suaveplan/api` platform. Authored with `@suaveplan/api-plugin-kit` `definePlugin`, it contributes 15 typed `RouteDescriptor`s under `/assets`, persisting to its own SurrealDB tables (`asset`, `depreciation_schedule`, `maintenance_record`, `asset_assignment`) via four SurrealDB-backed repositories constructed from one injected `SurrealAdapter` — the plugin OWNS its persistence.
|
||||
|
||||
It computes depreciation (straight-line, reducing-balance, units-of-activity) with `@suaveplan/datetime` date math, renders asset-tag QR labels with `@suaveplan/qrcode`, and manages maintenance records and cost-centre assignments.
|
||||
|
||||
## Architecture
|
||||
|
||||
| Component | Source | Role |
|
||||
|---|---|---|
|
||||
| `createAssetRegisterPlugin` | `src/plugin/plugin.ts` | Plugin factory |
|
||||
| `createAssetRegister` | `src/plugin/plugin.ts` | Returns `{ plugin, repositories }` for live access |
|
||||
| `calculateDepreciation` | `src/depreciation/depreciation.ts` | Pure depreciation engine |
|
||||
| `SurrealAssetRepository` | `src/repositories/asset/asset.ts` | Asset CRUD persistence |
|
||||
| `SurrealDepreciationRepository` | `src/repositories/depreciation/depreciation.ts` | Depreciation schedule persistence |
|
||||
| `SurrealMaintenanceRepository` | `src/repositories/maintenance/maintenance.ts` | Maintenance record persistence |
|
||||
| `SurrealAssignmentRepository` | `src/repositories/assignment/assignment.ts` | Cost-centre assignment persistence |
|
||||
| `ASSET_REGISTER_API_CODES` | `src/error-codes/error-codes.ts` | Error-code registry |
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
src/
|
||||
index.ts # Barrel: plugin factories, repositories, routes, depreciation, codes, types
|
||||
plugin/
|
||||
plugin.ts # createAssetRegisterPlugin, createAssetRegister
|
||||
depreciation/
|
||||
depreciation.ts # calculateDepreciation (pure)
|
||||
repositories/
|
||||
asset/ # SurrealAssetRepository + InMemoryAssetStore
|
||||
depreciation/ # SurrealDepreciationRepository + InMemoryDepreciationStore
|
||||
maintenance/ # SurrealMaintenanceRepository + InMemoryMaintenanceStore
|
||||
assignment/ # SurrealAssignmentRepository + InMemoryAssignmentStore
|
||||
shared/ # Row mappers, query helpers
|
||||
routes/
|
||||
all-routes/ # buildAllAssetRegisterRoutes
|
||||
assets/ # CRUD, depreciation, maintenance, assignment, label routes
|
||||
schema/
|
||||
schema.ts # SurrealQL DDL + applyAssetRegisterSchema
|
||||
error-codes/
|
||||
error-codes.ts # ASSET_REGISTER_API_CODES + AssetRegisterApiError
|
||||
otel/
|
||||
instruments.ts # asset_register_api.* OTel bundle
|
||||
```
|
||||
|
||||
## Entry Points
|
||||
|
||||
| Import | Exports |
|
||||
|---|---|
|
||||
| `@suaveplan/api-plugin-asset-register` | `createAssetRegisterPlugin`, `createAssetRegister`, repositories, routes, depreciation, codes, types |
|
||||
| `@suaveplan/api-plugin-asset-register/plugin` | `createAssetRegisterPlugin`, `createAssetRegister`, `AssetRegisterWiring` |
|
||||
| `@suaveplan/api-plugin-asset-register/depreciation` | `calculateDepreciation`, `DepreciationContext`, `DepreciationResult` |
|
||||
| `@suaveplan/api-plugin-asset-register/routes` | `buildAllAssetRegisterRoutes`, `buildAssetRoutes`, `RouteDeps` |
|
||||
| `@suaveplan/api-plugin-asset-register/repositories/asset` | `SurrealAssetRepository`, `InMemoryAssetStore`, types |
|
||||
| `@suaveplan/api-plugin-asset-register/error-codes` | `ASSET_REGISTER_API_CODES`, `AssetRegisterApiError` |
|
||||
| `@suaveplan/api-plugin-asset-register/otel` | OTel instruments |
|
||||
| `@suaveplan/api-plugin-asset-register/schemas` | `AssetRegisterPluginOptionsSchema` |
|
||||
| `@suaveplan/api-plugin-asset-register/types` | Public types |
|
||||
|
||||
## Patterns
|
||||
|
||||
### Basic usage
|
||||
|
||||
```ts
|
||||
import { createApi } from "@suaveplan/api";
|
||||
import { createAuth } from "@suaveplan/api-plugin-auth";
|
||||
import { createAssetRegister } from "@suaveplan/api-plugin-asset-register";
|
||||
import { SurrealAdapter } from "@suaveplan/surrealdb";
|
||||
|
||||
const db = new SurrealAdapter({ url: "ws://localhost:8000" });
|
||||
await db.connect();
|
||||
|
||||
const { plugin: authPlugin, sessionResolver } = createAuth({ betterAuth });
|
||||
const { plugin } = createAssetRegister({ db });
|
||||
|
||||
const runtime = createApi({
|
||||
plugins: [authPlugin, plugin],
|
||||
sessionResolver,
|
||||
tenantResolver,
|
||||
});
|
||||
await runtime.start("auth");
|
||||
await runtime.start("asset-register");
|
||||
```
|
||||
|
||||
## Routes
|
||||
|
||||
All routes are auth-gated and tenant-scoped. Default mount prefix `/`.
|
||||
|
||||
| Method | Path | Operation |
|
||||
|---|---|---|
|
||||
| GET | `/assets` | list assets |
|
||||
| POST | `/assets` | create asset |
|
||||
| GET | `/assets/:id` | read one asset |
|
||||
| PATCH | `/assets/:id` | update asset |
|
||||
| POST | `/assets/:id/dispose` | dispose asset |
|
||||
| GET | `/assets/:id/label` | QR SVG label |
|
||||
| GET | `/assets/:id/depreciation` | compute depreciation snapshot |
|
||||
| GET | `/assets/:id/depreciation/history` | depreciation audit trail |
|
||||
| GET | `/assets/:id/maintenance` | list maintenance records |
|
||||
| POST | `/assets/:id/maintenance` | schedule maintenance |
|
||||
| PATCH | `/assets/:id/maintenance/:maintenanceId` | complete maintenance |
|
||||
| DELETE | `/assets/:id/maintenance/:maintenanceId` | cancel maintenance |
|
||||
| GET | `/assets/:id/assignments` | list assignments |
|
||||
| POST | `/assets/:id/assignments` | assign to cost centre |
|
||||
| POST | `/assets/:id/assignments/:assignmentId/return` | return assignment |
|
||||
|
||||
## Constraints
|
||||
|
||||
- **Server-tier** — consumes `@suaveplan/surrealdb`.
|
||||
- **Owns its persistence** — four SurrealDB tables: `asset`, `depreciation_schedule`, `maintenance_record`, `asset_assignment`.
|
||||
- **Depreciation methods** — straight-line, reducing-balance, units-of-activity.
|
||||
- **Lifecycle enforcement** — disposed assets reject further updates (409); invalid maintenance transitions raise `MAINTENANCE_CONFLICT` (409); at most one active assignment per asset.
|
||||
- **In-memory variants** — each repository has an `InMemory*Store` for testing.
|
||||
- **Dependencies**: `@suaveplan/api`, `@suaveplan/api-plugin-auth`, `@suaveplan/api-plugin-kit`, `@suaveplan/api-types`, `@suaveplan/datetime`, `@suaveplan/error`, `@suaveplan/qrcode`, `@suaveplan/surrealdb`, `@suaveplan/types`, `@opentelemetry/api`, `tslib`, `zod`.
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] Read `src/depreciation/depreciation.ts` before modifying depreciation logic
|
||||
- [ ] Read `src/plugin/plugin.ts` before changing plugin wiring
|
||||
- [ ] Preserve lifecycle state-machine constraints
|
||||
- [ ] Ensure disposed assets remain immutable
|
||||
Reference in New Issue
Block a user