HarithaRandunu
22657f0910
- Added a new Ledgers sidebar section for statutory-format financial reports and cash/bank-account management. - Introduced dedicated GL client for API interactions, handling response envelopes and error management. - Developed report screens for Trial Balance, Balance Sheet, General Ledger, Profit & Loss, Cash Flow, Budget vs Actual, and a new Tax Report. - Implemented CSV download functionality alongside existing PDF downloads for all report screens. - Separated Cash and Bank accounts into distinct tables/endpoints, with updated create forms and unified list view. - Created a new Accounts section for Cheque Management, moving Cash/Bank Accounts from the Ledgers section. - Updated RBAC navigation to include new permissions and sub-navigation items for the added features. - Ensured compliance with GL's updated API contract, including renaming fields and adjusting response shapes. - Addressed various bugs and presentation issues, enhancing user experience across the new module.
207 lines
12 KiB
Markdown
207 lines
12 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 |
|
|
| `12-GENERAL-LEDGER-INTEGRATION.md` | High | ERPCore ↔ external **General Ledger service**: connection/proxy contract, config, progress. GL's own endpoint contract lives in the GL service's own repo, not here. | Any work touching the GL proxy or a future internal GL caller. | 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 |
|
|
| `21-GENERAL-LEDGER-FRONTEND.md` | High | **Ledgers** sidebar section: statutory-format report screens + PDF download, Cash/Bank Accounts (list/create; edit gap explained). Extends `20-FRONTEND.md` rather than duplicating it. | Any work on `app/dashboard/ledgers/*`. | 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.*
|