# 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**