78 lines
6.2 KiB
Markdown
78 lines
6.2 KiB
Markdown
# Development Instructions
|
|
|
|
## Documentation maintenance
|
|
|
|
- Keep [CHANGELOG.md](D:/CODING/mrp-codex/CHANGELOG.md) updated whenever shipped functionality, architecture expectations, deployment behavior, or user-facing workflows materially change.
|
|
- If a change invalidates [README.md](D:/CODING/mrp-codex/README.md), [STRUCTURE.md](D:/CODING/mrp-codex/STRUCTURE.md), [ROADMAP.md](D:/CODING/mrp-codex/ROADMAP.md), or [UNRAID.md](D:/CODING/mrp-codex/UNRAID.md), update those files in the same change set.
|
|
|
|
## Current milestone
|
|
|
|
This repository implements the platform foundation milestone:
|
|
|
|
- workspace scaffolding
|
|
- local auth and RBAC
|
|
- company settings and branding
|
|
- file attachment storage
|
|
- CRM foundation through reseller hierarchy, contacts, attachments, and lifecycle metadata
|
|
- inventory master data, BOM, warehouse, stock-location, transactions, and item attachments
|
|
- inventory transfers, reservations, available-stock visibility, and work-order reservation automation
|
|
- sales quotes and sales orders with quick actions and quote conversion
|
|
- sales approvals, approval stamps, and automatic revision history on quotes and sales orders
|
|
- purchase orders with quick actions and searchable vendor/SKU entry
|
|
- purchase orders restricted to inventory items flagged as purchasable
|
|
- purchase receiving foundation with inventory posting and receipt history
|
|
- branded sales and purchasing PDFs through the shared Puppeteer document pipeline
|
|
- purchase-order supporting documents and vendor-side purchasing visibility
|
|
- shipping shipments linked to sales orders with packing slips, shipping labels, bills of lading, and logistics attachments
|
|
- projects with customer/commercial/shipment linkage, owners, due dates, notes, attachments, and dashboard visibility
|
|
- manufacturing work orders with project linkage, station master data, item operation templates, auto-generated work-order operations, attachments, and dashboard visibility
|
|
- planning gantt timelines backed by live project and manufacturing schedule data
|
|
- sales-order demand planning with multi-level BOM explosion, net stock/open-supply coverage, and build/buy recommendations
|
|
- planner-assisted conversion of demand-planning recommendations into prefilled work-order and purchase-order drafts
|
|
- pegged work-order and purchase-order supply coverage tied back to sales demand, with preferred-vendor sourcing defaults
|
|
- shared shortage and readiness rollups across dashboard, planning, projects, purchasing, and manufacturing
|
|
- admin diagnostics with runtime footprint, storage visibility, record counts, and recent audit activity
|
|
- admin user management with account creation, activation, role assignment, role-permission editing, and session visibility/revocation
|
|
- safer destructive-action confirmations and recovery messaging across admin, inventory, manufacturing, and attachment workflows
|
|
- CRM/shipping audit coverage and startup validation surfaced through diagnostics
|
|
- backup/restore guidance, richer startup diagnostics, and exportable support bundles in diagnostics
|
|
- backup verification checklist and restore-drill runbook in diagnostics
|
|
- support-log viewing and support debugging helpers in diagnostics
|
|
- Dockerized single-container deployment
|
|
- Puppeteer PDF pipeline foundation
|
|
|
|
## Workflow
|
|
|
|
1. Update the roadmap before starting large features.
|
|
2. Keep backend and frontend modules grouped by domain.
|
|
3. Add Prisma models and migrations for all persisted schema changes.
|
|
4. Keep uploaded files on disk under `/app/data/uploads`; never store blobs in SQLite.
|
|
5. Reuse shared DTOs and permission keys from the `shared` package.
|
|
6. Any non-filter UI that looks up records or items must use a searchable picker/autocomplete, not a long static dropdown.
|
|
7. Inventory items must carry both `defaultCost` and `defaultPrice`; sales documents should default line pricing from the selected item `defaultPrice`.
|
|
8. Maintain the denser UI baseline on active screens; avoid reintroducing oversized `px-4 py-3` style controls, tall action bars, or overly loose card spacing without a specific reason.
|
|
9. Treat the landing page as `Dashboard`: a metric-oriented, modular command surface that should accumulate reusable operational panels over time.
|
|
10. Purchase-order item selection must be restricted to inventory items where `isPurchasable = true`.
|
|
11. Treat `Projects` as a first-class cross-module domain tying together CRM, sales, inventory, purchasing, shipping, and planning; do not bury it as a one-off manufacturing subfeature.
|
|
12. Keep `Projects`, `Manufacturing`, and `Planning` distinct: projects are long-running program records, manufacturing is execution, and planning is scheduling/visibility.
|
|
13. New top-level modules added to the app shell should include a matching SVG icon in navigation so the module list remains visually scannable.
|
|
|
|
## Operational notes
|
|
|
|
- Run `npm run prisma:generate` after schema changes.
|
|
- Run `npm run prisma:migrate` during development to create versioned migrations.
|
|
- Use `npm run prisma:deploy` in production environments.
|
|
- Prefer Node 22 locally when running Prisma migration commands to match the Docker runtime.
|
|
- Branding defaults live in the frontend theme token layer and are overridden by the persisted company profile.
|
|
- Back up the whole `/app/data` volume to capture both the database and attachments.
|
|
- Treat searchable lookup as a standing UX requirement for inventory, BOM, sales, purchasing, manufacturing, customer, vendor, and other operational record-picking flows. Filter-only controls can still use dropdowns.
|
|
- Extend the existing Puppeteer document pipeline when adding customer-facing or logistics PDFs instead of creating a parallel export mechanism.
|
|
- Add future dashboard features as modular metric/action panels instead of one-off hero sections or static marketing-style content.
|
|
- When implementing projects, model the relationships explicitly so project records can anchor execution across customer, order, material, schedule, and shipment workflows.
|
|
- When implementing manufacturing, keep work orders, routings, labor, and shop-floor execution in their own domain rather than collapsing them into projects.
|
|
|
|
## Next roadmap candidates
|
|
|
|
- deeper session history, filtering, and admin-side access review polish
|
|
- extend destructive-action safety coverage across sales, purchasing, shipping, and project workflows
|