vmall/docs/backend-guidelines.md

Backend Guidelines (vmall-api)

Normative layering lives in docs/tech-specs/rust-api.md and openspec/specs/api-architecture/spec.md. This file is the practical playbook with patterns proven by the existing modules.

Layering

src/modules/<ctx>/: handlers.rs (Axum extractors only) → service.rs (ApiResult<Dto>, no Json/StatusCode) → optional repo.rs (sqlx in &mut PgConnection / &mut Transaction). Simple CRUD may call repo from handlers. No generic Repository trait.

New domain checklist: migration → models.rs rows/enums → module (mod.rs/service.rs/handlers.rs) → register in modules/mod.rs → apps/api/tests/<ctx>.rs → shared contract → frontends.

Errors

ApiError envelope {"error":{"code","message"}}. NotFound 404, BadRequest 400, Forbidden 403, Conflict 409. Use unique_conflict(err, msg) to map unique violations to 409.

Concurrency and state machines (do not improvise)

-- status transition: condition on the expected prior state
UPDATE aftersales SET status = $1, updated_at = now()
 WHERE id = $2 AND status = ANY($3)          -- 0 rows → ApiError::Conflict

-- guarded decrement (stock): never SET col = col - n unconditionally
UPDATE skus SET stock = stock - $2 WHERE id = $1 AND stock >= $2

-- one-time flag (reply, reopen): guard on the empty state
UPDATE product_reviews SET reply = $2 WHERE id = $1 AND reply IS NULL

-- one-time review out of a pending state (wallet withdrawals, payouts)
UPDATE wallet_withdrawals SET status = $2, reviewed_by = $3, reviewed_at = now()
 WHERE id = $1 AND status = 'pending'          -- 0 rows → ApiError::Conflict

Idempotent generation guarded by a unique index (settlement statements): insert with ON CONFLICT (<cols>) DO NOTHING RETURNING id; a None result means a repeat or a racing request won, so re-read the existing row and return it unchanged instead of recomputing.

"At most one live row per owner" (merchant applications: one pending/approved per user) is a partial unique index — UNIQUE (user_id) WHERE status IN (...) — checked first in the service for a friendly 409 and relied on as the concurrency backstop via unique_conflict. Transactional provisioning (approval creating a shop + owner account) reads the row FOR UPDATE, provisions, then runs the guarded status flip last so any failure rolls the whole thing back.

Event side effects (membership growth, system messages) run inside the transition's transaction and are made idempotent by a partial unique index plus ON CONFLICT DO NOTHING, so a retried handler cannot double-write:

-- one message per customer, kind, and reference
INSERT INTO messages (...) VALUES (...)
ON CONFLICT (user_id, kind, reference_type, reference_id)
    WHERE reference_id IS NOT NULL DO NOTHING

A per-customer ledger total (growth) serializes on SELECT id FROM users WHERE id = $1 FOR UPDATE, then reads COALESCE(SUM(delta),0)::bigint and appends the entry carrying the new running total.

Multi-row FOR UPDATE must ORDER BY primary key. Ledger writes are append-only: change a balance only via account::service::credit/debit inside the caller's transaction, never by writing an absolute balance. A credit in a currency the customer never held: create the zero-balance row first (account::service::ensure_monetary_account).

Money and i18n

i64 minor units, BIGINT in SQL, number in TS. Currency conversion only via money::convert_minor(amount, from, to). User-facing text columns are JSONB {en, zh}; validate with the bilingual() pattern (both locales non-empty) or some_locale() (at least one — chat/message-style content).

Watch out: Postgres type traps

• SUM(bigint) returns NUMERIC — always COALESCE(SUM(x), 0)::bigint before decoding into i64. (Regression test: tests/aftersales.rs and tests/freight.rs cover this.)
• INSERT column count must equal value count; when a table grows, update every column-list constant (ORDER_COLS, ORDER_ITEM_COLS, …) and both INSERT lists. sqlx decodes at runtime, not compile time — cargo check green does not prove queries.

Testing

apps/api/tests/ with tests/common/mod.rs fixtures; the shared test DB is never truncated, so fixtures use unique slugs/emails and tests assert only on ids they created. spawn_state() initializes tracing (RUST_LOG works). Run cargo test -p vmall-api twice before archiving a change; list/discovery endpoints especially. Mind pipefail: cargo test | grep hides failures.

Adding a column to an existing table

1. Migration: ALTER TABLE … ADD COLUMN (append-only file, never edit old ones once applied anywhere).
2. Add the field to the model struct in models.rs.
3. Add the column to every SELECT/RETURNING list for that table.
4. Extend INSERT binds if writable.
5. Mirror in packages/shared/src/types.ts.

Nuance: a column that only one module writes and reads may stay out of the shared models.rs row when adding the field would force every existing SELECT/RETURNING list for that table to change. Example: orders.completed_at (settlement period attribution) is written by the order completion transition and read by modules/settlement/repo.rs; models::Order does not carry it. Also remember updated_at is not a completion timestamp — refunds bump it — so period attribution needs a dedicated column.