# 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

### From feature.json (single source of truth)

The business analysis skill (`/business-analyse`) produces a `feature.json` file per module at:
`docs/business/{app}/{module}/business-analyse/v{X.Y}/feature.json`

All documentation data is extracted from this file.

#### Specification section → DocData fields

| feature.json Path | DocData Field | Extraction |
|-------------------|---------------|------------|
| `specification.useCases[]` | `useCases[]` | UC-XXX entries (id, name, actor, description, permission, priority) |
| `specification.functionalRequirements[]` | `features[]` | FR-XXX entries grouped as features |
| `specification.permissionsMatrix` | `permissions[]` | Role-permission entries |
| `specification.apiEndpoints[]` | `apiEndpoints[]` | Endpoint entries (method, path, handler, permission) |
| `specification.wireframes[]` | `steps[]` | Inferred from wireframe descriptions |
| `specification.gherkinScenarios` | (used for test data, not doc) | - |

#### Analysis section → DocData fields

| feature.json Path | DocData Field | Extraction |
|-------------------|---------------|------------|
| `analysis.businessRules[]` | `businessRules[]` | BR-XXX entries (id, name, category, statement) |
| `analysis.objectives[]` | `overview.stats` | Count objectives |
| `analysis.entities[]` | `technicalRef.entityNames` | Entity names from analysis |
| `analysis.integrations[]` | `technicalRef` | Integration notes |

#### Discovery section → DocData fields

| feature.json Path | DocData Field | Extraction |
|-------------------|---------------|------------|
| `discovery.problem` | `overview.problem` | Problem statement |
| `discovery.scope.inScope` | `overview.objective` | Functional objective text |
| `discovery.scope.outOfScope` | `overview.solution` | Solution statement (inferred) |
| `discovery.risks[]` | (optional) | Risk documentation |

#### Handoff section → DocData fields

| feature.json Path | DocData Field | Extraction |
|-------------------|---------------|------------|
| `handoff.filesToCreate.domain` | `technicalRef.entityNames` | Entity names |
| `handoff.apiEndpointSummary[]` | `apiEndpoints[]` | Endpoint entries (cross-validate) |
| `handoff.brToCodeMapping[]` | `technicalRef` | BR-to-code mapping |

### Generated/Inferred Fields

| Field | Source |
|-------|--------|
| `featureId` | `metadata.featureId` from feature.json |
| `moduleName` | `metadata.moduleName` from feature.json |
| `applicationName` | `metadata.applicationName` from feature.json |
| `version` | `metadata.version` from feature.json |
| `benefits[]` | Inferred from analysis objectives or i18n |
| `beforeAfter` | Inferred from discovery problem/solution |
| `steps[]` | Inferred from use cases main scenario |
| `faq[]` | Inferred from discovery open questions |
| `screenshots` | Convention: `/assets/docs/{module}/step-{N}.png` |

## Fallback: No feature.json Available

If no feature.json exists (e.g., module was created without `/business-analyse`),
the `/documentation` skill extracts data directly from code:

| Source | DocData Field | Extraction |
|--------|---------------|------------|
| Controller `[Http*]` attributes | `apiEndpoints[]` | Method, path, permission |
| `Permissions.cs` constants | `permissions[]` | Permission paths |
| `Domain/Entities/*.cs` | `technicalRef.entityNames` | Entity class names |
| i18n JSON files | `overview`, `features` | Existing translations |

## 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: 'docs.support.sla.overview.objective',
    problem: 'docs.support.sla.overview.problem',
    solution: 'docs.support.sla.overview.solution',
    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' },
    // ...
  ],

  benefits: [
    { icon: 'time', titleKey: 'docs.support.sla.benefits.time.title', value: '-70%', descriptionKey: 'docs.support.sla.benefits.time.description' },
    { icon: 'quality', titleKey: 'docs.support.sla.benefits.quality.title', value: '+95%', descriptionKey: 'docs.support.sla.benefits.quality.description' },
    { icon: 'roi', titleKey: 'docs.support.sla.benefits.roi.title', value: '3x', descriptionKey: 'docs.support.sla.benefits.roi.description' },
  ],

  beforeAfter: {
    beforeItems: ['Manual SLA tracking', 'No escalation alerts', 'No compliance visibility', 'Scattered data'],
    afterItems: ['Automated SLA monitoring', 'Real-time escalation', 'Compliance dashboard', 'Centralized metrics'],
  },

  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: 'docs.support.sla.faq.1.question', answerKey: 'docs.support.sla.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-{app}-{module}.json
{
  "support": {
    "sla": {
      "overview": {
        "objective": "Gestion des niveaux de service (SLA)",
        "problem": "Les engagements de service ne sont pas suivis, les escalades sont manuelles",
        "solution": "Monitoring automatique des SLA avec alertes et escalades configurables"
      },
      "benefits": {
        "time": { "title": "Temps economise", "description": "Reduction de 70% du temps de suivi manuel" },
        "quality": { "title": "Fiabilite", "description": "95% des SLA respectes grace au monitoring" },
        "roi": { "title": "ROI", "description": "Retour sur investissement en 3 mois" }
      },
      "faq": {
        "1": {
          "question": "Dois-je configurer chaque SLA manuellement ?",
          "answer": "Non, des templates predefinis sont disponibles pour les cas courants."
        }
      }
    }
  }
}
```

> **Note:** Seul FR est genere. EN/IT/DE sont marques comme "deferred" et generes par un pipeline de traduction separe.

## 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.
