# Go modular backend

This directory contains the separately runnable Go implementation of ADR-003.
It now owns the checked-in compatibility implementation for all 66 explicit
HTTP method/path entries, but it is **not** the current production traffic
owner: Next.js, the Node Worker, Docker Compose, and the ACK manifests remain
unchanged until a later, explicit cutover.

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, verified-CA TLS, 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 local foundation manually without changing the existing Next
server, use a different port:

```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 is the same optional-auth super administrator used by the
current Next 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.

No Ingress, Docker, ACK, Secret, or Worker ownership has moved to Go yet, so
Next.js remains the deployed owner of every route. Real RDS/CA, OSS, provider,
Webhook, Worker drain/recovery, and rollback validation are mandatory before
that route ownership changes.