NetForge/.planning/phases/03-operational-modules/03-CONTEXT.md

Phase 3: Operational Modules - Context

Gathered: 2026-03-05 Status: Ready for planning

## 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.

## 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)

## 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

## Deferred Ideas

None — discussion stayed within phase scope

---

Phase: 03-operational-modules Context gathered: 2026-03-05