ERP-RFC-003 — Travel and Expense Engine

  • Status: Stub
  • Date: 2026-04-12
  • Author: Koder Team
  • Depends on: erp-RFC-000-architecture-overview.md, kompass-RFC-001-identity-and-org-unification.md
  • Phase: 3 (Travel engine extraction)
  • Blocked by: kompass-RFC-001 (identity unification)
  • Seed 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, per-diem calculation (diárias), expense report with receipts, reimbursement handoff to the financial engine. Seeded from the working modules/viagens prototype in Crescer/c-corp, which is already in production for Crescer/Vivver and covers solicitação → autorização → minhas viagens → relatório.

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

Name decision

Deferred. 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: submodule of platform/hr rather than a top-level engine. Travel is strictly employee-facing 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)

  • Solicitação de viagem — form capturing origin, destination, dates, reason, estimated cost, cost center.
  • Approval 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.
  • Cost estimate breakdown — transport (air/ground), accommodation, per-diem (diárias), incidentals, total. Per-diem rates are tenant-configurable tables keyed by destination tier.
  • Booking capture — after approval, attach booking references (not booking search; the engine does not shop for flights, it records what was bought externally).
  • Travel timeline — list of all active, upcoming, and past trips per person, per unit, per tenant.
  • Prestação de contas — after the trip, the traveller uploads receipts and reconciles them against the estimate. Receipts are stored via products/horizontal/drive.
  • Expense report — generated PDF with line items, receipts, approvals, ready for financial handoff.
  • Reimbursement 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.
  • Per-diem policy — tenant-configurable rules for diárias based on destination, role, duration.
  • CLT vs PJ — PJ travellers follow a different reimbursement flow (invoice against service contract instead of per-diem + receipts). The employment_type from kompass-RFC-001's Membership determines the path.
  • Multi-tenant policies — each Kompass tenant has its own per-diem rates, approval thresholds, and reimbursement rules. Crescer, Vivver, and Koder have independent policies.

Out of scope (MVP)

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

Dependencies

Dependency Used for Required day one
services/foundation/kompass person + membership + unit + manager chain yes
services/foundation/id authentication yes
infra/data/kdb persistence yes
products/horizontal/form solicitação and prestação forms yes
products/horizontal/drive or infra/data/s3 receipt storage yes
products/horizontal/sign formal approval of prestação de contas yes
products/horizontal/kmail notifications at each approval step yes
products/horizontal/cal calendar integration for trip dates yes
products/horizontal/pdf expense report generation yes
platform/fin-br (future) reimbursement handoff optional at MVP; required when fin-br exists
platform/BPM (future) replaces the linear approval chain with a real BPMN flow optional

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 infra/data/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. Dual-run c-corp'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 per-diem policies versioned when they change mid-trip? 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

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