@atlashub/smartstack-cli 3.39.0 → 3.40.0

package/templates/skills/documentation/steps/step-02-generate.md

@@ -1,231 +1,231 @@
----
-name: Generate - Documentation Content
-description: Generate documentation TSX, i18n files, and data files based on type
-next_step: step-03-validate.md
----
-
-## STEP 02: Generate — Documentation Content
-
-### Purpose
-
-Generate the complete documentation structure based on type (user/developer/database/testing/update) using data collected in step-01.
-
-### Generation By Type
-
-#### For `user` Type: Standalone Mock UI Page
-
-**IMPORTANT:** Generate a **standalone TSX page** with **annotated Mock UI** components that faithfully reproduce the real application interface. Each Mock UI section MUST be followed by `Annotation` components explaining each visual element. **DO NOT use DocRenderer or doc-data.ts for user type.**
-
-**Output:** Standalone React TSX component (~400-600 lines)
-
-**Structure — 9 Sections:**
-
-1. **Section 1: Business Value** — Problem + solution
-2. **Section 2: Access** — Navigation breadcrumb + URL
-3. **Section 3: Interface Overview** — Annotated Mock UI (faithful to real page)
-4. **Section 4: Create Form** — Annotated Mock UI (faithful to real form)
-5. **Section 5: Detail View** — Annotated Mock UI (faithful to real detail)
-6. **Section 6: Use Cases** — 2-3 personas
-7. **Section 7: Features** — 5 features with examples
-8. **Section 8: FAQ** — 5 non-technical questions
-9. **Section 9: Technical Reference** — Collapsible: business rules + API endpoints
-
-> **REMOVED:** "Benefits" and "Before/After" sections are NOT included. This is user documentation, not a sales pitch.
-
-**Files to Generate:**
-
-- `docs/business/{application}/{module}/index.tsx` (main page)
-- `docs/business/{application}/{module}/i18n/fr.json` (French)
-- `docs/business/{application}/{module}/i18n/en.json` (English)
-- `docs/business/{application}/{module}/i18n/de.json` (German)
-- `docs/business/{application}/{module}/i18n/it.json` (Italian)
-
-**i18n Format:** FLAT JSON (no root key) for standalone pages
-
-```json
-{
-  "title": "Module Title",
-  "subtitle": "...",
-  "sections": { ... }
-}
-```
-
-#### For `developer|database|testing` Types: Data-Driven with DocRenderer
-
-**Files to Generate:**
-
-- `docs/developer/{category}/{tool}Page.tsx` (wrapper)
-- `docs/developer/{category}/doc-data.ts` (data, ~50 lines)
-- `docs/developer/{category}/i18n/fr.json` (French)
-- `docs/developer/{category}/i18n/en.json` (English)
-- `docs/developer/{category}/i18n/de.json` (German)
-- `docs/developer/{category}/i18n/it.json` (Italian)
-
-**Workflow:**
-
-```
-1. Read source data (feature.json, code patterns)
-2. Generate doc-data.ts (data file, ~50 lines)
-3. Generate index.tsx (page wrapper, ~10 lines) with i18nNamespace prop
-4. Generate i18n files in ALL 4 languages (FR, EN, DE, IT) — with root key for DocRenderer
-5. Update docs-manifest.json
-6. Update App.tsx routing and parent indexes
-```
-
-**index.tsx Format for DocRenderer:**
-
-```tsx
-import { DocRenderer } from '@/components/docs';
-import { docData } from './doc-data';
-
-export default function {Tool}DocPage() {
-  return (
-    <DocRenderer
-      data={docData}
-      backPath="/docs/developer"
-      backLabel="nav.backToDeveloper"
-      i18nNamespace="docsDeveloper{Tool}"
-    />
-  );
-}
-```
-
-**i18n Format:** Nested JSON with root key matching namespace
-
-```json
-{
-  "docsDeveloper{Tool}": {
-    "title": "Tool Title",
-    "subtitle": "...",
-    "sections": { ... }
-  }
-}
-```
-
-#### For `update` Type
-
-Re-generate files using the same workflow as original type, but:
-
-```
-1. Read real page TSX → update Mock UI if interface changed
-2. Read controller → update API endpoints and business rules
-3. Update i18n files in ALL 4 languages (FR, EN, DE, IT)
-4. Update docs-manifest.json timestamps (refreshed_at)
-5. Do NOT regenerate route registration (already exists)
-```
-
-### Extraction Scripts Reference
-
-#### extract-api-endpoints.ts
-
-**Purpose:** Extract all API endpoints from SmartStack controllers
-
-**Input:**
-- `--module {module}` - Module name (e.g., users, tenants)
-- `--app-path {path}` - Path to SmartStack.app
-
-**What it extracts:**
-- Controller file path (e.g., `UsersController.cs`)
-- HTTP method (`[HttpGet]`, `[HttpPost]`, `[HttpPut]`, `[HttpDelete]`, `[HttpPatch]`)
-- Route suffix (e.g., `{id:guid}`, `activate`)
-- Base path from `[NavRoute("administration.users")]`
-- Permission from `[RequirePermission(Permissions.Admin.Users.View)]`
-- Handler method name
-
-**Output:** JSON array
-```json
-[
-  {
-    "method": "GET",
-    "path": "/api/administration/users",
-    "handler": "GetUsers",
-    "permission": "administration.users.read"
-  }
-]
-```
-
-#### extract-business-rules.ts
-
-**Purpose:** Extract business rules from Domain entities and unit tests
-
-**Input:**
-- `--module {module}` - Module name (e.g., users, tenants)
-- `--app-path {path}` - Path to SmartStack.app
-
-**Phase 1: Domain Entity Extraction**
-- Scans Domain entity (e.g., `User.cs`)
-- Looks for guard clauses: `if (...) throw new DomainException("...")`
-- Looks for validation in Create/Update methods
-- Extracts exception messages and context
-
-**Phase 2: Unit Tests Extraction**
-- Scans unit test file (e.g., `UserTests.cs`)
-- Looks for test methods with `[Fact]` attribute
-- Extracts test names and scenarios (edge cases)
-- Maps to business rule statements
-
-**Output:** JSON array
-```json
-[
-  {
-    "id": "BR-001",
-    "name": "Email requis",
-    "category": "Validation",
-    "statement": "Un utilisateur doit avoir une adresse email valide et non vide"
-  }
-]
-```
-
-#### generate-doc-with-mock-ui.ts
-
-**Purpose:** Main generator - creates complete documentation TSX with Mock UI
-
-**Input:**
-- `--module {module}` - Module name (e.g., users)
-- `--application {application}` - Application (e.g., administration)
-- `--app-path {path}` - Path to SmartStack.app
-
-**Workflow:**
-1. Find Domain entity file (users → User.cs via singularize)
-2. Extract entity properties (name, type, nullable, required)
-3. Call `extract-api-endpoints.ts`
-4. Call `extract-business-rules.ts`
-5. Generate mock data (5 sample records with realistic values)
-6. Generate KPI stats (Total, Active/Inactive, Status breakdown)
-7. Generate table UI (smart column selection - 6 most relevant)
-8. Generate form UI (intelligent field types based on property)
-9. Output complete TSX file to stdout
-
-**Smart Features:**
-- **Singularize**: users → User.cs, tenants → Tenant.cs
-- **Property filtering**: Excludes hash, token, *Id, normalized, internal
-- **Priority selection**: name/title > email > status > date
-- **Field type detection**: email → email input, bool → checkbox
-- **Mock value generation**: Realistic emails, names, dates, GUIDs
-
-**Output:** Complete React TSX component (400-500 lines)
-
-### Absolute Rules
-
-1. **NEVER** hardcoded text → `useTranslation('namespace')`
-2. **NEVER** ASCII art → React/HTML components for ERD
-3. **ALWAYS** read the REAL page TSX before generating Mock UI
-4. **ALWAYS** read the controller to extract real API endpoints
-5. **ALWAYS** annotate every Mock UI section with `Annotation` components
-6. **ALWAYS** generate i18n in ALL 4 languages (FR, EN, DE, IT)
-7. **ALWAYS** use FLAT JSON (no root key) for standalone `user` type pages
-8. **ALWAYS** use nested JSON with root key for DocRenderer pages
-
-### Success Metrics
-
-- [x] TSX file generated with correct structure
-- [x] Mock UI faithfully reproduces real interface
-- [x] Every Mock UI section annotated with `Annotation` components
-- [x] i18n files created in ALL 4 languages (FR, EN, DE, IT)
-- [x] JSON format correct (FLAT for user, nested for others)
-- [x] All hardcoded text uses `useTranslation()`
-- [x] No "Benefices" or "Avant/Apres" sections present
-
-### Next Step
-
-→ **step-03-validate.md** — Validate completeness and integrate into project.
+---
+name: Generate - Documentation Content
+description: Generate documentation TSX, i18n files, and data files based on type
+next_step: step-03-validate.md
+---
+
+## STEP 02: Generate — Documentation Content
+
+### Purpose
+
+Generate the complete documentation structure based on type (user/developer/database/testing/update) using data collected in step-01.
+
+### Generation By Type
+
+#### For `user` Type: Standalone Mock UI Page
+
+**IMPORTANT:** Generate a **standalone TSX page** with **annotated Mock UI** components that faithfully reproduce the real application interface. Each Mock UI section MUST be followed by `Annotation` components explaining each visual element. **DO NOT use DocRenderer or doc-data.ts for user type.**
+
+**Output:** Standalone React TSX component (~400-600 lines)
+
+**Structure — 9 Sections:**
+
+1. **Section 1: Business Value** — Problem + solution
+2. **Section 2: Access** — Navigation breadcrumb + URL
+3. **Section 3: Interface Overview** — Annotated Mock UI (faithful to real page)
+4. **Section 4: Create Form** — Annotated Mock UI (faithful to real form)
+5. **Section 5: Detail View** — Annotated Mock UI (faithful to real detail)
+6. **Section 6: Use Cases** — 2-3 personas
+7. **Section 7: Features** — 5 features with examples
+8. **Section 8: FAQ** — 5 non-technical questions
+9. **Section 9: Technical Reference** — Collapsible: business rules + API endpoints
+
+> **REMOVED:** "Benefits" and "Before/After" sections are NOT included. This is user documentation, not a sales pitch.
+
+**Files to Generate:**
+
+- `docs/business/{application}/{module}/index.tsx` (main page)
+- `docs/business/{application}/{module}/i18n/fr.json` (French)
+- `docs/business/{application}/{module}/i18n/en.json` (English)
+- `docs/business/{application}/{module}/i18n/de.json` (German)
+- `docs/business/{application}/{module}/i18n/it.json` (Italian)
+
+**i18n Format:** FLAT JSON (no root key) for standalone pages
+
+```json
+{
+  "title": "Module Title",
+  "subtitle": "...",
+  "sections": { ... }
+}
+```
+
+#### For `developer|database|testing` Types: Data-Driven with DocRenderer
+
+**Files to Generate:**
+
+- `docs/developer/{category}/{tool}Page.tsx` (wrapper)
+- `docs/developer/{category}/doc-data.ts` (data, ~50 lines)
+- `docs/developer/{category}/i18n/fr.json` (French)
+- `docs/developer/{category}/i18n/en.json` (English)
+- `docs/developer/{category}/i18n/de.json` (German)
+- `docs/developer/{category}/i18n/it.json` (Italian)
+
+**Workflow:**
+
+```
+1. Read source data (feature.json, code patterns)
+2. Generate doc-data.ts (data file, ~50 lines)
+3. Generate index.tsx (page wrapper, ~10 lines) with i18nNamespace prop
+4. Generate i18n files in ALL 4 languages (FR, EN, DE, IT) — with root key for DocRenderer
+5. Update docs-manifest.json
+6. Update App.tsx routing and parent indexes
+```
+
+**index.tsx Format for DocRenderer:**
+
+```tsx
+import { DocRenderer } from '@/components/docs';
+import { docData } from './doc-data';
+
+export default function {Tool}DocPage() {
+  return (
+    <DocRenderer
+      data={docData}
+      backPath="/docs/developer"
+      backLabel="nav.backToDeveloper"
+      i18nNamespace="docsDeveloper{Tool}"
+    />
+  );
+}
+```
+
+**i18n Format:** Nested JSON with root key matching namespace
+
+```json
+{
+  "docsDeveloper{Tool}": {
+    "title": "Tool Title",
+    "subtitle": "...",
+    "sections": { ... }
+  }
+}
+```
+
+#### For `update` Type
+
+Re-generate files using the same workflow as original type, but:
+
+```
+1. Read real page TSX → update Mock UI if interface changed
+2. Read controller → update API endpoints and business rules
+3. Update i18n files in ALL 4 languages (FR, EN, DE, IT)
+4. Update docs-manifest.json timestamps (refreshed_at)
+5. Do NOT regenerate route registration (already exists)
+```
+
+### Extraction Scripts Reference
+
+#### extract-api-endpoints.ts
+
+**Purpose:** Extract all API endpoints from SmartStack controllers
+
+**Input:**
+- `--module {module}` - Module name (e.g., users, tenants)
+- `--app-path {path}` - Path to SmartStack.app
+
+**What it extracts:**
+- Controller file path (e.g., `UsersController.cs`)
+- HTTP method (`[HttpGet]`, `[HttpPost]`, `[HttpPut]`, `[HttpDelete]`, `[HttpPatch]`)
+- Route suffix (e.g., `{id:guid}`, `activate`)
+- Base path from `[NavRoute("administration.users")]`
+- Permission from `[RequirePermission(Permissions.Admin.Users.View)]`
+- Handler method name
+
+**Output:** JSON array
+```json
+[
+  {
+    "method": "GET",
+    "path": "/api/administration/users",
+    "handler": "GetUsers",
+    "permission": "administration.users.read"
+  }
+]
+```
+
+#### extract-business-rules.ts
+
+**Purpose:** Extract business rules from Domain entities and unit tests
+
+**Input:**
+- `--module {module}` - Module name (e.g., users, tenants)
+- `--app-path {path}` - Path to SmartStack.app
+
+**Phase 1: Domain Entity Extraction**
+- Scans Domain entity (e.g., `User.cs`)
+- Looks for guard clauses: `if (...) throw new DomainException("...")`
+- Looks for validation in Create/Update methods
+- Extracts exception messages and context
+
+**Phase 2: Unit Tests Extraction**
+- Scans unit test file (e.g., `UserTests.cs`)
+- Looks for test methods with `[Fact]` attribute
+- Extracts test names and scenarios (edge cases)
+- Maps to business rule statements
+
+**Output:** JSON array
+```json
+[
+  {
+    "id": "BR-001",
+    "name": "Email requis",
+    "category": "Validation",
+    "statement": "Un utilisateur doit avoir une adresse email valide et non vide"
+  }
+]
+```
+
+#### generate-doc-with-mock-ui.ts
+
+**Purpose:** Main generator - creates complete documentation TSX with Mock UI
+
+**Input:**
+- `--module {module}` - Module name (e.g., users)
+- `--application {application}` - Application (e.g., administration)
+- `--app-path {path}` - Path to SmartStack.app
+
+**Workflow:**
+1. Find Domain entity file (users → User.cs via singularize)
+2. Extract entity properties (name, type, nullable, required)
+3. Call `extract-api-endpoints.ts`
+4. Call `extract-business-rules.ts`
+5. Generate mock data (5 sample records with realistic values)
+6. Generate KPI stats (Total, Active/Inactive, Status breakdown)
+7. Generate table UI (smart column selection - 6 most relevant)
+8. Generate form UI (intelligent field types based on property)
+9. Output complete TSX file to stdout
+
+**Smart Features:**
+- **Singularize**: users → User.cs, tenants → Tenant.cs
+- **Property filtering**: Excludes hash, token, *Id, normalized, internal
+- **Priority selection**: name/title > email > status > date
+- **Field type detection**: email → email input, bool → checkbox
+- **Mock value generation**: Realistic emails, names, dates, GUIDs
+
+**Output:** Complete React TSX component (400-500 lines)
+
+### Absolute Rules
+
+1. **NEVER** hardcoded text → `useTranslation('namespace')`
+2. **NEVER** ASCII art → React/HTML components for ERD
+3. **ALWAYS** read the REAL page TSX before generating Mock UI
+4. **ALWAYS** read the controller to extract real API endpoints
+5. **ALWAYS** annotate every Mock UI section with `Annotation` components
+6. **ALWAYS** generate i18n in ALL 4 languages (FR, EN, DE, IT)
+7. **ALWAYS** use FLAT JSON (no root key) for standalone `user` type pages
+8. **ALWAYS** use nested JSON with root key for DocRenderer pages
+
+### Success Metrics
+
+- [x] TSX file generated with correct structure
+- [x] Mock UI faithfully reproduces real interface
+- [x] Every Mock UI section annotated with `Annotation` components
+- [x] i18n files created in ALL 4 languages (FR, EN, DE, IT)
+- [x] JSON format correct (FLAT for user, nested for others)
+- [x] All hardcoded text uses `useTranslation()`
+- [x] No "Benefices" or "Avant/Apres" sections present
+
+### Next Step
+
+→ **step-03-validate.md** — Validate completeness and integrate into project.