# Go modular backend

This directory contains the production application backend. Go is the sole
runtime owner of `/api`, `/uploads`, and `/generated-results`, including browser
sessions, authorization, persistence, provider calls, and the embedded
WorkerLoop. The frontend is a static Next.js export served by Nginx and calls
these Go routes through the public same-origin Ingress.

Implemented Modules:

- `identity` and `administration`: legacy `zhinian_session` HMAC/chunking,
  database-refreshed authorization, password lifecycle, accounts, and
  organizations.
- `assets`: scoped registration, upload, download, deletion, local filesystem,
  bounded remote import, and Alibaba Cloud OSS adapters.
- `jobs`, `providers`, and `orchestration`: provider preparation/protocols,
  idempotent creation, embedded WorkerLoop, retries, output assets, usage,
  refunds, Seedance settlement, and signed Webhooks.
- `billing` and `usage`: integer-fen quote/wallet/ledger/catalog behavior and
  tenant-scoped reports.
- `templates`, `prompt`, `settings`, and `logging`: the remaining compatibility
  modules used by the HTTP surface.
- `postgres`: fail-closed configuration, code-enforced plaintext
  `sslmode=disable`, readiness, atomic account mutations, and calls to the
  existing claim and wallet PostgreSQL functions. PostgreSQL is the production
  relational source of truth.
- `localstore`: a mutex-protected, non-durable, single-process development
  store covering the same business Module ports.
- `httpapi`: the complete checked-in route compatibility surface.
- `application`: composition and the `cmd/zhinian-api` process entry point.

From the repository root:

```bash
npm run go:fmt
npm run go:test
npm run go:vet
npm run go:build
```

## Container images

Self-contained build (recommended for China CI; single command, only the
alpine base image is pulled — the Go toolchain comes from Alpine's packages
via the Aliyun apk mirror and modules come from goproxy.cn):

```bash
docker build -f backend/Dockerfile.alpine \
  -t REGISTRY/PROJECT/zhinian-go-api:TAG backend/
```

Standard multi-stage build (needs the `golang` builder image):

```bash
docker build -f backend/Dockerfile -t REGISTRY/PROJECT/zhinian-go-api:TAG backend/
```

Mirror-friendly build (override the base images when the registry accelerator
cannot serve docker.io images):

```bash
docker build -f backend/Dockerfile \
  --build-arg GOLANG_IMAGE=<mirror>/golang:1.21-alpine \
  --build-arg RUNTIME_IMAGE=<mirror>/alpine:3.20 \
  -t REGISTRY/PROJECT/zhinian-go-api:TAG backend/
```

Prebuilt-binary build (no `golang` image at all; compile the static binary on
any Go 1.21 machine, then assemble from `alpine` only):

```bash
cd backend
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
  go build -trimpath -ldflags="-s -w" -o zhinian-api.linux ./cmd/zhinian-api
docker build -f backend/Dockerfile.runtime \
  -t REGISTRY/PROJECT/zhinian-go-api:TAG backend/
```

The runner defaults to `CGO_ENABLED=0` for reproducible cross-platform builds.
To exercise the backend locally, listen on port 8080 and route browser API
requests there with a same-origin development proxy:

```bash
ZHINIAN_DATA_BACKEND=local GO_BACKEND_PORT=8080 ./backend/zhinian-api
```

In local mode, persistent business data is process-local and is discarded on
restart; it is intended only for development and contract smoke tests. The
default demo identity supports the optional-auth frontend development flow.

## First super administrator

On the first PostgreSQL deployment, the first super administrator is created
from configuration at startup — no separate script or CLI step is needed. When
the three variables below are all present and the process runs against
PostgreSQL, startup creates the account exactly once and skips the bootstrap
when any super administrator (including a disabled one) already exists:

- `ZHINIAN_BOOTSTRAP_ADMIN_PHONE`
- `ZHINIAN_BOOTSTRAP_ADMIN_PASSWORD` (minimum 8 characters)
- `ZHINIAN_BOOTSTRAP_ADMIN_NAME` (defaults to `平台超级管理员`)

A failed bootstrap (invalid phone, short password, database error) fails
process startup so a misconfigured bootstrap is visible instead of silently
missing. Local development mode keeps the seeded demo administrator and never
bootstrap-creates accounts.

Production routing, Secret ownership, probes, and rollout commands are defined
in [`../docs/DEPLOYMENT.md`](../docs/DEPLOYMENT.md) and `../deploy/ack/`. Go owns
the session signing Secret and backend runtime configuration; the static Web
workload receives neither. PostgreSQL does not use TLS, so production must use
the RDS internal endpoint and restrict access with VPC boundaries, security
groups, and allowlists. Validate RDS connectivity, OSS, providers, Webhooks,
embedded Worker recovery, and rollback behavior for each production release.