Example: Backend Service Specification

Scope shape: a merchant settlement service. Most risk sits in the interface contract, and two surfaces consume it. This example instantiates the surface section twice, so it reads as eight parts.

Values here are illustrative. Reuse the structure, not the names.

1. Requirement Overview

Background. Merchant payouts are currently computed by a nightly script whose output nobody can explain to a merchant. Support cannot answer "why is this amount lower than last week", and disputes are resolved by manual spreadsheet.

In scope. Daily settlement computation for completed orders, an auditable statement per merchant per day, an operations review and adjustment path, and merchant-facing statement visibility.

Out of scope. Payment execution, tax withholding, cross-currency conversion, and refund policy itself. Settlement consumes refund records; it does not decide them.

Roles. Merchant reads own statements. Operator reviews and adjusts. Finance Approver approves adjustments above a threshold. Service Consumer is another internal service calling the contract.

Glossary.

• Settlement Day: a closed 24-hour window in the merchant's configured timezone. Orders are assigned by completion time, not creation time.
• Statement: the immutable computed result for one merchant and one Settlement Day.
• Adjustment: a signed correction attached to an existing Statement. It never edits the Statement; it appends.
• Settled Amount: gross order value minus platform commission minus refunds minus the sum of applied Adjustments.

2. Data Model and Interface Contract

Table settlement_statement (new)

Column	Type	Null	Note
id	bigint	no	primary key
merchant_id	bigint	no	unique with settlement_day
settlement_day	date	no	merchant-local day
gross_amount	decimal(18,4)	no	minor-unit safe
commission_amount	decimal(18,4)	no	non-negative
refund_amount	decimal(18,4)	no	non-negative
settled_amount	decimal(18,4)	no	may be negative
status	varchar(16)	no	see StatementStatus
computed_at	timestamp	no	UTC
version	int	no	optimistic lock

Table settlement_adjustment (new)

Column	Type	Null	Note
id	bigint	no	primary key
statement_id	bigint	no	foreign key
amount	decimal(18,4)	no	signed, non-zero
reason_code	varchar(32)	no	see AdjustmentReason
operator_id	bigint	no	who requested
approver_id	bigint	yes	null until approved
state	varchar(16)	no	PENDING, APPROVED, REJECTED

Enumerations.

• StatementStatus: COMPUTING, READY, UNDER_REVIEW, CLOSED.
• AdjustmentReason: MISSING_ORDER, DUPLICATE_CHARGE, COMMISSION_ERROR, DISPUTE_RESOLUTION, OTHER. OTHER requires a free-text note.

RPC contract SettlementQueryService (internal, consumed by other services)

• getStatement(merchantId, settlementDay) -> StatementView
• listStatements(merchantId, dayRange, pageRequest) -> Page<StatementSummary>
• Read-only. Idempotent. No method mutates state.

REST endpoints (operations console and merchant app)

• GET /v1/settlements?merchantId&from&to&status -> paginated summaries.
• GET /v1/settlements/\{id\} -> full statement with applied adjustments.
• POST /v1/settlements/\{id\}/adjustments -> creates a PENDING adjustment. Requires an Idempotency-Key header.
• POST /v1/settlements/\{id\}/close -> transitions READY or UNDER_REVIEW to CLOSED.

Emitted events. SettlementReadyEvent, SettlementAdjustedEvent, SettlementClosedEvent. Each carries merchantId, settlementDay, statementId, settledAmount, and version. Consumers must tolerate redelivery and use version to discard stale payloads.

3a. Surface Specification: Operations Console

Skeleton. Statement list page -> statement detail page -> adjustment drawer.

Component granularity. The list owns filtering and pagination only. The detail page owns the amount breakdown and the adjustment history. The drawer owns adjustment entry and its own validation. The drawer never mutates the detail page's data directly; it reloads the statement on success.

State machine (statement detail).

READY -> UNDER_REVIEW when a PENDING adjustment exists. UNDER_REVIEW -> READY when all adjustments reach APPROVED or REJECTED. READY -> CLOSED on explicit close. CLOSED is terminal and read-only.

Actions. View breakdown (Operator, Finance Approver); request adjustment (Operator, disabled when CLOSED); approve or reject adjustment (Finance Approver only, and never the requesting operator); close statement (Finance Approver, disabled while any adjustment is PENDING).

3b. Surface Specification: Merchant Mini-Program

Skeleton. Statement history list -> statement detail. Read-only throughout.

Component granularity. Reuses the platform list and detail shells. The amount breakdown component is shared with the console but rendered in a merchant-facing label set.

State machine. Merchants observe two states only: Processing (maps to COMPUTING and UNDER_REVIEW) and Available (maps to READY and CLOSED). Internal review states are never exposed.

Interaction constraints. No adjustment entry. Pull-to-refresh re-fetches. A statement absent for a requested day renders an empty state, never an error.

4. Business Rules

• BR-01. A Settlement Day closes at 00:00 in the merchant's configured timezone; orders are assigned by completion timestamp.
• BR-02. Only orders in a terminal completed state enter a statement. In-flight orders roll into the next Settlement Day.
• BR-03. settled_amount equals gross minus commission minus refunds minus the sum of APPROVED adjustments. PENDING adjustments never affect it.
• BR-04. A refund is deducted from the Settlement Day in which the refund completed, not the day of the original order.
• BR-05. settled_amount may be negative. A negative statement carries to the next day as an opening balance and is never silently clamped to zero.
• BR-06. An adjustment whose absolute value exceeds the configured approval threshold requires a Finance Approver distinct from the requesting operator.
• BR-07. A CLOSED statement accepts no new adjustment. Corrections after close are made as a new adjustment on the current open statement.
• BR-08. Recomputation is idempotent for the same input set and must not change a CLOSED statement.
• BR-09. Adjustment creation is deduplicated by Idempotency-Key for 24 hours; a repeated key returns the original adjustment rather than a second one.
• BR-10. Every state transition writes an audit entry with actor, before state, after state, and reason code.

5. Exception Scenarios

• E-01. Merchant timezone unset. Console: "Merchant timezone is not configured." Mini-program: statement absent, empty state. Code SETTLEMENT_TZ_MISSING. Computation is skipped, not defaulted to UTC.
• E-02. Order data incomplete for the window. Statement stays COMPUTING past its deadline and raises an operational alert. Code SETTLEMENT_SOURCE_INCOMPLETE. A partial statement is never published.
• E-03. Adjustment amount zero. Console inline error "Amount must not be zero." Code ADJUSTMENT_AMOUNT_INVALID.
• E-04. Approver equals requester. Console: "An adjustment must be approved by a different person." Code ADJUSTMENT_SELF_APPROVAL.
• E-05. Adjustment on a CLOSED statement. Console: "This statement is closed. Raise the correction on the current period." Code STATEMENT_CLOSED.
• E-06. Close attempted with a PENDING adjustment. Console: "Resolve all pending adjustments before closing." Code STATEMENT_HAS_PENDING.
• E-07. Concurrent adjustment on the same statement loses the optimistic lock. Console re-reads and re-renders, then asks the operator to resubmit. Code STATEMENT_VERSION_CONFLICT.
• E-08. Repeated Idempotency-Key with a different payload. Code IDEMPOTENCY_KEY_REUSED; the request is rejected rather than merged.
• E-09. Consumer receives an out-of-order event. No user-visible message; the consumer discards payloads with a version lower than the one already applied.

6. Acceptance Criteria

Operator

• AC-01 (BR-03, normal). Given a READY statement with an APPROVED adjustment of -50.00, when the operator opens the detail page, then settled_amount reflects the deduction and the adjustment appears in history.
• AC-02 (BR-06, E-04, exception). Given an adjustment above the threshold, when the requesting operator tries to approve it, then approval is refused with ADJUSTMENT_SELF_APPROVAL and the adjustment stays PENDING.
• AC-03 (BR-07, E-05, exception). Given a CLOSED statement, when the operator opens the adjustment drawer, then the submit action is disabled and the closed-statement message is shown.
• AC-04 (BR-09, boundary). Given an adjustment request that timed out client-side, when the client retries with the same Idempotency-Key, then exactly one adjustment exists and the original is returned.

Finance Approver

• AC-05 (BR-06, normal). Given a PENDING adjustment above the threshold, when a different approver approves it, then the statement returns to READY and settled_amount is recomputed.
• AC-06 (BR-04, E-06, exception). Given a statement with one PENDING adjustment, when the approver attempts to close it, then close is refused with STATEMENT_HAS_PENDING.

Merchant

• AC-07 (BR-05, boundary). Given a Settlement Day whose refunds exceed gross value, when the merchant opens the statement, then a negative settled amount is displayed and the carry-forward note is visible.
• AC-08 (3b constraint, normal). Given a statement in UNDER_REVIEW, when the merchant opens the history list, then it renders as Processing and no internal review state or operator identity is exposed.

Service Consumer

• AC-09 (BR-08, boundary). Given a recomputation over an unchanged input set, when getStatement is called before and after, then both responses are byte-identical including version.
• AC-10 (E-09, exception). Given a redelivered SettlementAdjustedEvent with a stale version, when the consumer processes it, then the payload is discarded and no downstream write occurs.

7. Open Questions and Decision Record

Open.

• Approval threshold value and whether it varies by merchant tier. Owner: Finance. Blocks BR-06 rollout configuration, not its implementation.
• Retention period for CLOSED statements. Owner: Legal.

Decided.

• Adjustments append rather than edit the statement. Rejected in-place mutation because it destroys the audit trail that motivated this work.
• Negative settled amounts carry forward rather than clamp. Clamping was rejected because it hides the discrepancy the merchant is disputing.
• Merchants see two collapsed states. Exposing UNDER_REVIEW was rejected because it invites support contact about an internal process.