Template — <unit>/requirements.md

# Requirements — <unit name>

**Confidence summary**: 🟢 N | 🔴 N

## Purpose

[One paragraph stating what this unit does in business terms, with citation. Plain language, no implementation details. If purpose isn't stated anywhere in source — README, module-level comment, in-repo doc — record a 🔴 in the Gaps section instead of writing a generic guess.]

## External interfaces

**HTTP / gRPC / WebSocket**:
- 🟢 `POST /api/orders` (public) — places a new order. Cite: `OrdersController.cs:42`. From external-surface.json.
- 🟢 `POST /internal/sync/orders` (private) — internal sync; covered transitively via @browser scenario "Submit order through UI".

**UI routes**:
- 🟢 `/orders/new` — order placement form. Cite: `pages/OrderForm.tsx:1`.

**CLI**:
- (none)

**Messages**:
- 🟢 `orders.created` (publisher) — emitted after successful order. Cite: `OrderService.cs:91`.

**Database (external dependency)**: only when database_ownership = external or mixed
- 🟢 `dbo.usp_CalculateInvoiceTotal` — invoked during order finalization. Cite: `InvoiceService.cs:142`.

## Functional Requirements

### FR-Local-1 — Place a new order
- **Description**: User submits a cart and receives an order ID.
- **Source**: `OrdersController.cs:42` 🟢
- **MoSCoW**: Must (called from `pages/OrderForm.tsx:88` and `pages/Cart.tsx:142` — central path per spec-impact-matrix)

### FR-Local-2 — Reject orders for inactive subscriptions
- **Description**: When the customer's subscription is not active, the order is rejected with a 403.
- **Source**: `OrdersService.cs:88` 🟢
- **MoSCoW**: Must

## Non-Functional Requirements

> **Generate this section only when source has a written non-functional contract** (SLO doc, OpenAPI x-rate-limit / x-timeout, README quantitative commitment, contract test asserting a quantitative bound). If none exists, **omit the section entirely** — do not invent NFRs from middleware presence, timeout configs, or rate-limiter usage. Those are observed behaviors and belong in `design.md` as observations.

(Example shown only when an `x-rate-limit` extension or equivalent written contract exists in source. If the only "evidence" is `appsettings.json:Timeout=800` or `Program.cs:UseAuthentication()`, that is **not** an NFR — those are observations and go in `design.md`.)

## Acceptance scenarios

### Public API (@api scenarios)

```gherkin
@api
Scenario: Place a new order with valid items
  Given a customer with an active subscription
  When they POST /api/orders with valid items
  Then the response is 201 with an order ID
  And an "orders.created" event is published

@api
Scenario: Reject order for inactive subscription
  Given a customer whose subscription is inactive
  When they POST /api/orders
  Then the response is 403
  And no "orders.created" event is published

@browser @api
Scenario: Submit order through the UI
  Given the customer is on /orders/new
  And they have an active subscription
  When they fill the cart and click "Place Order"
  Then they see "Order #N confirmed"

@database
Scenario: Order finalization invokes the legacy invoice procedure
  Given a finalized order with subtotal $100
  When the order completes
  Then dbo.usp_CalculateInvoiceTotal is invoked with @OrderId and @Subtotal
  And the result is persisted in invoices.total via the existing trigger chain

## Notes

- Local IDs (`FR-Local-1`) become `FR-NNN` global IDs only after `doc-this-promote` runs.
- "External interfaces" lists every surface the unit owns — pulled from `external-surface.json`.
- The **Realization map** is a derived projection (`external-surface.json` joined with `code-analysis.md` / `spec-impact-matrix.md`); it is where owned-DB table/column/proc, scheduler, and internal-orchestration detail lives so scenario steps stay externally observable. Author no fact not already cited upstream.
- **NFR section is omitted** when no written non-functional contract exists. The agent must not fabricate NFRs from middleware, timeouts, retry policies, or other observed behaviors.
- Every Gherkin scenario carries a 🟢 confidence with a citation, or it goes to `questions.md` as 🔴 — never 🟡.
- The reviewer rejects (does not downgrade) any output containing 🟡, judgment phrasing in any language, fabricated NFRs, or "should/recommend/propose" content.