feat: add Go migration compatibility foundation

.project-docs/30-worklog/tasks/20260812-go-migration-foundation-b74c9e21.md

@@ -0,0 +1,76 @@
+# Task: Implement Go migration compatibility foundation
+
+## Identity
+
+- Task ID: 20260812-go-migration-foundation-b74c9e21
+- Mode: Feature
+- Branch: codex/20260812-go-migration-foundation-b74c9e21-go-migration-foundation
+- Worktree: /Users/brother7/Documents/AI/NianAIGC-go-foundation-b74c9e21
+- Base commit: 7de3300034accc7a0332b56207298d1e15d91de8
+- Owner: codex
+- Status: Ready for Integration
+
+## Scope
+
+- Establish executable, language-neutral compatibility contracts for the current HTTP route surface, session Cookie wire format, and PostgreSQL runtime/concurrency requirements.
+- Add a runnable Go 1.21 backend foundation with strict configuration, PostgreSQL readiness, legacy-session parsing/chunking, and health/readiness HTTP handlers.
+- Add developer verification commands without changing the current Next.js, Node Worker, Docker Compose, or ACK production routing.
+
+## Intent And Constraints
+
+- Follow red-green TDD at the approved HTTP, Cookie, PostgreSQL, and Adapter seams.
+- Preserve ACK-001 as the current deployable truth; this task does not cut traffic, remove Route Handlers, start the embedded WorkerLoop, or move production Secrets.
+- Preserve the HMAC-SHA256/base64url/chunked `zhinian_session` wire contract so a future release can avoid forced logout; do not yet make the release-policy choice.
+- Keep production PostgreSQL explicit and fail-closed, verified-CA TLS explicit, and both concurrency-sensitive database functions authoritative.
+- Use deep Go Modules around configuration, identity Cookie handling, PostgreSQL access, and HTTP lifecycle rather than one shallow Interface per table.
+
+## Outcome
+
+- Added language-neutral compatibility contracts for the complete current route surface (47 Route Handler files and 66 method/path entries) and the full version-one `zhinian_session` lifecycle: HMAC wire format, 3000-character chunks, 20-chunk/60000-character ceiling, Cookie attributes, Secure precedence, stale-chunk cleanup, and logout cleanup.
+- Added TypeScript contract tests that detect route drift, prove the current TypeScript signer/parser matches the shared Cookie golden fixture, and freeze Cookie writing/clearing semantics. The current writer now rejects values that the 20-chunk reader cannot reconstruct.
+- Added a runnable Go 1.21 module under `backend/` with:
+  - an Identity Module for legacy Cookie signing, parsing, normalization, tamper/expiry validation, bounded chunking/reassembly, Secure resolution, and transport-neutral set/clear operations;
+  - a PostgreSQL Module for fail-closed backend selection, URI and numeric validation, explicit `disable` or verified-CA `verify-full` TLS, pool lifecycle, the exact readiness privilege matrix, bounded job claims through `claim_generation_jobs`, and wallet posting through `billing_post_wallet_entry`;
+  - an HTTP Module for the stable `/api/health` liveness contract and three-second `/api/ready` database probe;
+  - an Application composition Module and `cmd/zhinian-api` process with loopback-by-default binding and bounded graceful shutdown.
+- Added cross-platform `npm run go:{fmt,test,vet,build}` commands through a small Node runner that defaults to `CGO_ENABLED=0` without mutating the user's global Go environment.
+- Kept the current Next.js, Node Worker, Docker Compose, ACK manifests, Ingress paths, Secrets, and production traffic ownership unchanged.
+- Corrected the earlier planning count from 45/64 to the source-derived 47 Route Handler files and 66 method/path entries; the two omitted routes were `/uploads/[...path]` and `/generated-results/[...path]`.
+
+## Verification
+
+- TDD RED evidence was captured independently for the HTTP manifest, Identity Module, PostgreSQL configuration/database/opening slices, HTTP health/readiness Module, application composition, cross-platform Go command runner, and final Cookie lifecycle ceiling before each slice reached GREEN.
+- `npm test -- --reporter=dot`: 34 files and 126 tests passed.
+- `npm run go:test`: all five Go packages passed.
+- `npm run go:vet`: passed.
+- `npm run go:build`: produced the ignored `backend/zhinian-api` binary.
+- Local smoke run on port 18080 returned the stable health payload and successful local readiness, then exited cleanly on SIGTERM.
+- `npm run deploy:check`: all 8 current ACK manifests passed, demonstrating that the existing deployment contract was not disturbed.
+- `npx tsc --noEmit --incremental false`: passed.
+- `npm run build`: Next.js 15.5.18 production build completed with all 33 pages/routes; the existing multiple-lockfile workspace-root warning remains.
+- `git diff --check`: passed.
+- The installed `/usr/local/go` 1.21.6 internal linker produces `missing LC_UUID` test binaries on this future macOS runtime; the repository runner uses the pure-Go `CGO_ENABLED=0` path, and external linking independently executed affected tests successfully.
+
+## Follow-ups
+
+- Add a black-box contract runner that can execute stable health/readiness/OpenAPI assertions against either Next.js or Go by base URL.
+- Resolve the observed OpenAPI drift before treating it as authoritative: reused idempotent job responses omit documented HTTP 200, `video.generate.bailian` is absent, and documentation alone advertises video `4k`.
+- Implement the first identity vertical slice in Go, including PostgreSQL revalidation of account status, organization status, role constraints, and `sessionVersion`; Cookie parsing alone is not authorization.
+- Expand job and wallet database return types only when their owning vertical slices migrate; this foundation intentionally exposes only the minimum needed contract.
+- Keep Go unrouted and the Node Worker active until exact path-level parity, single-writer ownership, Worker drain, rollback, and production RDS/ACK checks pass.
+
+## Promotion Candidates
+
+- Target: `.project-docs/30-worklog/current-state.md`, `.project-docs/20-architecture/system-overview.md`, `.project-docs/20-architecture/module-map.md`, and `.project-docs/80-commitments/commitments.md`.
+  Proposal: record that ADR-003 implementation has started with executable route/Cookie contracts and a runnable but unrouted Go foundation; ACK-001 remains authoritative for production.
+  Evidence: the shared contract fixtures/tests, Go Modules and entry point, complete Node/Go/build/ACK verification, and local smoke run in this task.
+  Future impact: subsequent slices can use the Go configuration, PostgreSQL, Identity Cookie, health/readiness, and process lifecycle foundations instead of recreating them.
+  Semantic conflicts: canonical documents currently say no Go implementation has been integrated; that statement becomes stale only after this feature is merged. This work does not supersede ACK-001 or claim a cutover.
+  Human confirmation required: no new direction is required because ADR-003 and the user's explicit implementation request authorize this first slice; serialized Integration Gate promotion is still required.
+
+- Target: `.project-docs/90-maintenance/stale-items.md` or corrected planning records if useful.
+  Proposal: correct the route inventory from 45 files / 64 handlers to 47 files / 66 method-path entries by including both file-serving Route Handlers.
+  Evidence: executable source-derived route manifest test.
+  Future impact: migration scope and progress calculations should use the complete surface.
+  Semantic conflicts: prior task records contain the lower count but are immutable historical evidence.
+  Human confirmation required: no; factual correction during Integration Gate.