# Handoff Mappings: BR-to-Code & API Summary

## Business Rules to Code Mapping

Derive from module `rules.json > rules[]` of **EACH module**.

Generate complete mapping for each BR:

```json
{
  "brToCodeMapping": [
    {
      "ruleId": "BR-VAL-001",
      "title": "Order total must equal sum of item prices",
      "statement": "The order total amount must equal the sum of all order item prices multiplied by their quantities",
      "example": "Order with 3 items at $10, $20, $30 → total must be $60. If total = $50 → validation error",
      "formula": null,
      "conditions": [],
      "entities": ["Order", "OrderItem"],
      "category": "validation",
      "sectionCode": "orders",
      "module": "{moduleCode}",
      "severity": "critical",
      "implementationPoints": [
        { "layer": "Domain", "component": "Order.cs", "method": "CalculateTotal()", "implementation": "Validate sum equals sum of OrderItems.Price" },
        { "layer": "Application", "component": "CreateOrderService.cs", "method": "Handle()", "implementation": "Calculate total before persisting" },
        { "layer": "API", "component": "OrdersController.cs", "method": "CreateOrder()", "implementation": "Return validation error if total mismatch" },
        { "layer": "Frontend", "component": "OrderForm.tsx", "method": "calculateTotal()", "implementation": "Real-time calculation on item change" }
      ]
    }
  ]
}
```

For each BR include:
- **ruleId**: Reference to `rules.json > rules[].id`
- **title**: Short descriptive title
- **statement**: VERBATIM copy of `rules.json > rules[].statement` — the full rule text, NOT a paraphrase
- **example**: VERBATIM copy of `rules.json > rules[].example` — concrete example illustrating the rule (null if absent)
- **formula**: VERBATIM copy of `rules.json > rules[].formula` — formula for BR-CALC-* rules (null if absent)
- **conditions**: VERBATIM copy of `rules.json > rules[].conditions[]` — conditions of applicability (empty array if absent)
- **entities**: Array of entity names this rule applies to (from `rules.json > rules[].entities[]` or inferred from rule context)
- **category**: Rule category from `rules.json > rules[].category` — one of: validation, calculation, workflow, security, data
- **sectionCode**: Section this rule belongs to (from `rules.json > rules[].sectionCode` or inferred)
- **module**: Which module it belongs to
- **severity**: From `rule.severity` (blocking, info, etc.) mapped to "critical", "high", "medium", "low"
- **implementationPoints**: Array of {layer, component, method, implementation}

Layers: Domain, Application, Infrastructure, API, Frontend

## Person Extension Mapping

When an entity has `personRoleConfig` in its entity data, it MUST be carried into the PRD:

| Source (entities.json) | Target (PRD) |
|------------------------|--------------|
| `entities[].personRoleConfig` | `modules[].entities[].personRoleConfig` |
| `personRoleConfig.userLinkMode` | Determines scaffold options: `isPersonRole: true, userLinkMode: "{mode}"` |
| `personRoleConfig.inheritedFields` | Fields to exclude from entity (mandatory) or mark as fallback (optional) |

The `personRoleConfig` object is passed through verbatim to ensure `/apex` and `/business-analyse-develop` receive the person extension configuration.

---

## API Endpoint Summary

> **Generated by step-01 from `usecases.json > useCases[]` + `entities.json > entities[]` + `permissions.json`.**
> BA does not produce apiEndpoints directly -- they are derived during transformation.

```json
{
  "apiEndpointSummary": [
    {
      "operation": "ListOrders",
      "method": "GET",
      "route": "/api/orders",
      "linkedUC": "UC-001",
      "permissions": ["orders.read"],
      "requestSchema": { "type": "query", "params": ["pageNumber", "pageSize", "status"] },
      "responseSchema": { "type": "PaginatedOrderDto[]" },
      "errorCodes": [401, 403, 400, 500],
      "module": "{moduleCode}"
    },
    {
      "operation": "CreateOrder",
      "method": "POST",
      "route": "/api/orders",
      "linkedUC": "UC-002",
      "permissions": ["orders.create"],
      "requestSchema": { "type": "body", "schema": "CreateOrderDto" },
      "responseSchema": { "type": "OrderDto" },
      "errorCodes": [400, 401, 403, 422, 500],
      "module": "{moduleCode}"
    }
  ]
}
```

For each endpoint:
- **operation**: Derived from use case name
- **method**: HTTP method (GET, POST, PUT, DELETE, PATCH)
- **route**: Generated from app/module path convention
- **linkedUC**: Use case ID from usecases.json
- **permissions**: Array of permission paths from permissions.json
- **requestSchema**: Input contract (query params or body)
- **responseSchema**: Output contract
- **errorCodes**: Expected HTTP error codes
- **module**: Which module
