@goweekdays/core 2.13.0 → 2.15.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @goweekdays/core
 
+## 2.15.0
+
+### Minor Changes
+
+- 770a91a: Finance business profile initial release
+
+### Patch Changes
+
+- c54c430: Integrate account balance tracker
+- b31181e: Support updating journal entries with line diffing
+
+## 2.14.0
+
+### Minor Changes
+
+- a604a6f: Initial release for finance journal and ledger
+
+### Patch Changes
+
+- 29b0676: Add indexes, search and fields for journal lines
+
 ## 2.13.0
 
 ### Minor Changes

package/CLAUDE.md

@@ -0,0 +1,274 @@
+# server-core-module (`@goweekdays/core`)
+
+Shared server module exported as a package consumed by all app servers.
+Built with Express + MongoDB (Atlas) + TypeScript.
+
+## Resource Layer Pattern
+
+Each resource lives under `src/resources/<resource-name>/` and follows this structure:
+
+```
+resource-name/
+  resource.model.ts       # Types and validation schema
+  resource.repository.ts  # Direct database interaction
+  resource.service.ts     # Business logic (optional — see below)
+  resource.controller.ts  # API request handler
+  index.ts                # Barrel export
+```
+
+### `.model.ts`
+
+Defines the TypeScript type and Joi validation schema for the resource. This is the source of truth for the shape of the data.
+
+### `.repository.ts`
+
+Contains all functions that directly interact with the database (MongoDB). No business logic here — only reads and writes.
+
+### `.service.ts`
+
+Builds business logic by composing repository functions and third-party integrations (e.g. hashing, email, S3, transactions). Never accesses the database directly — all DB interaction goes through the repository. **This layer is optional** — if a resource only needs basic CRUD with no business logic, a service file is not required.
+
+### `.controller.ts`
+
+Handles incoming API requests. Validates the request input, then delegates to the service layer if business logic exists, or calls the repository directly if the resource has no service.
+
+### `index.ts`
+
+Re-exports all layers so consumers can import from the resource folder directly.
+
+```typescript
+export * from "./user.model";
+export * from "./user.repository";
+export * from "./user.service";
+export * from "./user.controller";
+```
+
+---
+
+## Naming Conventions
+
+| Layer      | Pattern                     | Example                                              |
+| ---------- | --------------------------- | ---------------------------------------------------- |
+| File       | `<resource>.<layer>.ts`     | `user.model.ts`, `finance.journal.config.service.ts` |
+| Type       | `T<Resource>`               | `TUser`, `TJobPost`                                  |
+| Schema     | `schema<Resource>`          | `schemaUser`, `schemaJobPost`                        |
+| Model fn   | `model<Resource>()`         | `modelUser()`, `modelJobPost()`                      |
+| Repository | `use<Resource>Repo()`       | `useUserRepo()`, `useOrgRepo()`                      |
+| Service    | `use<Resource>Service()`    | `useUserService()`, `useOrgService()`                |
+| Controller | `use<Resource>Controller()` | `useUserController()`                                |
+
+Multi-word resource names use dot notation in file names: `finance.journal.config.model.ts`, `job.post.repository.ts`.
+
+---
+
+## Error Handling
+
+Always use the typed error classes from `@goweekdays/utils` — never throw a generic `new Error()`.
+
+- `BadRequestError` — invalid input or a violated business rule
+- `NotFoundError` — resource does not exist
+- `InternalServerError` — unexpected DB or system failure
+- `AppError` — base class; use `instanceof AppError` in catch blocks to re-throw typed errors as-is
+
+---
+
+## Controller Input Extraction
+
+Validate the entire `req.body` against a Joi schema to ensure no unexpected keys are passed. Extract only the fields you need after validation.
+
+1. Define a Joi schema that describes exactly the expected shape
+2. Validate `req.body` (or `req.params` / `req.query`) against it — reject if invalid
+3. Destructure only the needed fields from the validated result
+4. Delegate to the service or repository
+
+This prevents unexpected or extra fields from leaking into the database.
+
+---
+
+## Transactions
+
+Use a MongoDB session whenever a service function writes to more than one collection. The pattern is always:
+
+1. Start session and transaction
+2. Pass `session` down to every repo call
+3. Commit on success, abort on error, and always end the session in `finally`
+
+Transactions belong in the service layer only — never in a controller or repository.
+
+---
+
+## What Not To Do
+
+- **No business logic in controllers** — controllers only handle HTTP input/output and delegate
+- **No direct DB access in controllers or services** — all DB interaction belongs in the repository only
+- **No generic `Error` throws** — use the typed error classes above
+- **No Zod** — validation is done with Joi throughout this module
+- **No extra fields into the DB** — always validate the full request body before using any of it
+
+# Monthly Account Balance Tracking — Instruction Set
+
+## Objective
+
+Maintain a monthly balance tracker for each account using the structure:
+
+(accountId, fiscalYear, month)
+
+Each record must contain:
+
+- openingDebit
+- openingCredit
+- movementDebit
+- movementCredit
+- closingDebit
+- closingCredit
+- netBalance
+
+---
+
+# 1. When Posting a Journal Entry
+
+For each journal line in a transaction:
+
+1. Identify:
+
+   - accountId
+   - transactionDate
+   - month
+   - fiscalYear
+   - debitAmount
+   - creditAmount
+
+2. Locate the balance record:
+
+(accountId, fiscalYear, month)
+
+---
+
+# 2. If Balance Record Exists
+
+Update the movement values.
+
+If the journal line is debit:
+
+movementDebit += debitAmount
+
+If the journal line is credit:
+
+movementCredit += creditAmount
+
+Then recompute the closing balance.
+
+---
+
+# 3. If Balance Record Does NOT Exist
+
+Create a new balance record.
+
+Determine the opening balance using the following rules.
+
+## Rule A — Previous Month Record Exists
+
+Find the latest previous balance record for the same account.
+
+(accountId, previousMonth, fiscalYear)
+
+Set the opening balance:
+
+openingDebit = previousRecord.closingDebit
+openingCredit = previousRecord.closingCredit
+
+## Rule B — No Previous Record Exists
+
+This means the account is used for the first time.
+
+Set:
+
+openingDebit = 0
+openingCredit = 0
+
+## Initialize Movement
+
+After determining the opening balance:
+
+movementDebit = debitAmount
+movementCredit = creditAmount
+
+---
+
+# 4. Recompute Closing Balance
+
+After movement updates, compute the net balance.
+
+netBalance = (openingDebit + movementDebit) - (openingCredit + movementCredit)
+
+If netBalance > 0:
+
+closingDebit = netBalance
+closingCredit = 0
+
+If netBalance < 0:
+
+closingDebit = 0
+closingCredit = abs(netBalance)
+
+If netBalance == 0:
+
+closingDebit = 0
+closingCredit = 0
+
+The `netBalance` field should always store the computed value so the system can quickly determine whether the account has a debit or credit balance without recalculating.
+
+---
+
+# 5. Month-to-Month Carry Forward Rule
+
+When a new month record is created:
+
+opening balance = previous month closing balance
+
+Example:
+
+January closing = 8,000 debit
+February opening = 8,000 debit
+
+---
+
+# 6. Summary of Posting Flow
+
+For each journal line:
+
+1. Determine account, fiscalYear, and month
+2. Find balance record
+3. If record exists → update movement
+4. If record does not exist
+
+   - find previous balance record
+   - set opening = previous closing (or zero)
+   - create new balance record
+
+5. Update movement values
+6. Recompute closing balance
+
+---
+
+# 7. Important Principle
+
+Opening balance always represents:
+
+balance before the period starts
+
+Therefore:
+
+opening = previous closing
+
+If no previous record exists:
+
+opening = 0
+
+---
+
+This logic ensures:
+
+- continuous balance tracking
+- correct month-to-month carry over
+- efficient financial reporting without recalculating all journal entries