@atlashub/smartstack-cli 2.3.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 {
@@ -174,7 +357,10 @@ export interface ValidationRule {
 
 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[];
@@ -453,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(
@@ -470,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
  */
@@ -482,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();
+}
 ```
 
 ---
@@ -492,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,
@@ -505,6 +735,7 @@ export type {
   FunctionalRequirement,
   Entity,
   PermissionMatrix,
+  Wireframe,
   BusinessMessage,
   EntityLifeCycle,
   SeedDataCore,