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:

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

Container images

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

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):

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):

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:

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.