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

## Business Rules to Code Mapping

Derive from `analysis.businessRules[]` of **EACH module**.

Generate complete mapping for each BR:

```json
{
  "brToCodeMapping": [
    {
      "ruleId": "BR-VAL-001",
      "title": "Order total must equal sum of item prices",
      "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 analysis.businessRules[].id
- **title**: The rule statement
- **module**: Which module it belongs to
- **severity**: "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 analysis data, it MUST be carried into the PRD:

| Source (feature.json) | Target (PRD) |
|----------------------|--------------|
| `analysis.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 `/ralph-loop` receive the person extension configuration.

---

## API Endpoint Summary

> **ABSOLUTE RULE:** Copy **EXACTLY** from `specification.apiEndpoints[]`. **NEVER** reinvent routes.

```json
{
  "apiEndpointSummary": [
    {
      "operation": "ListOrders",
      "method": "GET",
      "route": "/api/orders",
      "linkedUC": "UC-001",
      "linkedFR": "FR-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",
      "linkedFR": "FR-002",
      "permissions": ["orders.create"],
      "requestSchema": { "type": "body", "schema": "CreateOrderDto" },
      "responseSchema": { "type": "OrderDto" },
      "errorCodes": [400, 401, 403, 422, 500],
      "module": "{moduleCode}"
    }
  ]
}
```

For each endpoint:
- **operation**: Use case name
- **method**: HTTP method (GET, POST, PUT, DELETE, PATCH)
- **route**: Full API path from specification
- **linkedUC/linkedFR**: Use case and feature requirement IDs
- **permissions**: Array of exact permission paths
- **requestSchema**: Input contract (query params or body)
- **responseSchema**: Output contract
- **errorCodes**: Expected HTTP error codes
- **module**: Which module
