docs backend DOMAIN_MODEL

Domain model and business rules

Status: planned v1. Existing Android BR-001…028 retain their meanings. New backend rules use B-BR-*; use cases use BUC-* to avoid collisions. No subscription field is an input to trust.

Bounded contexts

• Directory — aggregate Station; entities StationIdentifier, LocationRevision; ports StationCatalog, StationResolver. CNPJ establishes business identity, UUID establishes platform identity. A rename is not a new station; CNPJ replacement requires explicit alias/merge review, never address-only automatic merging.
• Official — aggregate ImportRun and immutable OfficialPrice; SurveyWeek, SourceRevision; ports AnpSource, OfficialRepository, StationResolver. Imported values carry dataset checksum, row provenance and parser version. Only successful revisions are published.
• Identity — aggregate Contributor, entities ContributorKey, Challenge; ports IdentityRepository, SignatureVerifier. Anonymous means no traditional account, not untraceable or unique human.
• Community — aggregate PriceObservation, immutable votes and disputes; ObservationDecision append-only events, mutable current status projection; ports ObservationRepository, StationResolver, TrustReader, EvidenceReader, ConsensusRepository.
• Evidence — aggregate UploadSession, entity EvidenceObject; ports ObjectStore, MediaValidator. The database holds metadata only; private objects have bounded retention.
• Trust — aggregate ContributorTrust, immutable TrustDecision; port TrustReader. Reliability changes from independently reviewed outcomes, not payment or raw submission volume.
• Moderation — aggregate ModerationCase, append-only ModerationAction; ports to community/identity application commands. Reasons and actor are mandatory.
• Later boundaries only — Account linking, Subscription/Entitlement and Cloud Sync. No empty services, tables or speculative packages required now.

Value objects

StationId, ContributorId, ObservationId, EvidenceId: UUIDs generated via injected ID source at application boundaries. FuelPrice: positive integer amount_milli_brl (1/1000 BRL), currency=BRL, unit=L|M3|KG_13. Initial representable range 1…1,000,000 milli-BRL; regional/product plausibility is a risk signal, not this structural bound. No float for monetary arithmetic. Standard deviation/statistical source fields may use exact decimal storage independent of FuelPrice.

FuelProduct: ETHANOL, GASOLINE_REGULAR, GASOLINE_ADDITIVED, DIESEL_S500, DIESEL_S10, CNG, LPG_P13. Fixed product-unit compatibility: CNG→M3, LPG_P13→KG_13, others→L. Legacy GASOLINE_PREMIUM maps only through a named Android adapter; it does not assert premium gasoline.

Cnpj: normalized 14 ASCII characters, first 12 uppercase alphanumeric and final two digits, official check-digit algorithm. Normalize approved punctuation only; never discard arbitrary letters. Preserve numeric legacy values and leading zeroes. Invalid source values go to quarantine. Do not use CNPJ as an integer or a UUID substitute.

PriceCondition: STANDARD, CASH, DEBIT, CREDIT, APP, LOYALTY, OTHER; conditional prices carry qualifier_id when an app/program/other restriction distinguishes eligibility. STANDARD forbids qualifier. Unknown condition is not STANDARD; OTHER requires explanation and is excluded from generic cheapest-price ranking. Unresolved qualifiers are observation-only until moderation maps them.

Coordinates validates latitude/longitude bounds; GpsAccuracy is nonnegative metres. SurveyWeek uses local calendar dates, inclusive range ≤7 days. Server timestamps are UTC instants; device capture timestamp is an untrusted claim. Confidence=LOW/MEDIUM/HIGH; Availability=AVAILABLE/DISPUTED/UNKNOWN; Freshness=FRESH/AGING/STALE. Separate concepts avoid overloaded states.

Rules (GIVEN / WHEN / THEN)

• B-BR-001 Provenance: GIVEN official and community values, WHEN reading prices, THEN expose separate sources, dates, units and conditions; never fill a missing community field with official data.
• B-BR-002 Exact money: GIVEN an input amount, WHEN parsing, THEN reject floats/invalid range/product-unit mismatch, preserve exact milli-BRL and original ANP decimal text.
• B-BR-003 Append-only facts: GIVEN a persisted observation, WHEN correcting, THEN append a replacement with supersedes_observation_id; no price/location/evidence mutation of that fact. Personal-data deletion is governed by ADR-008, not blocked by this rule.
• B-BR-004 Attribution: GIVEN a signed write, WHEN authorizing, THEN derive contributor from the verified key, not a body-supplied ID; blocked/revoked keys cannot act.
• B-BR-005 Idempotency: GIVEN the same contributor and client submission ID, WHEN retrying, THEN return the same resource; a different payload conflicts. Request nonce and operation identity are different concepts.
• B-BR-006 Independent support: GIVEN a price key, WHEN counting support, THEN count at most one latest eligible vote per contributor in the window, no self-confirmation and no additional weight for multiple linked keys.
• B-BR-007 Deterministic consensus: GIVEN the same eligible facts, clock and policy version, WHEN rebuilding, THEN return the same result/explanation independent of input order.
• B-BR-008 Freshness: GIVEN an expired projection, WHEN serving or using cache, THEN expose STALE/UNKNOWN and exclude from current-price ranking, even if the worker is down.
• B-BR-009 Payment isolation: GIVEN identical facts/trust, WHEN entitlement changes, THEN confidence and ordering are unchanged.
• B-BR-010 Evidence ownership: GIVEN an evidence ID, WHEN attaching, THEN owner, ready/pending state and binding must match; a hash is not proof of ownership or location.
• B-BR-011 Privacy: GIVEN a public response/log, WHEN serializing, THEN no contributor identity, exact contributor GPS, IP, EXIF, private object key or signed URL is emitted.
• B-BR-012 Moderation: GIVEN a review action, WHEN changing eligibility, THEN append actor/reason/policy/event and enqueue recalculation atomically; do not edit raw price history.
• B-BR-013 ANP revisions: GIVEN identical source bytes, WHEN reimporting, THEN no duplicate revision; changed bytes create a new revision and preserve published history.
• B-BR-014 Unknown location: GIVEN an unverified station coordinate, WHEN validating proximity, THEN record UNKNOWN, never use a city centroid as a precise station position.
• B-BR-015 Quotas: GIVEN exhausted write/media quota, WHEN submitting, THEN reject before granting expensive work; no accepted command may be silently dropped.
• B-BR-016 Retention: GIVEN an expired personal-data record/object, WHEN cleanup runs, THEN purge its payload and record a minimal deletion outcome; replay after restore must not resurrect it.

Observation state and related processes

Observation content is immutable. A separate sequence of decision events derives its validation state:

stateDiagram-v2
    [*] --> RECEIVED
    RECEIVED --> VALIDATING: worker claims validation
    VALIDATING --> VALIDATED: admissibility checks pass
    VALIDATING --> REJECTED: permanent invalidity
    VALIDATED --> REJECTED: audited moderation invalidation

Loading

RECEIVED→VALIDATING requires a persisted command/job; actor worker; emits ValidationStarted. VALIDATING→VALIDATED requires station/product/ownership/admissibility checks; emits ObservationValidated and consensus job in one transaction. VALIDATING→REJECTED requires stable reason codes; emits ObservationRejected. VALIDATED→REJECTED requires a privileged reviewed case/reason; adds a revocation event and recomputes affected keys. REJECTED is terminal for that observation; appeal creates a new reviewed observation referencing it.

Worker retries/leases do not regress business state. Waiting for media/provider dependencies leaves VALIDATING with a processing reason; a missing-evidence timeout of 24 h rejects an explicitly photo-dependent submission. A deliberately metadata-only observation can validate with weaker evidence signals. No arbitrary state assignment in HTTP handlers.

Confirmation is a separate immutable vote; dispute is a separate OPEN→RESOLVED/REJECTED case. Neither pretends the original fact changed. Freshness is computed from receipt/eligibility policy; expiry does not rewrite historical observation state. Community projection may be AVAILABLE, DISPUTED or UNKNOWN and has its own version.

Domain events

StationRegistered, StationLocationRevised, OfficialRevisionPublished, ContributorRegistered, ContributorKeyRotated, PriceObserved, ValidationStarted, ObservationValidated, ObservationRejected, PriceConfirmed, ObservationDisputed, CommunityPriceChanged, ContributorTrustChanged, EvidenceVerified, EvidenceRejected, EvidenceDeleted, ModerationActionRecorded, PrivacyRequestCompleted.

Each carries event ID, aggregate ID/version, occurred_at, policy version where relevant and a minimal non-sensitive payload. Event DTOs are owned by the publishing module. No full photos/GPS in general event payloads. Application interfaces are allowed for synchronous queries; durable jobs handle required asynchronous effects.