jerryW123
96 lines
3.0 KiB
Markdown
96 lines
3.0 KiB
Markdown
# 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`.
|