From 4b4f7bce3b11f918c7febdfccaaa87247191999d Mon Sep 17 00:00:00 2001
From: kevin-asprec <kevin.asprec@irely.com>
Date: Thu, 5 Mar 2026 05:53:44 +0800
Subject: [PATCH] docs(03): capture phase context

Phase 03: Operational Modules
- Implementation decisions documented
- Phase boundary established
---
 .../03-operational-modules/03-CONTEXT.md      | 105 ++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 .planning/phases/03-operational-modules/03-CONTEXT.md

diff --git a/.planning/phases/03-operational-modules/03-CONTEXT.md b/.planning/phases/03-operational-modules/03-CONTEXT.md
new file mode 100644
index 0000000..e8ffda7
--- /dev/null
+++ b/.planning/phases/03-operational-modules/03-CONTEXT.md
@@ -0,0 +1,105 @@
+# Phase 3: Operational Modules - Context
+
+**Gathered:** 2026-03-05
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Collectors can log field cash collections and remit to management with a verified audit trail; staff can create support tickets and convert them to job orders; technicians update their assigned work; the system calculates technician compensation per job or monthly salary. Client portal ticket submission is Phase 5. Inventory/expense tracking is Phase 4.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Collector field collection
+- Collector selects subscriber and logs total amount received (lump sum per subscriber)
+- System applies FIFO allocation against outstanding invoices — same pattern as existing PaymentService
+- No per-invoice selection in the field — keeps collector workflow fast and simple
+
+### Remittance verification
+- Independent count model: office staff enters their own counted total
+- System compares staff count against collector's logged collections and displays variance
+- Collector does NOT declare a remittance total — the logged collections are the collector's side of the ledger
+
+### Variance handling
+- Variance is recorded and flagged for review but does NOT block remittance completion
+- Remittance completes with the actual counted amount
+- Discrepancy tracked separately for management review
+- Journal entry posts based on verified (staff-counted) amount
+
+### Daily collection summary
+- Summary level: totals per collector (collected, remitted, variance, number of collections)
+- Drill-down to per-subscriber detail on click
+- Not per-subscriber detail by default — keeps the report scannable
+
+### Ticket creation and sources
+- Ticket model supports both staff and subscriber as source types from the start
+- Only staff creation UI built in Phase 3 — subscriber self-service portal hooks in Phase 5
+- Avoids model rework when Phase 5 adds portal ticket submission
+
+### Ticket categories
+- Admin-configurable categories per tenant (not a fixed enum)
+- Tenant admin can create, edit, and deactivate ticket categories
+- Default seed categories provided at tenant creation (No Connection, Slow Speed, Billing Inquiry, New Installation, Equipment Issue, Other)
+
+### Ticket-to-job-order conversion
+- One ticket can have multiple job orders (1:many relationship)
+- Covers complex issues needing multiple visits or different skill types
+- Each job order tracks independently but rolls up to parent ticket
+
+### Ticket-job status synchronization
+- When ALL job orders on a ticket are completed, ticket auto-moves to Resolved
+- Staff manually closes ticket after confirming resolution with subscriber
+- Two-step: auto-resolve (system) → close (staff confirmation)
+
+### Technician compensation model
+- Hybrid model: technician can have base monthly salary PLUS per-job bonuses
+- Both components are optional — pure salary, pure per-job, or hybrid all supported
+- Admin configures per technician
+
+### Per-job rate structure
+- Flat rate per job type (e.g., Installation = ₱500, Repair = ₱300)
+- Admin sets rates per job type at the tenant level
+- No tiered/distance-based rates — simple and predictable
+
+### Job completion for compensation
+- Only jobs with "completed" status count toward per-job compensation
+- Cancelled, failed, or in-progress jobs earn nothing
+- No partial credit mechanism
+
+### Compensation summary
+- Summary level: technician name, total jobs completed, base salary, job bonuses, total compensation
+- Drill-down to job-by-job detail (type, date, rate) per technician
+- Same drill-down pattern as collector daily summary — consistent report UX
+
+### Claude's Discretion
+- Zone/territory data model design
+- Ticket priority levels and SLA implementation
+- Job order status state machine details
+- Exact report query optimization
+- Remittance variance threshold for flagging (if any)
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- Collector payment logging reuses existing PaymentService FIFO allocation pattern — consistency across payment entry points
+- Reports follow summary-with-drill-down pattern throughout (collector summary, compensation summary)
+- Ticket categories seeded with ISP-relevant defaults but fully configurable
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope
+
+</deferred>
+
+---
+
+*Phase: 03-operational-modules*
+*Context gathered: 2026-03-05*