@stackonward/cli 0.0.1 → 1.0.1

package/dist/resources/templates/go-backend/Dockerfile

@@ -0,0 +1,14 @@
+FROM golang:1.24-alpine AS build
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 go build -trimpath -o /out/product-api ./cmd/product-api && CGO_ENABLED=0 go build -trimpath -o /out/worker ./cmd/worker
+FROM alpine:3.21
+RUN apk add --no-cache ca-certificates tzdata && addgroup -S app && adduser -S -G app app
+WORKDIR /app
+COPY --from=build /out/ /app/bin/
+COPY configs/ /app/configs/
+USER app
+EXPOSE 3100 3101
+CMD ["/app/bin/product-api"]

package/dist/resources/templates/go-backend/Makefile

@@ -0,0 +1,71 @@
+GO ?= go
+BUILD_DIR := bin
+MIGRATE := $(GO) run -tags postgres github.com/golang-migrate/migrate/v4/cmd/migrate@v4.18.3
+COMPOSE := docker compose -p {{projectName}}-backend --env-file .env -f deployments/compose.yaml
+.PHONY: check build build-api build-worker run-api run-worker test test-cov test-race lint wire generate migrate-up migrate-down migrate-version migrate-create docker-dev docker-down docker-logs docker-ps clean
+build: build-api build-worker
+build-api:
+	$(GO) build -o $(BUILD_DIR)/product-api ./cmd/product-api
+build-worker:
+	$(GO) build -o $(BUILD_DIR)/worker ./cmd/worker
+run-api:
+	$(GO) run ./cmd/product-api
+run-worker:
+	APP_NAME={{projectName}}-worker APP_PORT=3101 $(GO) run ./cmd/worker
+test:
+	$(GO) test ./...
+test-cov:
+	$(GO) test -coverprofile=coverage.out ./...
+	$(GO) tool cover -html=coverage.out -o coverage.html
+test-race:
+	$(GO) test -race ./...
+lint:
+	$(GO) vet ./...
+	@unformatted="$$(gofmt -l cmd internal pkg api)"; if test -n "$$unformatted"; then printf '%s\n' "$$unformatted"; exit 1; fi
+wire:
+	$(GO) run github.com/google/wire/cmd/wire@v0.7.0 ./cmd/product-api ./cmd/worker
+generate: wire openapi-generate
+migrate-up:
+	@test -n "$(DATABASE_URL)"
+	@$(MIGRATE) -path migrations -database "$(DATABASE_URL)" up
+migrate-down:
+	@test -n "$(DATABASE_URL)"
+	@$(MIGRATE) -path migrations -database "$(DATABASE_URL)" down 1
+migrate-version:
+	@test -n "$(DATABASE_URL)"
+	@$(MIGRATE) -path migrations -database "$(DATABASE_URL)" version
+migrate-create:
+	@test -n "$(name)"
+	$(MIGRATE) create -ext sql -dir migrations -seq "$(name)"
+docker-dev:
+	$(COMPOSE) up -d --build
+docker-down:
+	$(COMPOSE) down
+docker-logs:
+	$(COMPOSE) logs -f
+docker-ps:
+	$(COMPOSE) ps
+clean:
+	rm -rf $(BUILD_DIR) coverage.out coverage.html
+
+.PHONY: openapi-install openapi-generate openapi-check openapi-test openapi-sdk openapi-breaking openapi-conformance openapi-clean-deletion test-migrations
+openapi-install:
+	cd api/openapi && pnpm install --ignore-workspace --frozen-lockfile
+openapi-generate:
+	cd api/openapi && pnpm run generate
+openapi-check:
+	cd api/openapi && pnpm run check
+openapi-test:
+	cd api/openapi && pnpm run test
+openapi-sdk:
+	cd api/openapi && pnpm run sdk
+openapi-breaking:
+	cd api/openapi && pnpm run breaking
+openapi-conformance:
+	cd api/openapi && pnpm run conformance
+openapi-clean-deletion:
+	bash scripts/check-openapi-clean-deletion.sh
+test-migrations:
+	bash scripts/test-migrations.sh
+
+check: lint build test openapi-check openapi-test openapi-clean-deletion

package/dist/resources/templates/go-backend/README.md

@@ -0,0 +1,66 @@
+# {{projectName}} Backend
+
+Go 产品后端，复用 OneX 的完整通用基础设施源码、测试和工程规范。API 与 Worker 独立进程，通过 Wire 在编译期装配；业务模块由产品拥有。
+
+## 目录
+
+```text
+cmd/product-api/          HTTP 入口与 Wire 装配
+cmd/worker/               Asynq、调度器与健康检查入口
+cmd/internal/runtime/     进程生命周期与公共 HTTP 装配
+internal/core/            基础设施源码与测试
+internal/common/          通用 HTTP、契约与数据转换
+internal/integrations/    外部平台协议边界
+internal/products/        产品业务模块
+internal/sharedevents/    产品跨模块事件
+pkg/                     可独立使用的基础包
+configs/                 配置文件
+migrations/              产品数据库迁移
+api/                     产品 API 契约
+scripts/                 开发与验证工具
+deployments/            容器编排
+```
+
+## 本地启动
+
+复制 `.env.example` 为 `.env`，设置独立数据库密码。`make docker-dev` 启动本产品的 PostgreSQL、Redis、API、Worker；API 绑定本机 `3100`，不会复用或修改其他产品数据库。容器中的数据库地址由 Compose 注入。
+
+本机运行 Go 时，设置 `.env` 中的 `DATABASE_*` 和 `REDIS_*` 为可访问的数据库与缓存地址，然后运行：
+
+```bash
+make wire
+make build
+make run-api
+make run-worker
+make check
+```
+
+`make run-worker` 使用端口 `3101`。先执行 `make openapi-install` 安装锁定的契约工具。`make check` 执行 vet、格式检查、构建、Go 测试及 OpenAPI 契约、工具测试和清理校验。`make test-migrations` 使用独立 PostgreSQL 容器验证迁移与关键数据库约束。`make test-race` 检查并发访问，`make test-cov` 输出覆盖率。
+
+## 数据库
+
+将 `DATABASE_URL` 显式导出为迁移账号的 PostgreSQL 连接串，再执行 `make migrate-up`。迁移账号与应用账号在生产环境分别配置；应用不自动迁移。`make migrate-version` 查询版本，`make migrate-down` 只回滚一个迁移，`make migrate-create name=description` 创建有序迁移对。
+
+首个迁移包含访问日志、登录日志、审计日志、操作日志、审计 inbox、Outbox 主记录和目标投递记录、命令回放记录。字段、唯一约束、检查约束、索引及不可变保护沿用源工程。日志父表保留分区结构，并提供默认分区保证新环境可写；启用审计保留策略时接入已有分区维护能力。
+
+Outbox 保留 `schema_version` 不可变约束，产品生产者负责写入自己的事件版本。平台事件目录的数据库触发器不进入独立产品数据库；不得为此跨库读取平台内部表。
+
+## 能力与装配
+
+| 能力 | 当前装配与使用方式 |
+| --- | --- |
+| PostgreSQL 连接池、查询指标 | API/Worker 的 `runtime.ProviderSet` |
+| 事务管理器 | 完整 `database.TransactionManager`，业务通过 `database.NewTransactionManager` 注入 |
+| Redis、L1/L2 缓存、缓存熔断重试 | API/Worker 的 `runtime.ProviderSet` |
+| 事件总线 | API/Worker 进程资源，停止时排空 |
+| Asynq 客户端 | API/Worker 注入，队列任务由业务模块注册 |
+| Asynq 消费者、Cron 调度器 | Worker 启动，保留指标中间件和优雅停止 |
+| Prometheus、OTel、Sentry | 指标默认可用；追踪与 Sentry 根据原配置启用 |
+| 健康检查 | `/health`、`/health/liveness`、`/health/readiness`、`/health/startup`，支持 GET/HEAD |
+| Outbox、Redis Stream、命令回放、分布式锁 | 完整源码与数据库基础，业务通过原 ProviderSet 和类型化事件/任务装配 |
+| 审计、限流、身份验证、安全、HTTP 客户端 | 完整源码与契约，入口按真实授权边界绑定 |
+| Temporal、存储、其他外部驱动 | 保留原配置、实现和测试；启用前配置实际服务和消费模块 |
+
+`/metrics` 用于内部采集，不应通过公网网关发布。当前入口只有基础健康与指标接口；产品登录、业务路由、OneX 服务身份和授权策略必须通过真实契约接入，健康检查成功不代表业务验收完成。
+
+通用源码来源见 `docs/source-provenance.json`；入口、配置、部署和迁移的来源与调整见 `docs/runtime-provenance.json`。阅读 `CLAUDE.md` 和 `.claude/docs/` 后开发，新增模块复用现有所有者和 ProviderSet。

package/dist/resources/templates/go-backend/_gitignore

@@ -0,0 +1,10 @@
+.env
+.env.*
+!.env.example
+bin/
+coverage.out
+coverage.html
+*.log
+.DS_Store
+node_modules/
+tmp/

package/dist/resources/templates/go-backend/api/openapi/README.md

@@ -0,0 +1,29 @@
+# API 契约工具链
+
+OpenAPI 3.1.1 与 JSON Schema 2020-12 是接口契约源。`services/` 按服务独立维护源契约，`service-registry.json` 定义服务、发布受众和明确的文档路由排除。健康探测和监控路由全部纳入契约。
+
+```bash
+make openapi-install
+make openapi-generate
+make openapi-check
+make openapi-test
+```
+
+`generate` 使用 Redocly 严格校验、引用解析、规范化、通用认证错误策略与路由歧义检测生成内嵌制品。`check` 重新编译并逐字节校验制品；Go 服务启动时由 `core/apicontract` 校验摘要和实际 Gin 路由，缺失、重复和未登记路由均导致启动失败。源契约、生成制品与 Go 装配应在同一次提交中更新。
+
+SDK 生成器保留 OneX 的 Hey API TypeScript 实现，服务显式声明 partner/public 发布后通过 `make openapi-sdk` 生成。当前服务仅有内部运行状态接口，不发布消费端 SDK。上线业务接口必须先声明真实认证与错误契约；健康检查的匿名访问规则不适用于业务接口。
+
+编译、策略、委托契约、Overlay、投影、语义版本、路由、SDK、确定性归档与 Scalar 本地化工具继承 OneX 实现。[`../../docs/openapi-provenance.json`](../../docs/openapi-provenance.json) 记录具体文件摘要及适配原因。平台契约审核账本、集成事件业务目录和文档发布平台属于 OneX 的发布服务，不由产品仓库复制其业务数据。
+
+## 兼容性与运行时验证
+
+`make openapi-breaking` 使用固定的 oasdiff 1.23.0 比较 Git 受保护基线。先安装对应版本的 oasdiff，并为 CI 获取目标分支历史；新仓库建立首次契约提交之后才有可比较的历史。报告写入 `tmp/openapi-breaking/`，缺少工具或基线直接失败。
+
+```bash
+ONEX_OPENAPI_CONFORMANCE_SERVERS='{"product-api":"http://127.0.0.1:3100","worker":"http://127.0.0.1:3101"}' \
+ONEX_OPENAPI_CONFORMANCE_INPUTS='{}' make openapi-conformance
+```
+
+运行时验证通过 Redocly Respect 执行每个服务的全部 9 个探测操作，并检验实际响应与内嵌契约。服务和依赖必须已经启动；运行报告写入 `tmp/openapi-conformance/`。这些变量沿用 OneX 工具协议，不授予任何业务访问权限。
+
+发布 partner/public 契约时，编译器按受众投影操作、组件和认证要求，再进行发布级校验。SDK 只从投影后的契约生成，不能携带内部接口；`SOURCE_REVISION` 可指定完整 Git SHA，否则读取当前提交。受众或接口删除后同时删除对应生成制品，保留基线供 breaking 检查。

package/dist/resources/templates/go-backend/api/openapi/dist/artifact-manifest.json

@@ -0,0 +1,19 @@
+{
+  "artifacts": [
+    {
+      "api_version": "1.0.0",
+      "audience": "internal",
+      "path": "services/product-api/dist/internal.openapi.json",
+      "service": "product-api",
+      "sha256": "7ae1525bfdd5b0a548620497dc79632fd2120829936f23a7b0d87d63a652e1d6"
+    },
+    {
+      "api_version": "1.0.0",
+      "audience": "internal",
+      "path": "services/worker/dist/internal.openapi.json",
+      "service": "worker",
+      "sha256": "195d968f4c042764405d5510411fd6dd3e303efc47a998990da73a4f9a09c0c8"
+    }
+  ],
+  "schema_version": 1
+}

package/dist/resources/templates/go-backend/api/openapi/dist/conformance-matrix.json

@@ -0,0 +1,276 @@
+{
+  "contract_assertion_count": 52,
+  "operation_count": 18,
+  "operations": [
+    {
+      "contract_assertions": [
+        "response:200",
+        "response:503",
+        "security:anonymous"
+      ],
+      "method": "GET",
+      "operation_id": "productapiGetHealth",
+      "path": "/health",
+      "runtime_scenarios": [
+        "healthy-response"
+      ],
+      "service": "product-api"
+    },
+    {
+      "contract_assertions": [
+        "response:200",
+        "response:503",
+        "security:anonymous"
+      ],
+      "method": "HEAD",
+      "operation_id": "productapiHeadHealth",
+      "path": "/health",
+      "runtime_scenarios": [
+        "healthy-response"
+      ],
+      "service": "product-api"
+    },
+    {
+      "contract_assertions": [
+        "response:200",
+        "response:503",
+        "security:anonymous"
+      ],
+      "method": "GET",
+      "operation_id": "productapiGetLiveness",
+      "path": "/health/liveness",
+      "runtime_scenarios": [
+        "healthy-response"
+      ],
+      "service": "product-api"
+    },
+    {
+      "contract_assertions": [
+        "response:200",
+        "response:503",
+        "security:anonymous"
+      ],
+      "method": "HEAD",
+      "operation_id": "productapiHeadLiveness",
+      "path": "/health/liveness",
+      "runtime_scenarios": [
+        "healthy-response"
+      ],
+      "service": "product-api"
+    },
+    {
+      "contract_assertions": [
+        "response:200",
+        "response:503",
+        "security:anonymous"
+      ],
+      "method": "GET",
+      "operation_id": "productapiGetReadiness",
+      "path": "/health/readiness",
+      "runtime_scenarios": [
+        "healthy-response"
+      ],
+      "service": "product-api"
+    },
+    {
+      "contract_assertions": [
+        "response:200",
+        "response:503",
+        "security:anonymous"
+      ],
+      "method": "HEAD",
+      "operation_id": "productapiHeadReadiness",
+      "path": "/health/readiness",
+      "runtime_scenarios": [
+        "healthy-response"
+      ],
+      "service": "product-api"
+    },
+    {
+      "contract_assertions": [
+        "response:200",
+        "response:503",
+        "security:anonymous"
+      ],
+      "method": "GET",
+      "operation_id": "productapiGetStartup",
+      "path": "/health/startup",
+      "runtime_scenarios": [
+        "healthy-response"
+      ],
+      "service": "product-api"
+    },
+    {
+      "contract_assertions": [
+        "response:200",
+        "response:503",
+        "security:anonymous"
+      ],
+      "method": "HEAD",
+      "operation_id": "productapiHeadStartup",
+      "path": "/health/startup",
+      "runtime_scenarios": [
+        "healthy-response"
+      ],
+      "service": "product-api"
+    },
+    {
+      "contract_assertions": [
+        "response:200",
+        "security:anonymous"
+      ],
+      "method": "GET",
+      "operation_id": "productapiGetMetrics",
+      "path": "/metrics",
+      "runtime_scenarios": [
+        "healthy-response"
+      ],
+      "service": "product-api"
+    },
+    {
+      "contract_assertions": [
+        "response:200",
+        "response:503",
+        "security:anonymous"
+      ],
+      "method": "GET",
+      "operation_id": "workerGetHealth",
+      "path": "/health",
+      "runtime_scenarios": [
+        "healthy-response"
+      ],
+      "service": "worker"
+    },
+    {
+      "contract_assertions": [
+        "response:200",
+        "response:503",
+        "security:anonymous"
+      ],
+      "method": "HEAD",
+      "operation_id": "workerHeadHealth",
+      "path": "/health",
+      "runtime_scenarios": [
+        "healthy-response"
+      ],
+      "service": "worker"
+    },
+    {
+      "contract_assertions": [
+        "response:200",
+        "response:503",
+        "security:anonymous"
+      ],
+      "method": "GET",
+      "operation_id": "workerGetLiveness",
+      "path": "/health/liveness",
+      "runtime_scenarios": [
+        "healthy-response"
+      ],
+      "service": "worker"
+    },
+    {
+      "contract_assertions": [
+        "response:200",
+        "response:503",
+        "security:anonymous"
+      ],
+      "method": "HEAD",
+      "operation_id": "workerHeadLiveness",
+      "path": "/health/liveness",
+      "runtime_scenarios": [
+        "healthy-response"
+      ],
+      "service": "worker"
+    },
+    {
+      "contract_assertions": [
+        "response:200",
+        "response:503",
+        "security:anonymous"
+      ],
+      "method": "GET",
+      "operation_id": "workerGetReadiness",
+      "path": "/health/readiness",
+      "runtime_scenarios": [
+        "healthy-response"
+      ],
+      "service": "worker"
+    },
+    {
+      "contract_assertions": [
+        "response:200",
+        "response:503",
+        "security:anonymous"
+      ],
+      "method": "HEAD",
+      "operation_id": "workerHeadReadiness",
+      "path": "/health/readiness",
+      "runtime_scenarios": [
+        "healthy-response"
+      ],
+      "service": "worker"
+    },
+    {
+      "contract_assertions": [
+        "response:200",
+        "response:503",
+        "security:anonymous"
+      ],
+      "method": "GET",
+      "operation_id": "workerGetStartup",
+      "path": "/health/startup",
+      "runtime_scenarios": [
+        "healthy-response"
+      ],
+      "service": "worker"
+    },
+    {
+      "contract_assertions": [
+        "response:200",
+        "response:503",
+        "security:anonymous"
+      ],
+      "method": "HEAD",
+      "operation_id": "workerHeadStartup",
+      "path": "/health/startup",
+      "runtime_scenarios": [
+        "healthy-response"
+      ],
+      "service": "worker"
+    },
+    {
+      "contract_assertions": [
+        "response:200",
+        "security:anonymous"
+      ],
+      "method": "GET",
+      "operation_id": "workerGetMetrics",
+      "path": "/metrics",
+      "runtime_scenarios": [
+        "healthy-response"
+      ],
+      "service": "worker"
+    }
+  ],
+  "runtime_operation_count": 18,
+  "runtime_step_count": 18,
+  "runtime_workflow_count": 2,
+  "schema_version": 2,
+  "services": [
+    {
+      "operation_count": 9,
+      "runtime_operation_count": 9,
+      "runtime_step_count": 9,
+      "runtime_workflow_count": 1,
+      "service": "product-api"
+    },
+    {
+      "operation_count": 9,
+      "runtime_operation_count": 9,
+      "runtime_step_count": 9,
+      "runtime_workflow_count": 1,
+      "service": "worker"
+    }
+  ]
+}

package/dist/resources/templates/go-backend/api/openapi/document.go

@@ -0,0 +1,30 @@
+package openapi
+
+import (
+	"embed"
+	"fmt"
+
+	"{{module}}/internal/core/apicontract"
+)
+
+//go:embed services/*/dist/*.json
+var artifacts embed.FS
+
+// Document 从构建制品加载契约，启动时校验摘要与运行时路由。
+func Document(service string) (apicontract.Document, error) {
+	switch service {
+	case "product-api", "worker":
+	default:
+		return apicontract.Document{}, fmt.Errorf("unknown service contract: %s", service)
+	}
+	root := "services/" + service + "/dist/"
+	spec, err := artifacts.ReadFile(root + "internal.openapi.json")
+	if err != nil {
+		return apicontract.Document{}, err
+	}
+	runtime, err := artifacts.ReadFile(root + "runtime-contract.json")
+	if err != nil {
+		return apicontract.Document{}, err
+	}
+	return apicontract.NewDocument(spec, runtime)
+}

package/dist/resources/templates/go-backend/api/openapi/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@stackonward/backend-contract",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "pnpm": "10.28.2"
+  },
+  "packageManager": "pnpm@10.28.2",
+  "scripts": {
+    "test": "node --test tooling/test/*.test.mjs",
+    "generate": "node tooling/build.mjs",
+    "check": "node tooling/build.mjs --check",
+    "sdk": "node tooling/build.mjs --sdk",
+    "breaking": "node tooling/breaking.mjs",
+    "conformance": "node tooling/runtime_conformance.mjs"
+  },
+  "devDependencies": {
+    "@hey-api/openapi-ts": "0.99.0",
+    "@redocly/cli": "2.39.0",
+    "@scalar/api-reference": "1.62.6",
+    "@swaggerexpert/jsonpath": "4.0.4",
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1",
+    "typescript": "5.9.3",
+    "yaml": "2.8.1"
+  }
+}