# Task: Add direct PostgreSQL support for Alibaba Cloud RDS

## Identity

- Task ID: 20260812-rds-postgres-adapter-7f2c1a
- Mode: Feature
- Branch: codex/rds-postgres-adapter-7f2c1a
- Worktree: D:\Datas\OthersProjects\NianAIGC-rds-postgres-7f2c1a
- Base commit: 0bcb149fad8e4131fdf960cc61106ac5912cf34f
- Owner: codex
- Status: Ready for Integration

## Scope

- Replace the Supabase/PostgREST persistence path in `data-store`, `account-store`, and `billing-store` with a shared server-only PostgreSQL adapter backed by `pg`.
- Migrate the bootstrap/import scripts to the same PostgreSQL configuration contract while preserving their existing public behavior.
- Add a versioned PostgreSQL migration runner and an RDS-compatible baseline schema that preserves atomic job claiming and wallet posting.
- Add fail-closed production backend selection, database readiness, Docker runtime support, and ACK deployment manifests for Web, Worker, migration Job, Service, Ingress, ConfigMap, and Secret templates.
- Update environment and deployment documentation for Alibaba Cloud ACK + RDS PostgreSQL.
- Preserve the local JSON backend for development and existing unit tests.

## Intent And Constraints

- `ZHINIAN_DATA_BACKEND=postgres` must never silently fall back to container-local JSON when database configuration or connectivity is missing.
- Keep store exports and route/component callers stable; isolate pooling, TLS, timeouts, transactions, and SQL execution behind one deep server-only module.
- Keep the Worker as an HTTP poller; only the Web workload connects directly to PostgreSQL in the current architecture.
- Retain the PostgreSQL functions that provide `FOR UPDATE SKIP LOCKED` job claiming and atomic wallet ledger posting.
- Use parameterized SQL and explicit transactions where an operation crosses multiple statements.
- Inject credentials through Kubernetes Secrets; do not place RDS passwords or application secrets in images or ConfigMaps.
- Use TLS verification for RDS when SSL is enabled; do not introduce `rejectUnauthorized: false` as a production shortcut.
- Do not modify canonical `.project-docs` files in feature mode; record promotion candidates here for later integration.
- No live RDS credentials or ACK cluster access are available, so actual external connectivity and rollout remain explicitly unverified.

## Outcome

- Replaced the Supabase/PostgREST runtime path with a shared server-only `pg` adapter across data, account, and billing persistence while preserving explicit local JSON mode for development and tests.
- Added fail-closed production backend selection, verified-CA TLS configuration, pooled queries/transactions, full schema-and-privilege readiness, versioned/checksummed/advisory-locked migrations, and constrained application-role grants.
- Migrated bootstrap/import tooling, preserved database-side atomic job claim and wallet posting, and hardened authentication/password and wallet idempotency concurrency paths.
- Added Docker migration assets and eight ACK manifests covering namespace, configuration, secret templates, migration Job, Web, Worker, Service isolation, and Ingress, with updated Chinese/English deployment guidance.
- Final independent Sol review returned `PASS` with no blocking findings.

## Verification

- `npm ci --ignore-scripts` — passed.
- `pnpm install --lockfile-only --frozen-lockfile` — passed; npm/pnpm Next and React resolutions remain aligned.
- `npm test -- --run` — passed, 31 files / 119 tests.
- `npx tsc --noEmit --pretty false --incremental false` — passed.
- `npm run build` — passed with `/api/ready` in the production route output.
- `npm run deploy:check` — passed static assertions for all 8 ACK manifests.
- PostgreSQL/account/worker script `node --check` commands — passed.
- `git diff --check` and project documentation drift checks — passed.
- Not externally verified: no live RDS credentials, ACK kubeconfig, `psql`, or available Docker daemon were present, so real migration execution, database concurrency, image startup, and cluster rollout remain deployment checks.

## Follow-ups

- Before production cutover, back up the target database, provision separate migration/application roles, mount the Alibaba Cloud RDS CA, verify the VPC/internal endpoint and whitelist, and run the one-shot migration Job before Web rollout.
- Keep Web at one replica until generated assets are externalized to OSS/shared object storage; PostgreSQL alone does not make container-local files multi-replica safe.
- Move the image to a non-root runtime user in a later hardening change after writable runtime paths and ownership are explicitly defined.

## Promotion Candidates

- Promote the explicit `ZHINIAN_DATA_BACKEND` fail-closed contract, shared server-only PostgreSQL boundary, and versioned migration ownership model into canonical architecture/deployment memory after this feature is integrated.
- Record that the Worker remains an HTTP-only poller and does not require RDS credentials in the current architecture.