docs product PREMIUM_PRODUCT_CONTRACT

Premium cloud and individual professional tools — proposed product contract

State: PLANNED / NOT IMPLEMENTED, 2026-10-13. Scope requested by the maintainer: one optional Premium offering containing cloud convenience and tools for an individual who uses a vehicle for work. Backend completion precedes a minimal Android UI using the existing design system; visual refinement is later. This planning request does not authorize implementation, charging, deployment or publication. The execution plan owns the microtasks; P11 remains the commercial parent.

Confirmed scope and proposed implementation decisions

Confirmed: automatic backup of vehicles/favorites/preferences, cross-device synchronization, assisted restoration, advanced configurable alerts, voluntary refueling/expense records, consumption and cost per kilometre, monthly reports, vehicle/period comparisons, backend first and minimal Android screens. Professional tools belong to Premium. Existing free features remain free; iOS is deferred.

The B-BR/BUC definitions below are proposed requirements to freeze in PRM00, not claims about current behavior. Price, trial, billing frequency, paid retention, grace duration, device/storage quotas and provider credentials have not been supplied. PRM00 records decisions and measurable limits before dependent code. Build the complete requested scope; demand validation informs packaging and release, rather than silently discarding requested capabilities.

Excluded: employees, shared fleet access, business tenants, payroll, earnings/profit accounting, tax/invoice services, bank integrations, automatic movement tracking, receipt OCR, permanent receipt photos, merchant tooling, API resale and a new public community ranking. Several vehicles owned by one person do not create a fleet product. Keep the existing three-vehicle allowance; selling extra vehicle slots requires a separate product decision.

Free guarantees and lifecycle

• B-BR-PR01 — Free foundation: existing anonymous reads, contribution rules, free signup/recovery, comments/votes, ANP history, offline reading, navigation, three local vehicles, tank estimates and basic alerts remain available. Public trust/consensus/moderation never read a paid entitlement. Do not reclassify existing analysis or notification features as Premium.
• B-BR-PR02 — Server authority: hosted Premium operations require a live authenticated account and server-verified capability. Purchase token, provider account binding, package/product/environment and lifecycle are checked server-side. A client flag, screenshot or notification is insufficient. Restoring a store purchase does not bypass free account proof or transfer another person's records/reputation.
• B-BR-PR03 — Explicit lifecycle: pending purchase gives no benefit; cancellation of renewal preserves access only through the verified paid-through time; refund/revocation, hold, grace, pause and expiry follow the frozen provider mapping. Unknown provider state cannot extend cloud rights indefinitely. Separate cancellation of renewal, actual expiry, provider outage and account deletion in API/UI.
• B-BR-PR04 — Safe expiry: stop new hosted paid writes, automatic backups, sync uploads and advanced alert evaluation when access ends. Existing local records, local free tools and downloaded reports remain readable. Free authenticated export/deletion and a bounded cloud exit download remain available under the published retention policy. New professional entries/report generation are paid capabilities; reading, exporting, deleting and correcting already-held local records are not held hostage. Corrections cannot silently upload after expiry. Do not erase local data on a billing event. Warn before cloud expiry/purge, permit cancellation of queued work, and do not promise indefinite storage. Exact grace/exit/retention intervals must be frozen before schema/jobs.
• B-BR-PR05 — Offline boundaries: define a short, versioned offline capability lease for new local paid work, bounded by last verified validity and a frozen maximum; wall-clock rollback never grants unlimited access. Reading/export/deletion of existing local data is independent of this lease. Cloud mutations always recheck live entitlement. Locally queued changes survive outage/lapse; after reactivation, resume only with current owner, consent and conflict checks. Show local-only/pending/synced states honestly.

Cloud data contract

• B-BR-PR06 — Owned datasets: allowlisted structured vehicles, favorite station UUIDs, chosen portable preferences, advanced alert rules and new professional records belong to one account. No generic Room/database replication. Exclude session/refresh tokens, private signing keys, purchase tokens, OS permissions, installation identifiers, precise GPS, operational/training photos and public ANP/community caches. A selected city is a preference, not location tracking. Unknown station references display unavailable; never recreate a station or community observation from a backup.
• B-BR-PR07 — Opt-in and device scope: cloud activation and automatic backup are explicit; device-local Wi-Fi/battery/permission settings stay device-local. Sync only documented portable fields; downloaded notification rules still require this device's permission. Account/origin changes cancel old work and isolate caches, cursors, notification tokens and encryption aliases. Never merge guest local data into a signed-in account without a preview and explicit choice. A second login provider linked by existing free proof is the same account; another account is not.
• B-BR-PR08 — Versioned commands: stable resource IDs, operation IDs, expected revisions and account deletion epoch; exact replay returns the original result and changed-payload reuse conflicts. Bound request/batch/page sizes and transaction duration. Use server revisions rather than client clocks as write authority. Expose per-command accepted/conflict/refused status; no partial success labelled as complete success.
• B-BR-PR09 — Conflicts and tombstones: concurrent incompatible edits return a recoverable conflict with private base/current/proposed versions. An explicit resolution is a new conditional command. Document which independent fields/set operations may merge; do not overwrite an entire record by arrival time. Deletion wins over stale edits; compacted/expired cursors force a safe resnapshot with local pending changes preserved. Device/order/retry cannot resurrect erased data. Vehicle removal archives dependencies or requires an explicit cascade preview; never silently orphan/delete refuel history.
• B-BR-PR10 — Backup is a snapshot: automatic server snapshots cover only acknowledged cloud revisions; pending device edits are explicitly excluded until sync. Record consistent revision, schema, datasets, checksums, counts and creation time. Apply private storage, encryption/key management, bounded quota/retention and inventory-before-object receipts using existing platform patterns. Never market snapshots as end-to-end encrypted unless that separate design is actually implemented. Snapshot/job completion requires verified durable bytes and metadata; restart/duplicate/failed writes are recoverable.
• B-BR-PR11 — Assisted restore: after free account recovery, list own snapshots and preview counts, conflicts, incompatibilities and exclusions before confirmation. Stage and validate data; check current owner, deletion epoch, retention, schema and limits at commit. Restore is idempotent and cancellable before commit. Preserve a recoverable pre-restore state and report partial/failed outcomes. Restoring private application data cannot restore credentials, revoked rights, expired photos or deleted records. No destructive automatic replacement of current Room data.
• B-BR-PR12 — Privacy survives backup: export/deletion are free, owner-only, bounded and cover ledger, rules, devices, objects, derived reports and snapshot inventory. Existing infrastructure backup recovery must replay a deletion ledger outside the recovered dataset before serving traffic. Per-record erasure also prevents old snapshots/offline clients from reintroducing erased material. Define physical purge deadlines and prove object/metadata deletion through retries and restored backups; retention of irreversibly retained financial metadata needs a documented purpose and minimal fields. Treat record deletion as distinct from subscription cancellation.

Professional records and exact calculations

• B-BR-PR13 — Voluntary private ledger: refuel record: stable ID, owner/vehicle, event instant plus entry timezone, fuel/unit, measured quantity, actual total paid, optional stated unit price, optional odometer, full/partial/unknown fill marker, optional station UUID and bounded note. Expense record: stable ID, owner/vehicle, event/timezone, actual amount, frozen category and bounded note; optional odometer. Station association is optional. No compulsory GPS, photograph, public post or employer data. User-entered paid price is private and never becomes a community price automatically.
• B-BR-PR14 — Exact values: store BRL totals in integer centavos; quantities in integer milli-litres or milli-cubic-metres; odometer in integer metres, displayed as km. Reuse existing integer milli-BRL unit-price vocabulary where suitable. Keep actual total authoritative; stated unit-price/quantity multiplication can differ through documented rounding and discount. Flag inconsistency for correction without silently rewriting the receipt total. Use checked integer/rational operations, maximum input bounds and one frozen display-rounding rule shared by Go/Kotlin golden vectors. Reject invalid currency, sign, unit, overflow, NaN and duplicate commands. Never sum L with m³ or average per-record ratios unweighted.
• B-BR-PR15 — History integrity: backdated edits/deletes invalidate dependent intervals/report revisions atomically. Monotonic odometer is enforced within a declared vehicle odometer segment; replacement/reset opens an explicit segment with an UNKNOWN boundary, rather than rejecting the entire history or inventing travel. Permit incomplete input, but explain which derived results are unavailable. Edits need expected revisions and preserve bounded change provenance without retaining erased free text. Exclude voided records from calculations; distinguish a correction from an additional expense.
• B-BR-PR16 — Consumption: for a supported fuel/unit/method, use consecutive confirmed full-tank anchors in the same vehicle/odometer segment: distance is ending minus starting odometer; quantity is the sum of fills after the starting anchor through the ending anchor, including intervening partial fills. Starting fill establishes the baseline and is excluded from that sum. Require positive distance/quantity and explicit absence of a known missing-fill gap. Partial-only sequences, unknown full markers, missing odometers and unsupported mixed-fuel/GNV methodology yield UNKNOWN with reason; purchases/tank capacity are not measured consumption. Record possible user omissions as a limitation even when computable. Freeze supported GNV/flex policies before implementation; ledger entry remains supported even when efficiency is unavailable.
• B-BR-PR17 — Cost per kilometre: separate fuel purchases per km over a complete fill interval from recorded vehicle expenses per km over a matched observation window. The first uses actual paid totals for the same fills as PR16, divided by eligible distance; label it a purchase-based estimate, not exact inventory/energy consumption cost. The second uses explicit odometer endpoints and included expenses for exactly the same documented window. Monthly expenses divided by partial-month kilometres is invalid. When month endpoints are missing, show month totals plus a separately labelled observed-window metric, or UNKNOWN. Never add refuel cost twice to an all-expenses total. No price lookup, estimated tank fill, route distance or background GPS substitutes for actual records.
• B-BR-PR18 — Reports: monthly BRL purchase/expense totals and category/vehicle breakdowns use event instants in the chosen IANA report timezone, half-open calendar-month bounds and explicit inclusion rules. Show data revision, generation time, scope, omitted/incomplete records and eligible distance/consumption coverage. Use weighted ratios of eligible totals, not averages of vehicle averages. No income collection in this scope; expenses do not establish profit, tax deductions or guaranteed savings. A correction regenerates a new report revision; prior cached output is visibly stale.
• B-BR-PR19 — Comparisons: compare selected vehicles or periods with the same currency, unit, calculation version and metric definition; show different distance/coverage and normalize costs only when denominators are valid. Relative variation needs a nonzero valid baseline. Mixed/unsupported/no-data cases remain labelled, not ranked as cheapest. Existing ANP price-history comparison remains free and separate. Include acquisition-based metric limitations and no claim that choosing a cheaper station produced measured savings.
• B-BR-PR20 — Reporting and exit: provide a paginated report API and downloadable CSV as the first deliverable; formatted PDF is later refinement. New report/comparison generation is Premium, while personal-data export includes raw records and held calculation metadata free of charge. Export uses safe CSV escaping/formula-injection defenses, private bounded downloads and expiry. No mandatory emailed reports or attachments to third parties.

Advanced alerts

• B-BR-PR21 — Bounded rule vocabulary: user selects station favorites or city, exact fuel/unit/condition, price threshold and/or change condition, days, preferred delivery window, IANA timezone, quiet hours and cooldown. Support a small explicit AND/OR combination of frozen predicates; no arbitrary scripts, SQL or unbounded nested expression language. Preserve basic local weekly drop alerts and free following/activity entitlements. Define source-specific comparison baselines; never mix ANP weekly reference with community current price or unconditional with loyalty prices.
• B-BR-PR22 — Truth and scheduling: recheck price validity, source/condition, subscription, rule revision and permissions at evaluation and dispatch. Expired/disputed/unknown data does not produce a cheap-price assertion. Windows crossing midnight, timezone changes and daylight-saving folds/gaps have deterministic documented behavior. Preferred times are delivery windows, not guaranteed exact alarms or guaranteed prices. Expired delayed candidates are dropped; a retry cannot send an old offer as current.
• B-BR-PR23 — Delivery and revocation: transactional candidate/inbox plus existing bounded job queue; dedupe by owner/rule revision/source event/window and documented device delivery policy. Provider/device acknowledgements have distinct meanings; sending is not proof of viewing. Bound retries, backlog, TTL and per-account/device rates. Unfollow, disable, expiry, logout, revoke or deletion stops future dispatch and stale-token reuse. Push payloads omit private expense/location details; app opening requires current account authorization. Server inbox is authoritative if push is delayed/unavailable. Provider selection requires dependency/privacy/cost review; no new broker/microservice.

Minimal Android contract

• B-BR-PR24 — Functional UI: entry under existing Perfil hub; reuse AnpScaffold, AnpTopAppBar, MaterialTheme, existing fields/dialogs/icons and strings/locales. Minimum screens: Premium status/manage/restore purchase; cloud/device status and opt-in; snapshot list/restore preview; vehicle ledger/list/add/edit; monthly report; vehicle/period comparison; advanced-rule list/editor; conflict resolution and free export/deletion actions. Simple text summaries/lists suffice; no redesign, custom chart system or web dashboard.
• B-BR-PR25 — Local reliability: Room transactions, account/origin-scoped queues and WorkManager persist drafts, stable commands and cursors through process death. No financial/network work on the main thread. Handle guest, loading, empty, local-only, pending, conflict, rejected, expired, offline, permission-denied and provider-outage states. Every essential action is reachable with TalkBack/large font and Portuguese money/date formatting. A backend success has to be acknowledged before the UI says synced/restored/active.

Use cases

• BUC-PR01: free account → verified purchase → capabilities → renewal/cancel/expiry → retain data and free exit; restore purchase after account proof.
• BUC-PR02: choose cloud datasets → preview guest/local import → enable → two-device concurrent edits → conflict resolution → revoke device.
• BUC-PR03: acknowledged data → automatic snapshot → recovery/login on another device → preview/confirm restore → recover from interrupted commit.
• BUC-PR04: choose existing vehicle → enter full/partial refuel or expense → offline save/retry → correct/delete → update affected intervals.
• BUC-PR05: complete/incomplete ledger → consumption/cost explanation → monthly report → comparable vehicles/periods → CSV export.
• BUC-PR06: create rule/combined conditions and delivery window → fresh eligible event → inbox/push → disable/unfollow/lapse prevents future delivery.
• BUC-PR07: lapse/logout/account switch → preserve private local records in the correct owner partition → free export/delete → purge/recovery cannot resurrect data.

Decisions to freeze in PRM00

• D-PR01: one Premium capability bundle; public name, products/prices/billing period/trial remain owner decisions before listing/charging. Proposed capabilities: cloud.sync, cloud.backup, cloud.restore, alerts.advanced, professional.write, professional.report; free exit operations are outside paid checks.
• D-PR02: provider lifecycle mapping, maximum stale/offline lease, grace, cloud exit access, snapshot/object/financial-metadata retention and notice deadlines. Freeze exact values with cost/privacy/provider evidence; no invented lifetime storage promise.
• D-PR03: dataset/record/device/page/storage/rule/job limits, snapshot cadence, backup key recovery and reconciliation budgets, supported Android/OS/provider scope. Limits must fit measured infrastructure and preserve the free allowance.
• D-PR04: exact refuel precision, rounding, actual-total discrepancy handling, supported liquid/GNV/flex full-to-full methods, missing-fill declaration, odometer segments, report timezone and matched-window comparisons. Attach synthetic worked examples and expected results.
• D-PR05: portable preference allowlist, initial local import policy, cursor/tombstone lifetime, restore merge semantics and alert predicate/device delivery policy. Resolve ownership/deletion before UI or generic sync code.

References and source evidence

Inspected source baseline: a3e01aac7f3bf1503b478d9010e7f263d2d4af93 in an isolated worktree from maintained dev; active primary-checkout changes were preserved. Existing Vehicle, UserPreferences, basic alert evaluation and Perfil are reuse targets. Backend account/privacy/jobs/storage mechanisms exist; no subscription, cloudsync or professional ledger module was found at opening. This is source inspection, not runtime/provider certification.

Primary provider references checked 2026-10-13; recheck at implementation and release:

• Google Play purchase security: server verification/account binding/acknowledgement and token replay handling.
• Subscription lifecycle: provider states and replacement/renewal/revocation reconciliation.
• Payments policy: digital services and applicable billing rules; no assumption that a site link permits bypass.
• WorkManager work requests: persistent constrained execution; no exact-clock delivery promise.
• FCM Android delivery: push delivery has failure cases; inbox/reconciliation remains necessary if FCM is selected.

Follow free/hosted boundaries, product contract, test strategy and delivery policy. No MIT/package changes, real customer data or credentials belong to this plan.