Add VISA backend foundation

2026-06-24 22:45:34 +08:00
parent f51f64f3bd
commit e1df743eb2
17 changed files with 1999 additions and 3 deletions
@@ -0,0 +1,95 @@
+# VISA API And Migration Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a real backend API surface and a database schema migration for the VISA backend foundation.
+
+**Architecture:** Add an Express app factory with seeded in-memory VISA data so the API can run without introducing a database driver yet. Add a PostgreSQL migration file that creates the normalized VISA schema described in `docs/visa-backend-database-design.md`.
+
+**Tech Stack:** TypeScript, Express, Node assert tests, PostgreSQL SQL migration.
+
+---
+
+### Task 1: API Tests
+
+**Files:**
+- Create: `src/server/visaApi.test.ts`
+
+- [ ] **Step 1: Write failing API tests**
+
+Test `GET /api/model-versions/:id/visa`, `GET /api/model-versions/:id/view-model`, `POST /api/model-versions/:id/actions/run-check`, and a missing model version response.
+
+- [ ] **Step 2: Run the test to verify red**
+
+Run: `npx.cmd tsx src/server/visaApi.test.ts`.
+Expected: FAIL because the server app module does not exist.
+
+### Task 2: API Implementation
+
+**Files:**
+- Create: `src/server/visaRepository.ts`
+- Create: `src/server/visaApi.ts`
+- Create: `src/server/index.ts`
+- Modify: `package.json`
+
+- [ ] **Step 1: Add in-memory repository**
+
+Seed the repository with `createDefaultVisaSpec()` and expose `getVisaSpec`, `getWorkflowViewModel`, and `runConsistencyCheck`.
+
+- [ ] **Step 2: Add Express app factory**
+
+Expose the VISA JSON endpoint, view-model endpoint, and run-check action.
+
+- [ ] **Step 3: Add server entry and npm script**
+
+Add `src/server/index.ts` and a `server` script using `tsx`.
+
+- [ ] **Step 4: Run API tests**
+
+Run: `npx.cmd tsx src/server/visaApi.test.ts`.
+Expected: PASS.
+
+### Task 3: Migration Tests
+
+**Files:**
+- Create: `db/migrations/202606230001_create_visa_schema.test.ts`
+
+- [ ] **Step 1: Write failing migration test**
+
+Assert the migration includes the system tables, VISA semantic tables, consistency check table, foreign keys, and indexes.
+
+- [ ] **Step 2: Run the test to verify red**
+
+Run: `npx.cmd tsx db/migrations/202606230001_create_visa_schema.test.ts`.
+Expected: FAIL because the SQL migration does not exist.
+
+### Task 4: Migration SQL
+
+**Files:**
+- Create: `db/migrations/202606230001_create_visa_schema.sql`
+
+- [ ] **Step 1: Add PostgreSQL schema migration**
+
+Create model/version tables, VISA T1-T8 normalized tables, consistency check table, foreign keys, uniqueness constraints, and basic indexes.
+
+- [ ] **Step 2: Run migration test**
+
+Run: `npx.cmd tsx db/migrations/202606230001_create_visa_schema.test.ts`.
+Expected: PASS.
+
+### Task 5: Verification
+
+**Files:**
+- Modify as needed based on test results.
+
+- [ ] **Step 1: Run model and API tests**
+
+Run:
+- `npx.cmd tsx src/workflowModel.test.ts`
+- `npx.cmd tsx src/visaModel.test.ts`
+- `npx.cmd tsx src/server/visaApi.test.ts`
+- `npx.cmd tsx db/migrations/202606230001_create_visa_schema.test.ts`
+
+- [ ] **Step 2: Run TypeScript check**
+
+Run: `npm.cmd run lint`.
@@ -0,0 +1,82 @@
+# VISA Backend Foundation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a VISA-native backend/database foundation while keeping the current frontend workflow model compatible through an adapter.
+
+**Architecture:** Define VISA T1-T8 as backend-oriented domain structures, add a canonical sample specification, and convert that specification into the existing `WorkflowModel` view model. Keep the database design in documentation for the next backend phase.
+
+**Tech Stack:** TypeScript, Node assert tests, Vite React, Markdown database design documentation.
+
+---
+
+### Task 1: Adapter Tests
+
+**Files:**
+- Create: `src/visaModel.test.ts`
+
+- [ ] **Step 1: Write tests for VISA-to-workflow conversion**
+
+Create tests that assert the adapter exposes VISA agents as frontend workflow nodes, internal functions as behavior sections, sensing records as observable rows, and model-level tables as schedule/data/I-O/validation rows.
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx tsx src/visaModel.test.ts`
+Expected: FAIL because `visaModel` does not exist yet.
+
+### Task 2: VISA Domain Model
+
+**Files:**
+- Create: `src/visaModel.ts`
+
+- [ ] **Step 1: Define VISA T1-T8 TypeScript interfaces**
+
+Define backend-facing types for agents, variables, sensing relations, internal functions, associated data, inputs, outputs, schedule steps, termination conditions, validations, and consistency check results.
+
+- [ ] **Step 2: Add a canonical default VISA specification**
+
+Create `createDefaultVisaSpec()` using the existing segregation-style example but expressed as VISA T1-T8 rather than frontend tables.
+
+### Task 3: Workflow Adapter
+
+**Files:**
+- Modify: `src/visaModel.ts`
+
+- [ ] **Step 1: Implement `buildWorkflowFromVisaSpec`**
+
+Convert T1 agents into workflow nodes, selected T3/T4 relations into view edges and behavior sections, and T5-T8 records into the existing table rows.
+
+- [ ] **Step 2: Run adapter tests**
+
+Run: `npx tsx src/visaModel.test.ts`
+Expected: PASS.
+
+### Task 4: Database Design Documentation
+
+**Files:**
+- Create: `docs/visa-backend-database-design.md`
+
+- [ ] **Step 1: Document the database schema**
+
+Write the scheme as eight VISA semantic modules plus normalized helper tables for sensing/function references, model versions, and consistency check results.
+
+- [ ] **Step 2: Document frontend boundary**
+
+State that the frontend must not show the eight tables as raw database tables; it consumes view models derived from VISA data.
+
+### Task 5: Verification
+
+**Files:**
+- Modify as needed based on test results.
+
+- [ ] **Step 1: Run all model tests**
+
+Run: `npx tsx src/workflowModel.test.ts` and `npx tsx src/visaModel.test.ts`.
+
+- [ ] **Step 2: Run TypeScript lint**
+
+Run: `npm run lint`.
+
+- [ ] **Step 3: Report status**
+
+Summarize changed files, tests, and remaining backend work.