112 lines
3.7 KiB
Markdown
112 lines
3.7 KiB
Markdown
# State Center Web State Machine 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:** Build the browser-based Web state machine for `state_center`: job list, timeline, task list, and task/node actions.
|
|
|
|
**Architecture:** Keep the existing FastAPI backend as the source of truth for workflow state. Add small, focused backend endpoints for timeline, jobs, tasks, and dev ingestion, then build a React/Vite frontend that only renders backend-computed state and posts actions back. Do not move business rules into the frontend.
|
|
|
|
**Tech Stack:** Python 3.13, FastAPI, Pydantic, pymysql, pytest, Node.js, Vite, React, TypeScript, plain CSS.
|
|
|
|
---
|
|
|
|
### Task 1: Add backend task/timeline data contracts
|
|
|
|
**Files:**
|
|
- Modify: `state_center/sql/schema.sql`
|
|
- Modify: `state_center/app/main.py`
|
|
- Create: `state_center/tests/test_web_state_machine.py`
|
|
|
|
- [ ] **Step 1: Write the failing test**
|
|
|
|
Add tests for:
|
|
- `GET /api/jobs/{job_id}/timeline` returns all 13 nodes with backend-computed statuses.
|
|
- `POST /api/tasks/{task_id}/submit` stores `submitted_result_json` and returns the stored result on duplicate `submitToken`.
|
|
- `POST /api/jobs/{job_id}/items` rejects unsafe replace-after-match behavior.
|
|
|
|
- [ ] **Step 2: Run test to verify it fails**
|
|
|
|
Run: `python -m pytest state_center/tests/test_web_state_machine.py -v`
|
|
Expected: fail because endpoints/fields do not exist yet.
|
|
|
|
- [ ] **Step 3: Write minimal implementation**
|
|
|
|
Add the schema column for stored task results, then implement the backend helpers and endpoints in `main.py`.
|
|
|
|
- [ ] **Step 4: Run test to verify it passes**
|
|
|
|
Run: `python -m pytest state_center/tests/test_web_state_machine.py -v`
|
|
Expected: pass.
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add state_center/sql/schema.sql state_center/app/main.py state_center/tests/test_web_state_machine.py
|
|
git commit -m "feat: add web state machine backend contracts"
|
|
```
|
|
|
|
### Task 2: Add browser-ready frontend app
|
|
|
|
**Files:**
|
|
- Create: `state_center_web/package.json`
|
|
- Create: `state_center_web/vite.config.ts`
|
|
- Create: `state_center_web/index.html`
|
|
- Create: `state_center_web/src/main.tsx`
|
|
- Create: `state_center_web/src/App.tsx`
|
|
- Create: `state_center_web/src/api/client.ts`
|
|
- Create: `state_center_web/src/components/JobList.tsx`
|
|
- Create: `state_center_web/src/components/JobTimeline.tsx`
|
|
- Create: `state_center_web/src/components/TaskList.tsx`
|
|
- Create: `state_center_web/src/styles.css`
|
|
|
|
- [ ] **Step 1: Write the failing test**
|
|
|
|
Add a lightweight frontend build check and a small unit test for timeline status mapping.
|
|
|
|
- [ ] **Step 2: Run test to verify it fails**
|
|
|
|
Run: `npm test`
|
|
Expected: fail because the app does not exist yet.
|
|
|
|
- [ ] **Step 3: Write minimal implementation**
|
|
|
|
Create the Vite app, route-less operational UI, and fetch-based API client.
|
|
|
|
- [ ] **Step 4: Run test to verify it passes**
|
|
|
|
Run: `npm test`
|
|
Expected: pass.
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add state_center_web
|
|
git commit -m "feat: add web state machine frontend"
|
|
```
|
|
|
|
### Task 3: Wire local dev workflow
|
|
|
|
**Files:**
|
|
- Create: `state_center_web/README.md`
|
|
- Modify: `state_center/README.md`
|
|
|
|
- [ ] **Step 1: Write the failing test**
|
|
|
|
Not required; this task is documentation and run instructions only.
|
|
|
|
- [ ] **Step 2: Write minimal implementation**
|
|
|
|
Document the start commands for the FastAPI backend and Vite frontend on Windows/macOS.
|
|
|
|
- [ ] **Step 3: Verify manually**
|
|
|
|
Start backend and frontend locally, open the browser app, and confirm the timeline and task list render.
|
|
|
|
- [ ] **Step 4: Commit**
|
|
|
|
```bash
|
|
git add state_center/README.md state_center_web/README.md
|
|
git commit -m "docs: add web state machine runbook"
|
|
```
|
|
|