ERPRFC003 — Travel and Expense Engine

• *tatus:*Stub
• *ate:*20260412
• *uthor:*Koder Team
• *epends on:*erp-RFC-000-architecture-overview.md, kompass-RFC-001-identity-and-org-unification.md
• *hase:*3 (Travel engine extraction)
• *locked by:*kompass-RFC-001 (identity unification)
• *eed code:*Crescer/c-corp/apps/c_corp/lib/modules/viagens/

Summary

A module that handles the full lifecycle of business travel and expense reimbursement: solicitação, cost estimate, approval chain, booking capture, execution, prestação de contas, perdiem calculation (diárias), expense report with receipts, reimbursement handoff to the financial engine. Seeded from the working modules/viagens prototype in `Crescer/ccorp`, which is already in production for Crescer/Vivver and covers solicitação → autorização → minhas viagens → relatório.

The need was identified by ccorp but not by the initial gap analysis in `erpRFC000` — it surfaced only when ccorp was inspected. Crescer and Vivver run ~90 field technicians across ~60 municipalities in MGRJSPPBBAMAPA; travel operations are daily, not exceptional.

Name decision

*eferred.*Candidates to evaluate per meta/docs/stack/specs/naming/brand-score.kmd:

• rota (pt: route) — may collide with mapping or logistics modules
• rumo (pt: direction) — also a candidate for BPM; cannot be used twice
• trilha (pt: trail)
• viator (latin: traveller)
• iter (latin: journey) — also a candidate for BPM
• peregrin (latin: wanderer)
• voyage (en)
• odo (greek: road) — possible collision with "odometer"

Hard filters: must not collide with existing mapping (platform/map), logistics, or scheduling modules. Length 4–7 preferred.

Alternative placement: *ubmodule of platform/hr*rather than a toplevel engine. Travel is strictly employeefacing and the approval chain resolves to HR managers. Keeping it inside HR reduces the number of top-level modules while still letting the feature exist. The RFC when promoted will pick one of the two placements.

Scope

In scope (MVP)

• *olicitação de viagem*— form capturing origin, destination, dates, reason, estimated cost, cost center.
• *pproval chain*— resolves to the requester's manager in Kompass; escalates to the unit-level budget approver for costs above threshold. In the interim (before BPM engine lands), a simple linear approval chain suffices.
• *ost estimate breakdown*— transport (air/ground), accommodation, perdiem (diárias), incidentals, total. Perdiem rates are tenant-configurable tables keyed by destination tier.
• *ooking capture*— after approval, attach booking references (not booking search; the engine does not shop for flights, it records what was bought externally).
• *ravel timeline*— list of all active, upcoming, and past trips per person, per unit, per tenant.
• *restação de contas*— after the trip, the traveller uploads receipts and reconciles them against the estimate. Receipts are stored via platform/drive.
• *xpense report*— generated PDF with line items, receipts, approvals, ready for financial handoff.
• *eimbursement handoff*— when prestação de contas is approved, a financial event is emitted for the future platform/fin-br engine (or today's platform/billing) to process.
• *erdiem policy*— tenantconfigurable rules for diárias based on destination, role, duration.
• *LT vs PJ*— PJ travellers follow a different reimbursement flow (invoice against service contract instead of perdiem + receipts). The employment_type from `kompassRFC-001`'s Membership determines the path.
• *ultitenant policies*— each Kompass tenant has its own perdiem rates, approval thresholds, and reimbursement rules. Crescer, Vivver, and Koder have independent policies.

Out of scope (MVP)

• *ooking search and purchase*— Koder does not rebuild a travel search engine. Integrations with corporate booking platforms are a future extension.
• *isa, passport, and international compliance*— deferred; the MVP handles domestic BR travel.
• *leet management*— company cars, GPS tracking, maintenance schedules. Belongs to a future fleet module if justified.
• *xpense categories beyond travel*— office supplies, equipment purchases, entertainment. These belong to a broader expense engine, not travel specifically.

Dependencies

Extraction plan

The c-corp seed is apps/c_corp/lib/modules/viagens/ with 5 screens totalling ~1580 Dart lines:

solicitacao_screen.dart     367 lines   form + cost estimate
autorizacao_screen.dart     367 lines   approval UI for managers
minhas_viagens_screen.dart  340 lines   traveller view
relatorio_screen.dart       308 lines   expense report
viagens_home_screen.dart    234 lines   landing

Plus lib/modules/viagens/models/viagem.dart (104 lines) containing the Viagem data model.

Extraction steps (deferred to the full RFC):

1. Port the Dart Viagem model to a Go model in the new module, replacing c-corp's internal IDs with references to Kompass Membership, Unit, Person.
2. Replace direct PostgreSQL access with platform/kdb.
3. Replace the c-corp modules/seguranca authorization with Koder ID + Kompass permissions.
4. Port the 5 screens to Flutter screens inside apps/mosaic (or the future ERP flagship), with the API contract defined by the new module.
5. Dualrun ccorp's viagens module and the new module for 30 days with real Crescer/Vivver data.
6. Retire c-corp's viagens module.

Open questions

• Pick the name, and decide whether this is a top-level module or a submodule of platform/hr.
• Per-diem tables: stored as tenant config in Kompass, or in a dedicated travel policy table? Probably the latter, but the decision has compliance implications.
• Integration with external booking platforms (e-Viagem federal, corporate travel agencies): which ones, with what API contracts, deferred.
• Receipt OCR and automated line-item extraction from nota fiscal: useful but not MVP.
• How are perdiem policies versioned when they change midtrip? Standard answer: trip is pinned to the policy version at approval time.

Non-goals

• This stub does not pick the name.
• This stub does not decide top-level vs submodule placement.
• This stub does not scope fleet, visas, or generic expense management.
• This stub does not commit integration contracts with external booking platforms.

Status

*tub.*Promoted to Draft once kompass-RFC-001 has landed and a named author commits to owning the design. Until then, this file reserves the RFC number and pins down the extraction envelope.