42 lines
2.6 KiB
Markdown
42 lines
2.6 KiB
Markdown
# Data Flow
|
|
|
|
## Primary Flows
|
|
|
|
| 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 | 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 for these flows is merged into `main` under `backend/`; they become active on the first production deployment, which routes `/api`, `/uploads`, and `/generated-results` to Go from day one:
|
|
|
|
| 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/data | Next.js | Internal Go HTTP Interface | Forward Cookie and origin; Go remains the sole authorization authority. |
|
|
| 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. |
|
|
|
|
## State Ownership
|
|
|
|
- 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
|
|
|
|
- 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.
|
|
|
|
The internal Worker HTTP endpoint remains part of the local-development implementation only; production never deploys the Node Worker and uses the embedded Go WorkerLoop from the first rollout.
|
|
|
|
## Last Updated
|
|
|
|
2026-08-14
|