wangxuming/NianAIGC
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: reconcile canonical memory with merged Go backend

Browse Source
This commit is contained in:
zn-admin committed 2026-08-14 07:19:41 +08:00
1 parent f10cdd9695
commit eacb4c67de
14 files changed
+171 -57
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.project-docs/20-architecture/data-flow.md
+3 -3
View File
@@ -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
.project-docs/20-architecture/module-map.md
+19 -12
View File
@@ -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
.project-docs/20-architecture/system-overview.md
+17 -14
View File
@@ -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