docs(03): capture phase context
Phase 03: Operational Modules - Implementation decisions documented - Phase boundary established
This commit is contained in:
kevin-asprec
105
.planning/phases/03-operational-modules/03-CONTEXT.md
Normal file
105
.planning/phases/03-operational-modules/03-CONTEXT.md
Normal file
@@ -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*
|
||||||
Reference in New Issue
Block a user