Repository navigation
docs enterprise modules intelligence
Module code(s) KPI, FIND, RPT. This file also owns the indicator definitions (IND) and the finding types (FT) named in 00-conventions §2.
Evidence. IMPLEMENTED: a pure consumption and cost engine in backend/internal/modules/metrics/ (consumption.go: full-to-full Interval.Compute; cost.go: FuelPurchasePerKm, MatchedWindowCost, SumIntervals, calculation version 1), its Kotlin twin domain/src/main/kotlin/com/anpfuel/domain/premium/PremiumConsumption.kt and shared vectors in contracts/testdata/premium/; the engine is reached today only through an account-keyed reader (backend/internal/modules/metrics/application/ports.go). Public price read models exist for official ANP prices with revision, survey week, collection date and source checksum (backend/internal/modules/official/application/queries.go, PriceReader, fixed STANDARD condition) and for the community projection with query-time expiry (backend/internal/modules/community/adapters/read/). The Android app exports the personal monthly indicators as CSV with formula-injection-safe escaping (application/src/main/kotlin/com/anpfuel/application/usecase/ledger/MonthlyIndicatorsUseCases.kt, object MonthlyIndicatorsCsv), and the public data portal writes CSV with the same protection (backend/internal/modules/enterpriseexport/portalgen/downloads.go, csvSafe). The job queue has de-duplication keys, not_before and per-kind serial dispatchers (backend/internal/platform/jobs/, backend/cmd/worker/dispatchers.go). PARTIAL: audit exists only as module ledgers and admin_audit_events; there is no organization audit trail (01-diagnosis §3.7). PROPOSED: organization indicators, price comparisons, findings, export jobs, reports, the audit viewer and the module backend/internal/modules/insight/ (proposed). backend/go.mod lists no PDF or spreadsheet-writing library.
Managers need to know what the fleet costs and consumes, where a record deserves a second look, and how to take the data out of the system. This module turns approved facts into figures with a stated method, raises differences for human review without accusing anyone, and produces files that say what they contain. The expected result is that every number can be traced to its records and its method, every missing input is shown as missing, and every finding ends with a justified human decision.
- Basic (F3): export jobs with private files and expiring access; CSV and spreadsheet exports of operational lists.
- Next (F6): indicator registry; read models by organization, unit, cost centre, driver, vehicle, trip, supplier and period; price comparison with stored reference and methodology; dashboards and drill-downs; findings with detection, review, justification and outcome; reprocessing; PDF reports; scheduled reports; full organization data export; audit trail viewer.
- Later: indicators defined by the organization as combinations of registry indicators; consolidated reading across an organization group (organizations); station-announced and negotiated prices as reference sources when station-commerce exists.
- Out of scope: fraud scores, automatic penalties or blocks, rankings of employees, forecasts shown as facts, accounting layouts (they use the export infrastructure and are specified in expenses-finance), and market datasets (data), which never read organization records (BR-SRC-005).
| Entity | Owner | Content | Invariants |
|---|---|---|---|
| Indicator definition | Platform (code-defined registry, versioned) | Identifier, name, formula, inputs, unit, dimensions, inclusion criteria, insufficiency reasons, method version | A change of formula or inclusion is a new method version. An identifier is never reused. |
| Indicator snapshot (derived) | Organization | Indicator, method version, dimension values, period, value or INSUFFICIENT_DATA with a reason, numerator and denominator, record counts, source revision, computed-at instant, revision, link to the revision that superseded it |
Rebuildable from facts; never the source of truth (09-architecture §5). One current revision per (indicator, dimension values, period). |
| Price comparison (analysis) | Organization | Fueling revision compared, the reference used (source, source revision, place rule, period, condition, coverage, unit price), methodology version and parameters, result or INSUFFICIENT_DATA with a reason, computed-at instant |
Immutable. A recomputation is a new analysis linked to the one it supersedes. |
| Finding type | Platform (catalog, versioned) | Identifier, trigger, default threshold and range, severity rule, statement of what it does not prove | §10.8. |
| Detection setting | Organization | Finding type, enabled flag, threshold inside the catalog range, reference source for price findings, who changed it and when | Out-of-range values are refused. Changes are audited. |
| Detection run | Organization | Run identifier, finding types, method versions, parameters, period or subject range, start, end, counts | Append-only. |
| Finding | Organization | Type, subject key, severity, evidence (references and the values compared), state, responsible member, decision, justification, follow-up link, detection run, revision | At most one finding that is not terminal per (type, subject key). |
| Export job | Organization | Kind, format, parameters, requester, rights recorded at request, state, file key, size, row count, SHA-256, expiry | File under the organization's export prefix; access bound to the requester. |
| Report schedule | Organization | Report kind, parameters, cadence, owner, recipients, last run, paused flag with reason | Each run uses each recipient's own rights. |
| Audit event (read only here) | Organization; stored by the audit module of 09-architecture §2 | Actor, action, target, time, reason | This module reads events and writes only the events of its own actions. |
Relations: a snapshot points to the indicator definition and to the source revision it was computed from; a finding points to its evidence records, to one detection run and, for price findings, to one price comparison; an export job points to its requester and, when scheduled, to its schedule.
Indicators:
- BR-KPI-001 — Figures come from the registry. Every figure on a dashboard, report or export is an indicator of the registry with identifier, formula, inputs, unit, inclusion criteria and method version; no screen computes a figure of its own.
- BR-KPI-002 — Approved by default. An indicator counts approved, non-voided revisions only; a view that adds submitted or in-review records labels the figure "inclui pendentes" and shows the pending part separately (BR-REV-009).
-
BR-KPI-003 — Insufficient data is a result. When an input required by the formula is missing or a denominator is zero, the indicator returns
INSUFFICIENT_DATAwith a reason code and no number, and a chart shows a gap (BR-TRUTH-003). - BR-KPI-004 — Ratios divide sums. For any group and period a ratio is the sum of the numerators divided by the sum of the denominators of the included records, never an average of per-record or per-vehicle ratios (BR-MONEY-008).
- BR-KPI-005 — Numerator and denominator match. A ratio uses a numerator and a denominator that cover the same records and the same window; the cost of a whole period is never divided by the distance of part of it.
- BR-KPI-006 — Incompatible units stay apart. Volume and efficiency are reported per fuel product and unit; a group with several products shows one line per product and no combined efficiency (BR-MONEY-009).
- BR-KPI-007 — The basis is shown. Each value carries its method version, period, time zone, filters, counts of records included, excluded by reason and pending, its computed-at instant and its revision, and the panel can list the records behind it (BR-TRUTH-004).
- BR-KPI-008 — A recalculation is a new revision. When a source record is approved late, amended or voided, or a method version changes, the affected snapshots are recomputed as a new revision and the previous revision is kept and marked superseded (BR-AMD-005).
- BR-KPI-009 — Period attribution. A record enters the period of its reporting day (BR-TIME-004); a consumption interval enters the period of its closing fueling; periods are half-open in the time zone of the unit, or of the organization when there is no unit.
- BR-KPI-010 — Dimensions use the record's own values. Grouping by unit, cost centre, vehicle, driver, trip or supplier uses the values stored on the record when it was created or allocated, not the current allocation of the asset or person (BR-AUTH-005).
- BR-KPI-011 — Scope filters the data. An indicator request returns only records inside the caller's role scope, and a figure computed on a narrower scope is labelled with that scope and never presented as the organization total.
-
BR-KPI-012 — A price comparison needs a comparable reference. A recorded price is compared only with one reference that matches fuel product, unit, place rule, period and payment and offer conditions, and that states its coverage and origin; sources are never blended (BR-SRC-001); otherwise the result is
INSUFFICIENT_DATA. - BR-KPI-013 — The reference and the method are preserved. Each price comparison stores the reference it used, the methodology version and parameters and the computed-at instant; a later revision of the public data does not change a stored analysis.
- BR-KPI-014 — A difference is not a loss. A price difference is shown as "diferença em relação à referência" for review; no screen, export or notification calls it loss, overpayment, waste or savings (BR-TRUTH-005).
- BR-KPI-015 — Rounding only at display. Stored values are exact integers and rationals; half-up rounding is applied only when a value is formatted, and machine exports carry the exact base-unit values.
- BR-KPI-016 — Sample size is visible. Every ratio shows the number of observations behind it; below the configured minimum (default 3 closed intervals, range 2 to 10) it is labelled "amostra pequena" and is not used as a baseline by any detection.
Findings:
- BR-FIND-001 — A finding describes a difference. The text of a finding states what was observed, the rule that triggered and the values compared; it never states fraud, theft, misuse, loss or savings (BR-TRUTH-005).
- BR-FIND-002 — Evidence is attached. A finding stores references to the records, readings, documents and price comparison it used, the values at detection time, the method version and the threshold applied.
- BR-FIND-003 — Types come from the catalog. Only the finding types of §10.8 are raised, each with its trigger, threshold, severity rule and statement of what it does not prove, which the finding screen always shows.
- BR-FIND-004 — One open finding per subject. For one type and one subject key at most one finding is not terminal; detecting the same difference again creates nothing.
-
BR-FIND-005 — Every finding has a responsible person. A new finding is routed to the members who hold
find.finding.resolveon the record's scope; one of them takes it or is assigned; a finding nobody took after the escalation age (default 15 days, range 1 to 60) is notified to the organization administrators. -
BR-FIND-006 — A decision needs a justification.
CONFIRMED,JUSTIFIED,FALSE_POSITIVEandDISMISSEDeach require a written justification of bounded length;CONFIRMEDalso records the follow-up chosen (amend the record, void it, or none) as a link, never as an automatic effect. -
BR-FIND-007 — Nobody decides on their own record. The member who authored a record under a finding, or the employee the record concerns, cannot take or decide that finding, whatever roles that person holds; the attempt fails with
SELF_APPROVAL. - BR-FIND-008 — A finding changes nothing by itself. Raising or deciding a finding never rejects, voids, amends or blocks a record, a payment, an asset or a person; corrections go through the review and amendment flows of the owning module (BR-AMD-001).
-
BR-FIND-009 — Severity orders the review. Severity is
LOW,MEDIUMorHIGH, derived from the type and the size of the difference by the catalog rule; it orders queues and notifications and says nothing about intent. - BR-FIND-010 — Thresholds are bounded configuration. An organization adjusts a threshold only inside the catalog range; the change is audited, applies to later detections and never rewrites existing findings.
-
BR-FIND-011 — Reprocessing is identifiable. Every detection belongs to a run with identifier, method versions, parameters and range; when a later run no longer supports a finding that is not decided, the finding becomes
SUPERSEDEDwith a link to that run; decided findings keep their outcome and receive a note (BR-TRUTH-004). -
BR-FIND-012 — Detection waits for accepted records. Detection reads records the server accepted; operations held in the sync review queue are not analysed until resolved, and a finding whose record is later rejected or voided becomes
SUPERSEDED.
Reports and exports:
-
BR-RPT-001 — Every export is a job. An export or report is an export job with the states of §6; a CSV estimated under the inline limit (default 2 000 rows) is produced in the request and returned
READY, and anything larger or in another format is produced by the worker while the request returns the job at once. -
BR-RPT-002 — An export repeats the screen's authorization. The job records requester, permission, scope, filters and an "as of" instant; when the worker starts it re-evaluates the requester's membership and scope and writes only rows the requester may read then; a requester who lost the right gets a
FAILEDjob and no file. -
BR-RPT-003 — Sensitive columns need their own permission. Location columns need
gps.track.readand document files needdoc.document.view_content; without the permission the columns or files are left out and the export says so (BR-AUTH-011). - BR-RPT-004 — Files are private and expire. The file is stored under the organization's export prefix, is delivered only through a capability of at most 5 minutes bound to the requester and the job, and is deleted at expiry (default 7 days, range 1 to 30); no storage address reaches a client (BR-PRIV-004).
- BR-RPT-005 — Every export is audited. Creating a job and each download write an audit event with requester, kind, a digest of the filters and the row count, and no content (BR-AUD-003, BR-AUD-004).
-
BR-RPT-006 — Cells cannot become formulas. In CSV a text cell that begins with
=,+,-,@, a tab or a carriage return is prefixed with an apostrophe (as is a cell that already begins with one, so the scheme is reversible), the field is quoted when it holds a separator, a quote, a line break or a leading space, and embedded quotes are doubled; in a spreadsheet every text cell is written as a string and no cell is ever a formula; numbers are written as plain canonical values. -
BR-RPT-007 — An export states its basis. Organization, requester, generation instant, time zone, period, filters, review basis ("somente aprovados" or "inclui pendentes"), indicator method versions and row count are stated inside a spreadsheet or PDF and in the manifest that accompanies a CSV;
INSUFFICIENT_DATAis written as that text with its reason, never as 0 or an empty numeric cell. - BR-RPT-008 — Machine formats carry exact values. CSV and spreadsheet exports carry integer base units (centavos, millilitres, metres, seconds) in columns named with the unit, beside optional formatted columns; a PDF shows formatted values rounded half-up at display.
-
BR-RPT-009 — Limits fail loudly. A requester has at most 3 jobs that are not terminal (default), and a job has a row ceiling (default 500 000) and a time ceiling; a job over a ceiling ends
FAILEDwithEXPORT_TOO_LARGEand is never delivered truncated; export jobs run on their own serial dispatcher. - BR-RPT-010 — Content is deterministic. The same parameters and "as of" instant produce the same rows in the same order (reporting day, then identifier), so two runs can be compared.
-
BR-RPT-011 — A new file-format dependency is a decision. CSV and ZIP use the standard library; PDF or spreadsheet generation that needs a new dependency is admitted only by a recorded review inside the task that needs it (CX-10); until then the format is not offered and the request fails with
EXPORT_FORMAT_UNAVAILABLE. -
BR-RPT-012 — The full export is complete and restricted. The full organization data export contains every category of organization-owned record with a manifest (file, row count and SHA-256 per category), excludes secrets and other organizations' data, needs
rpt.export.runandorg.settings.manageat organization scope with fresh authentication (BR-AUTH-010), includes document files only for a requester who holdsdoc.document.view_contentat organization scope, and notifies every organization owner when it is requested. -
BR-RPT-013 — The audit viewer reads and never edits. Members with
audit.event.readlist audit events inside their scope by actor, action, target and period; the viewer shows references and bounded reasons only (BR-AUD-004), and exporting the list is itself an audited export (BR-AUD-006). - BR-RPT-014 — A schedule runs with each recipient's rights. A scheduled report creates one export job per recipient under that recipient's permission and scope at run time; a recipient who lost the right is skipped and the schedule owner is told; a schedule whose owner lost the right is paused; delivery is a notification with a link to the panel, never a file attachment.
- BR-RPT-015 — A logbook report says what it is not. A trip logbook report states on every page that it is an operational record and not a time or journey record, and it computes no working hours (EDR-028).
UC-KPI-01 — Read a dashboard. Actor: member with kpi.dashboard.read. Preconditions: active membership; the indicator capability is enabled for the organization. Main flow: open the overview → choose period and, when the role allows, unit or cost centre → the server returns each indicator with value or INSUFFICIENT_DATA, unit, basis and revision, limited to the caller's scope → the panel shows the figures, the pending items and the series over the chosen periods. Alternatives: scope narrower than the organization → figures labelled with the scope (BR-KPI-011); "inclui pendentes" switched on → pending part shown separately (BR-KPI-002); a snapshot is being recomputed → the last revision is shown with its computed-at instant. Result: figures with their basis; nothing is written.
UC-KPI-02 — Drill down from a figure to its records. Actor: as UC-KPI-01, plus the read permission of the record type opened. Main flow: select a figure → break it down by one dimension (unit, cost centre, driver, vehicle, trip, supplier) → open the indicator detail with formula, numerator, denominator, counts and revisions → list the records included and the records excluded with the reason. Alternatives: the dimension does not apply to the indicator (§10.3) → not offered; a record outside the caller's read permission → counted, not listed; a previous revision is selected → shown as superseded with what changed. Result: the member can explain the number.
UC-KPI-03 — Compare a fueling price with a reference. Actor: system when a fueling is accepted or amended; a member with kpi.dashboard.read and fuel.fueling.read reads the result. Preconditions: the fueling carries product, unit, quantity, paid total, place and price condition (fuelings). Main flow: for each reference source enabled, select the candidate reference captured for the fueling → test the comparability criteria of §10.6 → compute the difference in centavos → store the analysis with the reference and the methodology version. Alternatives: a criterion fails → analysis stored as INSUFFICIENT_DATA with the reason and no number; no candidate → NO_REFERENCE; fueling from an internal tank → not compared. Result: one immutable analysis per fueling revision and source.
UC-KPI-04 — Recalculate after a correction (system). Actor: recalculation job. Trigger: a source record was approved late, amended or voided, a consumption interval was recomputed, or a method version changed. Main flow: find the snapshots whose inputs include the record → recompute them from facts → write a new revision → mark the previous one superseded → emit the event. Alternatives: the job runs twice → the second run finds the same source revision and writes nothing; the result becomes INSUFFICIENT_DATA → stored as such, never left as the old number. Result: the recalculation is identifiable by revision (BR-KPI-008).
UC-FIND-01 — Detect and raise a finding (system). Actor: detection job. Preconditions: the finding type is enabled; the record was accepted by the server. Main flow: an event of an owning module arrives → the detector of each type evaluates its trigger with the organization's threshold → when it fires, compute severity, build the subject key, collect evidence → create the finding in OPEN unless a non-terminal one exists for the key → route it (BR-FIND-005) → notify by digest. Alternatives: inputs missing (no baseline, no comparable reference) → nothing is raised, because insufficient data is not a finding; job retried → the de-duplication key prevents a second finding. Result: at most one open finding per subject.
UC-FIND-02 — Review and decide a finding. Actor: member with find.finding.resolve whose scope covers the record, who is neither the record's author nor the employee concerned. Main flow: open the queue → take a finding (IN_REVIEW) → read the evidence, the threshold and what the type does not prove → open the linked records as far as the member's permissions allow → decide CONFIRMED, JUSTIFIED or FALSE_POSITIVE with a justification → when confirmed, choose the follow-up and go to the owning module's amendment or void flow. Alternatives: not worth analysing → DISMISSED with a reason; the author's explanation is needed → the reviewer records it in the justification, or returns the underlying record for correction when it is still in review; another member decided first → CONFLICT; own record → SELF_APPROVAL. Result: outcome, justification, actor and time recorded and audited; no record changed by the decision itself.
UC-FIND-03 — Adjust detection settings. Actor: member with org.settings.manage. Main flow: open detection settings → enable or disable a type, change its threshold inside the range, or choose the reference source of price findings → save with a reason. Alternatives: value outside the range → VALIDATION_FAILED with the allowed range; the member wants existing findings re-evaluated → UC-FIND-04. Result: applies to later detections; audited.
UC-FIND-04 — Reprocess an analysis. Actor: member with org.settings.manage, or the system after a method version change. Main flow: choose finding types and a period → a detection run is created → records of the period are re-evaluated with the current method and thresholds → new findings are raised, findings that are not decided and are no longer supported become SUPERSEDED with a link to the run, decided findings get a note → the run is listed with its counts. Alternatives: a run for the same types and period is in progress → CONFLICT; period longer than the limit (default 13 months) → VALIDATION_FAILED. Result: every finding names the run that produced or superseded it.
UC-RPT-01 — Export a list. Actor: member with rpt.export.run and the read permission of the list, in the same scope. Main flow: on a list or indicator table choose "Exportar" → choose CSV or spreadsheet and the columns (EMP-RPT-002 admits CSV for assets, meter readings and the employee register with fixed columns) → the server creates the job with the current filters → the dialog polls the job → when READY the member downloads through a short-lived capability → the download is audited. Alternatives: small CSV → READY in the same response; too many open jobs → EXPORT_QUEUE_FULL; over the row ceiling → FAILED with EXPORT_TOO_LARGE and advice to narrow the filter; the member closes the dialog → the job continues and appears in "Minhas exportações" with a notification when ready. Result: a file that states its basis and expires.
UC-RPT-02 — Generate a PDF report. Actor: as UC-RPT-01. Main flow: choose a report (trip logbook, fueling statement, period summary) and its parameters → job created → the worker renders the report with the header block of BR-RPT-007 → download. Alternatives: PDF generation not yet admitted (BR-RPT-011) → EXPORT_FORMAT_UNAVAILABLE, with the spreadsheet offered instead; an indicator in the summary has no data → printed as "dados insuficientes" with the reason. Result: a formatted document for people, with the same numbers as the panel.
UC-RPT-03 — Schedule a report. Actor: member with rpt.export.run. Main flow: choose a report or export, a cadence (weekly or monthly) and recipients among members → at each run one job per recipient is created under that recipient's rights → each recipient receives a notification with a link. Alternatives: a recipient lost the right → skipped, owner told; the owner lost the right → schedule paused, owner and administrators told; the organization is suspended → runs stop. Result: recurring exports that never widen anyone's access.
UC-RPT-04 — Export all organization data. Actor: member with rpt.export.run and org.settings.manage at organization scope, freshly authenticated. Main flow: open the full export → choose data only, or data and documents by month → confirm → jobs are created → every owner is notified → the requester downloads a ZIP per job with one CSV per category and a manifest. Alternatives: no fresh authentication → FRESH_AUTH_REQUIRED; requester without doc.document.view_content → documents not offered; a job exceeds the size ceiling → split by month. Result: a complete, verifiable copy for portability, backup or closure (organizations).
UC-RPT-05 — Consult the audit trail. Actor: member with audit.event.read. Main flow: open the viewer → filter by period, actor, action or target → open an event to see actor, delegation when present, target reference, time and reason → follow the link to the target when the member may read it. Alternatives: target outside the member's read permission → reference shown, link disabled; export of the list → UC-RPT-01, audited. Result: accountability without exposing content.
Finding (review kind; names from 08-state-model §3):
| From | To | Actor | Validation | Effect | Reversal |
|---|---|---|---|---|---|
| — | OPEN |
Detection job | Trigger fired; no non-terminal finding for the key | Routed and notified by digest | — |
OPEN |
IN_REVIEW |
Member with find.finding.resolve
|
Scope covers the record; BR-FIND-007 | Member becomes responsible | Release back to OPEN
|
IN_REVIEW |
OPEN |
Responsible member, or an administrator reassigning | — | No responsible member | Take again |
IN_REVIEW |
CONFIRMED |
Responsible member | Justification; follow-up chosen; expected revision | Outcome recorded; follow-up link created | None; a wrong decision is corrected by a new finding linked to this one |
IN_REVIEW |
JUSTIFIED |
Responsible member | Justification | The difference is real and explained | Same |
IN_REVIEW |
FALSE_POSITIVE |
Responsible member | Justification | The detection was wrong; counted for threshold tuning | Same |
OPEN, IN_REVIEW
|
DISMISSED |
Member with find.finding.resolve
|
Reason | Closed without analysis | Same |
OPEN, IN_REVIEW
|
SUPERSEDED |
System | A later run no longer supports it, or its record was rejected or voided | Closed with a link to the run or event | A new detection creates a new finding |
stateDiagram-v2
[*] --> OPEN: detection
OPEN --> IN_REVIEW: taken
IN_REVIEW --> OPEN: released
IN_REVIEW --> CONFIRMED: justified decision
IN_REVIEW --> JUSTIFIED: justified decision
IN_REVIEW --> FALSE_POSITIVE: justified decision
OPEN --> DISMISSED: reason
IN_REVIEW --> DISMISSED: reason
OPEN --> SUPERSEDED: reprocessing or record removed
IN_REVIEW --> SUPERSEDED: reprocessing or record removed
CONFIRMED --> [*]
JUSTIFIED --> [*]
FALSE_POSITIVE --> [*]
DISMISSED --> [*]
SUPERSEDED --> [*]
Export job (lifecycle kind):
| From | To | Actor | Validation | Effect | Reversal |
|---|---|---|---|---|---|
| — | QUEUED |
Requester | Permissions, scope, format available, open-job limit | Job stored; audit event | Cancel while queued (ends FAILED with EXPORT_CANCELLED) |
— / QUEUED
|
RUNNING |
Request (inline CSV) or worker | Requester's rights re-evaluated | Rows read as of the recorded instant | Lease lost → back to QUEUED
|
RUNNING |
READY |
Worker | File written; size, rows and hash recorded | Requester notified; download allowed | — |
RUNNING, QUEUED
|
FAILED |
Worker or requester | Ceiling exceeded, rights lost, cancelled, or attempts exhausted | Partial file deleted; code recorded | Request again |
READY |
EXPIRED |
Time | Expiry reached (also checked at download) | File deleted; metadata kept for the audit period | Request again |
stateDiagram-v2
[*] --> QUEUED
QUEUED --> RUNNING
RUNNING --> QUEUED: lease lost
RUNNING --> READY
RUNNING --> FAILED
QUEUED --> FAILED: cancelled or rights lost
READY --> EXPIRED
FAILED --> [*]
EXPIRED --> [*]
An indicator snapshot and a price comparison have no state machine: each is a revision that is either current or superseded by a later one, and its result is a value or INSUFFICIENT_DATA. A report schedule is enabled or paused by a flag with a reason.
| Permission | Allows here | Roles in 07-permissions §7.3 |
|---|---|---|
kpi.dashboard.read |
Read indicators, breakdowns, bases and price comparisons | OWNER, ADMIN, FLEET_MANAGER, SUPERVISOR, FINANCE, AUDITOR |
find.finding.read |
List and open findings in scope | Registry key with no matrix row; this module assumes the roles that hold find.finding.resolve, plus AUDITOR (gap reported) |
find.finding.resolve |
Take, release, decide and dismiss findings | OWNER, ADMIN, FLEET_MANAGER, FINANCE |
rpt.export.run |
Create export jobs, reports and schedules | OWNER, ADMIN, FLEET_MANAGER, FINANCE, AUDITOR |
audit.event.read |
Read the audit trail | OWNER, ADMIN, AUDITOR |
org.settings.manage |
Change detection settings, start a reprocessing, request the full export (with rpt.export.run) |
OWNER, ADMIN |
Every action also needs the read permission of what it shows: an export of fuelings needs fuel.fueling.read, a drill-down into expenses needs exp.expense.read, location columns need gps.track.read, document files need doc.document.view_content. Scopes follow BR-AUTH-004 and BR-AUTH-005. Drivers and operations staff hold none of these permissions, so the app shows no indicators in this plan. An entitlement gate applies to dashboards, findings and scheduled reports; exporting existing data stays available when a capability is turned off (09-architecture §10). For exports this is enforced by EMP-AUTH-011: every admitted kind declares one registered <module>.<resource>.read key outside location, checked with rpt.export.run in the request transaction, at each worker attempt and at each capability issue and download (EDR-167).
- Offline: everything here needs the server (10-offline-sync §10.3: exports, reports and indicators are online). Records still waiting on a device or in the sync review queue are not in any figure; the count of the review queue is itself an indicator so that the gap is visible.
-
Concurrency: a finding command names the expected revision; the second of two members acting on one finding receives
CONFLICT. Two reprocessing runs for the same types and period cannot run together. Snapshot writes are serialised per (indicator, dimension values, period). -
Idempotency: commands carry
operation_id. Detection uses the key (finding type, subject key, method version). Snapshot recomputation is keyed by the source revision. An export job is created once peroperation_id; the worker handler is safe to re-run and replaces a partial file. - Corrections: amendments and voids of source records lead to new snapshot revisions and re-evaluated findings (BR-AMD-005). A wrong finding decision is never edited: a new finding linked to it is opened. A wrong export is requested again.
Produced: kpi.snapshot.recomputed, kpi.comparison.computed, find.finding.raised, find.finding.taken, find.finding.decided, find.finding.superseded, find.run.completed, rpt.export.requested, rpt.export.ready, rpt.export.failed, rpt.export.downloaded, rpt.export.expired, rpt.schedule.paused.
Consumed: approval, amendment and void events of fuelings, expenses, trips and work orders; consumption interval recomputation (fuelings); reading recorded, corrected or voided and availability changes (fleet); conference and reconciliation changes (documents); sync review items opened and resolved (10-offline-sync); membership ended and organization suspended (to stop schedules and fail queued exports).
Notifications, through imports-notifications-integrations: new findings as a digest per responsible member, HIGH severity at once; findings past the escalation age to administrators; export ready or failed to the requester; full export requested to every owner; schedule paused to its owner. No notification text carries a value judgement about a person.
Integrations: none of its own. Accounting layouts and connectors reuse the export job. Reference prices come only from the public read models of the existing official and community modules and, later, from announced and negotiated prices; no private record of this module ever leaves the organization (BR-SRC-003, BR-SRC-005).
Unless a row says otherwise, an indicator includes only records of the organization, inside the caller's scope, approved and not voided (BR-KPI-002), attributed to the period by reporting day (BR-KPI-009) and grouped by the values stored on the record (BR-KPI-010). Periods offered: day, week (Monday to Sunday), month, quarter, year or a custom range. Consumption intervals themselves, including the full-to-full method, partial fuelings, anchors and segment boundaries, are defined in fuelings; the rows below define only the indicators built on them.
| ID | Indicator (interface) | Formula | Inputs | Unit (stored → shown) |
|---|---|---|---|---|
| IND-001 | Fuel spend (Gasto com combustível) |
Σ company_amount_cents of expenses whose origin is a fueling |
Expense company amount, origin, reporting day, allocation rows | centavos → R$ |
| IND-002 | Fuel volume by product (Volume por produto) |
Σ quantity per fuel product and unit |
Fueling quantity, product, unit | mL → L; milli-m³ → m³; Wh → kWh; one line per product |
| IND-003 | Distance per unit of fuel (km/L) |
Σ distance_m ÷ Σ quantity_ml over closed consumption intervals (numerically kilometres per litre) |
Intervals in state COMPUTED: distance, eligible quantity, product |
exact rational → km/L, 2 decimals (km/m³ for gas) |
| IND-004 | Fuel per 100 km (L/100 km) |
Σ quantity_ml × 100 ÷ Σ distance_m over the same intervals as IND-003 |
Same as IND-003 | exact rational → L/100 km, 2 decimals |
| IND-005 | Fuel per hour (L/h) |
Σ quantity_ml × 3 600 ÷ (Σ hour_meter_seconds × 1 000) over closed intervals measured by hour meter |
Intervals in state COMPUTED on an hour-meter basis: seconds, eligible quantity |
exact rational → L/h, 2 decimals |
| IND-006 | Fuel cost per km (Custo de combustível por km) |
Σ interval_cost_cents × 1 000 ÷ Σ distance_m over the same intervals as IND-003 |
Interval eligible cost, distance | centavos per km → R$/km, 2 decimals |
| IND-007 | Fuel cost per hour (Custo de combustível por hora) |
Σ interval_cost_cents × 3 600 ÷ Σ hour_meter_seconds over the same intervals as IND-005 |
Interval eligible cost, seconds | centavos per hour → R$/h, 2 decimals |
| IND-008 | Total operating cost (Custo operacional total) |
Σ company_amount_cents of expenses whose category counts as operating cost |
Expense company amount, category flag, allocation rows | centavos → R$ |
| IND-009 | Total operating cost per km (Custo operacional por km) | Per asset: Σ operating cost inside the observed window × 1 000 ÷ distance_m of that window; group: sum of the assets' numerators ÷ sum of their denominators |
Expenses as IND-008 with their asset; observed window and distance of IND-017 | centavos per km → R$/km, 2 decimals |
| IND-010 | Total operating cost per hour (Custo operacional por hora) | As IND-009 with × 3 600 ÷ hour_meter_seconds of the observed window of IND-018 |
Expenses as IND-008; observed window and hours of IND-018 | centavos per hour → R$/h, 2 decimals |
| IND-011 | Maintenance cost (Custo de manutenção) |
Σ company_amount_cents of expenses whose origin is a work order or whose category is maintenance |
Expense company amount, origin, category | centavos → R$ |
| IND-012 | Availability (Disponibilidade) |
Σ available_seconds ÷ Σ active_seconds, where available seconds are active seconds not spent in IN_MAINTENANCE, BLOCKED or UNAVAILABLE
|
Availability history and lifecycle periods of each asset | ratio → %, 1 decimal |
| IND-013 | Records pending review (Registros aguardando revisão) | Count of records in SUBMITTED or IN_REVIEW per record type, with the age of the oldest; RETURNED shown apart as "aguardando correção" |
Review state of trips, fuelings, expenses and work orders | count; seconds → days |
| IND-014 | Documents not reconciled (Documentos não conciliados) | Count and Σ document_total_cents of stored documents whose reconciliation is UNALLOCATED, PARTIALLY_ALLOCATED or OVER_ALLOCATED
|
Document reconciliation status and totals | count; centavos → R$ |
| IND-015 | Sync items awaiting review (Envios aguardando decisão) | Count of sync review items not yet resolved, by reason code, with the age of the oldest | Review items of 10-offline-sync §6 | count; seconds → days |
| IND-016 | Price difference against reference (Diferença em relação à referência) |
Σ (paid_cents − reference_cents) over fuelings with a comparable reference, with reference_cents = round_half_up(quantity_milli × reference_unit_price_milli ÷ 10 000)
|
Fueling quantity and paid total; stored price comparison (§10.6) | centavos, signed → R$; always with "n de m comparados" |
| IND-017 | Distance travelled (Distância percorrida) | Per asset: usage between the first and the last valid odometer reading of the observed window; group: sum | Valid odometer readings, meter replacements | metres → km |
| IND-018 | Hours operated (Horas operadas) | As IND-017 with hour meters | Valid hour-meter readings, meter replacements | seconds → h |
| IND-019 | Open findings (Achados em aberto) | Count of findings in OPEN or IN_REVIEW by type and severity, with the age of the oldest |
Findings | count; seconds → days |
| IND-020 | Change against a previous period (Variação) |
(current − baseline) ÷ baseline for one indicator, same dimension values and same method version |
Two snapshots of one indicator | ratio → %, 1 decimal |
The observed window of an asset in a period runs from its first to its last valid reading inside the period. It follows the matched-window rule already implemented in MatchedWindowCost: costs outside the window are left out of the ratio, and the window's dates are shown with the figure.
Update classes: event — recomputed by a job after each approval, amendment or void of a source record (target lag under 5 minutes, hypothesis to be measured) and rebuilt nightly for the current and the previous month; query — computed from current rows when read; analysis — stored when the fueling is accepted and recomputed as a new analysis on amendment or on a new methodology version. A sum over zero included records is stored as 0 with a record count of 0 and is shown as "sem registros aprovados no período", never as a bare zero.
| Indicator | Inclusion criteria | Behaviour with missing data | Update | Source | Limits of interpretation |
|---|---|---|---|---|---|
| IND-001 Fuel spend | Approved fuel expenses; fuel from an internal tank at the cost recognised when dispensed; company amount only | Sum rule above; pending amount shown beside | event | Expenses projected from fuelings (expenses-finance) | Follows the day of the fueling, not the day of payment; a late approval changes a past period, with a new revision |
| IND-002 Fuel volume | Approved fuelings; additives as their own product line | Sum rule above | event | fuelings | Volume bought, not volume burned; fuel left in tanks at the period edges is not measured |
| IND-003 km/L, IND-004 L/100 km | Intervals COMPUTED whose fuelings are all approved; one product per line; superseded intervals excluded |
No closed interval → INSUFFICIENT_DATA (NO_CLOSED_INTERVAL); intervals in INSUFFICIENT_DATA are counted and listed, never estimated; product not supported by the method → METHOD_UNSUPPORTED
|
event, after interval recalculation | Consumption intervals of fuelings, computed with the existing engine | Purchase-to-purchase measure, sensitive to load, route, idling and weather; not comparable across products; below the minimum sample it is labelled (BR-KPI-016) |
| IND-005 L/h | As IND-003, hour-meter assets |
NO_CLOSED_INTERVAL, NO_HOUR_BASIS
|
event | Same | Engine hours include idling |
| IND-006 Fuel cost per km, IND-007 per hour | Same intervals as the consumption figure; cost of the fuel counted in those intervals | Same as IND-003 or IND-005 | event | Same | A purchase-based estimate between two full fills; excludes the anchor fill; not the total cost of running the asset |
| IND-008 Total operating cost | Approved expenses whose category is flagged as operating cost in expenses-finance; each cost once: payments, reimbursements and stock purchases are not costs | Sum rule above; categories with no record listed as such | event | Expenses and allocation rows | Not an accounting result: no depreciation or capital, and salaries only if recorded as expenses; recurring costs fall in their competence period; not comparable between organizations with different category flags |
| IND-009 Operating cost per km, IND-010 per hour | Assets with an observed window (two valid readings in the period, no replacement gap inside); costs dated inside the window; other assets excluded from the ratio and listed | No asset with a window → INSUFFICIENT_DATA (NO_DISTANCE_BASIS or NO_HOUR_BASIS); zero usage → ZERO_DENOMINATOR
|
event | Expenses; meter readings of fleet | The window may be shorter than the period; periodic costs such as insurance distort short windows; only costs allocated to an asset enter |
| IND-011 Maintenance cost | Approved expenses from work orders (parts and services) and maintenance categories; each work order once | Sum rule above | event | maintenance, expenses | Recognised when the cost is approved, not when the failure happened; covered repairs show only the company amount |
| IND-012 Availability | Assets with lifecycle ACTIVE, for the seconds they were active; calendar time, 24 hours a day; RESERVED and IN_USE count as available |
No availability history for the period → INSUFFICIENT_DATA (NO_AVAILABILITY_HISTORY); never assumed to be 100 % |
event | Derived availability of fleet and maintenance | Calendar-based, not shift-based; depends on maintenance start and end being recorded on time |
| IND-013 Records pending review | Records in the caller's scope, of every type the caller may read | A module not enabled for the organization is omitted, not shown as zero | query | Review states (BR-REV-001) | A count, not a quality measure; a high number may mean that reviewers are missing |
| IND-014 Documents not reconciled | Documents in storage state STORED; replaced and deleted ones excluded |
Documents not enabled → omitted | query | documents | Not reconciled does not mean irregular; says nothing about fiscal authenticity (BR-TRUTH-002) |
| IND-015 Sync items awaiting review | Items the caller may resolve or read, including those past the escalation age | — | query | 10-offline-sync | While this is above zero the other figures may be understated, because held records count nowhere |
| IND-016 Price difference | Approved fuelings whose stored comparison is a number, one reference source at a time; internal-tank fuelings excluded | No fueling with a comparable reference → INSUFFICIENT_DATA with the most frequent reason; the share compared is always shown |
analysis | Stored price comparisons; references from the public read models of official and community
|
A difference for review, not loss or savings (BR-KPI-014); covers only the compared share; positive and negative parts are shown beside the net |
| IND-017 Distance, IND-018 Hours | Readings in state VALID; SUSPECT and VOIDED excluded; a meter replacement closes one segment and opens another |
Fewer than two valid readings in the period → INSUFFICIENT_DATA (NO_DISTANCE_BASIS, NO_HOUR_BASIS) |
event | Meter readings of fleet | Usage of the observed window, not necessarily of the whole period; meter values, never replaced by GPS or planned distance |
| IND-019 Open findings | Findings in scope that are not terminal | Detection off for a type → omitted | query | Findings | Open questions, not irregularities |
| IND-020 Change | Both periods computed for the same indicator, unit, dimension values and method version | Baseline zero → ZERO_BASELINE; either side insufficient → INSUFFICIENT_DATA; different versions → METHOD_MISMATCH
|
with its snapshots | Snapshots | A change between two periods is not a trend; small samples swing widely; periods may differ in number of days |
| Indicators | Organization | Unit | Cost centre | Driver | Vehicle | Trip | Supplier |
|---|---|---|---|---|---|---|---|
| Fuel spend, fuel volume, price difference | yes | yes | yes | yes | yes | yes, fuelings linked to the trip | yes |
| Consumption and fuel cost per km or hour | yes | yes | yes | only intervals driven entirely by one driver; otherwise MIXED_DRIVERS
|
yes | per-trip allocation defined in fuelings | — |
| Total operating cost | yes | yes | yes | yes | yes | yes, expenses linked to the trip | yes |
| Operating cost per km or hour | yes | yes | yes | — | yes | yes, with the trip's own readings | — |
| Maintenance cost | yes | yes | yes | — | yes | — | yes (workshop) |
| Availability, distance, hours | yes | yes | — | — | yes | distance and hours only | — |
| Pending records, sync items, open findings | yes | yes | yes | yes (author) | yes | — | — |
| Documents not reconciled | yes | yes | yes | — | — | — | yes (issuer) |
Evolution over time is a series of one indicator over consecutive periods with the same dimension values. Each point is a snapshot with its own basis; a point with insufficient data is a gap, not a zero. A series that crosses a method version change shows a marker at the change and computes no variation across it.
NO_CLOSED_INTERVAL, METHOD_UNSUPPORTED, NO_DISTANCE_BASIS, NO_HOUR_BASIS, ZERO_DENOMINATOR, NO_AVAILABILITY_HISTORY, MIXED_DRIVERS, ZERO_BASELINE, METHOD_MISMATCH, and for price comparisons NO_REFERENCE, PLACE_UNKNOWN, REFERENCE_STALE, LOW_COVERAGE, CONDITION_MISMATCH, CONDITION_UNKNOWN. Each has a plain-language text in the interface and is written as a code in machine exports.
Synthetic data. Two vehicles of one unit, both fuelled with diesel S10, October:
| Closed interval | Distance | Quantity | Cost |
|---|---|---|---|
| Truck A, interval 1 | 612 000 m | 180 000 mL | 116 820 centavos |
| Truck A, interval 2 | 588 000 m | 170 000 mL | 110 330 centavos |
| Van B, interval 1 | 400 000 m | 40 000 mL | 23 960 centavos |
| Sum | 1 600 000 m | 390 000 mL | 251 110 centavos |
- Distance per unit:
1 600 000 ÷ 390 000 = 160/39 = 4.1026…, shown as 4.10 km/L. Per vehicle: A1 200 000 ÷ 350 000 = 24/7, shown 3.43; B400 000 ÷ 40 000 = 10, shown 10.00. The average of the two vehicle figures would be 6.71 and is never used (BR-KPI-004). - Fuel per 100 km:
390 000 × 100 ÷ 1 600 000 = 24.375, shown as 24.38 L/100 km. - Fuel cost per km:
251 110 × 1 000 ÷ 1 600 000 = 156.94375centavos per km, shown as R$ 1.57/km. - A tractor with one closed interval of 180 000 s (50 h), 600 000 mL and 359 400 centavos:
600 000 × 3 600 ÷ (180 000 × 1 000) = 12L/h;359 400 × 3 600 ÷ 180 000 = 7 188centavos per hour, R$ 71.88/h. - Total operating cost of Truck A in October: fuel 227 150 + maintenance 84 000 + tolls 12 640 + parking 3 000 = 326 790 centavos (R$ 3 267.90). Its observed window has readings 184 532 000 m and 185 782 000 m, so the distance is 1 250 000 m and the cost per km is
326 790 × 1 000 ÷ 1 250 000 = 261.432centavos, shown as R$ 2.61/km. Had Truck A only one valid reading in October, the result would beINSUFFICIENT_DATA(NO_DISTANCE_BASIS). - Availability of Truck A in October: 31 days are
31 × 86 400 = 2 678 400s; it spent 2 days and 6 hours in maintenance,194 400s;(2 678 400 − 194 400) ÷ 2 678 400 = 2 484 000 ÷ 2 678 400 = 115/124, shown as 92.7 %.
Methodology price-comparison-v1. A comparison is made per reference source; the four sources of BR-SRC-001 are never merged, averaged or used as a fallback for one another inside one analysis.
| Criterion | Rule | When it is not met |
|---|---|---|
| Fuel product | Same product code; different grades are different products | No candidate: NO_REFERENCE
|
| Unit | Same unit as the fueling | NO_REFERENCE |
| Place |
SAME_STATION: the fueling is linked to a catalog station and the reference is that station's price; or SAME_MUNICIPALITY: the reference is the figure of that station's municipality. The rule used is stored |
Fueling with no catalog station or municipality: PLACE_UNKNOWN
|
| Period | The reference was valid at the fueling instant: official survey → the survey week containing the reporting day, or the latest published week ending at most 14 days before it (default, range 7 to 28); community → projection not expired at that instant; announced → inside its validity; negotiated → table in force | REFERENCE_STALE |
| Coverage | The reference states how many observations or stations it represents; a municipal figure needs at least 3 stations (default, range 1 to 10) | LOW_COVERAGE |
| Payment form and offer conditions | The reference's condition equals the fueling's price condition, in the vocabulary of the public price model (STANDARD, CASH, DEBIT, CREDIT, APP, LOYALTY, OTHER); a promotional price compares only with a fueling under the same offer |
CONDITION_MISMATCH; unknown on either side: CONDITION_UNKNOWN
|
| Origin | Exactly one source, named in the analysis with its revision | One analysis per source |
Computation, when every criterion is met: reference_cents = round_half_up(quantity_milli × reference_unit_price_milli ÷ 10 000); difference_cents = paid_cents − reference_cents; difference_per_unit_milli = effective_unit_price_milli − reference_unit_price_milli, where the effective unit price is the paid total divided by the quantity (BR-MONEY-006). The paid total is the authoritative amount (BR-MONEY-001) and is never recomputed.
Stored with every analysis: methodology identifier and version, place rule, maximum reference age, minimum coverage, rounding rule; the reference's source, source revision, place, period, condition, coverage and unit price; the fueling revision; the computed-at instant. A new methodology version, a changed parameter or an amended fueling produces a new analysis that names the one it supersedes; the old one stays readable (BR-TRUTH-004).
Case A — comparable reference. A fueling of 150 litres of diesel S10 recorded at R$ 6.49 per litre, paid total R$ 973.50, price condition STANDARD, at a catalog station. The reference is the official survey figure for the same product in the same municipality, in the survey week of the fueling, with 8 stations surveyed, condition STANDARD: R$ 6.09 per litre. Every criterion of §10.6 is met.
- Recorded:
150 000 × 6 490 ÷ 10 000 = 97 350centavos (150 × 6.49 = 973.50). - Reference:
150 000 × 6 090 ÷ 10 000 = 91 350centavos (150 × 6.09 = 913.50). - Difference:
97 350 − 91 350 = 6 000centavos (973.50 − 913.50 = 60.00), R$ 0.40 per litre.
The panel shows "Diferença de R$ 60,00 em relação à referência", with the source, municipality, survey week, condition, coverage and methodology version. This indicates a difference for review. It does not prove a loss, and it does not prove savings that could have been realised: the reference is a figure observed at other stations and moments, the vehicle may not have been able to buy at that price on its route or at that hour, the product or the payment term may not have been available elsewhere, and the recorded price may simply be correct for that station. Without an adequate reference the result is INSUFFICIENT_DATA, and no number is shown.
Case B — reference not comparable. The same fueling was paid by credit card at the station's card price (condition CREDIT). The only candidate reference is R$ 6.09 per litre for condition CASH. The payment condition differs, so the analysis is stored as INSUFFICIENT_DATA with the reason CONDITION_MISMATCH. No difference is computed, the fueling does not enter IND-016, and no finding is raised. The detail screen lists the candidate as "não comparável: condição de pagamento diferente", so that the reviewer sees why there is no figure.
Thresholds are defaults with the range an organization may set (BR-FIND-010). Where the owning module already validates the same condition at entry (fuelings, fleet, documents), the finding uses that module's parameter value: there is one configuration, not two.
| ID | Type and trigger | Inputs | Default threshold | Severity | Evidence shown | What it does not prove |
|---|---|---|---|---|---|---|
| FT-001 | Suspected duplicate fueling: two accepted, non-voided fuelings with different record identifiers for the same asset and product, with equal quantity and equal paid total inside the time window; or two fuelings linked to the same fiscal access key or the same file hash | Fuelings (asset, product, instant, quantity, paid total, author, device); document links (access key, content hash) | Window 30 minutes (5 to 1 440) |
MEDIUM; HIGH when the same access key or file supports both |
Both records side by side, authors, devices, sync times, documents, trip | That a fueling was invented or paid twice. Two real fuelings can be identical, and one receipt can cover two assets when it is allocated |
| FT-002 | Incoherent meter reading: a reading lower than an earlier valid reading of the same meter with no recorded replacement; or usage between two readings that implies more than the plausible average speed; or hour-meter usage greater than the elapsed time | Readings (value, instant, source, author), meter replacements, trips | Any decrease; average speed above 150 km/h (80 to 200); hour-meter usage above elapsed time |
MEDIUM; HIGH when it invalidates a closed consumption interval or an approved trip distance |
The readings in sequence with source and author, the implied usage, the trips and fuelings that use them | Tampering. Typing mistakes, misread photos, swapped vehicles and an unregistered meter replacement are common |
| FT-003 | Volume incompatible with the tank: quantity above the usable capacity of the asset's tanks for that product plus the tolerance; or a product the tank does not accept | Fueling quantity and product; tank capacities and accepted products; previous fueling and distance since | 5 % above capacity (0 to 20 %) |
MEDIUM; HIGH above 20 % over capacity or for an incompatible product |
Quantity against capacity, registered tanks, receipt, previous fueling and distance | That fuel went elsewhere. The registered capacity may be wrong, an auxiliary tank may be unregistered, or one receipt may cover two vehicles |
| FT-004 | Consumption outside the asset's pattern: a closed interval whose distance per unit differs from the asset's baseline by more than the threshold, in either direction. Baseline: sum of distances ÷ sum of quantities of the previous closed intervals of the same asset and product | The interval tested; the previous 6 closed intervals (minimum 3, BR-KPI-016) | 20 % (10 to 50 %) |
MEDIUM; HIGH beyond twice the threshold |
Interval and baseline figures, the fuelings and readings of the interval, trips in the interval | Misuse of fuel. Load, route, idling, weather, tyre pressure and a fueling that was never recorded all change consumption |
| FT-005 | Document divergent from the record: a linked document whose conference result is DIVERGENT; or structured fiscal data that differ from the record beyond tolerance in amount, quantity, date, product or issuer; or allocations above the document total (OVER_ALLOCATED) |
Conference and reconciliation status, fiscal items, allocations; record amount, quantity, day, product, supplier | Amount 1 centavo (BR-MONEY-005); quantity 1 % (0 to 5 %); date 1 day (0 to 7) |
LOW for date only; MEDIUM for quantity, product or an amount difference up to 5 %; HIGH for an amount difference above 5 % or a different issuer |
Record and document values side by side, the document link, allocations, extraction confidence | That the document is false or the record wrong. The wrong photo may be attached, the receipt may cover operations not yet allocated, extraction may have misread; fiscal authenticity is not assessed (BR-TRUTH-002) |
| FT-006 | Price above the reference: a price comparison with a comparable reference (§10.6) whose effective unit price exceeds the reference by more than the percentage threshold and whose difference reaches the minimum amount | The stored price comparison and its reference; the organization's chosen reference source | 5 % (1 to 30 %) and R$ 10.00 (R$ 0.00 to R$ 500.00) |
LOW below 10 %; MEDIUM from 10 % to below 20 %; HIGH from 20 % |
Recorded unit price and total, the reference with source, place, period, condition and coverage, methodology version, difference per unit and in total | A loss, an overpayment or savings that could have been realised (BR-KPI-014). The reference comes from other stations, moments or conditions |
A type is evaluated only when its inputs exist. A missing baseline, a missing capacity or a comparison in INSUFFICIENT_DATA raises nothing.
- FT-001: two fuelings of one truck, diesel S10, 150 000 mL and 97 350 centavos each, at 13:42 and 13:55 of the same day, with different record identifiers. 13 minutes ≤ 30: one finding,
MEDIUM. The same operation sent twice by the app is not a duplicate: it has one identifier and is absorbed by the acknowledgement (BR-OFFL-004). - FT-002: readings of 185 000 000 m at 08:00 and 185 900 000 m at 12:00. Usage 900 000 m in 14 400 s;
900 000 × 3 600 = 3 240 000 000is greater than150 000 × 14 400 = 2 160 000 000, so the average speed exceeds 150 km/h (it is 225 km/h): one finding,MEDIUM. - FT-003: tank of 275 000 mL, fueling of 300 000 mL. Limit
275 000 × 105 ÷ 100 = 288 750mL; 300 000 > 288 750: one finding. Excess over capacity25 000 ÷ 275 000 = 9.09 %, below 20 %:MEDIUM. - FT-004: baseline of six intervals, 3 600 000 m and 1 050 000 mL (24/7, shown 3.43 km/L). Interval tested: 500 000 m and 200 000 mL (2.50 km/L). Ratio to baseline
(500 000 × 1 050 000) ÷ (200 000 × 3 600 000) = 35/48 = 0.7292, a deviation of 27.08 %. Above 20 % and below 40 %: one finding,MEDIUM. - FT-005: record of 150 000 mL and 97 350 centavos; fiscal item of 150 000 mL and 98 350 centavos. Difference 1 000 centavos, above 1 centavo;
1 000 ÷ 97 350 = 1.03 %, up to 5 %: one finding,MEDIUM. - FT-006: Case A of §10.7.
6 490 × 100 = 649 000is greater than6 090 × 105 = 639 450, and 6 000 centavos ≥ 1 000: one finding.649 000is less than6 090 × 110 = 669 900:LOW. Its text reads "Preço registrado 6,57 % acima da referência; diferença de R$ 60,00. Revise as condições da compra." Case B raises nothing.
| Format | Used for | Writer | Notes |
|---|---|---|---|
| CSV | Lists, indicator tables, audit list, error-free machine reading | Standard library, as the existing CSV writers do | UTF-8 with byte-order mark, comma separator, header with stable column names; BR-RPT-006, BR-RPT-008; delivered with its manifest in a ZIP package (application/zip, <list>.csv + manifest.json, EMP-RPT-002) |
| Spreadsheet (XLSX) | The same lists for people who work in spreadsheets | Proposed: a minimal in-repository writer on the standard ZIP and XML packages (one data sheet and one "Sobre este relatório" sheet, strings and numbers only, no formulas, macros or external links), mirroring decision D06 for reading; confirmed or replaced by the recorded review in EMP-RPT-002 (CX-10) EMP-RPT-002 did not admit it (no reviewed writer); the kinds stay EXPORT_FORMAT_UNAVAILABLE. |
Text cells typed as strings |
| Trip logbook, fueling statement, period summary | No standard-library option. EMP-RPT-003 starts with a recorded decision among a reviewed library, a minimal in-repository writer for text and tables, or a print-ready panel page printed by the browser (which cannot be scheduled) | Header block with the basis; no remote resources | |
| ZIP | Full export and multi-file exports | Standard library |
manifest.json with file, row count and SHA-256 per category |
Full export categories: organization and structure; employees, memberships and role assignments; assets, meters and readings; missions, trips and logbook events; track summaries (raw fixes only while retained); fuelings and consumption intervals; documents (metadata, and files on request); expenses, allocations, payables and payments; budgets; maintenance; internal stock; findings and price comparisons; audit events; notification history. Never included: credentials, activation and voucher codes, key hashes, integration secrets, platform-internal records, and anything of another organization.
Shared codes are in 09-architecture §6. Added here:
| Code | HTTP | Meaning |
|---|---|---|
EXPORT_TOO_LARGE |
422 | The export exceeds a row, size or time ceiling; narrow the filter |
EXPORT_QUEUE_FULL |
429 | The requester already has the maximum number of open jobs |
EXPORT_NOT_READY |
409 | Download asked for a job that is not READY
|
EXPORT_EXPIRED |
410 | The file was deleted at expiry |
EXPORT_FORMAT_UNAVAILABLE |
422 | The format is not admitted or not enabled |
EXPORT_CANCELLED |
— | Recorded on a job cancelled by its requester |
FINDING_CLOSED |
409 | A command targeted a finding in a terminal state |
INSUFFICIENT_DATA is a result with a reason (§10.4), not an error: the request succeeds.
EMP-RPT-001 records EXPORT_RIGHTS_LOST and EXPORT_ATTEMPTS_EXHAUSTED as job
failure codes (no HTTP status; read on the job). F3 delivers files through a
base64 JSON capability exchange with a 16 MiB ceiling.
| ID | Surface | Objective | Actor | Data | Actions | Rules and permissions | Validations and states |
|---|---|---|---|---|---|---|---|
| SCR-KPI-01 | PANEL | See the state of the fleet for a period | kpi.dashboard.read |
Spend, volume, consumption, cost per km and hour, operating cost, maintenance, availability, pending items, series over periods | Choose period and scope, switch "inclui pendentes", open a figure, export | BR-KPI-001, 002, 007, 011 | Insufficient data shown as text with the reason, never as 0. Empty: "Ainda não há registros aprovados neste período", with the pending count. Scope label always visible. |
| SCR-KPI-02 | PANEL | Break a figure down by a dimension | kpi.dashboard.read |
One indicator by unit, cost centre, driver, vehicle, trip or supplier, with sample size | Sort, filter, change dimension, open a row, export | BR-KPI-004, 006, 010, 016 | Dimensions that do not apply are not offered (§10.3). Rows below the minimum sample labelled "amostra pequena". |
| SCR-KPI-03 | PANEL | Understand how a figure was computed |
kpi.dashboard.read, plus the record type's read permission to list records |
Formula, numerator, denominator, method version, counts included, excluded and pending, revisions, records | Open a record, compare revisions | BR-KPI-007, 008 | Superseded revisions marked. Records the member cannot read are counted, not listed. |
| SCR-KPI-04 | PANEL | See a price comparison and its reference |
kpi.dashboard.read, fuel.fueling.read
|
Recorded price and total, reference with source, place, period, condition, coverage, methodology version, difference, candidates not comparable with the reason | Open the fueling, open the finding | BR-KPI-012, 013, 014; BR-SRC-001 | No figure when insufficient; the reason is shown. Reference age shown (BR-TRUTH-006). |
| SCR-FIND-01 | PANEL | Work the queue of findings | find.finding.read |
Findings by state, type, severity, age, responsible member, subject | Filter, take, assign, open | BR-FIND-004, 005, 009 | Empty: "Nenhum achado em aberto". Colour is never the only severity cue. Own records cannot be taken (BR-FIND-007). |
| SCR-FIND-02 | PANEL | Review one finding and decide |
find.finding.resolve to act; find.finding.read to see |
Evidence side by side, threshold and method, what the type does not prove, history, linked records | Take, release, decide with justification, choose follow-up, dismiss | BR-FIND-001, 002, 006, 007, 008 | Justification required. Conflict: "já decidido por outra pessoa". Links to records follow the member's permissions. |
| SCR-FIND-03 | PANEL | Configure detection and reprocess | org.settings.manage |
Types with thresholds and ranges, reference source, runs with counts | Enable, change threshold, start a reprocessing | BR-FIND-010, 011 | Out-of-range values refused with the range shown. A run in progress disables a second one. |
| SCR-RPT-01 | PANEL | Export the current list or table |
rpt.export.run and the list's read permission |
Format, columns, filters in effect, estimated rows | Create the job, download when ready | BR-RPT-001, 002, 003, 006 | Progress by polling. Sensitive columns absent without their permission, with a note. Errors: queue full, too large, format unavailable. |
| SCR-RPT-02 | PANEL | Follow own exports | rpt.export.run |
Jobs with kind, state, rows, size, expiry | Download, cancel while queued, request again | BR-RPT-004, 005, 009 | Expired jobs listed without a download. Empty: "Você ainda não gerou exportações". |
| SCR-RPT-03 | PANEL | Generate and schedule reports | rpt.export.run |
Report catalogue, parameters, schedules with cadence, recipients and last run | Generate, schedule, pause, remove | BR-RPT-011, 014, 015 | Paused schedules show the reason. Recipients who lack the right are flagged before saving. |
| SCR-RPT-04 | PANEL | Export all organization data |
rpt.export.run and org.settings.manage, organization scope |
Categories, size estimate, documents by month, previous full exports | Confirm with fresh authentication, download parts | BR-RPT-012; BR-AUTH-010 | States that owners are notified and that files expire. Documents not offered without doc.document.view_content. |
| SCR-RPT-05 | PANEL | Consult the audit trail | audit.event.read |
Events with actor, delegation, action, target reference, time, reason | Filter, open an event, follow the target, export | BR-RPT-013; BR-AUD-004, 005, 006 | Empty state explains what is recorded. No content is shown. The sensitive-access view SCR-PRIV-06 is a preset filter of this screen. |
Acceptance criteria:
- The registry answers, for every indicator of §10.1, its formula, inputs, unit, inclusion criteria, missing-data behaviour, update class, source and limits, with a method version.
- With the fixture of §10.5 the group distance per unit is 160/39 (shown 4.10) and never 6.71; every other figure of §10.5 is reproduced exactly.
- A ratio with a zero denominator or a missing input returns
INSUFFICIENT_DATAwith its reason in the API, the panel, CSV, spreadsheet and PDF; no surface shows 0. - Dashboards count approved records by default; with pending records included the figure carries "inclui pendentes" and the pending part is separate.
- Amending an approved fueling produces a new snapshot revision; the previous revision remains readable and marked superseded.
- Case A of §10.7 yields exactly 6 000 centavos and no wording of loss or savings; Case B yields
INSUFFICIENT_DATAwithCONDITION_MISMATCHand no finding. - A stored price comparison keeps its reference after the public price is revised.
- Each example of §10.9 raises exactly one finding with the stated severity; running detection again creates no second finding.
- A finding cannot reach a decided state without a justification; the record's author is refused with
SELF_APPROVAL; the second of two concurrent decisions receivesCONFLICT. - Deciding a finding changes no fueling, expense, reading, payment or person.
- A reprocessing run supersedes unsupported findings that are not decided, leaves decided ones unchanged with a note, and is named on each affected finding.
- An export job, its file and its capability of organization A are not found by a member of organization B; a capability fails after 5 minutes, for another member and for another job; after expiry the file no longer exists.
- A job whose requester's membership ended before the worker started ends
FAILEDand writes no file. - A text value beginning with
=is exported as text in CSV and in the spreadsheet, and opening the file runs no formula. - The full export has a manifest whose row counts and hashes match its files, contains no secret, requires fresh authentication, writes an audit event and notifies every owner.
- The audit viewer lists only events in the caller's scope and never shows document content, coordinates or credentials.
Dependencies: fuelings (fuelings, intervals, price reference capture), expenses-finance (expenses, categories, review), fleet (readings, availability, tanks), maintenance, documents, trips, 10-offline-sync (review queue), 07-permissions, 09-architecture §7 to §9, 11-privacy-security; decisions EDR-011, EDR-013, EDR-030 and conflict CX-10.
Risks: figures read as verdicts about people (wording rules, sample sizes, no rankings); findings ignored when too many are raised (bounded thresholds, severity, false-positive counts feeding threshold review); references rarely comparable while fuelings lack a price condition (the share compared is always shown); read models drifting from facts (nightly rebuild and revision checks); exports as a path for data to leave (permission repeat, audit, expiry, owner notification); a PDF or spreadsheet library admitted without review (BR-RPT-011); recalculation load after bulk amendments (keyed, batched jobs on a dedicated dispatcher).
Phase: F3 for the export infrastructure and list exports, because every operational list needs a way out before indicators exist and other modules build on the job (14-roadmap §2). F6 (EMP-KPI-001..006, EMP-FIND-001..005, EMP-RPT-003..006, EMP-REL-007, EMP-REL-010, recorded in EDR-375..385) for indicators, price comparison, findings, PDF and scheduled reports, the full export and the audit viewer: they need approved fuelings, consumption intervals, expenses, readings, documents and maintenance. Announced and negotiated reference sources follow F7.
Microtasks: EMP-KPI-001 to EMP-KPI-006, EMP-FIND-001 to EMP-FIND-005, EMP-RPT-001 to EMP-RPT-006 (F3 + F6 local/integration implemented).
- Home
- Roadmap
- docs-README
- docs-android-build
- docs-android-design-system
- docs-android-forum
- docs-android-games
- docs-android-map-engine
- docs-android-navigation
- docs-android-ocr-image
- docs-android-ocr-live-framing
- docs-android-premium-area
- docs-android-premium-integration
- docs-android-release
- docs-android-ui-containers
- docs-architecture-android-stack
- docs-architecture-android
- docs-architecture-backend
- docs-architecture-data-sources
- docs-architecture-overview
- docs-architecture-sources-ev-research
- docs-architecture-sources-national-limits
- docs-architecture-sources-national-stations
- docs-architecture-sources-register
- docs-assets-app-tutorial-CAPTURE_CONTRACT
- docs-assets-app-tutorial-FABLE_LANDING_POLISH_PROMPT
- docs-assets-app-tutorial-README
- docs-assets-attribution
- docs-assets-brand-README
- docs-assets-flags-ATTRIBUTION
- docs-assets-fuel-icons-README
- docs-assets-games-fuel-v1-README
- docs-assets-home-icons-README
- docs-assets-landing-fleet-android-20261012-BRIEF
- docs-assets-landing-hero-20261011-BRIEF
- docs-assets-landing-illustrated-20261012-BRIEF
- docs-assets-landing-illustrated-20261012-README
- docs-assets-landing-minimal-20261012-BRIEF
- docs-assets-landing-open-data-20261026-BRIEF
- docs-assets-landing-redesign-20261011-PREPARATION_EVIDENCE
- docs-assets-landing-redesign-20261011-README
- docs-assets-landing-redesign-20261011-REFERENCE_BRIEF
- docs-assets-landing-sync-20261012-BRIEF
- docs-assets-map-icons-README
- docs-backend-anp-ingestion
- docs-backend-api
- docs-backend-community-pricing
- docs-backend-data-model
- docs-backend-domain-model
- docs-backend-driver-private-data
- docs-backend-forum-architecture
- docs-backend-forum-bulletins
- docs-backend-forum-sources
- docs-backend-payments-provider-admission
- docs-backend-payments-provider-register
- docs-backend-photos-capture
- docs-backend-photos-subset-submission
- docs-backend-premium-api
- docs-backend-premium-cloud-protocol
- docs-backend-testing
- docs-backend-toolchain
- docs-brand-app-icons
- docs-brand-identity
- docs-decisions-001-kotlin-compose-stack
- docs-decisions-002-price-import-immutability
- docs-decisions-003-nominatim-reverse-geocode
- docs-decisions-005-modular-monolith-and-postgresql
- docs-decisions-006-official-catalog-and-exact-contracts
- docs-decisions-007-anonymous-proof-of-possession
- docs-decisions-008-privacy-and-retention
- docs-decisions-009-community-consensus-and-projections
- docs-decisions-010-private-object-evidence
- docs-decisions-012-licensing-and-hosted-business
- docs-decisions-015-kotlin-multiplatform-shared-domain
- docs-decisions-016-android-commercial-community-ios-deferred
- docs-decisions-017-station-profile-and-verified-representation
- docs-decisions-021-community-first-contribution
- docs-decisions-022-comaps-derived-native-map-engine
- docs-decisions-023-admin-suite-granted-tiers-contributors
- docs-decisions-025-private-abastevo-empresas-organization-boundary
- docs-decisions-026-multilingual-public-site
- docs-decisions-README
- docs-enterprise-README
- docs-enterprise-architecture
- docs-enterprise-backlog-INDEX
- docs-enterprise-backlog-ep00-governance
- docs-enterprise-backlog-ep01-platform
- docs-enterprise-backlog-ep02-organizations
- docs-enterprise-backlog-ep03-identity-access
- docs-enterprise-backlog-ep04-sync
- docs-enterprise-backlog-ep05-fleet-meters
- docs-enterprise-backlog-ep06-trips
- docs-enterprise-backlog-ep07-gps-navigation
- docs-enterprise-backlog-ep08-fuelings
- docs-enterprise-backlog-ep09-documents
- docs-enterprise-backlog-ep10-expenses-finance
- docs-enterprise-backlog-ep11-maintenance
- docs-enterprise-backlog-ep12-fuel-stock
- docs-enterprise-backlog-ep13-intelligence
- docs-enterprise-backlog-ep14-station-claims
- docs-enterprise-backlog-ep15-station-commerce
- docs-enterprise-backlog-ep16-subscriptions
- docs-enterprise-backlog-ep17-data
- docs-enterprise-backlog-ep18-imports-notifications-integrations
- docs-enterprise-backlog-ep19-back-office
- docs-enterprise-backlog-ep20-release
- docs-enterprise-business-rules
- docs-enterprise-contract
- docs-enterprise-conventions
- docs-enterprise-data-offering
- docs-enterprise-decisions
- docs-enterprise-domain-model
- docs-enterprise-glossary
- docs-enterprise-journeys
- docs-enterprise-modules-back-office
- docs-enterprise-modules-data
- docs-enterprise-modules-documents
- docs-enterprise-modules-expenses-finance
- docs-enterprise-modules-fleet
- docs-enterprise-modules-fuel-stock
- docs-enterprise-modules-fuelings
- docs-enterprise-modules-gps-navigation
- docs-enterprise-modules-identity
- docs-enterprise-modules-imports-notifications-integrations
- docs-enterprise-modules-intelligence
- docs-enterprise-modules-maintenance
- docs-enterprise-modules-organizations
- docs-enterprise-modules-station-claims
- docs-enterprise-modules-station-commerce
- docs-enterprise-modules-subscriptions
- docs-enterprise-modules-trips
- docs-enterprise-offline-sync
- docs-enterprise-permissions
- docs-enterprise-portal-routes
- docs-enterprise-privacy-security
- docs-enterprise-product-vision
- docs-enterprise-source-admission
- docs-enterprise-state-model
- docs-enterprise-testing
- docs-enterprise-ux-app
- docs-enterprise-ux-web
- docs-operations-README
- docs-operations-backup
- docs-operations-deploy-agent
- docs-operations-dou-editions
- docs-operations-edge-cache
- docs-operations-enterprise-activation
- docs-operations-map-static-overlay
- docs-operations-moderation-feedback
- docs-operations-moderation-profiles
- docs-operations-monitoring
- docs-operations-operator-access
- docs-operations-payments
- docs-operations-premium-billing
- docs-operations-recovery
- docs-operations-registry-daily-sync
- docs-operations-registry-runs
- docs-product-README
- docs-product-admin-tiers
- docs-product-community-community-first
- docs-product-community-experience
- docs-product-community-metrics
- docs-product-community-moderation
- docs-product-community-safety
- docs-product-community-terms-pt-br
- docs-product-driver-suite-README
- docs-product-driver-suite-android-state
- docs-product-driver-suite-cloud-sync
- docs-product-driver-suite-cost-profiles-and-maintenance
- docs-product-driver-suite-driver-model-and-earnings
- docs-product-driver-suite-foundation-decisions
- docs-product-driver-suite-gps-lifecycle
- docs-product-driver-suite-mobile-hub
- docs-product-driver-suite-odometer-review
- docs-product-driver-suite-outbox-wire
- docs-product-driver-suite-quick-refuel
- docs-product-driver-suite-reports
- docs-product-driver-suite-shifts-and-distance
- docs-product-driver-suite-signed-commands
- docs-product-ev-README
- docs-product-ev-charging-stop-planner
- docs-product-ev-energy-model
- docs-product-ev-financial-method
- docs-product-ev-journey-ui
- docs-product-ev-preparation
- docs-product-ev-typed-data
- docs-product-exploration
- docs-product-forum-contract
- docs-product-forum-policies
- docs-product-glossary
- docs-product-landing-content
- docs-product-landing-guides
- docs-product-landing-organic-growth-i18n-plan
- docs-product-licensing
- docs-product-map-discovery
- docs-product-map-favorites-and-trips
- docs-product-map-reports-routing-guidance
- docs-product-notification-content
- docs-product-official-prices
- docs-product-open-source-business
- docs-product-overview
- docs-product-payments-README
- docs-product-payments-offer-policy
- docs-product-premium-README
- docs-product-premium-financial-method
- docs-product-premium-source-policy
- docs-product-stations-catalog
- docs-product-stations-fuel-feedback
- docs-product-stations-fuel-quality
- docs-product-stations-identity-and-ev-catalog
- docs-product-stations-profile-contract
- docs-product-stations-profile-representation
- docs-product-stations-registry-sources
- docs-product-vehicle-registration
- docs-product-vehicles-and-occurrences
- docs-security-android-terms-acceptance
- docs-security-free-account-access
- docs-security-identity-profile
- docs-security-media-location-policy
- docs-security-privacy-notice
- docs-security-privacy-policy
- docs-security-retention
- docs-security-risks
- docs-security-security-privacy
- docs-store-README
- docs-store-play-readiness
- docs-store-play-store-listing
- docs-store-ugc-safety
Source: AlexandreZanata/Abastevo @ e4a67580fc368a59bc1c0f1e0466fc011313f330