scriptCat/docs/superpowers/plans/2026-03-31-yuntu-report-server.md

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