@atlashub/smartstack-cli 2.1.0 → 2.3.0

package/templates/skills/business-analyse/react/schema.md

@@ -1,141 +1,487 @@
-# TypeScript Schema - FRD Data Types
+# TypeScript Schema - Feature JSON Types
 
-> **Usage:** TypeScript interfaces for FRD documentation
-> **Loaded in:** step-06-doc-html.md
+> **Usage:** TypeScript interfaces aligned with feature-schema.json
+> **Loaded in:** step-04-handoff.md (for web app rendering)
+> **Source:** `docs/business/{app}/{module}/business-analyse/v{X.Y}/feature.json`
 
 ---
 
 ## Type Definitions
 
 ```typescript
-// web/smartstack-web/src/pages/docs/business/{app}/{module}/types.ts
+// web/smartstack-web/src/types/business-analyse.ts
 
 /**
- * Use Case definition from FRD
+ * Complete Feature JSON structure
+ * Matches schemas/feature-schema.json
+ * Progressively enriched by each BA step
  */
-export interface UseCase {
-  /** Unique identifier (e.g., "UC-001") */
+export interface FeatureJson {
+  id: string;               // FEAT-XXX
+  version: string;          // 1.0, 1.1, etc.
+  status: FeatureStatus;
+  metadata: FeatureMetadata;
+  discovery: FeatureDiscovery;
+  analysis: FeatureAnalysis;
+  specification: FeatureSpecification;
+  validation: FeatureValidation;
+  handoff: FeatureHandoff;
+  suggestions: FeatureSuggestion[];
+  changelog: ChangelogEntry[];
+}
+
+export type FeatureStatus = 'draft' | 'analysed' | 'specified' | 'approved' | 'handed-off';
+
+export interface FeatureMetadata {
+  application: string;
+  module: string;
+  language: string;
+  featureType: 'new' | 'refactoring' | 'micro';
+  createdAt: string;
+  updatedAt: string;
+  previousVersion: string | null;
+}
+
+// --- Discovery ---
+
+export interface FeatureDiscovery {
+  problem: string;
+  asIs: string;
+  toBe: string;
+  trigger: string;
+  stakeholders: Stakeholder[];
+  scope: FeatureScope;
+  risks: Risk[];
+  acceptanceCriteria: AcceptanceCriterion[];
+}
+
+export interface Stakeholder {
+  role: string;
+  description: string;
+  tasks: string[];
+  frequency: 'daily' | 'weekly' | 'monthly' | 'rarely';
+}
+
+export interface FeatureScope {
+  mustHave: string[];
+  shouldHave: string[];
+  couldHave: string[];
+  outOfScope: string[];
+  mainFlow: string[];
+  alternativeFlows: AlternativeFlow[];
+}
+
+export interface AlternativeFlow {
+  condition: string;
+  steps: string[];
+}
+
+export interface Risk {
   id: string;
-  /** Use case name */
-  name: string;
-  /** Primary actor role */
-  actor: string;
-  /** Required permission path */
-  permission: string;
-  /** Brief description */
   description: string;
+  severity: 'high' | 'medium' | 'low';
+  mitigation: string;
 }
 
-/**
- * Business Rule from BRD
- */
-export interface BusinessRule {
-  /** Unique identifier (e.g., "BR-001") */
+export interface AcceptanceCriterion {
+  id: string;
+  description: string;
+  testable: boolean;
+}
+
+// --- Analysis ---
+
+export interface FeatureAnalysis {
+  objectives: BusinessObjective[];
+  businessRules: BusinessRule[];
+  entities: Entity[];
+  processFlow: string;
+  integrations: Integration[];
+}
+
+export interface BusinessObjective {
   id: string;
-  /** Rule description */
+  description: string;
+  measurable: boolean;
+}
+
+export interface BusinessRule {
+  id: string;            // BR-XXX
   rule: string;
-  /** Category: Validation, Calculation, Workflow, Security, Data */
   category: 'Validation' | 'Calculation' | 'Workflow' | 'Security' | 'Data';
-  /** MoSCoW priority */
   priority: 'Must' | 'Should' | 'Could';
+  condition: string;
+  action: string;
+  examples: BusinessRuleExample[];
+  linkedRules: string[];  // Cross-reference other BR-IDs
 }
 
-/**
- * Permission definition
- */
-export interface Permission {
-  /** Full permission path (e.g., "business.sales.orders.read") */
-  path: string;
-  /** Human-readable description */
+export interface BusinessRuleExample {
+  input: string;
+  expected: string;
+}
+
+export interface Entity {
+  name: string;           // PascalCase
   description: string;
-  /** Roles that have this permission */
-  roles: string[];
+  attributes: EntityAttribute[];
+  relationships: EntityRelationship[];
 }
 
-/**
- * Complete FRD data structure
- */
-export interface FrdData {
-  /** Feature identifier (e.g., "FEAT-001") */
-  featureId: string;
-  /** Module name in PascalCase */
-  moduleName: string;
-  /** Application name in PascalCase */
-  applicationName: string;
-  /** Document version */
-  version: string;
-  /** List of use cases */
+export interface EntityAttribute {
+  name: string;
+  type: string;
+  required: boolean;
+  rules: string;
+}
+
+export interface EntityRelationship {
+  target: string;
+  type: '1:1' | '1:N' | 'N:1' | 'N:M';
+  description: string;
+}
+
+export interface Integration {
+  system: string;
+  direction: 'inbound' | 'outbound' | 'bidirectional';
+  protocol: string;
+  description: string;
+}
+
+// --- Specification ---
+
+export interface FeatureSpecification {
+  actors: Actor[];
   useCases: UseCase[];
-  /** List of business rules */
-  businessRules: BusinessRule[];
-  /** List of permissions */
-  permissions: Permission[];
+  functionalRequirements: FunctionalRequirement[];
+  permissionMatrix: PermissionMatrix;
+  navigation: NavigationHierarchy;
+  gherkinScenarios: GherkinScenario[];
+  apiEndpoints: ApiEndpoint[];
+  validations: ValidationRule[];
+  wireframes: Wireframe[];
+  messages: BusinessMessage[];
+  lifeCycles: EntityLifeCycle[];
+  seedDataCore: SeedDataCore;
+  i18nKeys: I18nKey[];
+}
+
+export interface ValidationRule {
+  field: string;
+  rules: string;
+  errorMessage: string;
+}
+
+export interface Wireframe {
+  screen: string;
+  description: string;
+  elements: string[];
+  actions: string[];
+  permissionsRequired: string[];
+}
+
+export interface BusinessMessage {
+  code: string;                // SCREAMING_SNAKE_CASE
+  type: 'success' | 'error' | 'warning' | 'info';
+  title: string;
+  message: string;             // User-facing with {placeholders}
+  i18nKey: string;             // Dot-separated key
+}
+
+export interface EntityLifeCycle {
+  entity: string;              // PascalCase entity name
+  states: LifeCycleState[];
+}
+
+export interface LifeCycleState {
+  id: string;                  // State code (Draft, Active, etc.)
+  displayName: string;
+  description?: string;
+  allowedTransitions: string[];
+  isTerminal: boolean;
+}
+
+export interface SeedDataCore {
+  navigationModules: SeedDataNavModule[];
+  navigationTranslations: SeedDataNavTranslation[];
+  permissions: SeedDataPermission[];
+  rolePermissions: SeedDataRolePermission[];
+  permissionConstants: SeedDataPermissionConstant[];
+}
+
+export interface SeedDataNavModule {
+  code: string;
+  label: string;
+  icon: string;
+  route: string;
+  parentCode: string | null;
+  sort: number;
+}
+
+export interface SeedDataNavTranslation {
+  moduleCode: string;
+  language: 'fr' | 'en' | 'it' | 'de';
+  label: string;
+}
+
+export interface SeedDataPermission {
+  path: string;                // Full path: business.{app}.{module}.{resource}.{action}
+  action: string;
+  description?: string;
+}
+
+export interface SeedDataRolePermission {
+  role: string;
+  permissionPath: string;      // Must match permissions[].path
+}
+
+export interface SeedDataPermissionConstant {
+  constantName: string;        // PascalCase (e.g., VehiclesRead)
+  path: string;                // Matching permission path
+}
+
+export interface Actor {
+  name: string;
+  description: string;
+  permissionBase: string;
+}
+
+export interface UseCase {
+  id: string;            // UC-XXX
+  name: string;
+  actor: string;
+  permission: string;
+  preconditions: string[];
+  postconditions: string[];
+  mainScenario: string[];
+  alternativeScenarios: { condition: string; steps: string[] }[];
+  errorScenarios: { error: string; message: string; action: string }[];
+  linkedRules: string[];  // BR-IDs
+}
+
+export interface FunctionalRequirement {
+  id: string;            // FR-XXX
+  statement: string;
+  priority: 'Must' | 'Should' | 'Could';
+  acceptanceCriteria: string[];
+  linkedUseCases: string[];  // UC-IDs
+  linkedRules: string[];     // BR-IDs
+}
+
+export interface PermissionMatrix {
+  roles: string[];
+  permissions: PermissionEntry[];
+  roleAssignments: RoleAssignment[];
+}
+
+export interface PermissionEntry {
+  path: string;          // business.{app}.{module}.{action}
+  description: string;
+}
+
+export interface RoleAssignment {
+  role: string;
+  permissions: string[];  // Permission paths
+}
+
+export interface NavigationHierarchy {
+  entries: NavigationEntry[];
+}
+
+export interface NavigationEntry {
+  level: 'context' | 'application' | 'module' | 'section';
+  code: string;
+  labels: Record<string, string>;  // {fr, en, it, de}
+  route: string;
+  icon: string;
+  isNew: boolean;
+}
+
+export interface GherkinScenario {
+  feature: string;
+  name: string;
+  tags: string[];
+  steps: string;
+}
+
+export interface ApiEndpoint {
+  path: string;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  permission: string;
+  requestBody: string | null;
+  responseType: string;
+}
+
+export interface I18nKey {
+  key: string;
+  fr: string;
+  en: string;
+  it: string;
+  de: string;
+}
+
+// --- Validation ---
+
+export interface FeatureValidation {
+  validatedAt: string | null;
+  completenessChecks: CompletenessCheck[];
+  consistencyChecks: ConsistencyCheck[];
+  conventionChecks: ConventionCheck[];
+  riskAssessments: RiskAssessment[];
+  warnings: string[];
+  decision: ValidationDecision;
+}
+
+export interface CompletenessCheck {
+  section: string;
+  count: number;
+  minimum: number;
+  status: 'PASS' | 'FAIL' | 'WARNING';
+}
+
+export interface ConsistencyCheck {
+  check: string;
+  passed: number;
+  warnings: number;
+  errors: number;
+  status: 'PASS' | 'FAIL' | 'WARNING';
+}
+
+export interface ConventionCheck {
+  check: string;
+  status: 'PASS' | 'FAIL' | 'WARNING';
+  details: string;
+}
+
+export interface RiskAssessment {
+  risk: string;
+  value: number;
+  threshold: number;
+  status: 'ACCEPTABLE' | 'WARNING' | 'CRITICAL' | 'MONITORED';
+}
+
+export interface ValidationDecision {
+  approved: boolean;
+  reason: string;
+  approvalMode: 'standard' | 'micro' | 'delta' | 'force';
+  approvedBy: string;
+  approvedAt: string;
+}
+
+// --- Handoff ---
+
+export interface FeatureHandoff {
+  complexity: 'simple' | 'medium' | 'complex';
+  complexityDetails?: {
+    entities: number;
+    useCases: number;
+    businessRules: number;
+    calculated: string;
+  };
+  filesToCreate: FilesToCreate;
+  brToCodeMapping: BrToCodeMapping[];
+  apiEndpointSummary: ApiEndpointSummaryEntry[];
+  ralphPrd: object | null;     // .ralph/prd.json content
+}
+
+export interface FilesToCreate {
+  domain: FileSpec[];
+  application: FileSpec[];
+  infrastructure: FileSpec[];
+  api: FileSpec[];
+  frontend: FileSpec[];
+  seedData: FileSpec[];
+  tests: FileSpec[];
+}
+
+export interface FileSpec {
+  path: string;
+  type: string;                // Entity, Service, DTO, HasData, Constants, ApiController, Page, Component, etc.
+  linkedFRs?: string[];        // FR-XXX references
+  linkedUCs?: string[];        // UC-XXX references
+  category?: 'core' | 'business';  // For seedData files
+  source?: string;             // Derivation source in feature.json
+  description?: string;
+}
+
+export interface BrToCodeMapping {
+  ruleId: string;              // BR-XXX from analysis.businessRules
+  title: string;
+  implementationPoints: ImplementationPoint[];
+}
+
+export interface ImplementationPoint {
+  layer: string;               // Domain, Application, Infrastructure, API, Frontend
+  component: string;           // File name
+  method: string;              // Method or attribute
+  implementation: string;      // How the rule is enforced
+}
+
+export interface ApiEndpointSummaryEntry {
+  operation: string;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  route: string;               // MUST match specification.apiEndpoints[].path
+  linkedUC: string;
+  permissions: string;
+}
+
+// --- Suggestions & Changelog ---
+
+export interface FeatureSuggestion {
+  type: 'module' | 'section' | 'integration' | 'enhancement';
+  code: string;
+  title: string;
+  reason: string;
+  accepted: boolean | null;
+}
+
+export interface ChangelogEntry {
+  step?: string;               // step-01-analyse, step-02-specify, etc.
+  version?: string;
+  timestamp: string;
+  author?: string;
+  changes: string[];
+  warnings?: string[];
+  decision?: string;
 }
 ```
 
 ---
 
-## Data File Template
+## Data Loading
 
 ```typescript
-// web/smartstack-web/src/pages/docs/business/{app}/{module}/frdData.ts
+// web/smartstack-web/src/services/businessAnalyse.ts
 
-import type { FrdData } from './types';
+import type { FeatureJson } from '../types/business-analyse';
 
 /**
- * FRD data extracted from 3-functional-specification.md
- * Generated by /business-analyse:6-doc-html
+ * Load feature.json from docs path
+ * The web app reads the JSON directly - no transformation needed
  */
-export const frdData: FrdData = {
-  featureId: '{{feature_id}}',
-  moduleName: '{{module_name}}',
-  applicationName: '{{application_name}}',
-  version: '1.0',
-
-  useCases: [
-    {
-      id: 'UC-001',
-      name: '{{use_case_name}}',
-      actor: '{{actor}}',
-      permission: 'business.{{app}}.{{module}}.{{action}}',
-      description: '{{description}}'
-    }
-    // Add more use cases...
-  ],
-
-  businessRules: [
-    {
-      id: 'BR-001',
-      rule: '{{rule_description}}',
-      category: 'Validation',
-      priority: 'Must'
-    }
-    // Add more business rules...
-  ],
-
-  permissions: [
-    {
-      path: 'business.{{app}}.{{module}}.read',
-      description: 'View {{module}} data',
-      roles: ['Admin', 'Manager', 'User', 'ReadOnly']
-    },
-    {
-      path: 'business.{{app}}.{{module}}.create',
-      description: 'Create new {{module}}',
-      roles: ['Admin', 'Manager']
-    },
-    {
-      path: 'business.{{app}}.{{module}}.update',
-      description: 'Update existing {{module}}',
-      roles: ['Admin', 'Manager']
-    },
-    {
-      path: 'business.{{app}}.{{module}}.delete',
-      description: 'Delete {{module}}',
-      roles: ['Admin']
-    }
-  ]
-};
+export async function loadFeature(
+  app: string,
+  module: string,
+  version: string
+): Promise<FeatureJson> {
+  const response = await fetch(
+    `/docs/business/${app}/${module}/business-analyse/v${version}/feature.json`
+  );
+  return response.json();
+}
+
+/**
+ * List available versions for a module
+ */
+export async function listVersions(
+  app: string,
+  module: string
+): Promise<string[]> {
+  const response = await fetch(
+    `/api/docs/business/${app}/${module}/business-analyse/versions`
+  );
+  return response.json();
+}
 ```
 
 ---
@@ -143,9 +489,30 @@ export const frdData: FrdData = {
 ## Index Export
 
 ```typescript
-// web/smartstack-web/src/pages/docs/business/{app}/{module}/index.ts
+// web/smartstack-web/src/types/index.ts
 
-export { {ModuleName}FrdDocPage } from './FrdDocPage';
-export type { FrdData, UseCase, BusinessRule, Permission } from './types';
-export { frdData } from './frdData';
+export type {
+  FeatureJson,
+  FeatureStatus,
+  FeatureMetadata,
+  FeatureDiscovery,
+  FeatureAnalysis,
+  FeatureSpecification,
+  FeatureValidation,
+  FeatureHandoff,
+  BusinessRule,
+  UseCase,
+  FunctionalRequirement,
+  Entity,
+  PermissionMatrix,
+  BusinessMessage,
+  EntityLifeCycle,
+  SeedDataCore,
+  FilesToCreate,
+  FileSpec,
+  BrToCodeMapping,
+  ValidationDecision,
+  FeatureSuggestion,
+  ChangelogEntry
+} from './business-analyse';
 ```