From a54e5901f0aa3ef5146cdb71c02f6bfc0a7cb4c6 Mon Sep 17 00:00:00 2001 From: jason Date: Sat, 14 Mar 2026 23:30:53 -0500 Subject: [PATCH] documentation --- AGENTS.md | 17 +++++++++++------ INSTRUCTIONS.md | 14 ++++++++------ README.md | 26 ++++++++++++++++++++++++-- ROADMAP.md | 14 ++++++++------ STRUCTURE.md | 1 + UNRAID.md | 3 ++- 6 files changed, 54 insertions(+), 21 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7b9dbcf..9d5084c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,6 +14,9 @@ MRP Codex is a modular Manufacturing Resource Planning platform intended to be a - local JWT auth and RBAC - Company Settings and runtime branding - filesystem-backed attachments +- CRM customers/vendors, hierarchy, contacts, lifecycle metadata, and attachments +- inventory items, BOMs, warehouses, locations, transactions, item attachments, and item pricing +- sales quotes and sales orders - Puppeteer PDF foundation - single-container Docker deployment @@ -94,16 +97,19 @@ If implementation changes invalidate those docs, update them in the same change - Light and dark mode must remain first-class, not bolted on later - New UI should respect the theme system and avoid hardcoded one-off colors where possible - Keep the interface intentional and operational, not generic admin-template filler +- Non-filter operational lookups must use searchable pickers/autocomplete instead of long static dropdowns +- Keep the denser UI baseline on active screens unless a specific workflow needs more space +- Inventory items maintain both cost and price; sales entry should default from item price ## Feature expectations Near-term priorities are: -1. CRM detail and edit workflows -2. Inventory and BOM data model -3. Sales and quote foundation -4. Shipping tied to sales orders -5. Live manufacturing gantt scheduling +1. Shipping tied to sales orders +2. Purchase orders and vendor-side flow +3. Sales and purchasing PDF templates +4. Live manufacturing gantt scheduling +5. Audit and operations maturity When adding new modules, preserve the ability to extend the system without refactoring the existing app shell. @@ -132,4 +138,3 @@ If you cannot run one of those checks, say so explicitly. - Prisma runtime on Debian bookworm requires `debian-openssl-3.0.x` - `shared` package exports must use Node ESM-compatible `.js` specifiers - Local Docker validation may fail if the Docker daemon is unavailable; distinguish daemon issues from image issues - diff --git a/INSTRUCTIONS.md b/INSTRUCTIONS.md index a567a82..bc42737 100644 --- a/INSTRUCTIONS.md +++ b/INSTRUCTIONS.md @@ -9,7 +9,8 @@ This repository implements the platform foundation milestone: - company settings and branding - file attachment storage - CRM foundation through reseller hierarchy, contacts, attachments, and lifecycle metadata -- inventory master data, BOM, warehouse, and stock-location foundation +- inventory master data, BOM, warehouse, stock-location, transactions, and item attachments +- sales quotes and sales orders with quick actions and quote conversion - Dockerized single-container deployment - Puppeteer PDF pipeline foundation @@ -21,7 +22,8 @@ This repository implements the platform foundation milestone: 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. 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. +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. ## Operational notes @@ -35,8 +37,8 @@ This repository implements the platform foundation milestone: ## Next roadmap candidates -- inventory transactions and on-hand tracking -- BOM/item drawing attachments and support documents -- sales orders, purchase orders, and document templates -- shipping workflows and printable logistics documents +- shipping workflows tied to sales orders +- purchase orders and vendor-facing receiving flow +- sales and purchasing document templates - manufacturing gantt scheduling with live project data +- broader audit and operations maturity diff --git a/README.md b/README.md index 1ef371c..9862a13 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,8 @@ Current foundation scope includes: - CRM customers and vendors with create/edit/detail workflows - CRM search, filtering, status tagging, and reseller hierarchy - CRM contact history, account contacts, and shared attachments -- inventory item master, BOM, warehouse, and stock-location foundation +- inventory item master, BOM, warehouse, stock-location, and stock-transaction flows +- sales quotes and sales orders with searchable customer and SKU entry - file storage and PDF rendering ## Workspace @@ -82,18 +83,36 @@ Recent CRM features depend on the committed Prisma migrations being applied. If The current inventory foundation supports: - protected item master list, detail, create, and edit flows -- SKU, description, type, status, unit-of-measure, sellable/purchasable, default cost, and notes fields +- SKU, description, type, status, unit-of-measure, sellable/purchasable, default cost, default price, and notes fields - BOM header and BOM line editing directly on the item form - searchable component lookup for BOM lines, designed for large item catalogs - SKU-first searchable component lookup for BOM lines, with SKU shown in the picker and description kept separate in the selected row - BOM detail display with component SKU, name, quantity, unit, notes, and position - protected warehouse list, detail, create, and edit flows - nested stock-location management inside each warehouse record +- inventory transaction posting for receipts, issues, and adjustments +- item on-hand quantity, stock-by-location balances, and recent stock history +- item-level file attachments for drawings and support documents - seeded sample inventory items and a starter assembly BOM during bootstrap - seeded sample warehouse and stock locations during bootstrap This module introduces `inventory.read` and `inventory.write` permissions. After updating the code, restart the server against the migrated database so bootstrap can upsert the new permissions onto the default administrator role. +`defaultPrice` now flows from inventory items into quote and sales-order line entry when a SKU is selected. Users can still override the line price after selection. + +## Sales + +The current sales foundation supports: + +- quote and sales-order list, detail, create, and edit flows +- searchable customer lookup instead of static customer dropdowns +- SKU-searchable line entry for quote and order lines +- status quick actions directly from quote and order detail pages +- quote conversion into a sales order +- line-level unit prices populated from the selected inventory item default price + +This module introduces `sales.read` and `sales.write` permissions. After updating the code, restart the server against the migrated database so bootstrap can upsert the new permissions onto the default administrator role. + Moving forward, any UI that requires searching for records or items should use a searchable picker/autocomplete rather than a static dropdown. Filter controls can remain dropdowns, but non-filter lookup fields such as SKU pickers, customer selectors, vendor selectors, and similar operational search inputs should not be implemented as long static selects. ## UI Density @@ -127,6 +146,9 @@ As of March 14, 2026, the latest committed domain migrations include: - CRM lifecycle stages and operational metadata - inventory item master and BOM foundation - warehouse and stock-location foundation +- inventory transactions and on-hand tracking +- sales quote and sales-order foundation +- inventory default price support ## UI Notes diff --git a/ROADMAP.md b/ROADMAP.md index 2dcf677..36d1b99 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -39,7 +39,9 @@ MRP Codex is being built as a streamlined, modular manufacturing resource planni - Prisma migration execution is committed and documented, but local Windows Node 24 schema-engine behavior remains inconsistent; use Node 22 or Docker for migration execution - The frontend bundle is functional but should be code-split later, especially around the gantt module - CRM reporting is now functional, but broader account-role depth and downstream document rollups can still evolve later -- Inventory currently covers master data and warehouse structure, but not stock movement, on-hand balances, or transaction history yet +- Shipping is not yet linked to sales orders +- Purchasing documents are not yet implemented +- The current sales foundation does not yet include approvals, revisions, or branded transactional PDFs ## Planned feature phases @@ -101,8 +103,8 @@ MRP Codex is being built as a streamlined, modular manufacturing resource planni ## Near-term priority order -1. Inventory transactions and on-hand tracking -2. BOM and item attachments for drawings and support docs -3. Sales order and quote foundation -4. Shipping module tied to sales orders -5. Live manufacturing gantt scheduling +1. Shipping module tied to sales orders +2. Purchase orders and vendor-facing document flow +3. Sales and purchasing PDF templates +4. Live manufacturing gantt scheduling +5. Broader audit and operations maturity diff --git a/STRUCTURE.md b/STRUCTURE.md index 858ded8..04f8f7b 100644 --- a/STRUCTURE.md +++ b/STRUCTURE.md @@ -16,6 +16,7 @@ - Theme state and brand tokens belong in `src/theme`. - PDF screen components must remain separate from API-rendered document templates. - Any non-filter lookup UI must be implemented as a searchable picker or autocomplete; do not use long static dropdowns for operational datasets such as items, customers, vendors, or document-linked records. +- Inventory items expose both cost and sell price. Downstream sales document entry should default from the item price field rather than requiring duplicate price maintenance. - Preserve the current dense operations UI style on active module pages: compact controls, tighter card padding, and shorter empty states unless a screen has a clear reason to be more spacious. ## Backend rules diff --git a/UNRAID.md b/UNRAID.md index c345405..b8096cd 100644 --- a/UNRAID.md +++ b/UNRAID.md @@ -125,6 +125,8 @@ When you publish a new image: Because MRP Codex runs `prisma migrate deploy` during startup, committed migrations are applied automatically before the app launches. +This is especially important now that recent releases added CRM expansion, inventory transactions, sales documents, and the inventory `defaultPrice` field. Let the container complete startup migrations before testing new screens. + ## Backup guidance Back up the host directory mapped to `/app/data`, typically: @@ -185,4 +187,3 @@ Set `CLIENT_ORIGIN` to the exact URL used by the browser, including protocol and - Env: `DATABASE_URL=file:../../data/prisma/app.db` - Env: `PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium` - Env: `CLIENT_ORIGIN=http://YOUR-UNRAID-IP:3000` -