kibin/NetForge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(02-02): complete JournalEntryService plan

Browse Source 
Tasks completed: 2/2
- Task 1: JournalEntry models + JournalEntryService
- Task 2: Journal entry API routes + comprehensive tests

SUMMARY: .planning/phases/02-subscriber-and-billing-core/02-02-SUMMARY.md
This commit is contained in:
kevin-asprec
2026-03-04 23:25:42 +08:00
parent 30ec936b68
commit c60c22b080
2 changed files with 189 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
.planning/STATE.md
View File

@@ -10,29 +10,29 @@ See: .planning/PROJECT.md (updated 2026-03-04)
## Current Position
Phase: 2 of 5 (Subscriber and Billing Core) — In progress
Plan: 3 of 5 in phase 2 complete (8/20 total)
Status: In progress. 02-01 (COA + Accounting Periods) and 02-03 (Subscriber + ServicePlan) complete.
Last activity: 2026-03-04 — Completed 02-03-PLAN.md (Subscriber management, service plans, 41 new tests, 162 total)
Plan: 4 of 5 in phase 2 complete (9/20 total)
Status: In progress. 02-01 (COA), 02-02 (JournalEntryService), 02-03 (Subscriber) complete. Now ready for 02-04 (BillingEngine).
Last activity: 2026-03-04 — Completed 02-02-PLAN.md (JournalEntryService, 36 new tests, 198 total)
Progress: [████████░░] 40% (8/20 plans across all phases)
Progress: [████████░░] 45% (9/20 plans across all phases)
## Performance Metrics
**Velocity:**
- Total plans completed: 6
- Average duration: 8.0 min
- Total execution time: 48 min
- Total plans completed: 7
- Average duration: 8.7 min
- Total execution time: 64 min
**By Phase:**
| Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------|
| 01-foundation | 5/5 complete | 41 min | 8.2 min |
| 02-subscriber-and-billing-core | 3/5 complete | 21 min | 7 min |
| 02-subscriber-and-billing-core | 4/5 complete | 37 min | 9.25 min |
**Recent Trend:**
- Last 7 plans: 01-01 (11 min), 01-02 (8 min), 01-03 (9 min), 01-04 (7 min), 01-05 (6 min), 02-01 (7 min), 02-03 (7 min)
- Trend: stable around 7-8 min
- Last 7 plans: 01-02 (8 min), 01-03 (9 min), 01-04 (7 min), 01-05 (6 min), 02-01 (7 min), 02-03 (7 min), 02-02 (16 min)
- Trend: slightly elevated (02-02 was complex — schema + service + API + 36 tests)
*Updated after each plan completion*
@@ -74,6 +74,13 @@ Recent decisions affecting current work:
- [02-01]: seedChartOfAccounts receives Prisma tx client — works inside createTenant $transaction for atomic provisioning
- [02-01]: Accounting periods created on-demand via getOpenPeriod() — not pre-seeded on signup (no wasted periods for unused months)
- [02-01]: close route uses closure pattern over withPermission HOF — withPermission doesn't support dynamic params directly; POST fn closes over Next.js params
- [02-02]: JournalEntry self-referential reversal uses reversesEntryId @unique — one-to-one Prisma relation requires unique; semantically correct (one entry reverses at most one other)
- [02-02]: tenantId passed explicitly in $transaction callbacks — raw tx client lacks the withTenantContext() extension; must inject tenantId manually in create data
- [02-02]: startDate added to getAccountBalance — enables date-range balance queries; needed for period-scoped reporting and test isolation
- [02-02]: Integer cents for debit=credit validation — Math.round(n*100) avoids floating point drift on decimal amounts
- [02-02]: SYSTEM source auto-posts (POSTED status), MANUAL entries start DRAFT for maker-checker workflow
- [02-02]: Self-approval allowed — single-person ISP operations are common; blocking self-approval breaks common use case
- [02-02]: JournalEntryService is sole gateway — NO other code may write to JournalEntry/JournalEntryLine directly
- [02-03]: creditBalance on Subscriber is operational convenience (FIFO credit allocation for 02-05), NOT a ledger balance — always updated atomically with journal entries
- [02-03]: billingDay capped at 28 — subscribers signing up on days 29-31 get billingDay=28 to avoid month-length invoice generation issues
- [02-03]: CANCELLED -> ACTIVE transition is reversible by design — ISPs frequently reinstate cancelled accounts per CONTEXT.md
@@ -89,9 +96,10 @@ None.
- [Phase 3 research flag]: Semaphore SMS API pricing/stability for 2026 is MEDIUM confidence — verify before any SMS work (SMS is v2, but abstraction layer design is relevant)
- [01-04 note]: CASL condition types for string subjects use any cast — upgrade to class-based subjects when Phase 2 Prisma models (Subscriber, Invoice, etc.) are defined
- [01-05 note]: /admin/tenants/[id] detail page is a stub link ("View") — detail view not implemented yet (out of Phase 1 scope)
- [02-02 note]: JournalEntry afterAll cleanup needs explicit order (lines → null reversesEntryId → entries → tenant) — document for any future test that involves journal entries
## Session Continuity
Last session: 2026-03-04T15:02:45Z
Stopped at: Completed 02-03-PLAN.md (Subscriber + ServicePlan management + 41 new tests, 162 total)
Last session: 2026-03-04T15:23:19Z
Stopped at: Completed 02-02-PLAN.md (JournalEntryService + 36 new tests, 198 total)
Resume file: None