70 lines
3.3 KiB
Markdown
70 lines
3.3 KiB
Markdown
# Yuntu Report Server 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 a local Node.js backend that exposes `POST /api/reports` for the browser script and persists validated report records into PostgreSQL.
|
|
|
|
**Architecture:** Use a small Express server with a thin HTTP layer, isolated validation/mapping utilities, and a PostgreSQL repository backed by parameterized SQL. Keep report validation and database row mapping in pure functions so they can be covered with fast `node:test` tests before wiring the HTTP server.
|
|
|
|
**Tech Stack:** Node.js, Express, PostgreSQL (`pg`), `dotenv`, built-in `node:test`
|
|
|
|
---
|
|
|
|
### Task 1: Bootstrap the local server package
|
|
|
|
**Files:**
|
|
- Create: `yuntu/yuntuReportFilling/server/package.json`
|
|
- Create: `yuntu/yuntuReportFilling/server/.env.example`
|
|
- Create: `yuntu/yuntuReportFilling/server/README.md`
|
|
|
|
- [ ] **Step 1: Create the package manifest**
|
|
- [ ] **Step 2: Add local development scripts for start, dev, and test**
|
|
- [ ] **Step 3: Add `.env.example` documenting required database and server variables**
|
|
- [ ] **Step 4: Add a minimal README with startup instructions**
|
|
|
|
### Task 2: Write failing tests for validation and mapping
|
|
|
|
**Files:**
|
|
- Create: `yuntu/yuntuReportFilling/server/test/report-service.test.js`
|
|
- Test: `yuntu/yuntuReportFilling/server/test/report-service.test.js`
|
|
|
|
- [ ] **Step 1: Write a test for accepting a valid manual report payload**
|
|
- [ ] **Step 2: Run the test and verify it fails because the module does not exist yet**
|
|
- [ ] **Step 3: Write a test for rejecting `AUTO_COPY` without `sourceReportId`**
|
|
- [ ] **Step 4: Write a test for mapping API payload fields into database-ready column values**
|
|
|
|
### Task 3: Implement the pure report service module
|
|
|
|
**Files:**
|
|
- Create: `yuntu/yuntuReportFilling/server/src/report-service.js`
|
|
- Test: `yuntu/yuntuReportFilling/server/test/report-service.test.js`
|
|
|
|
- [ ] **Step 1: Implement payload validation helpers**
|
|
- [ ] **Step 2: Implement normalization/mapping helpers for database insertion**
|
|
- [ ] **Step 3: Re-run the focused test suite and verify it passes**
|
|
|
|
### Task 4: Implement the database repository and HTTP server
|
|
|
|
**Files:**
|
|
- Create: `yuntu/yuntuReportFilling/server/src/db.js`
|
|
- Create: `yuntu/yuntuReportFilling/server/src/report-repository.js`
|
|
- Create: `yuntu/yuntuReportFilling/server/src/server.js`
|
|
- Create: `yuntu/yuntuReportFilling/server/src/index.js`
|
|
- Modify: `yuntu/yuntuReportFilling/PRD.md`
|
|
|
|
- [ ] **Step 1: Add PostgreSQL pool creation from environment variables**
|
|
- [ ] **Step 2: Add repository insert logic with idempotent `report_id` handling**
|
|
- [ ] **Step 3: Add Express routes for `GET /health` and `POST /api/reports`**
|
|
- [ ] **Step 4: Add CORS and JSON parsing suitable for local browser-script access**
|
|
- [ ] **Step 5: Re-run tests and add any missing focused coverage**
|
|
|
|
### Task 5: Verify the local backend end-to-end
|
|
|
|
**Files:**
|
|
- Verify: `yuntu/yuntuReportFilling/server/*`
|
|
|
|
- [ ] **Step 1: Install dependencies**
|
|
- [ ] **Step 2: Run `npm test` and confirm all tests pass**
|
|
- [ ] **Step 3: Start the server locally and confirm `GET /health` returns success**
|
|
- [ ] **Step 4: Summarize required next step for integrating the browser script**
|