From eacb4c67def1af1de1f76669a00e4170afbb5392 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=99=88=E5=AE=97=E7=90=A6?= <442782435@qq.com> Date: Fri, 14 Aug 2026 07:19:41 +0800 Subject: [PATCH] docs: reconcile canonical memory with merged Go backend --- .project-docs/00-brief/project-positioning.md | 22 +++++--- .project-docs/00-brief/success-criteria.md | 12 +++-- .../10-decisions/adr-003-next-go-target.md | 2 +- .project-docs/10-decisions/decision-index.md | 2 +- .project-docs/20-architecture/data-flow.md | 6 +-- .project-docs/20-architecture/module-map.md | 31 ++++++----- .../20-architecture/system-overview.md | 31 ++++++----- .project-docs/30-worklog/current-state.md | 25 +++++---- .project-docs/30-worklog/task-history.md | 9 +++- .../20260814-go-memory-reconcile-7f2a9c41.md | 52 +++++++++++++++++++ .project-docs/40-domain/business-rules.md | 16 ++++-- .project-docs/40-domain/glossary.md | 12 +++++ .project-docs/80-commitments/commitments.md | 4 +- .project-docs/90-maintenance/stale-items.md | 4 +- 14 files changed, 171 insertions(+), 57 deletions(-) create mode 100644 .project-docs/30-worklog/tasks/20260814-go-memory-reconcile-7f2a9c41.md diff --git a/.project-docs/00-brief/project-positioning.md b/.project-docs/00-brief/project-positioning.md index a9347d6..3e2f0db 100644 --- a/.project-docs/00-brief/project-positioning.md +++ b/.project-docs/00-brief/project-positioning.md @@ -2,28 +2,36 @@ ## One-line Positioning -This project is {one-line project positioning}. +智念AIGC平台 (Zhinian AIGC Platform) is a production-deployable Web workbench for AI image and video creation with organization accounts, usage tracking, and billing. ## Primary Goal -The project exists to {primary project goal}. +The project exists to give organizations an Alibaba Cloud ACK-deployable AI creation platform: prompt authoring, material upload, image generation (即梦/Jimeng 4.6 and EvoLink GPT Image 2), video generation (Seedance 2.0), task management, result download, account and role management, usage reporting, and organization billing backed by direct RDS PostgreSQL persistence. ## Target Users / Consumers -- {primary user or consumer} +- Ordinary organization members: create images and videos, manage their own account and password. +- Organization administrators: manage members, organizations, and engine settings. +- Super administrators: own pricing rules, wallets, ledger adjustments, and platform logs. +- External partner systems: consume the API-key authenticated public `/api/v1` surface. ## Non-goals -This project does not aim to {non-goal or boundary}. +- This project does not aim to be a model-training, dataset, or labeling platform. +- It is not a public social sharing site; assets stay account and organization scoped. +- In the current version it is not a horizontally auto-scaled multi-region SaaS: one Web replica until generated assets move to shared OSS. ## Core Constraints -- {core constraint} +- Same-origin browser authentication through signed, chunked `zhinian_session` cookies with per-request account/organization/sessionVersion revalidation. +- Production persistence fails closed: explicit RDS PostgreSQL through a server-only adapter; local JSON is development/test only. +- Cross-instance concurrency stays in PostgreSQL: `claim_generation_jobs` for job claims and `billing_post_wallet_entry` for wallet idempotency; no process-local lock replacements. +- Chinese-first product surfaces; production deployment targets Alibaba Cloud ACK. ## Quality Bar -A good solution should {quality bar}. +A good solution should preserve current HTTP/Cookie/authorization behavior, keep provider, billing, and storage semantics idempotent and tenant-scoped, pass the executable contract tests under `contracts/`, and remain reversible through a single-writer cutover. ## Last Reviewed -{YYYY-MM-DD} +2026-08-14 diff --git a/.project-docs/00-brief/success-criteria.md b/.project-docs/00-brief/success-criteria.md index c43c6a4..8da1683 100644 --- a/.project-docs/00-brief/success-criteria.md +++ b/.project-docs/00-brief/success-criteria.md @@ -2,16 +2,20 @@ ## Project Success -- {observable project-level success condition} +- Production cutover of the Go backend passes the executable contract suites under `contracts/` with real RDS/OSS/provider/Webhook dependencies, without visible user-facing behavior change. ## Task Completion Standard -- {condition that means a task is complete} +- A task is complete when the Concurrent Task Gate and Planning Gate passed, the implementation meets its scope and constraints, verification commands pass, the task record is updated with outcome and promotion candidates, the drift check passes, and ownership is released from a clean worktree. ## Quality Checks -- {verification command, review expectation, or acceptance check} +- `npm test` (full Vitest suite), `npx tsc --noEmit`, and `npm run build` pass. +- `go test -count=1 ./...` and `go vet ./...` pass for backend changes. +- `node scripts/check-ack-manifests.mjs` and `npm run deploy:check` pass for deployment changes. +- `check_project_docs.py` and `check_doc_drift.py --task-id ` pass for documentation changes. +- Diff hygiene: no generated binaries, secrets, or unrelated files committed. ## Last Reviewed -{YYYY-MM-DD} +2026-08-14 diff --git a/.project-docs/10-decisions/adr-003-next-go-target.md b/.project-docs/10-decisions/adr-003-next-go-target.md index 2f34d3b..208451c 100644 --- a/.project-docs/10-decisions/adr-003-next-go-target.md +++ b/.project-docs/10-decisions/adr-003-next-go-target.md @@ -2,7 +2,7 @@ ## Status -Accepted target; implementation pending +Accepted target; Go implementation merged into `main` on 2026-08-14 (see `.project-docs/30-worklog/current-state.md`); deployment and traffic cutover pending ## Date diff --git a/.project-docs/10-decisions/decision-index.md b/.project-docs/10-decisions/decision-index.md index bbd46c2..d49d12c 100644 --- a/.project-docs/10-decisions/decision-index.md +++ b/.project-docs/10-decisions/decision-index.md @@ -7,7 +7,7 @@ | 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. | -| ADR-003 | Target architecture is a same-origin Next.js frontend plus Go modular-monolith backend with an initially embedded WorkerLoop. | Accepted target; implementation pending | 2026-08-12 | Application and ACK architecture | Current ACK-001 topology remains authoritative until code migration and cutover pass the required compatibility tests. See `adr-003-next-go-target.md`. | +| ADR-003 | Target architecture is a same-origin Next.js frontend plus Go modular-monolith backend with an initially embedded WorkerLoop. | Accepted target; Go implementation merged into `main` 2026-08-14; deployment/cutover pending | 2026-08-12 | Application and ACK architecture | Current ACK-001 topology remains authoritative until code migration and cutover pass the required compatibility tests. See `adr-003-next-go-target.md`. | ## Superseded Decisions diff --git a/.project-docs/20-architecture/data-flow.md b/.project-docs/20-architecture/data-flow.md index cadefc8..a2ce4bf 100644 --- a/.project-docs/20-architecture/data-flow.md +++ b/.project-docs/20-architecture/data-flow.md @@ -11,7 +11,7 @@ ## Approved Target Flows -These flows become active only after ADR-003 is implemented: +The Go implementation for these flows is merged into `main` under `backend/`; they become active only after the single-writer deployment cutover routes traffic to Go and drains the Node Worker: | Flow | Source | Destination | Required behavior | |---|---|---|---| @@ -34,8 +34,8 @@ These flows become active only after ADR-003 is implemented: - Alibaba Cloud ACK resources under `deploy/ack/`. - Internal Worker HTTP endpoint is cluster-internal and blocked from public Ingress routing. -In the approved target, the internal Worker HTTP endpoint is removed only after the Node Worker is drained and the Go WorkerLoop is verified. It remains part of the current implementation until that cutover. +In the approved target, the internal Worker HTTP endpoint is removed only after the Node Worker is drained and the Go WorkerLoop is verified. It remains part of the deployed implementation until that cutover. ## Last Updated -2026-08-12 +2026-08-14 diff --git a/.project-docs/20-architecture/module-map.md b/.project-docs/20-architecture/module-map.md index 0fb2431..8d3e08b 100644 --- a/.project-docs/20-architecture/module-map.md +++ b/.project-docs/20-architecture/module-map.md @@ -6,29 +6,35 @@ |---|---|---| | `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`. | +| `database/migrations/` | Immutable versioned PostgreSQL schema changes | Applied by `scripts/migrate-postgres.mjs`; 0001 initial schema, 0002 generation lifecycle fencing. | | `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. | +| `deploy/ack/` | ACK deployment resources and secret/config templates | Migration Job precedes Web/Worker rollout; Go ownership changes wait for cutover. | | `app/api/ready/route.ts` | Database/schema/privilege readiness endpoint | Separate from process-level liveness. | +| `backend/cmd/zhinian-api` | Go application entrypoint, configuration, HTTP server composition, readiness | Locally runnable; production routing still owned by Next.js. | +| `backend/internal/*` | ADR-003 deep modules and adapters, 18 packages: `identity`, `administration`, `assets`, `billing`, `usage`, `jobs`, `providers`, `webhook`, `httpapi`, `publicapi`, `application`, `orchestration`, `postgres`, `localstore`, `logging`, `settings`, `templates`, `prompt` | Merged into `main`; unrouted until cutover. | +| `contracts/**/*.json` | Language-neutral HTTP/Cookie/auth/jobs/billing/storage/webhook contract fixtures | Shared acceptance source for TypeScript and Go consumers. | ## Dependency Direction - 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. +- Go modules depend on the PostgreSQL transport and storage/provider adapters; `httpapi`/`publicapi` depend on deep modules, never the reverse. ## Approved Target Module Map -The target below is a design contract, not current source layout: +The target below is implemented in `backend/internal/` and merged into `main`; deployment and traffic cutover remain pending: -| Target Module | Interface | Implementation notes | +| Target Module | Go package | Implementation notes | |---|---|---| -| Next.js frontend | Pages, SSR, and same-origin browser calls | Forwards Cookie/request context to Go; no direct persistence or domain ownership. | -| Go Identity | Login/logout/session/password/authorization | Preserves the current signed chunked Cookie and per-request account/organization/sessionVersion validation. | -| Go Administration | Organizations, accounts, settings visibility, logs, administrative usage | Enforces current super-admin and organization-admin rules. | -| Go Assets | Register/upload/list/get/delete/download | Uses object-storage Adapter; preserves owner-scoped 404 and storage metadata. | -| Go Jobs | Submit/query/cancel/retry/claim/execute/terminal transitions/Webhooks | Uses the PostgreSQL claim function and hides provider/retry/refund state. | -| Go Billing | Quote/wallet/ledger/price/charge/refund/settlement | Uses the PostgreSQL wallet function and integer-fen arithmetic. | -| Go Usage | Platform/public attribution and usage records | Retains organization/account context and job uniqueness. | +| Next.js frontend | (Next.js, unchanged) | Forwards Cookie/request context to Go; no direct persistence or domain ownership after cutover. | +| Go Identity | `internal/identity` | Login/logout/session/password/authorization; preserves the signed chunked Cookie and per-request account/organization/sessionVersion validation. | +| Go Administration | `internal/administration` | Organizations, accounts, settings visibility, logs, administrative usage; enforces super-admin and organization-admin rules. | +| Go Assets | `internal/assets` | Register/upload/list/get/delete/download; uses object-storage Adapter; preserves owner-scoped 404 and storage metadata. | +| Go Jobs | `internal/jobs` | Submit/query/cancel/retry/claim/execute/terminal transitions/Webhooks; uses the PostgreSQL claim function and hides provider/retry/refund state. | +| Go Billing | `internal/billing` | Quote/wallet/ledger/price/charge/refund/settlement; uses the PostgreSQL wallet function and integer-fen arithmetic. | +| Go Usage | `internal/usage` | Platform/public attribution and usage records; retains organization/account context and job uniqueness. | +| Compatibility HTTP | `internal/httpapi`, `internal/publicapi` | Preserve current browser and public `/api/v1` paths, JSON shapes, status codes, and auth boundaries. | +| Infrastructure seams | `internal/postgres`, `internal/localstore`, `internal/providers`, `internal/webhook`, `internal/orchestration`, `internal/application`, `internal/logging` | PostgreSQL transport, storage adapters, provider adapters, webhook delivery, embedded WorkerLoop orchestration, application composition, streamed event logging. | Real internal seams are PostgreSQL transport, object storage, generation providers, and deterministic test dependencies. Avoid one shallow repository Interface per table. @@ -37,7 +43,8 @@ Real internal seams are PostgreSQL transport, object storage, generation provide - `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. +- `backend/internal/{postgres,jobs,billing}`: claim and wallet correctness across Go replica scaling until WorkerLoop concurrency is deliberate. ## Last Updated -2026-08-12 +2026-08-14 diff --git a/.project-docs/20-architecture/system-overview.md b/.project-docs/20-architecture/system-overview.md index 8592a2b..ef4a95e 100644 --- a/.project-docs/20-architecture/system-overview.md +++ b/.project-docs/20-architecture/system-overview.md @@ -2,34 +2,36 @@ ## Current Architecture -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. +The deployed production architecture is the Next.js Web workload plus a separate HTTP-polling Node 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. -This remains the implemented and deployable architecture. No Go backend code or Go deployment resources have been integrated. +ADR-003's Go backend is implemented and merged into `main` under `backend/` (see the Module Map), but no Go workload is deployed and no production traffic is routed to it. Until the single-writer cutover passes its compatibility checks, the Next.js/Node topology above remains the deployed and authoritative truth. ## Approved Target Architecture The accepted target in ADR-003 is a same-origin Next.js frontend plus Go modular-monolith backend: -| Target component | Responsibility | Constraint | -|---|---|---| -| Next.js frontend | Pages, static assets, SSR, browser UI | Calls Go over HTTP; no RDS/provider/OSS/business Secret. | -| Go backend | Existing HTTP/file contracts, identity, administration, assets, jobs, billing, usage, providers, storage, Webhooks, readiness | Owns relational access and initially embeds WorkerLoop. | -| RDS PostgreSQL | Relational state and cross-instance concurrency | Retains versioned migrations and both concurrency-sensitive database functions. | -| Migration Job | Schema and application-role grants | Remains one-shot and separate from long-lived workloads. | -| Alibaba Cloud OSS | Shared generated/uploaded assets | Must be production-ready before horizontal workload scaling. | +| Target component | Responsibility | Constraint | Implementation state | +|---|---|---|---| +| Next.js frontend | Pages, static assets, SSR, browser UI | Calls Go over HTTP; no RDS/provider/OSS/business Secret. | Existing; unchanged until cutover. | +| Go backend | Existing HTTP/file contracts, identity, administration, assets, jobs, billing, usage, providers, storage, Webhooks, readiness | Owns relational access and initially embeds WorkerLoop. | Implemented in `backend/` and merged; unrouted in production. | +| RDS PostgreSQL | Relational state and cross-instance concurrency | Retains versioned migrations and both concurrency-sensitive database functions. | Production database; migrations 0001/0002 apply at rollout. | +| Migration Job | Schema and application-role grants | Remains one-shot and separate from long-lived workloads. | Existing Job; migration 0002 included. | +| Alibaba Cloud OSS | Shared generated/uploaded assets | Must be production-ready before horizontal workload scaling. | Still behind a storage Adapter; not validated against real OSS. | -Ingress will eventually route page/static paths to Next.js and `/api`, `/uploads`, and `/generated-results` to Go. The initial target remains two long-lived Pods (`Next x1 + Go x1`). This target is not yet implemented. +Ingress will eventually route page/static paths to Next.js and `/api`, `/uploads`, and `/generated-results` to Go. The initial target remains two long-lived Pods (`Next x1 + Go x1`). The Go implementation is complete and merged; deployment and traffic cutover are not. ## 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`. | +| Next.js Web | Browser/API routes, domain services, persistence calls, internal Worker tick endpoint | Owns the PostgreSQL pool and `/api/ready` until cutover. | | 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. | +| Go backend | `cmd/zhinian-api` plus 18 `internal/` packages: identity, administration, assets, billing, usage, jobs, providers, webhook, httpapi, publicapi, application, orchestration, postgres, localstore, logging, settings, templates, prompt | Merged into `main`; locally runnable and contract-tested; unrouted in production. | +| Contract fixtures | Language-neutral JSON contracts for auth, admin, assets, billing, http, jobs, logs, providers, settings, usage, webhook under `contracts/` | Shared executable acceptance source for TypeScript and Go consumers. | +| RDS PostgreSQL | Accounts, assets, jobs, usage, templates, billing state | Schema managed by versioned migrations (0001, 0002). | | 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. | +| Runtime/object storage | Uploads, generated assets, and logs | Container-local/PVC by default; use OSS/shared storage before scaling horizontally. | ## Important Boundaries @@ -37,6 +39,7 @@ Ingress will eventually route page/static paths to Next.js and `/api`, `/uploads - 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. +- The merged Go implementation must not be routed in production before the cutover review; Next Route Handlers, Secrets, and ACK manifests stay under their current owners until then. ## Related Decisions @@ -45,4 +48,4 @@ Ingress will eventually route page/static paths to Next.js and `/api`, `/uploads ## Last Updated -2026-08-12 +2026-08-14 diff --git a/.project-docs/30-worklog/current-state.md b/.project-docs/30-worklog/current-state.md index 590fe94..294321e 100644 --- a/.project-docs/30-worklog/current-state.md +++ b/.project-docs/30-worklog/current-state.md @@ -8,39 +8,46 @@ This file is the integrated default-branch snapshot. Feature tasks record progre - `79d29bb` (cross-platform ACK manifest validation fix) - `4485899` (task-scoped Next.js frontend plus Go backend target design and explicit not-implemented progress record) - `064e155` (canonical ADR-003, architecture, current-state, history, and commitment promotion) +- `b8db39d` (merge of `aef5a97` — completed Go backend modules: foundation, identity, current-session, password lifecycle, plus remaining modules; tasks `20260812-go-migration-foundation-b74c9e21`, `20260813-go-identity-vertical-c4e91a72`, `20260813-go-auth-me-http-8d6f3a21`, `20260813-go-auth-lifecycle-3f9a6c12`, `20260813-go-remaining-modules-7d3a9e42`) +- `d0fb346` (merge of `c1cbd78` — Go backend implementation, contract fixtures, migration 0002, and task-scoped records into `main`; tasks `20260813-go-remaining-modules-7d3a9e42` and `20260814-go-remaining-integration-5e7c9a1b`) +- `f10cdd9` (record of completed task `20260812-architecture-task-breakdown-a83f61c2`) ## Current Focus -The implemented application 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. ADR-003 now records the approved future Next.js frontend plus Go modular-monolith backend, but no Go implementation has been merged. +ADR-003's Go modular-monolith backend is implemented and merged into `main` under `backend/`: `cmd/zhinian-api` plus 18 `internal/` packages (154 Go files), 24 language-neutral contract fixtures under `contracts/`, and lifecycle-fencing migration `0002_generation_lifecycle_fencing.sql`. The deployed production architecture remains the Next.js full-stack Web plus HTTP-polling Node Worker (ACK-001): no Go traffic cutover, Next Route Handler deletion, or manifest/Secret ownership change has happened, and no Go workload is deployed. ## Recently Completed - 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. -- 2026-08-12: Accepted and documented the Next.js frontend plus Go backend target, migration contracts, and acceptance criteria. Implementation was explicitly deferred; interrupted code drafts were discarded. +- 2026-08-12: Accepted and documented the Next.js frontend plus Go backend target, migration contracts, and acceptance criteria. +- 2026-08-14: Implemented and merged the Go backend (foundation, identity, administration, assets, billing, usage, jobs/providers/webhooks/worker loop, public and compatibility HTTP surfaces) with language-neutral contract fixtures and migration 0002. +- 2026-08-14: Reconciliated canonical architecture, decision, history, commitment, and positioning memory with the merged Go implementation (task `20260814-go-memory-reconcile-7f2a9c41`). ## In Progress -- Production environment values and the real RDS/ACK rollout are not yet validated in this repository environment. -- The Go backend migration has not started. Current code remains Next.js full-stack plus the HTTP-polling Node Worker under ACK-001. +- None. All Go implementation feature tasks are merged; five feature worktrees remain `ready_for_integration` with completed records and can be released after review. ## Next Recommended Steps -1. Before any Go implementation, turn the ADR-003 compatibility requirements into executable HTTP, Cookie, tenant, job, billing, storage, and Webhook contracts. -2. For the current implementation, back up RDS; verify roles, internal networking, TLS and CA; then run the reviewed migration/Web/Worker rollout if production deployment proceeds before the Go migration. -3. Keep the current Web at one replica until generated assets are externalized to OSS or another shared object store. +1. Validate the merged Go backend against a non-production RDS instance (real application role, verified-CA TLS), real OSS, provider credentials, external Webhooks, and production-like Worker recovery before any Go traffic cutover. +2. Obtain the product/release decisions deferred by ADR-003: parse existing `zhinian_session` cookies without logout versus one-time global re-login, and the public `/api/v1` compatibility promise. +3. After validation, plan the single-writer cutover: route `/api`, `/uploads`, and `/generated-results` to Go, drain and stop the Node Worker, and only then delete Next Route Handlers and relocate RDS/provider/OSS Secrets and ACK manifests. +4. Release the five completed Go feature worktrees once their records and merges are confirmed. ## Open Questions / Blockers - Target RDS PostgreSQL version, connection budget, endpoint, TLS enforcement, CA bundle, database roles, and ACK network policy remain deployment inputs. -- Go implementation still needs a deliberate decision on whether to parse existing `zhinian_session` cookies without logout, plus measured API/backlog data before any later Worker split. +- Go Cookie compatibility (no-logout parsing versus forced re-login) still needs a product decision. +- Public `/api/v1` compatibility obligations for the cutover need explicit confirmation. ## Risky Areas - 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. +- The merged Go code is contract-tested but unrouted; parity gaps can only surface under real provider, OSS, RDS, and Webhook traffic. ## Last Updated -2026-08-12 +2026-08-14 diff --git a/.project-docs/30-worklog/task-history.md b/.project-docs/30-worklog/task-history.md index bdb7895..b03e177 100644 --- a/.project-docs/30-worklog/task-history.md +++ b/.project-docs/30-worklog/task-history.md @@ -6,7 +6,14 @@ |---|---|---|---| | 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 | | 2026-08-12 | `20260812-go-backend-migration-6f4a92` | Accepted the Next.js frontend plus Go backend target and recorded migration/acceptance contracts; no application code implemented. | ADR-003, current state, architecture, data flow, module map | +| 2026-08-14 | `20260812-go-migration-foundation-b74c9e21` | Go compatibility foundation (health/readiness, configuration, PostgreSQL transport, identity seams) merged into `main`. | Task record | +| 2026-08-14 | `20260813-go-identity-vertical-c4e91a72` | Database-refreshed Go identity authorization vertical slice merged into `main`. | Task record | +| 2026-08-14 | `20260813-go-auth-me-http-8d6f3a21` | Go current-session HTTP adapter merged into `main`. | Task record | +| 2026-08-14 | `20260813-go-auth-lifecycle-3f9a6c12` | Go password session lifecycle vertical slice merged into `main`. | Task record | +| 2026-08-14 | `20260813-go-remaining-modules-7d3a9e42` | Remaining Go modules (administration, assets, billing, usage, jobs/providers/webhooks/worker loop, HTTP surfaces), language-neutral contract fixtures, and migration 0002 merged into `main`. | Task record | +| 2026-08-14 | `20260814-go-remaining-integration-5e7c9a1b` | Serialized Integration Gate merging the completed Go remaining modules into `main`. | Task record | +| 2026-08-14 | `20260814-go-memory-reconcile-7f2a9c41` | Reconciled canonical architecture, decisions, history, commitments, positioning, domain, and success-criteria memory with the merged Go backend. | Current state, system overview, module map, data flow, decision index, ADR-003, migration proposal, commitments, positioning, business rules, glossary, success criteria | ## Notes -This is legacy integrated history. Feature tasks must not append here. Record new work in `30-worklog/tasks/{task_id}.md`; an integration workflow may render or summarize accepted history later. +This is legacy integrated history. Feature tasks must not append here. Record new work in `30-worklog/tasks/{task_id}.md`; an integration workflow may render or summarize accepted history later. The Go migration rows were appended during the 2026-08-14 integration gate. diff --git a/.project-docs/30-worklog/tasks/20260814-go-memory-reconcile-7f2a9c41.md b/.project-docs/30-worklog/tasks/20260814-go-memory-reconcile-7f2a9c41.md new file mode 100644 index 0000000..79a385c --- /dev/null +++ b/.project-docs/30-worklog/tasks/20260814-go-memory-reconcile-7f2a9c41.md @@ -0,0 +1,52 @@ +# Task: Reconcile canonical memory with merged Go backend + +## Identity + +- Task ID: 20260814-go-memory-reconcile-7f2a9c41 +- Mode: Integration +- Branch: main +- Worktree: /Users/brother7/Documents/AI/NianAIGC +- Base commit: f10cdd9695db37b9f306b6353f0e2a7a4c9fd991 +- Owner: dsh +- Status: Ready for Integration + +## Scope + +- Reconcile canonical `.project-docs` memory with the Go backend implementation merged into `main` by `b8db39d` and `d0fb346`. +- Promote the pending promotion candidates of tasks `20260813-go-remaining-modules-7d3a9e42` and `20260814-go-remaining-integration-5e7c9a1b` (Go module map and contract fixtures) into canonical architecture memory. +- Repair stale canonical documents that still described the Go migration as not started. +- Complete task-lifecycle housekeeping: commit the untracked record of `20260812-architecture-task-breakdown-a83f61c2`, correct its Status, and release its stale ownership of `main`. + +## Intent And Constraints + +- Record factual implementation progress; do not claim a production cutover that has not happened. ACK-001 remains the deployed truth. +- Do not reverse or weaken accepted decisions (RDS-001, RDS-002, ACK-001, ADR-003). +- Fill template files only from facts already present in the repository (READMEs, task records, contracts, migrations); keep unknowns explicit. +- Feature task records of the source tasks stay read-only; only my own integration record and canonical documents change. + +## Outcome + +- Updated `current-state.md` with `Integrated Through` entries for `b8db39d`, `d0fb346`, and `f10cdd9`, current focus (implemented but unrouted Go backend), next steps, open questions, and risky areas. +- Updated `system-overview.md`, `module-map.md`, and `data-flow.md` to describe the merged Go implementation while keeping the deployed Next.js/Node topology authoritative until cutover. +- Updated `decision-index.md` (ADR-003 row), `adr-003-next-go-target.md` Status, and the migration proposal implementation/canonical-promotion lines. +- Appended the six Go migration tasks to `task-history.md`. +- Updated `commitments.md`: marked the pre-implementation contract commitment completed and added cutover-validation and Cookie/`/api/v1` decision commitments. +- Filled the placeholder templates `project-positioning.md`, `business-rules.md`, `glossary.md`, `success-criteria.md`, and `stale-items.md` missing context from repository facts. +- Committed the completed record of task `20260812-architecture-task-breakdown-a83f61c2` (Status corrected to Ready for Integration) as `f10cdd9` and released its stale ownership of the main worktree. + +## Verification + +- Verified merge topology: `b8db39d` (merge of `aef5a97`) and `d0fb346` (merge of `c1cbd78` into main at `7de3300`; 219 files, +32465/-23). +- Verified repository facts used in the docs: 154 Go files under `backend/`, 18 `internal/` packages, 24 contract fixtures under `contracts/`, migrations 0001/0002. +- `check_project_docs.py` passes; `check_doc_drift.py --task-id 20260814-go-memory-reconcile-7f2a9c41` passes. +- No application, database, test, or deployment file was changed. + +## Follow-ups + +- Five completed Go feature worktrees remain owned and `ready_for_integration`; release them after their records and merges are confirmed. +- Root `README.md`/`README.zh-CN.md` tech-stack sections still describe only the Next.js stack; update when the Go backend becomes deployed. +- Real RDS/OSS/provider/Webhook validation and the cutover plan remain open (see `commitments.md` and `current-state.md`). + +## Promotion Candidates + +- None beyond what this integration task already applied; no canonical changes remain pending from the merged Go tasks. diff --git a/.project-docs/40-domain/business-rules.md b/.project-docs/40-domain/business-rules.md index 7bef29f..4c9fa0e 100644 --- a/.project-docs/40-domain/business-rules.md +++ b/.project-docs/40-domain/business-rules.md @@ -2,12 +2,22 @@ ## Durable Rules -- {business or product rule} +- Production data backend selection is explicit and fail-closed: a PostgreSQL configuration failure must never silently fall back to local JSON. +- Billing amounts use integer-fen arithmetic; wallet balance enforcement and ledger insertion happen inside the PostgreSQL `billing_post_wallet_entry` function. +- Job claiming uses the PostgreSQL `claim_generation_jobs` function (`FOR UPDATE SKIP LOCKED`, lease, stale recovery); Go process-local locks must never replace it. +- Ordinary members cannot submit generation when the organization balance is insufficient; submission is rejected before provider dispatch. +- Super administrators calculate and record generation cost without checking, freezing, or refunding organization quota. +- All new organization balance entries are organization-owned; generation charge/refund entries keep member attribution for consumption reporting. +- Logged-in users may change their own password; account management and organization member actions require admin roles. +- Public `/api/v1` access authenticates with API keys and stays outside browser SSO middleware; API data is partitioned by the API account owner. +- Database schema changes ship as versioned, checksummed, advisory-locked one-shot migrations; they never run in each Web pod init container. +- Generated and uploaded assets remain runtime/object-storage state; PostgreSQL does not make them shared for horizontal scaling. ## Open Questions -- {rule that needs human confirmation} +- Whether Go must parse existing `zhinian_session` cookies without logout, or a one-time global re-login is acceptable at cutover. +- The exact public `/api/v1` compatibility promise to preserve during and after the Go cutover. ## Last Reviewed -{YYYY-MM-DD} +2026-08-14 diff --git a/.project-docs/40-domain/glossary.md b/.project-docs/40-domain/glossary.md index 9b02844..87a43c5 100644 --- a/.project-docs/40-domain/glossary.md +++ b/.project-docs/40-domain/glossary.md @@ -2,3 +2,15 @@ | Term | Meaning | Notes | |---|---|---| +| 素材 / Material | Uploaded source content referenced in prompts as `@图片1`, `@视频1`, `@音频1`. | Uploads become assets under the authenticated owner. | +| Asset | Stored upload or generated result with metadata and owner scope. | Owner-scoped not-found behavior (404) is a compatibility contract. | +| Generation job / Task | Async unit of image or video generation: submit, claim, execute, poll provider, terminal transition, optional Webhook. | Claimed via `claim_generation_jobs`; idempotent per provider task id. | +| Wallet | Organization balance with immutable ledger entries. | Posted atomically via `billing_post_wallet_entry`; integer-fen arithmetic. | +| Ledger | Append-only record of wallet movements (charge, refund, settlement, adjustment). | Replayable for reconciliation. | +| Quote | Server-side estimate for a generation request using the matched billing rule and parameter tiers. | Preview is quote-only; submission is balance-gated. | +| Engine / Provider | External generation service: 即梦 (Jimeng), EvoLink GPT Image 2, Seedance 2.0, Bailian. | Adapters isolate provider payloads and status mapping. | +| Worker | Process that periodically calls the internal Worker tick endpoint to claim and execute jobs. | Node Worker has no RDS credentials; Go embeds a WorkerLoop after cutover. | +| WorkerLoop | Embedded async task loop inside the Go backend. | Replaces the HTTP-polling Node Worker only after drain and verification. | +| Cutover | Single-writer routing of `/api`, `/uploads`, `/generated-results` to Go, Node Worker drain, then Next Route Handler deletion. | Must stay reversible; ACK-001 remains truth until it passes. | +| Contract fixture | Language-neutral JSON contract under `contracts/` for HTTP, Cookie, auth, jobs, billing, storage, Webhook behavior. | Executable by both TypeScript and Go consumers. | +| `zhinian_session` | Signed (HMAC-SHA256), chunked (3000 chars, up to 20 chunks) session cookie. | `HttpOnly`, `SameSite=Lax`, `Path=/`, production `Secure`. | diff --git a/.project-docs/80-commitments/commitments.md b/.project-docs/80-commitments/commitments.md index 094bca4..855d7f5 100644 --- a/.project-docs/80-commitments/commitments.md +++ b/.project-docs/80-commitments/commitments.md @@ -7,7 +7,9 @@ Track future-facing memory: promised follow-ups, unfinished loops, timed checks, | 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. | -| 2026-08-12 | Implement ADR-003 only after executable compatibility contracts exist. | Before starting the Go migration | Application owner | Open | Add golden tests for HTTP/Cookie/authorization/jobs/billing/storage/Webhooks, then implement vertical slices with single-writer cutover. | +| 2026-08-12 | Implement ADR-003 only after executable compatibility contracts exist. | Before starting the Go migration | Application owner | Completed | Contracts exist under `contracts/`; Go implementation merged 2026-08-14. | +| 2026-08-14 | Validate the merged Go backend against non-production RDS, real OSS, provider credentials, external Webhooks, and production-like Worker recovery before any Go traffic cutover. | Before Go cutover | Deployment owner | Open | Stand up non-production RDS/OSS and run the contract and recovery suites against the Go binary. | +| 2026-08-14 | Decide Cookie cutover behavior (parse existing `zhinian_session` without logout vs. one-time global re-login) and confirm the public `/api/v1` support promise. | Before freezing cutover contracts | Product owner | Open | Product/release decision with explicit re-login or no-logout announcement. | ## Use diff --git a/.project-docs/90-maintenance/stale-items.md b/.project-docs/90-maintenance/stale-items.md index 8a90f3a..af06b72 100644 --- a/.project-docs/90-maintenance/stale-items.md +++ b/.project-docs/90-maintenance/stale-items.md @@ -9,7 +9,9 @@ This is the integrated registry of stale or conflicting canonical memory. Update ## Missing Context -- {missing information that affects future planning} +- RDS deployment inputs (target version, connection budget, endpoint, TLS/CA bundle, database roles, ACK network policy) — needed before production validation. +- Go Cookie compatibility decision (no-logout parsing versus forced re-login) and the public `/api/v1` support promise — needed before freezing cutover contracts. +- Real OSS bucket/credential configuration — needed before horizontal scaling or Go asset validation. ## Feature Task Routing