ImanThiyanga
7d6e597389
- Implemented CRUD operations for production templates, including listing, retrieving, creating, updating, and deactivating templates. - Introduced a new API contract for production runs, detailing the lifecycle from creation to completion, including handling of stock inputs and outputs. - Documented the architecture, requirements, entity model, and API contract for the manufacturing phase 2, ensuring clarity on the production process and its integration with existing systems.
205 lines
11 KiB
Markdown
205 lines
11 KiB
Markdown
# 01 · DOC-GUIDE — Documentation Map & Tracking Conventions
|
|
|
|
> **Purpose:** This file explains the documentation system itself — what every doc is for, the order to read them, the single navigation rule, and the conventions for the two `PROGRESS.md` tracking files. It does **not** contain requirements or API detail; it tells you where those live and how to keep everything in sync.
|
|
|
|
---
|
|
|
|
## 1. The one navigation rule
|
|
|
|
**All navigation starts at `00-CORE.md`.**
|
|
|
|
`00-CORE.md` is the hub. Whatever the task, open it first and use its routing table (§7 there) to jump to the correct document. Do not work from memory or jump straight into a spec file — the hub exists so there is a single, consistent entry point for humans and for Claude.
|
|
|
|
```
|
|
┌─────────────────┐
|
|
any task → │ 00-CORE.md │ (hub: structure, stack, setup, routing)
|
|
└────────┬────────┘
|
|
┌────────────┬───┴────────┬─────────────┬────────────┐
|
|
▼ ▼ ▼ ▼ ▼
|
|
10-BACKEND-P1 11-BACKEND-P1 20-FRONTEND 02-SECURITY 01-DOC-GUIDE
|
|
(SRS+ER+arch) (API req/res) (flows+rules) (risks+ (this file)
|
|
│ │ │ checklist)
|
|
▼ ▼ ▼
|
|
Backend/PROGRESS.md (record changes) Frontend/PROGRESS.md
|
|
```
|
|
|
|
02-SECURITY is cross-cutting: consult it alongside the backend/frontend docs, and run its checklist before ticking any feature in a PROGRESS.md.
|
|
|
|
---
|
|
|
|
## 2. Document index
|
|
|
|
| Doc | Level | Role | Read when | Who maintains |
|
|
|---|---|---|---|---|
|
|
| `00-CORE.md` | High | **Hub.** Structure, tech stack, runnable backend init, routing. | First — every task. | Claude + humans |
|
|
| `01-DOC-GUIDE.md` | High | **This file.** Doc map, reading order, tracking conventions. | To understand the doc system. | Claude + humans |
|
|
| `02-SECURITY.md` | High (cross-cutting) | **Security review aid:** accepted-risks register + per-feature checklist. | Before ticking any feature in a PROGRESS.md; during security review. | Claude + humans |
|
|
| `10-BACKEND-PHASE1.md` | High | Backend spec: **full SRS**, **ER model / 38-entity list**, tech stack detail, layer/architecture rules. Schema is **authoritative** here. | Any backend model / business-rule / requirement work (Phase 1). | Claude + humans |
|
|
| `11-BACKEND-PHASE1.md` | High | Backend **API reference**: every endpoint with complete request/response, error catalog, enums. | Any API contract / controller / client work (Phase 1). | Claude + humans |
|
|
| `12-BACKEND-HRM.md` | High | HRM backend spec: SRS, ER model, HRM-specific architecture notes. Schema is **authoritative** here. | Any HRM model / business-rule / requirement work (Phase 2). | Claude + humans |
|
|
| `13-BACKEND-HRM-API.md` | High | HRM **API reference**: every endpoint, error catalog additions, enums. | Any HRM API contract / controller work. | Claude + humans |
|
|
| `20-FRONTEND.md` | High | Frontend **user-flows**, architecture rules to follow, **validation posture**. | Any frontend work (Phase 1). | Claude + humans |
|
|
| `21-FRONTEND-HRM.md` | High | HRM frontend **user-flows**, screens, validation specifics. | Any HRM frontend work. | Claude + humans |
|
|
| `30-BACKEND-PHASE2.md` | High | Manufacturing (Production Lines) backend: SRS, ER model, status machines, stock/costing integration, **and** the full API contract — model and API in one doc, unlike Phase 1. Schema is **authoritative** here. | Any manufacturing model / rule / API work. | Claude + humans |
|
|
| `21-FRONTEND-PHASE2.md` | High | Manufacturing frontend **user-flows**: template canvas builder, run board, run execution screens. | Any manufacturing frontend work. | Claude + humans |
|
|
| `Backend/PROGRESS.md` | Low | Backend **change checklist**, git-shared. | After making backend changes. | **Claude** |
|
|
| `Frontend/PROGRESS.md` | Low | Frontend **change checklist**, git-shared. | After making frontend changes. | **Claude** |
|
|
|
|
Numbering convention: `0x` = high-level hub/guide/cross-cutting, `1x` = backend, `2x` = frontend. Numbers sort in read order in any file browser.
|
|
|
|
> **Known deviation:** `30-BACKEND-PHASE2.md` is a backend doc numbered `3x` rather than continuing the `1x` decade, and it merges the model and the API contract into one file instead of the `10`/`11` split. Left as-is — it is already the established reference for the manufacturing phase and renumbering it would invalidate every existing cross-reference. New backend phases should return to the `1x` convention.
|
|
|
|
---
|
|
|
|
## 3. Reading order (first time)
|
|
|
|
1. **`00-CORE.md`** — understand the project, structure, stack, and how to stand up the backend.
|
|
2. **`01-DOC-GUIDE.md`** (this file) — understand the doc system and tracking.
|
|
3. Then, per task, jump via the hub to `10-`, `11-`, or `20-`.
|
|
4. **`02-SECURITY.md`** — read the accepted-risks register once, then use its checklists during development.
|
|
|
|
You do not need to read `10/11/20` end-to-end before starting; open the section relevant to your task via the hub.
|
|
|
|
---
|
|
|
|
## 4. Which doc answers which question
|
|
|
|
| Question | Answer lives in |
|
|
|---|---|
|
|
| "What is the business rule for X?" / "What entity/field is this?" | `10-BACKEND-PHASE1.md` |
|
|
| "What does endpoint Y accept and return?" / "What's the error code?" | `11-BACKEND-PHASE1.md` |
|
|
| "How does the user move through the UI?" / "What do I validate on the client vs server?" | `20-FRONTEND.md` |
|
|
| "How do I set up / run the project?" | `00-CORE.md` |
|
|
| "What security risks apply to this feature?" / "What must I check before shipping it?" | `02-SECURITY.md` |
|
|
| "Is this exposure a bug or an accepted Phase-1 risk?" | `02-SECURITY.md` (Part A register) |
|
|
| "Where do I record what I changed?" | `Backend/PROGRESS.md` or `Frontend/PROGRESS.md` (this file, §6) |
|
|
|
|
If a question spans backend + frontend (e.g. a new feature), read the backend spec/API first (the contract), then the frontend doc (how the UI consumes it). For any feature that mutates data, also run its `02-SECURITY.md` checklist.
|
|
|
|
---
|
|
|
|
## 5. Maintenance rules (single source of truth)
|
|
|
|
- **One source of truth per topic.** Requirements live only in `10-`; API contracts live only in `11-`; frontend rules live only in `20-`. Do not copy content between docs — link instead.
|
|
- **Edit in place.** When a requirement or endpoint changes, update it where it lives. Never fork a second copy.
|
|
- **Contract before consumer.** Change the backend spec/API doc first, then update the frontend doc and code to match.
|
|
- **Keep the hub thin.** `00-CORE.md` routes and sets up; it must not accumulate requirement/API detail.
|
|
- **Every material change updates a `PROGRESS.md`** (see §6). Docs and trackers move together in the same commit as the code.
|
|
|
|
---
|
|
|
|
## 6. Tracking convention — `PROGRESS.md`
|
|
|
|
Two low-level checklists record what has actually been built. They live **inside** each project so they travel with code across branches and are diff-visible in git:
|
|
- `Backend/PROGRESS.md`
|
|
- `Frontend/PROGRESS.md`
|
|
|
|
### 6.1 Rules
|
|
- **Claude maintains these.** On every change to a side, update that side's `PROGRESS.md` in the **same commit** as the code.
|
|
- Use checkboxes: `- [ ]` not started · `- [~]` in progress · `- [x]` done.
|
|
- Each entry is a concrete, verifiable unit of work (an endpoint, an entity + its configuration, a service method, a screen, a validation rule) — not vague ("did stuff").
|
|
- Group by module/area so the file mirrors the spec structure.
|
|
- When ticking `- [x]`, append a short note: what was done + any deviation from the spec (and why).
|
|
- Never delete history; move completed items under a **Done** section if the active list gets long.
|
|
- If a change alters a spec doc (`10/11/20`), reference it: `(updates 11-BACKEND-PHASE1 §5.4)`.
|
|
|
|
### 6.2 Backend `PROGRESS.md` starter template
|
|
```markdown
|
|
# Backend — PROGRESS (Phase 1: Inventory & Supply Chain)
|
|
|
|
Legend: [ ] not started · [~] in progress · [x] done
|
|
Spec: docs/10-BACKEND-PHASE1.md (model) · docs/11-BACKEND-PHASE1.md (API)
|
|
|
|
## 0. Bootstrap
|
|
- [ ] Solution + Web API project (net10.0), packages restored
|
|
- [ ] Folder structure per 00-CORE §5.3
|
|
- [ ] ErpDbContext + Npgsql wired; InitialCreate migration applied
|
|
- [ ] Serilog, JWT, Swagger, HealthChecks, ProblemDetails in Program.cs
|
|
- [ ] UnitOfWork + generic repository base
|
|
- [ ] ICurrentUser (audit stamp from token)
|
|
|
|
## 1. Master Data
|
|
- [ ] Item: entity + config + enum(s)
|
|
- [ ] Item: repository + service + controller (CRUD, DTOs)
|
|
- [ ] UOM + conversions
|
|
- [ ] Category (hierarchy)
|
|
- [ ] Vendor
|
|
- [ ] Warehouse + Bin
|
|
- [ ] Item reorder settings
|
|
|
|
## 2. Procurement
|
|
- [ ] Requisition (+ lines)
|
|
- [ ] RFQ + quotations + comparison
|
|
- [ ] Purchase Order (create, edit-while-open, auto-approve, cancel)
|
|
- [ ] Purchase Return
|
|
|
|
## 3. Goods Receipt
|
|
- [ ] GRN (create against PO / direct)
|
|
- [ ] GRN confirm → FIFO layer + ledger + PO qtyReceived
|
|
- [ ] Inspection hold release/reject
|
|
|
|
## 4. Stock Core
|
|
- [ ] StockLayer + StockLedger entities/config
|
|
- [ ] FifoCostingService (consume oldest-first, valuation)
|
|
- [ ] Stock enquiry (onHand/available/onHold/inTransit)
|
|
- [ ] Ledger query · Valuation query
|
|
|
|
## 5. Stock Transactions
|
|
- [ ] Transfer (create → dispatch → receive, in-transit, cost-preserving)
|
|
- [ ] Adjustment (auto-post, reason code)
|
|
- [ ] Count (cycle/full → variance → post)
|
|
- [ ] Reorder alerts
|
|
|
|
## 6. Cross-cutting
|
|
- [ ] ProblemDetails error catalog + domain exceptions
|
|
- [ ] Audit log on mutations
|
|
- [ ] Auth (simple in-app login → JWT)
|
|
- [ ] Document numbering sequences
|
|
|
|
## Done
|
|
<!-- move [x] items here with date + note if the active list grows -->
|
|
```
|
|
|
|
### 6.3 Frontend `PROGRESS.md` starter template
|
|
```markdown
|
|
# Frontend — PROGRESS (Phase 1: Inventory & Supply Chain)
|
|
|
|
Legend: [ ] not started · [~] in progress · [x] done
|
|
Spec: docs/20-FRONTEND.md (flows + rules) · docs/11-BACKEND-PHASE1.md (API contract)
|
|
|
|
## 0. Foundation
|
|
- [ ] API base URL env wired (NEXT_PUBLIC_API_BASE_URL)
|
|
- [ ] Typed API client / fetch wrapper + auth token handling
|
|
- [ ] Shared types mirroring API DTOs
|
|
- [ ] Client-side validation helpers (dependency-free)
|
|
|
|
## 1. Screens / flows (per 20-FRONTEND user-flows)
|
|
- [ ] Login
|
|
- [ ] Items (list + create/edit)
|
|
- [ ] Vendors · Warehouses/Bins
|
|
- [ ] Requisition → PO flow
|
|
- [ ] GRN (receive + hold handling)
|
|
- [ ] Stock: enquiry · transfer · adjustment · count · reorder
|
|
|
|
## 2. Validation posture (client for UX; server authoritative)
|
|
- [ ] Client format/required/range checks on forms
|
|
- [ ] Surface server ProblemDetails errors (incl. domain codes)
|
|
- [ ] Never assume stock/availability rules client-side
|
|
|
|
## Done
|
|
<!-- move [x] items here with date + note if the active list grows -->
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Adding future docs
|
|
|
|
When later phases arrive (Sales & CRM, Manufacturing, QC/QA, Accounting), follow the same scheme HRM (Phase 2) established:
|
|
- Backend spec/API for a phase → new `1x-` files continuing the backend decade (e.g. HRM used `12-BACKEND-HRM.md` + `13-BACKEND-HRM-API.md`, mirroring the `10`/`11` SRS+ER / API-reference split), linked from the hub.
|
|
- Frontend additions → extend `20-FRONTEND.md` or add `2x-` files (e.g. HRM used `21-FRONTEND-HRM.md`).
|
|
- Always register the new doc in `00-CORE.md` routing (§7) and in this index (§2).
|
|
|
|
---
|
|
|
|
*End of 01-DOC-GUIDE.md. Return to `00-CORE.md` to route to your task.*
|