# Compact Templates

> **Illustrative sample domain.** Endpoint paths, routes, roles, and entity names in
> the filled examples below are a SAMPLE domain for demonstrating the template shapes —
> substitute your project's own (auth wrapper, roles from `identity.audience_segments`,
> routes, entities). Only the template *structure* is normative.

Templates validated on 45 files across 3 compression waves. Each template includes: before/after, line count, critical notes.

## API Endpoint Template

### Standard (80% dei casi)

```markdown
### POST /api/v1/domain/resource

**Auth**: `<authWrapper>`  |  **Access**: `<ROLE_A>` + `<ROLE_B>`

**Body**:
| Field | Type | Required | Desc |
|-------|------|----------|------|
| storeId | string | yes | Store UUID |
| name | string | yes | Display name, 1-120 chars |

**Returns**: [ResourceResponse](./schemas.md#resourceresponse)
**Errors**: NAME_REQUIRED, STORE_NOT_FOUND ([errors.md](../errors.md#domain-domain))
```

**Dimensione**: 10-15 linee per endpoint. Target: 30+ endpoint = ~400 linee totali.

### Varianti

**GET con query params**:
```markdown
**Query**:
| Param | Type | Required | Desc |
|-------|------|----------|------|
| storeId | string | yes | FK Store |
| limit | number | no | Default 50, max 200 |
```

**Path params embedded**:
```markdown
### PATCH /api/v1/domain/resource/[resourceId]
```
Non serve tabella separata per path param (è nell'URL pattern).

**Public endpoint (no auth)**:
```markdown
**Auth**: public  |  **Access**: anonymous
```

**Cron endpoint**:
```markdown
**Auth**: cron secret  |  **Schedule**: daily 03:00 UTC
```

### Cosa NON includere

- ❌ JSON response inline (vai a schemas.md)
- ❌ Stringhe errore italiane hardcoded (usa error codes → errors.md)
- ❌ "Store Access Control" spiegato per ogni endpoint (vedi §Cross-reference)
- ❌ Esempi curl/fetch ridondanti (1 per dominio è sufficiente)

## PRD Template

### Struttura compatta

```markdown
---
doc_type: prd
domain: booking
canonicality: canonical-source
status: in_progress
last_updated: 2026-04-05
---

# PRD — Feature Name

## Context & Problem
[3-5 paragrafi focalizzati]

## User Stories
| ID | Story | Priority |
|----|-------|----------|
| MS-01 | As merchant I can... | P0 |

## Functional Requirements
| ID | Requirement | Component |
|----|-------------|-----------|
| FR-01 | System must... | booking-service |

## Acceptance Criteria
| ID | Given | When | Then |
|----|-------|------|------|
| AC-01 | ... | ... | ... |

## Data Model
[reference to schemas or inline if new]

## API Surface
[link a endpoint docs esistenti o nuovi]

## Edge Cases
| ID | Case | Handling |
|----|------|----------|
| EC-01 | ... | ... |
```

**Dimensione target**: max 1500 linee. Se supera, split in sub-PRD per capitolo.

### Cosa comprimere rispetto a PRD verbosi

- ASCII tree/box diagrams → tabelle o prosa compatta
- Code blocks TypeScript long-form → prosa descrittiva (preserva logica)
- Esempi JSON multipli → 1 esempio + schema reference
- "Discussion Log" 200 linee → key bullets per decisione
- Validation rules narrative → tabella | Field | Rule | Error code |

## UI Reference Template

### Pattern "Conventions block + Pages"

```markdown
---
doc_type: reference
domain: ui
canonicality: canonical-source
last_updated: 2026-04-05
---

# Merchant UI Reference

## Conventions (applies to all pages below)

- **Auth**: merchantUserId + MERCHANT role
- **Layout**: MerchantResponsiveLayout
- **Store switching**: CT-0067 multi-store support
- **Styling**: the project's design system (per `identity.design_philosophy`)
- **Hidden modules**: disabled via license gating

## License Gating System (FEAT-0128)

| Module | License tier | Gated route | Behavior |
|--------|--------------|-------------|----------|
| booking | Pro | /merchant/bookings/* | 302 → /merchant/dashboard |
| crm | Starter | /merchant/crm/* | 404 |

## Pages

### /merchant/bookings/planner

**Purpose**: Drag-drop table reservations
**Auth**: MERCHANT
**Key features**: [concise bullet list]
**Data sources**: GET /api/v1/merchant/booking/reservations
```

**Dimensione**: 15-25 linee per pagina. Target: 30 pagine = ~600 linee.

## Collections / Data Model Template

```markdown
## Collection: bookingRooms

Path: `merchants/{mid}/stores/{sid}/bookingRooms/{rid}`

**Fields**:
| Field | Type | Req | Notes |
|-------|------|-----|-------|
| name | string | yes | 1-80 chars, unique per store |
| capacity | number | yes | >0 |
| order | number | no | Display sort |

**Composite indexes**:
| Fields | Query |
|--------|-------|
| storeId + order | Sort rooms by display order |
```

Bullet lists SHORT se preferibile a tabelle per collezioni con pochi campi.

## Rules of thumb

1. **Prima scegli la struttura**, poi scrivi (outline first)
2. **Grep before write**: verifica se schema/error code/concept esiste già
3. **Test mentale**: se un lettore AI riesce a rispondere al 100% delle domande legittime con le info date, è completo
4. **Dense ≠ criptico**: comprimi verbosità, non chiarezza
