@atlashub/smartstack-cli 2.2.0 → 2.4.0

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

@@ -1,8 +1,9 @@
 # TypeScript Schema - Feature JSON Types
 
-> **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`
+> **Usage:** TypeScript interfaces aligned with feature-schema.json and application-schema.json
+> **Loaded in:** step-05-handoff.md (for web app rendering)
+> **Source (module):** `docs/business/{app}/{module}/business-analyse/v{X.Y}/feature.json`
+> **Source (application):** `docs/business/{app}/business-analyse/v{X.Y}/feature.json`
 
 ---
 
@@ -11,8 +12,179 @@
 ```typescript
 // web/smartstack-web/src/types/business-analyse.ts
 
+// ===================================================================
+// APPLICATION-LEVEL TYPES (master feature.json, scope: "application")
+// ===================================================================
+
+/**
+ * Application-level Feature JSON structure
+ * Matches schemas/application-schema.json
+ * Master document for multi-module BA
+ */
+export interface ApplicationFeatureJson {
+  id: string;               // FEAT-XXX
+  version: string;
+  status: ApplicationStatus;
+  scope: 'application';
+  metadata: ApplicationMetadata;
+  cadrage: ApplicationCadrage;
+  modules: ApplicationModule[];
+  dependencyGraph: DependencyGraph;
+  consolidation: ApplicationConsolidation;
+  suggestions: FeatureSuggestion[];
+  changelog: ChangelogEntry[];
+}
+
+export type ApplicationStatus = 'draft' | 'framed' | 'decomposed' | 'specified' | 'consolidated' | 'handed-off';
+
+export interface ApplicationMetadata {
+  application: string;
+  language: string;
+  featureDescription: string;
+  scope: 'application';
+  createdAt: string;
+  updatedAt: string;
+  workflow: WorkflowState;
+}
+
+export interface WorkflowState {
+  mode: 'application' | 'module';
+  moduleOrder: string[];
+  currentModuleIndex: number;
+  completedModules: string[];
+  currentModule: string | null;
+}
+
+export interface ApplicationCadrage {
+  problem: string;
+  asIs: string;
+  toBe: string;
+  trigger: string;
+  stakeholders: Stakeholder[];
+  globalScope: GlobalScope;
+  applicationRoles: ApplicationRole[];
+  risks: Risk[];
+  acceptanceCriteria: AcceptanceCriterion[];
+  codebaseContext?: Record<string, unknown>;
+}
+
+export interface GlobalScope {
+  mustHave: string[];
+  shouldHave: string[];
+  couldHave: string[];
+  outOfScope: string[];
+}
+
+export interface ApplicationRole {
+  name: string;
+  level: 'admin' | 'manager' | 'contributor' | 'viewer';
+  description: string;
+  defaultPermissions: string[];
+  moduleRestrictions?: string[];
+}
+
+export interface ApplicationModule {
+  code: string;
+  description: string;
+  featureType: string;
+  entities: string[];
+  priority: 'must' | 'should' | 'could';
+  estimatedComplexity: 'simple' | 'medium' | 'complex';
+  status: 'pending' | 'in-progress' | 'specified' | 'validated';
+  featureJsonPath?: string;
+  sortOrder: number;
+  dependencies: string[];
+  dependents: string[];
+}
+
+export interface DependencyGraph {
+  edges: DependencyEdge[];
+  topologicalOrder: string[];
+  layers: DependencyLayer[];
+}
+
+export interface DependencyEdge {
+  from: string;
+  to: string;
+  type: 'FK' | 'Event' | 'Shared-entity' | 'Lookup';
+  description: string;
+}
+
+export interface DependencyLayer {
+  layer: number;
+  modules: string[];
+}
+
+export interface ApplicationConsolidation {
+  crossModuleInteractions: CrossModuleInteractions;
+  permissionCoherence: PermissionCoherence;
+  e2eFlows: E2EFlow[];
+  globalRiskAssessment: Record<string, unknown>;
+}
+
+export interface CrossModuleInteractions {
+  fkReferences: FKReference[];
+  sharedEntities: SharedEntity[];
+  events: ModuleEvent[];
+  sharedReferenceData: SharedReferenceData[];
+}
+
+export interface FKReference {
+  sourceModule: string;
+  sourceEntity: string;
+  sourceField: string;
+  targetModule: string;
+  targetEntity: string;
+  targetField: string;
+  required: boolean;
+}
+
+export interface SharedEntity {
+  entity: string;
+  definedIn: string;
+  referencedBy: string[];
+  referenceType: string;
+}
+
+export interface ModuleEvent {
+  producer: string;
+  event: string;
+  consumers: string[];
+  description: string;
+}
+
+export interface SharedReferenceData {
+  table: string;
+  usedBy: string[];
+  owner: string;
+}
+
+export interface PermissionCoherence {
+  roleConsistency: boolean;
+  pathFormatValid: boolean;
+  hierarchyRespected: boolean;
+  conflictsResolved: number;
+}
+
+export interface E2EFlow {
+  name: string;
+  steps: E2EFlowStep[];
+  actors: string[];
+  data: string;
+}
+
+export interface E2EFlowStep {
+  module: string;
+  action: string;
+  permission: string;
+}
+
+// ===================================================================
+// MODULE-LEVEL TYPES (per-module feature.json, scope: "module")
+// ===================================================================
+
 /**
- * Complete Feature JSON structure
+ * Module-level Feature JSON structure
  * Matches schemas/feature-schema.json
  * Progressively enriched by each BA step
  */
@@ -20,7 +192,9 @@ export interface FeatureJson {
   id: string;               // FEAT-XXX
   version: string;          // 1.0, 1.1, etc.
   status: FeatureStatus;
+  scope?: 'module';
   metadata: FeatureMetadata;
+  applicationContext?: ApplicationContext;
   discovery: FeatureDiscovery;
   analysis: FeatureAnalysis;
   specification: FeatureSpecification;
@@ -30,18 +204,27 @@ export interface FeatureJson {
   changelog: ChangelogEntry[];
 }
 
-export type FeatureStatus = 'draft' | 'analysed' | 'specified' | 'approved' | 'handed-off';
+export type FeatureStatus = 'draft' | 'framed' | 'analysed' | 'decomposed' | 'specified' | 'consolidated' | 'approved' | 'handed-off';
 
 export interface FeatureMetadata {
   application: string;
   module: string;
   language: string;
   featureType: 'new' | 'refactoring' | 'micro';
+  scope?: 'application' | 'module';
+  applicationRef?: string | null;
+  moduleIndex?: number | null;
   createdAt: string;
   updatedAt: string;
   previousVersion: string | null;
 }
 
+export interface ApplicationContext {
+  applicationRoles: ApplicationRole[];
+  permissionBase: string;
+  relatedModules: string[];
+}
+
 // --- Discovery ---
 
 export interface FeatureDiscovery {
@@ -137,7 +320,7 @@ export interface EntityAttribute {
 
 export interface EntityRelationship {
   target: string;
-  type: 'OneToMany' | 'ManyToOne' | 'ManyToMany' | 'OneToOne';
+  type: '1:1' | '1:N' | 'N:1' | 'N:M';
   description: string;
 }
 
@@ -158,9 +341,91 @@ export interface FeatureSpecification {
   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;
+  section?: string;              // Section code (list, detail, create, etc.)
+  description: string;
+  mockupFormat?: 'ascii' | 'svg';  // Format of the mockup
+  mockup?: string;                 // ASCII art or inline SVG content
+  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;
@@ -244,54 +509,112 @@ export interface I18nKey {
 // --- Validation ---
 
 export interface FeatureValidation {
-  decision: 'APPROVED' | 'REJECTED';
-  completeness: Record<string, { score: string; issues: string[] }>;
-  consistency: Record<string, 'OK' | 'FAIL'>;
-  conventions: Record<string, 'OK' | 'FAIL'>;
-  risks: ValidatedRisk[];
-  issues: ValidationIssue[];
+  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 ValidatedRisk {
+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;
-  severity: 'High' | 'Medium' | 'Low';
-  mitigation: string;
-  status: 'Mitigated' | 'Accepted' | 'Open';
+  value: number;
+  threshold: number;
+  status: 'ACCEPTABLE' | 'WARNING' | 'CRITICAL' | 'MONITORED';
 }
 
-export interface ValidationIssue {
-  severity: 'critical' | 'warning' | 'info';
-  section: string;
-  message: string;
+export interface ValidationDecision {
+  approved: boolean;
+  reason: string;
+  approvalMode: 'standard' | 'micro' | 'delta' | 'force';
+  approvedBy: string;
+  approvedAt: string;
 }
 
 // --- Handoff ---
 
 export interface FeatureHandoff {
-  complexity: 'Simple' | 'Medium' | 'Complex';
-  filesToCreate: FileSpec[];
+  complexity: 'simple' | 'medium' | 'complex';
+  complexityDetails?: {
+    entities: number;
+    useCases: number;
+    businessRules: number;
+    calculated: string;
+  };
+  filesToCreate: FilesToCreate;
   brToCodeMapping: BrToCodeMapping[];
-  ralphPrd: object | null;  // .ralph/prd.json content
+  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;
-  layer: string;
-  type: string;
-  description: 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 {
-  brId: string;
-  rule: string;
-  implementation: string;
-  file: string;
+  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';
+  type: 'module' | 'section' | 'integration' | 'enhancement';
   code: string;
   title: string;
   reason: string;
@@ -299,9 +622,13 @@ export interface FeatureSuggestion {
 }
 
 export interface ChangelogEntry {
-  version: string;
+  step?: string;               // step-01-analyse, step-02-specify, etc.
+  version?: string;
   timestamp: string;
+  author?: string;
   changes: string[];
+  warnings?: string[];
+  decision?: string;
 }
 ```
 
@@ -312,10 +639,10 @@ export interface ChangelogEntry {
 ```typescript
 // web/smartstack-web/src/services/businessAnalyse.ts
 
-import type { FeatureJson } from '../types/business-analyse';
+import type { FeatureJson, ApplicationFeatureJson } from '../types/business-analyse';
 
 /**
- * Load feature.json from docs path
+ * Load module-level feature.json from docs path
  * The web app reads the JSON directly - no transformation needed
  */
 export async function loadFeature(
@@ -329,6 +656,19 @@ export async function loadFeature(
   return response.json();
 }
 
+/**
+ * Load application-level (master) feature.json
+ */
+export async function loadApplicationFeature(
+  app: string,
+  version: string
+): Promise<ApplicationFeatureJson> {
+  const response = await fetch(
+    `/docs/business/${app}/business-analyse/v${version}/feature.json`
+  );
+  return response.json();
+}
+
 /**
  * List available versions for a module
  */
@@ -341,6 +681,18 @@ export async function listVersions(
   );
   return response.json();
 }
+
+/**
+ * List available versions for an application (master)
+ */
+export async function listApplicationVersions(
+  app: string
+): Promise<string[]> {
+  const response = await fetch(
+    `/api/docs/business/${app}/business-analyse/versions`
+  );
+  return response.json();
+}
 ```
 
 ---
@@ -351,9 +703,28 @@ export async function listVersions(
 // web/smartstack-web/src/types/index.ts
 
 export type {
+  // Application-level types
+  ApplicationFeatureJson,
+  ApplicationStatus,
+  ApplicationMetadata,
+  WorkflowState,
+  ApplicationCadrage,
+  GlobalScope,
+  ApplicationRole,
+  ApplicationModule,
+  DependencyGraph,
+  DependencyEdge,
+  DependencyLayer,
+  ApplicationConsolidation,
+  CrossModuleInteractions,
+  E2EFlow,
+  PermissionCoherence,
+
+  // Module-level types
   FeatureJson,
   FeatureStatus,
   FeatureMetadata,
+  ApplicationContext,
   FeatureDiscovery,
   FeatureAnalysis,
   FeatureSpecification,
@@ -364,6 +735,14 @@ export type {
   FunctionalRequirement,
   Entity,
   PermissionMatrix,
+  Wireframe,
+  BusinessMessage,
+  EntityLifeCycle,
+  SeedDataCore,
+  FilesToCreate,
+  FileSpec,
+  BrToCodeMapping,
+  ValidationDecision,
   FeatureSuggestion,
   ChangelogEntry
 } from './business-analyse';