# Documentation Data Schema

> **SCOPE:** This schema applies to `developer`, `database`, and `testing` doc types ONLY.
> For `user` type modules, generate standalone Mock UI TSX pages — see [templates.md](templates.md).

## Purpose

This file describes how to generate `doc-data.ts` files for the `DocRenderer` shared component.
Used for non-user doc types (`developer`, `database`, `testing`).

## DocData Interface Reference

The full TypeScript interface is in `web/smartstack-web/src/components/docs/types.ts`.

## Data Extraction Mapping

### Primary (and only) machine source — the extract-doc report

> The Studio-era `feature.json` (`/business-analyse` v4) **no longer exists** —
> the v5 BA lives as markdown under `.smartstack/ba/`. The doc pipeline never
> reads it directly: everything machine-extracted comes from the colocated
> `extract-doc` CLI (step-01), which reads the PROJECT CODE (source of truth)
> and enriches it with the committed core-seed state + the BA rbac.md through
> the `accessRoles` join.

| extract-doc report field | DocData field | Notes |
|--------------------------|---------------|-------|
| `apiEndpoints[]` (controller `[Http*]` + `[RequirePermission]` resolved against `Permissions.cs`) | `apiEndpoints[]` | method, path, handler, permission |
| `businessRules[]` (Domain `DomainException` guard clauses; tests fallback) | `businessRules[]` | curated, not dumped verbatim |
| `entity.name` / `entity.properties[]` | `technicalRef.entityNames` + realistic examples | |
| `accessRoles` (code permissions × core-seed state roles × rbac.md portée) | `permissions[]` | `{ path, description, roles[] }` — roles come ONLY from `accessRoles.rows` (never invented); when `accessRoles.source === 'none'`, author `permissions[]` without `roles` |
| `navRoute` | `technicalRef.permissionBase` / `controllerRoute` | |
| counts of the above | `overview.stats` | |

**Authored by you** (not extracted): `overview.objective` (a factual description
of what the module does), `features[]`, `steps[]`, `faq[]`, screenshots.

> `overview.problem` / `overview.solution`, `benefits[]` and `beforeAfter` are **no longer generated** — the doc leads with `objective` only (a factual description of what the module does), never a value-proposition pitch (SKILL.md rule #12). These fields remain optional in the `DocData` / `DocOverview` types for backward-compat, but the skill never authors them.

## Generated File Structure

### doc-data.ts (per module, ~50-80 lines)

```typescript
// web/smartstack-web/src/pages/docs/business/{app}/{module}/doc-data.ts
import type { DocData } from '@/components/docs';

export const docData: DocData = {
  featureId: 'FEAT-001',
  moduleName: 'Sla',
  applicationName: 'Support',
  version: '1.0',

  overview: {
    objective: 'docsSupportSla.overview.objective',
    stats: { useCases: 4, businessRules: 6, permissions: 5, endpoints: 5 },
  },

  useCases: [
    { id: 'UC-001', name: 'Create SLA', actor: 'Admin', description: '...', permission: 'support.sla.create', priority: 'Must' },
    // ...
  ],

  features: [
    { id: 'F-001', title: 'SLA Configuration', description: '...', example: '...' },
    // ...
  ],

  steps: [
    { number: 1, title: 'Navigate to SLA module', description: '...', screenshotKey: 'step1' },
    { number: 2, title: 'Create SLA policy', description: '...', screenshotKey: 'step2' },
    // ...
  ],

  faq: [
    { questionKey: 'docsSupportSla.faq.1.question', answerKey: 'docsSupportSla.faq.1.answer' },
    // ...
  ],

  businessRules: [
    { id: 'BR-001', name: 'SLA Time Calculation', category: 'Calculation', statement: '...' },
    // ...
  ],

  permissions: [
    { path: 'support.sla.read', description: 'View SLA policies', roles: ['Admin', 'Manager', 'User', 'ReadOnly'] },
    { path: 'support.sla.create', description: 'Create SLA policies', roles: ['Admin', 'Manager'] },
    // ...
  ],

  apiEndpoints: [
    { method: 'GET', path: '/api/support/sla', handler: 'GetAllSlaQuery', permission: '.read' },
    { method: 'POST', path: '/api/support/sla', handler: 'CreateSlaCommand', permission: '.create' },
    // ...
  ],

  screenshots: {
    step1: '/assets/docs/sla/step-1.png',
    step2: '/assets/docs/sla/step-2.png',
  },

  technicalRef: {
    permissionBase: 'support.sla',
    controllerRoute: 'support.sla',
    entityNames: ['Sla', 'SlaPolicy', 'SlaEscalation'],
  },
};
```

### Page wrapper (per module, ~10 lines)

```typescript
// web/smartstack-web/src/pages/docs/business/{app}/{module}/index.tsx
import { DocRenderer } from '@/components/docs';
import { docData } from './doc-data';

export default function {Module}DocPage() {
  return (
    <DocRenderer
      data={docData}
      backPath="/docs/business/{app}"
      backLabel="nav.backToApp"
    />
  );
}
```

### i18n file (FR source, ~30 lines)

```json
// web/smartstack-web/src/i18n/locales/fr/docs-support-sla.json
// NESTED under the namespace key for DocRenderer types (developer/database/testing) —
// because DocRenderer resolves keys as t('<namespace>.overview.objective').
// You author FLAT content; scaffold-doc wraps it under the namespace for these types.
// (user-type standalone docs stay FLAT — no root key, resolved via t('title').)
{
  "docsSupportSla": {
    "overview": {
      "objective": "Gestion des niveaux de service (SLA)"
    },
    "faq": {
      "1": {
        "question": "Dois-je configurer chaque SLA manuellement ?",
        "answer": "Non, des templates predefinis sont disponibles pour les cas courants."
      }
    }
  }
}
```

> **Note:** les 4 langues (FR source, EN/DE/IT) sont authorées et écrites par `scaffold-doc` (SKILL.md règle 6) ; `deferredLanguages` du manifest ne sert que lorsqu'une langue est volontairement différée.

## Screenshot Convention

| Key | Path | Description |
|-----|------|-------------|
| `step{N}` | `/assets/docs/{module}/step-{N}.png` | Step-by-step guide screenshots |
| `overview` | `/assets/docs/{module}/overview.png` | Module overview screenshot |
| `dashboard` | `/assets/docs/{module}/dashboard.png` | Dashboard view |

Screenshots are added manually or via Playwright E2E tests.
The `DocRenderer` shows a "Screenshot a venir" placeholder when the image file is not found.