Repository navigation
docs enterprise offline sync
Module code OFFL. This file is the module specification for offline behaviour and the transversal offline matrix for the whole suite.
Evidence. The repository already has a private command protocol for one account's data: stable operation identifiers, expected revisions, durable acknowledgements, conflict responses and anti-resurrection fences (PREMIUM_CLOUD_PROTOCOL, IMPLEMENTED on the server; the Android side has separate queues per feature, PARTIAL). That protocol states "No tenant/fleet ownership". This module is PROPOSED: it reuses the protocol's identifiers, acknowledgement and replay rules, and changes what an organization needs changed. The differences are listed in §3.
Field employees work where there is no signal. They must be able to record what happened, keep working, and trust that the record reaches the right company. Managers must be able to trust that what arrives was recorded by an authorized person, and must see and resolve what the server could not accept by itself. Nothing is ever dropped silently.
- Basic (F1–F2, cut C1): operation envelope and contract; server intake with idempotency and dependency order; Android persistent queue with fixed organization context; sync status on every record; attachment upload with retry; reference data pull; device clock handling; a review queue with basic resolution; behaviour on context switch and logout.
- Next (F4): intake after a membership ends; cleanup of revoked devices; organization and plan state changes; a resilience test suite.
- Later: background upload scheduling tuned by measured battery and data use; conflict resolution assistants in the panel.
- Out of scope: real-time collaboration, merging of concurrent edits to the same field, peer-to-peer sync between devices.
| Entity | Owner | Content | Invariants |
|---|---|---|---|
| Operation | Organization (created by a member on a device) | Identifier, organization, membership, device, type and schema version, target entity and identifier, expected revision, declared time and zone, dependencies, attachment references, payload, payload digest | Immutable after creation. Organization never changes (BR-TEN-004). |
| Acknowledgement | Organization | Operation identifier, result, code, resulting revision, receipt time, review item | One per (organization, operation identifier). Kept as long as the record it produced. |
| Review item | Organization | Operation, reason code, context, state, resolution, resolver | Resolved exactly once. |
| Attachment upload | Organization | Attachment identifier, declared size and hash, received size and hash, state | Bytes accepted only for a declared attachment of an accepted or pending operation. |
| Reference snapshot | Organization (read copy on device) | Versioned copy of what the member may see: assets, assignments, missions, templates, categories, policies | Carries the server revision and the time it was confirmed. |
| Device queue | Device, partitioned by (account, API origin, organization) | Pending operations and attachment bytes | Another account on the same device can neither read nor send it. |
What is reused from the personal cloud protocol, and what differs:
| Aspect | Personal protocol v1 | Organization operations |
|---|---|---|
| Owner | One account | One organization; the actor is a membership on a device |
| Unit of work | A batch of record writes, atomic as a whole | Each operation is its own transaction; a batch is only transport. One conflicting record must not hold back the others recorded in the field. |
| Shape | Generic typed record with expected revision | Domain commands (trip.start, fueling.submit, expense.submit schema 1 (EDR-289), …) handled by the owning module |
| Replay | Same identifier and body returns the first result; changed body conflicts | Same |
| Conflict | Refuse with base, current and proposed | Field facts are kept for review instead of refused (BR-OFFL-006) |
| Consent mask and deletion epoch | Per-dataset opt-in by the account holder | Not applicable; activation is per organization, and personal-data rights follow 11-privacy-security |
| Acknowledgement retention | 30 days | As long as the resulting record, because the acknowledgement is part of the audit trail |
- BR-OFFL-001 — Local identifiers are final. Every record and operation gets a UUID on the device. The server never renumbers.
- BR-OFFL-002 — The queue is durable. An operation is written to persistent storage before the interface reports success. It survives process death, restart and app update.
- BR-OFFL-003 — Organization context is sealed. The organization, membership and device of an operation are fixed when it is created. No later action on the device rewrites them.
-
BR-OFFL-004 — Exactly one acknowledgement. The server stores one acknowledgement per (organization, operation identifier). An identical resend returns it. The same identifier with a different payload digest is refused with
OPERATION_ID_REUSED. - BR-OFFL-005 — Delivery is at least once; effects are once. The network may deliver an operation several times. BR-OFFL-004 makes the effect happen once. No component is described as delivering exactly once.
- BR-OFFL-006 — Facts are kept; authority is decided. A well-formed operation from a device that was legitimately enrolled is never discarded because of a business conflict. It is accepted, or accepted for review. Permanent refusal is reserved for: unauthenticated or unknown device, device revoked as lost or compromised, organization mismatch, malformed or unknown schema, identifier reuse, a declared time after the member's access ended, and a closed intake window (BR-OFFL-011).
-
BR-OFFL-007 — Order follows dependencies. An operation lists the operations it depends on. The server applies it only after those were accepted; otherwise it answers
RETRYwithDEPENDENCY_PENDING. A soft reference (for example a fueling pointing to a trip) to a refused or missing target is accepted for review with the link removed and the codeORPHAN_REFERENCE. -
BR-OFFL-008 — Two times, one authority. The device declares
occurred_at; the server setsreceived_at. Authorization uses server time and the server's own history of memberships, assignments, plans and locks (BR-TIME-003). - BR-OFFL-009 — Device time is evidence, not proof. When the right to perform an operation changed between the declared time and receipt, the operation is accepted for review even if the member was authorized at the declared time. It is never accepted automatically on the strength of the device clock.
- BR-OFFL-010 — Four visible states. Every record shows whether it is saved on the device, sent, accepted by the company or needs review (08-state-model §2). A refused operation stays visible with its reason until the user dismisses it.
-
BR-OFFL-011 — Intake after access ends. When a membership ends or is suspended, operations declared before that moment and received within the intake window (default 15 days, organization-configurable 0 to 60) are accepted for review with
ACCESS_ENDED_BEFORE_RECEIPT. Operations declared after that moment are refused withMEMBERSHIP_ENDED. After the window everything is refused withINTAKE_WINDOW_CLOSED. Intake-only access gives no reading right. - BR-OFFL-012 — Revocation reasons differ. A device revoked as lost or compromised is refused entirely from the moment of revocation. A device whose member was offboarded keeps intake-only access for the window of BR-OFFL-011.
- BR-OFFL-013 — No silent loss on the device. The app never deletes an unsent operation by itself: not on retry exhaustion, not on low storage, not on context switch, not on logout. It asks the user and says what will happen.
- BR-OFFL-014 — No remote-wipe promise. Revocation takes effect on the server at once. Local data of a disconnected device is erased only when the app next reaches the server or when its local access expires (BR-PRIV, 11-privacy-security). The interface and the documentation say so.
- BR-OFFL-015 — Attachments follow their operation. An operation can be accepted before its attachment bytes arrive. The record then shows the attachment as pending. Bytes are accepted only when size and SHA-256 match the declaration.
- BR-OFFL-016 — Reference data shows its age. Cached lists (assets, missions, policies) show when they were last confirmed. Choices made on stale reference data are checked on the server like any other.
- BR-OFFL-017 — Online-only actions say so. An action that needs the server (see §10) is disabled offline with the reason, never queued as if it had happened.
- BR-OFFL-018 — Limits. A batch carries at most 50 operations and 64 KiB, 8 KiB per operation, following the existing protocol bounds. Limits are configuration, verified by tests, and may be revised with measurements.
UC-OFFL-01 — Record offline and deliver later. Actor: member in enterprise mode. Preconditions: device enrolled; reference data cached. Flow: user records something → app validates locally → operation written to the queue → record shown as "Salvo no aparelho" → when a network is available the app sends operations in dependency order → server answers per operation → record shows "Aceito pela empresa". Alternatives: transient failure → stays saved, retried with backoff; server answers needs review → record shows "Precisa de revisão" with the reason; server refuses → "Não aceito" with the reason and the option to copy the data into a new record when that makes sense. Result: organization record created exactly once.
UC-OFFL-02 — Resend after a lost answer. Flow: the app sent a batch and the connection dropped before the answer → the app resends the same operations → the server returns the stored acknowledgements. Result: no duplicate record (BR-OFFL-004).
UC-OFFL-03 — Upload an attachment. Flow: operation declares an attachment (identifier, size, hash) → metadata operation is sent first → app requests an upload capability → sends bytes to the API ingress → server verifies size and hash and queues safety checks → document state becomes STORED. Alternatives: connection drops → the same upload is retried and is idempotent; hash mismatch → refused, app retries from the stored file; file missing on the device → record shows "comprovante não encontrado no aparelho" and asks for a new capture. Result: document linked to the operation.
UC-OFFL-04 — Resolve a review item. Actor: member with the permission of the record type (for example trip.trip.review for trip conflicts). Flow: open the review queue → see the operation, the reason and the context (declared time, receipt time, last successful sync) → choose accept, accept with a change (for example another asset) or refuse with a reason → server applies and audits → the author's device shows the outcome at next sync. Result: item resolved once.
UC-OFFL-05 — Switch context with pending operations. Flow: user switches from organization A to personal mode or to organization B → pending operations of A stay queued and keep being sent in the background while the session allows → the switcher shows a pending count per context. Result: no operation changes organization (BR-OFFL-003).
UC-OFFL-06 — Log out with pending operations. Flow: user asks to log out → app shows the pending count and offers "send now" (if online) or "keep on this device" → kept operations stay encrypted and bound to the account → at the next login of the same account they are sent. Alternatives: a different account logs in → it cannot see or send them; the device is reset or the app uninstalled → they are lost, and the logout dialog said so. Result: nothing is sent under another identity.
UC-OFFL-07 — Deliver after offboarding. Flow: a driver is offboarded while offline with three unsent fuelings → the driver's phone reconnects within the window → the app can still deliver, with intake-only access → the three fuelings are accepted for review → a manager decides each one. Alternative: reconnects after the window → refused with INTAKE_WINDOW_CLOSED; the app shows that the company must be contacted. Result: no automatic acceptance after access ended (BR-OFFL-009, 011).
UC-OFFL-08 — Refresh reference data. Flow: on opening enterprise mode and periodically, the app asks for changes since its revision → applies them → updates "confirmed at". Alternative: an asset the user is about to pick was reassigned → picker updates; if the user already started a trip with it offline, UC-OFFL-01 delivers it and the server puts it in review with ASSET_UNAVAILABLE.
Operation sync states: 08-state-model §2. Review item:
| From | To | Actor | Validation | Effect | Reversal |
|---|---|---|---|---|---|
| — | OPEN |
Server intake | A review reason applies | Record exists in a held form; excluded from costs and indicators | — |
OPEN |
RESOLVED_ACCEPTED |
Member with the record type's review permission | Not the author (BR-REV-003 applies to the resolver too) | Operation applied, possibly with the stated change; audit | Amend or void the resulting record (BR-AMD) |
OPEN |
RESOLVED_REFUSED |
Same | Reason required | Operation marked refused; device shows "Não aceito" | The author records again |
OPEN |
EXPIRED_UNRESOLVED |
Time (default 60 days) | — | Escalated to organization administrators; stays listed | Resolve late |
Attachment upload: DECLARED → UPLOADING → RECEIVED → STORED, or QUARANTINED / FAILED (document storage states in 08-state-model).
Sending operations needs the permission of the command itself (for example fuel.fueling.record). Resolving a review item needs the review permission of the record type (trip.trip.review, fuel.fueling.review, exp.expense.review, meter.reading.correct). Listing the review queue shows only items in the member's scope. Intake-only access after offboarding carries no permission other than delivering operations created before the end.
-
Concurrency on the server: intake serialises per target entity (row lock on the entity or its parent). Two devices starting a trip on the same asset: the first received is accepted; the second is accepted for review with
ASSET_BUSY(modules/trips). -
Edits: a change to a record already accepted is a new operation with the expected revision. A stale revision is accepted for review with
STALE_REVISIONand both versions shown, never overwritten by arrival order. - Corrections of refused operations: the device offers "create again from this" which copies the payload into a new operation with a new identifier.
- Retry policy on the device: exponential backoff with jitter, no attempt cap for transient errors, manual "send now". After repeated failures the record shows "needs attention".
- Storage pressure: the app warns when the queue or attachments exceed a threshold and never deletes unsent data by itself (BR-OFFL-013).
Produced: offl.operation.accepted, offl.operation.review, offl.operation.refused, offl.review.resolved, offl.attachment.stored. The logical needs-review event originally named offl.operation.needs_review is persisted as offl.operation.review (EDR-074), conforming to the existing audit/outbox SQL identifier vocabulary; the frozen ACCEPTED_FOR_REVIEW result and codes are unchanged. Consumed: idn.membership.ended, idn.device.revoked, org.organization.suspended, subs.subscription.state_changed. Notifications: the author is told when an item needs review, is resolved or is refused; reviewers are told when their queue has new items (digest, not one notification per item).
The components EnterpriseSyncOperation, EnterpriseSyncBatch and
EnterpriseSyncAcknowledgement in OpenAPI
freeze the wire structure. The pure Go orgsync/protocol and Kotlin
domain.enterprise.sync codecs enforce the lexical and semantic constraints
which JSON Schema cannot express. This source checkpoint installs no route,
intake ledger, delivery worker or business effect. Current source authority is
still mandatory when OFFL-002 admits an operation.
All fields are required, including explicit null revisions and result fields.
An operation carries schema_version, operation_id, owner_account_id, api_origin,
org_id, membership_id, enrollment_id, type, operation_schema, entity,
occurred_at, entry_zone, device_offset_seconds, depends_on, soft_references,
attachments, payload and payload_digest. enrollment_id names the organization
registration row; it is not a key ID or proof that a device is active. A type
has at least two lower snake_case segments, such as example.record. The
positive int64 operation_schema is structural; only version1 is supported now.
Payload business fields belong to the owning feature, not this transport.
Hash the complete immutable operation except payload_digest. Owner, exact API
origin, organization, member, enrollment, entity/revision, declared time/zone/
offset, dependencies, references, attachment metadata and payload are covered.
The digest is sha256: plus64 lowercase hexadecimal digits. Attachment hashes
are bare64-digit lowercase hexadecimal strings. Transient family/token,
signatures, batch attempts, clock samples and server receipt time are excluded.
Renewing delivery credentials preserves the captured operation bytes and digest.
A reused ID with changed immutable intent cannot become an identical replay.
The canonical JSON profile accepts null, booleans, well-formed Unicode strings,
arrays, objects and arbitrary-precision integer lexemes. It refuses fractions,
exponents, leading zeros, negative zero, duplicate decoded keys and invalid UTF-8
or surrogate escapes. Object keys must match
^[a-z][a-z0-9]*(_[a-z0-9]+)*$ and sort by ASCII. Ordinary arrays retain their
order. Dependency, soft-reference and attachment sets sort canonically and
refuse duplicate identities. Quote and backslash use two-character JSON escapes;
C0 controls use lowercase six-character Unicode escapes; other valid Unicode
is emitted without normalization or HTML escapes. This is not RFC8785/JCS.
Operation origins are exact canonical lowercase HTTPS origins, with ASCII DNS LDH labels or valid IP literals, no userinfo/path/query/fragment/IPv6 zone IDs. Ambiguous all-numeric hosts must be valid IPv4; DNS trailing dots and valid lowercase IPv6 spelling are preserved. Ports are1..65535 without zero padding; default443 is omitted. Configuration normalization happens before creation and cannot rewrite a queued operation. Neither codec performs a DNS lookup.
The transport wrapper has schema_version, family_id, access_token and operations. Credentials are untrimmed ASCII graphic strings of1..512 bytes. It may contain 0..50 raw operation candidates. Parsing the wrapper is not admission: preserve exact raw spans, then parse each operation against independently captured source binding. OFFL-002 must preflight trustworthy correlation identities and source bindings for the whole body before any intake budget, claim, receipt or effect. Every candidate uses the complete frozen operation parser, not a partial correlation parser. Broken envelopes, digests and source bindings refuse the whole body before prefix effects. Structurally valid unsupported operation schemas or malformed business payloads can be independent only after a real owning handler establishes current command/resource authority. Duplicate valid operation IDs are refused. Identity nonce consumption retains its independent authentication semantics. Signing must cover the exact transmitted body.
The signed intake response is EnterpriseSyncBatchResponse, an object with schema_version 1 and acknowledgements in request order (0..50). Each item is the complete canonical frozen EnterpriseSyncAcknowledgement; a replay retains its original bytes. This transport wrapper does not disclose account proof or add batch atomicity. Global source denial returns the safe error envelope instead of exposing buffered acknowledgement items.
Default limits are65536 raw UTF-8 batch bytes (including credentials),8192 raw and complete canonical bytes per operation and64 transport container levels (62 per operation, reserving the two wrappers). Trusted immutable limits may reduce these maxima, never widen them or be selected by a request; the operation byte limit cannot exceed the batch limit. Tests share literal byte-boundary fixtures across both languages.
Results echo operation_id and the attempted payload_digest. The public decoder requires the original immutable operation and checks both before exposing an outcome. ACCEPTED requires a positive revision and null code/review item. ACCEPTED_FOR_REVIEW requires a supported review code and review_item_id; its revision may be null. REJECTED requires a refusal code and null revision/ review item. All three are final and require a nonzero canonical server received_at. RETRY only permits DEPENDENCY_PENDING or UNAVAILABLE and has null revision, received_at and review_item_id. Finality is derived, never a wire flag. Warnings are a unique set, initially only CLOCK_SKEW; they do not rewrite device time. An OPERATION_ID_REUSED response correlates the attempted digest without replacing the first stored acknowledgement. Future reserved codes do not activate future membership/grace/plan policies. Hard dependencies wait for an actual accepted source effect or completed review, without rewriting the original ACK.
Shared literal vectors live in contracts/testdata/enterprise/sync. The task evidence records hashes, tests and remaining runtime work. The minimum OrgTime instant is valid declared evidence; it is forbidden as a final server receipt.
The table describes the owning integrations' target behavior, not blanket runtime authority. OFFL-002 requires a current signed account, source origin, membership and enrollment for the whole batch and inside every operation's transaction. Current unknown/revoked/ended/suspended proof remains a safe transport denial; F4 historical/grace outcomes require their actual historical authority and review producers. Missing type, history, held-fact/review, follow-up or explicitly configured transport budget returns UNAVAILABLE without a new claim. Unsupported operation schema is per-operation MALFORMED only after the owning installed type can authorize it. No generic FORBIDDEN result pretends to prove that a permission was never held.
Claims, final ACKs and applied-effect readiness are distinct. An authorized DEPENDENCY_PENDING claim has no final receipt/audit/effect. Review acceptance alone is not dependency readiness. Owning current parent-record read coverage is also required; a same-organization receipt/effect does not prove visibility. After base command/target admission, a coverage refusal rolls back this operation and returns the same DEPENDENCY_PENDING as a missing parent without a new claim. Covered cross-device dependencies remain valid (EDR-075). Each operation commits its real effect or held facts, audit, required follow-up and immutable final receipt atomically; replay rechecks original ownership and current read coverage. Fresh DB time and current source/feature authority are confirmed after transactional waits and before commit. A later source denial withholds the response without claiming that earlier committed operations rolled back. Declared time is evidence only: normal offline delivery delay cannot establish CLOCK_SKEW. See B-BR-EMP-108..114, BUC-EMP-56/57 and OFFL-002 evidence.
| Condition at receipt | Result | Code |
|---|---|---|
| Valid, authorized now, no conflict | ACCEPTED |
— |
| Identical resend | stored acknowledgement | — |
| Same identifier, different digest | REJECTED |
OPERATION_ID_REUSED |
| Unknown schema or malformed payload | REJECTED |
MALFORMED |
| Device unknown or revoked as lost | REJECTED |
DEVICE_REVOKED |
| Dependency not yet accepted | RETRY |
DEPENDENCY_PENDING |
| Soft reference to refused or missing target | ACCEPTED_FOR_REVIEW |
ORPHAN_REFERENCE |
| Membership ended or suspended; declared before; inside window | ACCEPTED_FOR_REVIEW |
ACCESS_ENDED_BEFORE_RECEIPT |
| Membership ended; declared after the end | REJECTED |
MEMBERSHIP_ENDED |
| Membership ended; window closed | REJECTED |
INTAKE_WINDOW_CLOSED |
| Permission removed between declared time and receipt | ACCEPTED_FOR_REVIEW |
PERMISSION_CHANGED |
| Never had the permission | REJECTED |
FORBIDDEN |
| Asset reserved, in maintenance, disposed or in another trip | ACCEPTED_FOR_REVIEW |
ASSET_UNAVAILABLE, ASSET_BUSY
|
| Trip already closed by someone else | ACCEPTED_FOR_REVIEW |
TRIP_ALREADY_CLOSED |
| Reporting day in a locked period | ACCEPTED_FOR_REVIEW |
PERIOD_LOCKED |
| Stale expected revision | ACCEPTED_FOR_REVIEW |
STALE_REVISION |
| Device clock skew above the limit | as otherwise decided, flagged | CLOCK_SKEW |
| Organization suspended; entity opened before suspension, or declared before it and inside the grace period (default 7 days) | ACCEPTED_FOR_REVIEW |
ORG_SUSPENDED_GRACE |
| Organization suspended; new entity declared after suspension | REJECTED |
ORG_SUSPENDED |
| Plan limit reached after a downgrade; declared before the change | ACCEPTED_FOR_REVIEW |
PLAN_CHANGED |
| Server or database unavailable | RETRY |
UNAVAILABLE |
A driver reading whose assignment changed between its declared instant and its receipt is held PERMISSION_CHANGED; one declared at or after the asset's disposal is held ASSET_UNAVAILABLE (B-BR-EMP-261, EMP-METER-002).
A fueling whose rights changed between its declared instant and its receipt, or declared at or after the asset's disposal, is not stored and stays RETRY/UNAVAILABLE until the held-fueling review owner exists (EMP-FUEL-002, EDR-177).
A device whose exact sealed period was revoked ACCESS_ENDED delivers it intake-only: from server history only (end instant, window in force at it, receipt), late operations are held ACCESS_ENDED_BEFORE_RECEIPT when their owner has a held path, else RETRY/UNAVAILABLE, or refused MEMBERSHIP_ENDED/DEVICE_REVOKED/INTAKE_WINDOW_CLOSED; a key revoked lost or compromised is refused as a whole (EMP-OFFL-009, EDR-197..199).
Before any owner, the organization's recorded suspension history holds work declared before a suspension and received inside its grace (ORG_SUSPENDED_GRACE), refuses later work (ORG_SUSPENDED), and keeps reviewing work declared during a resolved suspension; work declared before its capability was turned off is held PLAN_CHANGED (EMP-OFFL-012, EDR-200/201).
A mission response (trip.mission.respond, EMP-TRIP-008, EDR-229) is not a field fact: it is decided on current facts at receipt only (current assignee, current trip.trip.start coverage, current revision), never on the declared instant. Another member or an ended assignment is a whole-response FORBIDDEN, a mission not stored here NOT_FOUND, a stale or already answered mission CONFLICT (08-state-model §4.7), each a transport denial that stores nothing; it has no held form and no late holder. The Android device therefore sends each response in a batch of its own, after every other due operation, so such a denial never holds another record; a denied response stays saved and unconfirmed (EMP-TRIP-021, EDR-343).
Tracking (gps.session.start, resume, suspend, interrupt, reduce, end and gps.track.batch, EMP-GPS-004, EDR-277/278) needs no online validation: every refusal is final and per operation. The first start opens the trip's one session only under the organization's tracking policy with its employee notice in force (OFF is REJECTED FORBIDDEN); another member is a whole-request FORBIDDEN; any other domain refusal and a batch above 200 fixes are REJECTED MALFORMED; a trip or session not stored here is RETRY DEPENDENCY_PENDING. A session follows the trip's stored pauses, cancellation and finish (GPS-001 FOLLOW) before each session command; a batch stores one segment whose fixes outside the followed recording periods, while the trip is paused or at or after its finish or cancellation are counted on the segment, never in the receipt. Tracking owners have no held form and no late holder.
OFFL-003's construction contract extends the accepted generation-backed Android vault with a versioned typed queue, atomic operation/local projection and per-operation ACK/projection. Preserve legacy opaque entries unsent. Actual owning offline eligibility/projectors are mandatory; custody is not permission and the initial production registry is empty. A fresh exact account/origin/org/ member/enrollment/family/fence attempt governs I/O, without adopting a replacement selection or holding local locks across network. Preflight the entire strict batch answer before independent atomic receipt application. Topological local ordering does not infer server effect readiness; children of external/review parents remain retryable, while retained cycles require attention. Technical retry defaults are30-second base/6-hour capped equal jitter without an attempt limit, honoring valid Retry-After; pressure warns at80% of the existing32MiB/ 10000-entry storage bounds, with no eviction. Retain final receipts until an explicit policy exists. See B-BR-EMP-115..122, EDR-076..080 and queue evidence.
"Offline" means the action works with no connection and is delivered later. "Online" means it needs the server at that moment.
| Operation | Consult | Create | Change | Complete | Needs online validation for |
|---|---|---|---|---|---|
| Sign in, activate corporate access, accept invitation | — | Online | — | Online | Everything |
| Switch context | Offline (cached, marked unconfirmed) | — | — | — | Fresh membership list |
| My assets, assignments, missions | Offline (cached) | — | — | — | Latest assignments |
| Accept or decline a mission | Offline | Offline | — | Offline | Mission still assigned to me |
| Checklist | Offline | Offline | Offline until completed | Offline | Blocking policy is applied locally from cached policy and rechecked on the server The server stores its own outcome and flags a disagreement for review (EMP-CHECK-002, EDR-284). |
| Start trip | — | Offline | — | — | Asset availability; one active trip per asset |
| Logbook events, stops, pause, resume | Offline | Offline | Offline (new operation) | Offline | Trip not closed by someone else |
| Meter reading | Offline (own history cached) | Offline | Online (correction by authorized role) | — | Monotonicity against readings from other devices |
| Tracking | Offline (own trip) | Offline (recorded locally) | — | Offline | Nothing; batches are uploaded later |
| Navigation | Offline with downloaded map region | Offline | Offline | Offline | Nothing; live traffic is not offered |
| Finish trip | — | — | — | Offline | Final reading plausibility |
| Fueling | Offline (own) | Offline | Offline until approved | Offline (submit) | Capacity, duplicates, budget limits |
| Fueling with an agreement voucher | Online | Online | — | Online | Authorization validity and single use |
| Receipt capture and attachment | Offline | Offline | Offline (replace before sending) | Upload needs network | Hash, type and safety checks |
| Expense | Offline (own) | Offline | Offline until approved | Offline (submit) | Category active, limits, duplicates |
| Incident or damage report, maintenance request | Offline | Offline | Offline | Offline | — |
| Dispense from an internal tank | Offline (cached tank list) | Offline | — | Offline | Stock balance; negative balance goes to review |
| Budget hold or pre-authorization | Online | Online | Online | Online | Concurrent limit |
| Review result of my records | Offline (last known) | — | — | — | Latest decisions |
| Correct a returned record | Offline | — | Offline | Offline (resubmit) | Revision still current |
| Approve, return, reject | Online | — | — | Online | Everything |
| People, roles, assets, missions planning (panel) | Online | Online | Online | Online | Everything |
| Exports, reports, indicators | Online | Online | — | Online | Everything |
| Station portal, Data portal, plan and billing | Online | Online | Online | Online | Everything |
The reference feed (EMP-OFFL-006) is a signed per-member versioned delta of the member's assigned assets with durable tombstones, a server confirmation instant and RESET on lost authority (EDR-216..218). The app keeps it as one versioned cache sealed in the protected partition and shows its server confirmation (EMP-FLEET-013, EDR-224..226). Trips are recorded offline as signed trip.* operations whose sealed per-partition index commits with each operation (EMP-TRIP-005, EDR-242..245). Attachments are sealed beside their operation in the same partition and delivered after it: a signed session declares, links and grants the upload, the bytes go to the capability-bound ingress, and only a STORED answer verifies them (EMP-OFFL-005, EDR-267..270). Receipt originals come from the system camera or the photo picker, are judged by content, kept unmodified, shown with a legibility hint that never validates them, and sealed beside their record only after a protected write (EMP-DOC-004, EDR-291..293). Fuelings are recorded offline as signed fueling.submit operations read back from the partition's queue, and their optional receipt is sealed after them and linked to the stored fueling through the FUELING link kind (EMP-FUEL-011, EDR-294..297). The missions inbox is a sealed copy of the member's own list that always shows its age from the device receipt clock; refreshing it is online only; answers are signed trip.mission.respond operations, a planned trip starts only from a confirmed acceptance with the mission's soft reference, and pause, resume and cancel are the EMP-TRIP-011 operations (EMP-TRIP-021, EDR-342..344). A revoked partition is cleaned on next contact (EMP-OFFL-011, EDR-348..350): a whole-response 403/404 or a late-intake code only makes the worker ask the exact signed device contact; ERASE (lost or compromised) erases that partition alone and nothing of it is sent again; LOCK (access ended) locks it for every use except delivering its sealed unsent work intake-only, and erases it once every operation has a final answer or the server closed its intake window. Erasure persists its intent first and is resumed by maintenance; the app says "removed" only after verified disposal and never while disconnected.
The pending screen reads sanitized pages and full-partition totals from one trusted protected generation, including final review/refusal receipts. It also keeps accepted records with unconfirmed attachment delivery visible. History is a separate retained local view, not a claim of a complete business audit. No payload, original wire bytes, token or file bytes enters presentation.
The queue's inner V2 visibility flag may explicitly hide only a final refusal; V1 reads as visible. This local action preserves original operation/ACK bytes, projection, retry, files and history. It does not alter business state. Unknown or changed framing is unavailable, never repaired or deleted automatically.
No final ACK means saved on device. Actual matching ACKs establish acceptance, review or refusal; connectivity and HTTP attempts do not. A bounded scoped memory-only activity hint may show sending for the actual selected batch until durable receipt/retry processing ends. Manual checking respects all retained delay, including server Retry-After. Missing real owning actions stay absent. Declared time is not local save time, retry timer observations are not a full send log, and server received_at is not complete device synchronization. Attachment metadata acceptance never confirms its upload.
Keep list/detail in the existing selected-context owner, clear private state on withdrawal and recheck exact current source plus rendered epoch/generation around every operation. Offline protected reads require actual custody rather than a fresh online catalog selection. See B-BR-EMP-123..130, EDR-082..086 and status evidence for actual implementation/acceptance state; this contract is not a PASS claim.
| ID | Surface | Objective | Actor | Data | Actions | Rules and permissions | Validations and states |
|---|---|---|---|---|---|---|---|
| SCR-OFFL-01 | APP | See everything not yet accepted by the company | Any member | Pending operations grouped by state, with type, time, organization and reason | Send now, open record, dismiss a refused item | BR-OFFL-010, 013 | Empty: "Tudo enviado". Offline: banner with last successful sync. Error: per-item reason in plain language. States announced to screen readers as text, not colour only. |
| SCR-OFFL-02 | APP | Understand one record's sync history | Author | Timeline: saved, sent, accepted, review, outcome; attachment progress | Retry attachment, create again from a refused record | BR-OFFL-010, 015 | Attachment missing on device: asks for a new capture. |
| SCR-OFFL-03 | PANEL | Resolve what the server kept for review | Reviewers by record type | Queue with reason, declared and receipt times, last successful sync, author, record preview | Accept, accept with change, refuse with reason | BR-OFFL-006, 009; scope filtering | Empty: "Nenhum registro aguardando decisão". Forbidden: standard pattern. Conflict when two reviewers act: second sees "já resolvido". |
| SCR-OFFL-04 | APP | Decide what happens to pending data before logout or context removal | Any member | Count and size of pending operations | Send now, keep on device, cancel | BR-OFFL-013, 014 | Explains that uninstalling or resetting the device loses unsent data. |
| SCR-OFFL-05 | APP | Warn about storage or long-unsent data | Any member | Queue size, oldest unsent item | Open pending list, free space guidance | BR-OFFL-013 | Shown as a persistent banner in enterprise mode, not a blocking dialog. |
Acceptance criteria:
- Killing the app process right after the interface reports "Salvo no aparelho" loses nothing; the record is sent after restart.
- Sending the same batch three times produces one record and three identical acknowledgements.
- Operations delivered out of order converge to the same final state as in-order delivery.
- Switching context or logging out and in with another account never changes the organization or author of a pending operation, and the other account cannot see it.
- Every row of §10.2 is covered by a test with the stated result and code.
- A fueling recorded offline before offboarding and delivered inside the window appears in the review queue and is not counted in costs until a manager accepts it.
- A refused operation remains visible on the device with its reason until dismissed.
- An attachment interrupted at any byte is completed by retry and the stored file matches the declared hash.
Dependencies: 07-permissions (authorization at receipt), modules/identity (devices, membership history), 09-architecture (API conventions, storage), EMP-GOV-008 (device storage protection).
Risks: review queue becoming a dumping ground (mitigated by precise reason codes, digests and an escalation after 60 days); device clocks far from real time (BR-TIME-006); storage growth on devices with many photos (thresholds and Wi-Fi-only uploads); divergence between this queue and the existing per-feature queues on Android (one shared queue component is built for enterprise mode; personal features keep theirs).
Phase: F1 core, F2 reference data and review queue, F3 attachments, F4 hardening. Microtasks: EMP-OFFL-001 to EMP-OFFL-014.
- 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