@atlashub/smartstack-cli 2.1.0 → 2.2.0

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

@@ -1,141 +1,346 @@
-# 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;
-  /** Rule description */
+  description: string;
+  testable: boolean;
+}
+
+// --- Analysis ---
+
+export interface FeatureAnalysis {
+  objectives: BusinessObjective[];
+  businessRules: BusinessRule[];
+  entities: Entity[];
+  processFlow: string;
+  integrations: Integration[];
+}
+
+export interface BusinessObjective {
+  id: string;
+  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;
+  attributes: EntityAttribute[];
+  relationships: EntityRelationship[];
+}
+
+export interface EntityAttribute {
+  name: string;
+  type: string;
+  required: boolean;
+  rules: string;
+}
+
+export interface EntityRelationship {
+  target: string;
+  type: 'OneToMany' | 'ManyToOne' | 'ManyToMany' | 'OneToOne';
+  description: string;
+}
+
+export interface Integration {
+  system: string;
+  direction: 'inbound' | 'outbound' | 'bidirectional';
+  protocol: string;
+  description: string;
+}
+
+// --- Specification ---
+
+export interface FeatureSpecification {
+  actors: Actor[];
+  useCases: UseCase[];
+  functionalRequirements: FunctionalRequirement[];
+  permissionMatrix: PermissionMatrix;
+  navigation: NavigationHierarchy;
+  gherkinScenarios: GherkinScenario[];
+  apiEndpoints: ApiEndpoint[];
+  i18nKeys: I18nKey[];
+}
+
+export interface Actor {
+  name: string;
   description: string;
-  /** Roles that have this permission */
+  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[];
 }
 
-/**
- * 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 */
+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 {
+  decision: 'APPROVED' | 'REJECTED';
+  completeness: Record<string, { score: string; issues: string[] }>;
+  consistency: Record<string, 'OK' | 'FAIL'>;
+  conventions: Record<string, 'OK' | 'FAIL'>;
+  risks: ValidatedRisk[];
+  issues: ValidationIssue[];
+}
+
+export interface ValidatedRisk {
+  risk: string;
+  severity: 'High' | 'Medium' | 'Low';
+  mitigation: string;
+  status: 'Mitigated' | 'Accepted' | 'Open';
+}
+
+export interface ValidationIssue {
+  severity: 'critical' | 'warning' | 'info';
+  section: string;
+  message: string;
+}
+
+// --- Handoff ---
+
+export interface FeatureHandoff {
+  complexity: 'Simple' | 'Medium' | 'Complex';
+  filesToCreate: FileSpec[];
+  brToCodeMapping: BrToCodeMapping[];
+  ralphPrd: object | null;  // .ralph/prd.json content
+}
+
+export interface FileSpec {
+  path: string;
+  layer: string;
+  type: string;
+  description: string;
+}
+
+export interface BrToCodeMapping {
+  brId: string;
+  rule: string;
+  implementation: string;
+  file: string;
+}
+
+// --- Suggestions & Changelog ---
+
+export interface FeatureSuggestion {
+  type: 'module' | 'section' | 'integration';
+  code: string;
+  title: string;
+  reason: string;
+  accepted: boolean | null;
+}
+
+export interface ChangelogEntry {
   version: string;
-  /** List of use cases */
-  useCases: UseCase[];
-  /** List of business rules */
-  businessRules: BusinessRule[];
-  /** List of permissions */
-  permissions: Permission[];
+  timestamp: string;
+  changes: 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 +348,23 @@ 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,
+  FeatureSuggestion,
+  ChangelogEntry
+} from './business-analyse';
 ```