refactor: serve static frontend with Go APIs

2026-08-16 20:47:45 +08:00
1 parent 763d2f0648
commit b14b4fced7
@@ -0,0 +1,104 @@
+# Task: Convert production frontend to static output backed only by Go APIs
+
+## Identity
+
+- Task ID: 20260816-static-frontend-go-api-4f8c2a7d
+- Mode: Feature
+- Branch: main
+- Worktree: D:\Datas\OthersProjects\NianAIGC
+- Base commit: 763d2f06486493b77db27aa164a9a2cbbc14a8cf
+- Owner: codex
+- Status: Ready for Integration
+
+## Scope
+
+- Convert the Next.js application to static export with no production SSR,
+  Middleware, or Route Handler runtime.
+- Replace server-rendered authentication/page authorization with a browser
+  auth module that consumes the same-origin Go `/api/auth/me` contract.
+- Keep every existing browser business request on same-origin `/api`,
+  `/uploads`, and `/generated-results` routes owned by the Go service.
+- Serve the exported frontend from an unprivileged Nginx container and update
+  ACK Web Service, probes, Ingress commentary, and deployment assertions.
+- Preserve Go-side authorization, session-version revocation, and HttpOnly
+  Cookie semantics as the security boundary.
+
+## Intent And Constraints
+
+- The user explicitly selected a pure static frontend after the production SSR
+  login bridge remained operationally fragile.
+- The Web workload must have no database credentials, session secret, Go
+  internal URL, or server-side runtime configuration.
+- Browser requests stay same-origin so no CORS or JavaScript token storage is
+  introduced.
+- Client-side route guards are presentation only; Go remains authoritative for
+  every protected API.
+- Existing API response shapes must remain compatible unless a verified Go
+  parity gap requires a focused backend change.
+- Feature mode may update this task record and implementation/deployment docs;
+  ADR-003 and canonical architecture/current-state promotion require a later
+  Integration task.
+
+## Outcome
+
+- Next.js now emits only a static `out/` site. The production Root Layout and
+  pages no longer read request Cookies, invoke server authorization, or depend
+  on Middleware/Route Handlers.
+- Added a browser auth Module around same-origin `GET /api/auth/me`; it owns
+  response validation, safe post-login navigation, shell identity state, and
+  client-only presentation guards. Go remains the authorization boundary.
+- Removed `middleware.ts`, all `app/api/**` handlers, and the dynamic
+  `/uploads` and `/generated-results` Next handlers. Existing browser fetch
+  paths remain unchanged and are routed to Go by Ingress.
+- Fixed the sole verified browser/Go parity defect: billing adjustment results
+  now serialize lowercase `wallet` and `entry` fields.
+- Replaced the Node production runner with unprivileged Nginx serving `out/`.
+  The Web Pod has no runtime ConfigMap, session Secret, database credential, or
+  Go internal URL; it exposes only `/healthz` for workload probes.
+- Removed deprecated Node Worker and Node migration ACK manifests that could no
+  longer run inside the static Web image. Go embeds the WorkerLoop; first schema
+  creation remains the documented manual SQL operation.
+- Renamed the first-deployment session Secret owner from `zhinian-web-auth` to
+  `zhinian-go-auth` because only Go signs and validates the Cookie.
+
+## Verification
+
+- `npm test`: PASS, 53 files / 158 tests.
+- `npx tsc --noEmit --incremental false`: PASS.
+- Clean `npm run build` after deleting generated `.next` and `out`: PASS, 14/14
+  static pages generated and exported; all 12 application routes are static.
+- `go test ./...` from `backend/`: PASS for all packages.
+- `npm run deploy:check`: PASS, 7 ACK YAML manifests plus static-runtime
+  assertions.
+- `npm run info`: PASS during deployment implementation.
+- `git check-ignore -v deploy/ack/secrets.production.yaml`: PASS; the real
+  first-deployment Secret file is protected by an exact repository rule.
+- `git diff --check`: PASS after final implementation and documentation.
+- Mandatory read-only `sol_reviewer` result: PASS after three review rounds;
+  all reported authentication, first-deployment, documentation, storage-risk,
+  and Secret-ignore blockers were fixed and reverified.
+- Docker image construction was not executed because the local Docker daemon
+  is unavailable. The Dockerfile pins the official unprivileged Nginx
+  `1.30.4-alpine` runner and its build inputs are covered by deployment checks.
+
+## Follow-ups
+
+- Build and smoke the Web image in CI or another host with a Docker daemon.
+- Deploy new Web and Go images plus the ACK manifests, then verify anonymous
+  login, authenticated `/create`, logout, administrator pages, static
+  `/healthz`, Go `/api/health`, and Go `/api/ready` on the public origin.
+- Use a new immutable image tag/digest so `IfNotPresent` cannot retain the old
+  SSR Web image.
+- Unreferenced legacy TypeScript server adapters may be removed in a separate
+  cleanup after confirming no operator scripts still consume them; they are not
+  present in the production `out/` image.
+
+## Promotion Candidates
+
+- Amend or supersede ADR-003: the accepted frontend responsibility is static
+  files only, not Next SSR; browser-to-Go same-origin HTTP is the sole runtime
+  application seam. Human confirmation is already present in this task.
+- Update `decision-index.md`, `current-state.md`, `system-overview.md`,
+  `module-map.md`, and `data-flow.md` to record Nginx static Web, Go-only API
+  ownership, browser `/api/auth/me`, Go-only session Secret ownership, and
+  removal of the Node Worker/migration Job manifests.