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

docs: integrate static frontend architecture

Browse Source
This commit is contained in:
brother7 committed 2026-08-16 21:02:42 +08:00
1 parent b14b4fced7
commit bb50d06d1d
13 files changed
+243 -82
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.project-docs/20-architecture/data-flow.md
+23 -13
View File
@@ -1,28 +1,35 @@
# Data Flow
## Local Full-Stack Flows
## Development Flows
These repository flows remain available for local development and do not establish which Service currently owns a path in the live production cluster.
`next dev` serves the page development loop; runtime API behavior still belongs
to a separately running Go backend or an equivalent same-origin development
proxy. Legacy TypeScript server adapters remain unreferenced cleanup candidates
and are not a supported production path.
| 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. |
| Browser UI development | Browser | Next dev page server | Pages/components only; no Next API or Middleware. |
| Runtime API development | Browser/tooling | Go HTTP server | Same contracts as production; Go localstore is explicit non-production mode. |
| Schema rollout | Manual SQL execution by the deployment operator | RDS PostgreSQL | Versioned checksummed files under `database/migrations/`; 0001 then 0002, then application-role grants. |
| Readiness | ACK probe | Web `/api/ready` -> RDS | Verifies connection, 11 runtime tables, required privileges, and 2 functions. |
## Approved Target Flows
The Go implementation and desired ACK routing for these flows are present in the repository. Production is already online, but its exact live Service ownership has not been confirmed from cluster configuration or logs:
The implementation and desired ACK routing are present in `b14b4fc`.
Production is already online, but the static revision and exact live Service
ownership have not been confirmed from cluster configuration or logs:
| Flow | Source | Destination | Required behavior |
|---|---|---|---|
| Browser UI | Browser | Same-origin Ingress -> Next.js or Go by path | Preserve current URLs; avoid cross-origin Cookie/CORS changes. |
| SSR identity | Next.js `getOptionalAuthSession()` | Internal Go `GET /api/auth/me` | Implemented in `498c2fa` when `ZHINIAN_GO_INTERNAL_BASE_URL` is configured: forward only enumerated `zhinian_session` Cookie chunks, use no-store transport, strictly validate authenticated/anonymous response shape and identity binding, and fail closed on bridge errors. No unrelated Cookie or origin forwarding. Without the URL, local full-stack mode keeps direct-store authorization. The live revision does not yet contain this fix. |
| Browser UI | Browser | Same-origin Ingress -> Nginx static Web | Preserve current page URLs; Nginx performs no application logic. |
| Browser identity | Browser auth Module | Same-origin Ingress -> Go `GET /api/auth/me` | Browser automatically sends HttpOnly Cookie; validate anonymous/authenticated response shapes, keep no token in JavaScript, and use client guards only for UX. |
| Browser business/file requests | Browser components | Same-origin Ingress -> Go `/api`, `/uploads`, `/generated-results` | Go revalidates session/account/organization/sessionVersion and enforces every protected action. |
| Backend persistence | Go Modules | PostgreSQL Adapter -> RDS | Parameterized queries and transactions; fail closed in production. |
| Task execution | Embedded Go WorkerLoop | RDS claim -> provider -> OSS -> RDS -> Webhook | Bounded concurrency, recoverable leases, one owner for external side effects. |
| Asset lifecycle | Go Assets | OSS plus RDS metadata | Shared storage required before horizontal scaling. |
| Schema rollout | Migration Job | RDS | Existing version/checksum/advisory-lock contract remains unchanged. |
| Schema rollout | Manual operator or dedicated CI | RDS | Execute immutable versioned SQL plus grants outside long-lived workloads; no Web-image migration Job. |
| Web health | ACK probe | Nginx `/healthz` | Static process/container health only; no database implication. |
| Go readiness | ACK probe | Go `/api/ready` -> RDS | Database/schema/privilege-aware readiness. |
## State Ownership
@@ -35,11 +42,14 @@ The Go implementation and desired ACK routing for these flows are present in the
- Alibaba Cloud RDS PostgreSQL via its internal endpoint and verified TLS CA.
- Alibaba Cloud ACK resources under `deploy/ack/`.
- Live production at `https://nianxxaigc.nianxx.cn`; public `/api/ready` has returned HTTP 200 with PostgreSQL configured, without proving the owning Service.
- Internal Worker HTTP endpoint is cluster-internal and blocked from public Ingress routing.
- The legacy internal Worker prefix is denied by Ingress; production uses the
embedded Go WorkerLoop and ships no Node Worker manifest.
The accepted production topology uses the embedded Go WorkerLoop rather than the local-development Node Worker. The exact live workload set remains to be confirmed from the cluster.
The SSR identity bridge and ACK internal URL are merged but not yet deployed. The current live revision produces a production RSC error for authenticated `/create`; the repair rollout must deploy `498c2fa` and verify the flow with an authenticated smoke test.
The accepted production topology uses the embedded Go WorkerLoop. The current
live revision produces an RSC error for authenticated `/create`; the rollout
must deploy `b14b4fc` under immutable image references and smoke login,
authenticated routes, logout, roles, `/healthz`, `/api/health`, and
`/api/ready`.
## Last Updated