diff --git a/.project-docs/10-decisions/decision-index.md b/.project-docs/10-decisions/decision-index.md index a30eae1..8afe4d9 100644 --- a/.project-docs/10-decisions/decision-index.md +++ b/.project-docs/10-decisions/decision-index.md @@ -4,6 +4,9 @@ | ID | Decision | Status | Date | Applies To | Detail | |---|---|---|---|---|---| +| RDS-001 | Production persistence uses explicit direct PostgreSQL through one server-only adapter; local JSON is explicit development/test mode. | Accepted | 2026-08-12 | Server stores and scripts | `ZHINIAN_DATA_BACKEND=postgres` fails closed and never silently falls back. | +| RDS-002 | Database changes use versioned, checksummed, advisory-locked migrations executed by a one-shot deployment Job. | Accepted | 2026-08-12 | Database schema and ACK rollout | Migrations do not run in each Web pod init container. | +| ACK-001 | Worker remains an HTTP poller and does not receive RDS credentials; Web owns database access. | Accepted | 2026-08-12 | ACK workloads | Worker calls the internal Web Service with a shared internal token. | ## Superseded Decisions diff --git a/.project-docs/20-architecture/data-flow.md b/.project-docs/20-architecture/data-flow.md index e108ed4..92379be 100644 --- a/.project-docs/20-architecture/data-flow.md +++ b/.project-docs/20-architecture/data-flow.md @@ -4,15 +4,23 @@ | Flow | Source | Destination | Notes | |---|---|---|---| +| Web persistence | Routes/services/stores | PostgreSQL adapter -> RDS | Parameterized SQL; related statements share one Pool client transaction. | +| Worker processing | Worker process | Internal Web Service `/api/internal/worker/tick` | Authenticated by internal token; Worker has no RDS credentials. | +| Schema rollout | ACK migration Job | RDS PostgreSQL | Versioned checksummed migrations under an advisory lock. | +| Readiness | ACK probe | Web `/api/ready` -> RDS | Verifies connection, 11 runtime tables, required privileges, and 2 functions. | ## State Ownership -- {state owner or persistence rule} +- Production relational state belongs to RDS PostgreSQL when `ZHINIAN_DATA_BACKEND=postgres`. +- Local JSON under the runtime directory is an explicit development/test backend, not a production fallback. +- Uploads/generated files remain runtime/object-storage state and are not made shared by the PostgreSQL migration. ## External Interfaces -- {API, file, service, or user-facing boundary} +- Alibaba Cloud RDS PostgreSQL via its internal endpoint and verified TLS CA. +- Alibaba Cloud ACK resources under `deploy/ack/`. +- Internal Worker HTTP endpoint is cluster-internal and blocked from public Ingress routing. ## Last Updated -{YYYY-MM-DD} +2026-08-12 diff --git a/.project-docs/20-architecture/module-map.md b/.project-docs/20-architecture/module-map.md index f3af847..99be425 100644 --- a/.project-docs/20-architecture/module-map.md +++ b/.project-docs/20-architecture/module-map.md @@ -4,15 +4,24 @@ | Path | Responsibility | Owner Notes | |---|---|---| +| `lib/server/database.ts` | Server-only PostgreSQL Pool, TLS, queries, transactions, readiness | Only deep database transport boundary for runtime stores. | +| `lib/server/{data-store,account-store,billing-store}.ts` | Domain persistence with PostgreSQL/local implementations | Preserve exported interfaces for callers. | +| `database/migrations/` | Immutable versioned PostgreSQL schema changes | Applied by `scripts/migrate-postgres.mjs`. | +| `scripts/postgres-client.mjs` | Validated database configuration for Node operations scripts | Shared by migration/bootstrap/import scripts. | +| `deploy/ack/` | ACK deployment resources and secret/config templates | Migration Job precedes Web/Worker rollout. | +| `app/api/ready/route.ts` | Database/schema/privilege readiness endpoint | Separate from process-level liveness. | ## Dependency Direction -- {dependency direction rule} +- Routes and services depend on store interfaces; stores depend on the shared database adapter; the adapter does not depend on domain stores. +- Worker depends on the internal Web HTTP API, not the database module. ## Risky Or Sensitive Areas -- {module or path that needs extra care} +- `database/migrations/` and the two concurrency-sensitive PostgreSQL functions. +- Account authentication/password transactions and billing wallet idempotency. +- ACK Secrets, RDS CA mounting, Ingress protection for internal Worker routes, and pool connection budgeting. ## Last Updated -{YYYY-MM-DD} +2026-08-12 diff --git a/.project-docs/20-architecture/system-overview.md b/.project-docs/20-architecture/system-overview.md index 894d903..2ae1f25 100644 --- a/.project-docs/20-architecture/system-overview.md +++ b/.project-docs/20-architecture/system-overview.md @@ -2,21 +2,30 @@ ## Current Architecture -{short description of the current system shape} +The Next.js application runs as a Web workload with a separate HTTP-polling Worker. Production server state is stored directly in PostgreSQL through a shared server-only adapter; development and tests can explicitly use local JSON. ACK deploys database migration, Web, Worker, Service, and Ingress resources separately. ## Main Components | Component | Responsibility | Notes | |---|---|---| +| Next.js Web | Browser/API routes, domain services, persistence calls, internal Worker tick endpoint | Owns the PostgreSQL pool and `/api/ready`. | +| Worker | Periodically invokes the internal Worker tick endpoint | No direct database connection or RDS Secret. | +| PostgreSQL adapter | Backend selection, Pool lifecycle, TLS, parameterized queries, transactions, readiness | Server-only module at `lib/server/database.ts`. | +| RDS PostgreSQL | Accounts, assets, jobs, usage, templates, billing state | Schema managed by versioned migrations. | +| Migration Job | Applies migrations and exact application-role privileges | Must complete before Web rollout. | +| Runtime/object storage | Uploads, generated assets, and logs | Container-local/PVC by default; use OSS/shared storage before scaling Web horizontally. | ## Important Boundaries -- {boundary that future work should respect} +- Production backend selection is explicit and fail-closed; never turn a PostgreSQL configuration failure into local JSON fallback. +- Store callers depend on stable store interfaces, not `pg` or SQL details. +- Multi-statement consistency uses one transaction client; atomic job claim and wallet posting remain database functions. +- Database credentials are injected only into Web and migration workloads; Worker uses the internal HTTP boundary. ## Related Decisions -- {ADR reference} +- `RDS-001`, `RDS-002`, `ACK-001` in the decision index. ## Last Updated -{YYYY-MM-DD} +2026-08-12 diff --git a/.project-docs/30-worklog/current-state.md b/.project-docs/30-worklog/current-state.md index 68bc5d9..d5bde32 100644 --- a/.project-docs/30-worklog/current-state.md +++ b/.project-docs/30-worklog/current-state.md @@ -4,33 +4,37 @@ This file is the integrated default-branch snapshot. Feature tasks record progre ## Integrated Through -- {source task or merge commit} +- `84d84ba94f136f10624700e8d34ed19fc6fe7fe7` (`20260812-rds-postgres-adapter-7f2c1a`) ## Current Focus -The project is currently focused on {current focus}. +The application now has a production deployment path for Alibaba Cloud ACK backed by direct Alibaba Cloud RDS PostgreSQL access. Local JSON remains an explicit development/test backend. ## Recently Completed -- {YYYY-MM-DD}: {completed work summary} +- 2026-08-12: Replaced the Supabase/PostgREST runtime path with a server-only `pg` adapter across data, account, and billing stores. +- 2026-08-12: Added versioned PostgreSQL migrations, strict backend selection, verified-CA TLS, database readiness, and ACK Web/Worker/migration manifests. ## In Progress -- {in-progress item} +- Production environment values and the real RDS/ACK rollout are not yet validated in this repository environment. ## Next Recommended Steps -1. {next recommended step} -2. {next recommended step} +1. Back up the target database; create separate migration and application roles; verify the RDS internal endpoint, VPC connectivity, whitelist, TLS mode, and CA certificate. +2. Build and push the reviewed image, run the one-shot migration Job, confirm `/api/ready`, then roll out Web and Worker. +3. Keep Web at one replica until generated assets are externalized to OSS or another shared object store. ## Open Questions / Blockers -- {open question or blocker} +- Target RDS PostgreSQL version, connection budget, endpoint, TLS enforcement, CA bundle, database roles, and ACK network policy remain deployment inputs. ## Risky Areas -- {risky area} +- Database migrations and least-privilege grants must be tested against the actual RDS instance before production cutover. +- Web pods still own runtime files; PostgreSQL does not make local uploads/generated assets safe for horizontal Web scaling. +- The current image runs as root; moving to a non-root user requires an explicit writable-path ownership design. ## Last Updated -{YYYY-MM-DD} +2026-08-12 diff --git a/.project-docs/30-worklog/task-history.md b/.project-docs/30-worklog/task-history.md index 0484e89..0a9306f 100644 --- a/.project-docs/30-worklog/task-history.md +++ b/.project-docs/30-worklog/task-history.md @@ -4,6 +4,7 @@ | Date | Task | Outcome | Docs Updated | |---|---|---|---| +| 2026-08-12 | `20260812-rds-postgres-adapter-7f2c1a` | Direct PostgreSQL/RDS persistence and ACK deployment support integrated; local JSON retained for development/tests. | Current state, architecture, data flow, module map, decisions, commitments | ## Notes diff --git a/.project-docs/30-worklog/tasks/20260812-integrate-rds-postgres-4e61c2.md b/.project-docs/30-worklog/tasks/20260812-integrate-rds-postgres-4e61c2.md new file mode 100644 index 0000000..d9ad0f2 --- /dev/null +++ b/.project-docs/30-worklog/tasks/20260812-integrate-rds-postgres-4e61c2.md @@ -0,0 +1,41 @@ +# Task: Integrate RDS PostgreSQL support into main + +## Identity + +- Task ID: 20260812-integrate-rds-postgres-4e61c2 +- Mode: Integration +- Branch: codex/20260812-integrate-rds-postgres-4e61c2-integrate-rds-postgres-4e61c2 +- Worktree: D:\Datas\OthersProjects\NianAIGC-integration-rds-4e61c2 +- Base commit: 84d84ba94f136f10624700e8d34ed19fc6fe7fe7 +- Owner: codex +- Status: Planning + +## Scope + +- Integrate feature commit `84d84ba94f136f10624700e8d34ed19fc6fe7fe7` into the default branch. +- Promote the completed RDS/ACK task's durable backend, migration, workload, and operational boundaries into canonical project memory. +- Preserve the pre-existing project-document initialization in the occupied `main` worktree without adopting unrelated application changes. + +## Intent And Constraints + +- Use an exclusively owned integration worktree and repository integration lock. +- Do not overwrite or delete the untracked `.project-docs` files in the occupied `main` worktree unless byte-equivalence with the committed initialization baseline is verified. +- Record only confirmed RDS/ACK architecture and deployment facts; leave unrelated placeholder project positioning/domain memory untouched. +- Keep live RDS migration, Docker runtime, and ACK rollout explicitly unverified. + +## Outcome + +- Integration in progress. + +## Verification + +- Source feature commit `84d84ba` is present and based directly on `main` through initialization commit `0bcb149`. +- Source task final and incremental Sol reviews returned `PASS`. + +## Follow-ups + +- None recorded. + +## Promotion Candidates + +- None recorded. diff --git a/.project-docs/80-commitments/commitments.md b/.project-docs/80-commitments/commitments.md index ae3d12c..0d45ca7 100644 --- a/.project-docs/80-commitments/commitments.md +++ b/.project-docs/80-commitments/commitments.md @@ -4,6 +4,9 @@ Track future-facing memory: promised follow-ups, unfinished loops, timed checks, | Date | Commitment | Trigger / Due | Owner | Status | Next Action | |---|---|---|---|---|---| +| 2026-08-12 | Validate migration, TLS, permissions, and readiness against the real Alibaba Cloud RDS instance. | Before production cutover | Deployment owner | Open | Back up RDS, provision roles/CA/network access, then run the one-shot migration Job. | +| 2026-08-12 | Keep Web at one replica until generated assets use OSS or another shared store. | Before raising Web replicas | Deployment owner | Open | Configure and validate external object storage. | +| 2026-08-12 | Harden the runtime image to non-root after writable paths are designed. | Security hardening follow-up | Application owner | Open | Define ownership for runtime and settings paths, then update Docker/ACK security context. | ## Use