85d495dd16
- add batch-scoped reconcile_runs persistence and queries - route batch detail and reconcile writes through batch_id/host_id - refresh production boards with host-scope acceptance artifacts - include latest real-host acceptance evidence for self_service and subscription
85 lines
6.0 KiB
Markdown
85 lines
6.0 KiB
Markdown
# Sub2api-CN-Relay-Manager 生产收口板
|
||
|
||
日期：2026-05-18
|
||
当前 Gate：APPROVED（按 PRD 首版范围放行；代码与真实宿主 fresh redeploy 复验均已满足，且已补充 reconcile host-scope 新一轮 acceptance artifact）
|
||
目标：达到可上线代码质量，并把剩余风险明确收敛为外部环境验收项与已接受 P2 技术债务。
|
||
|
||
## 当前门控结论
|
||
|
||
| 维度 | 状态 | 证据 |
|
||
|------|------|------|
|
||
| Build & Test | ✅ PASS | `go test -race ./...` |
|
||
| Integration | ✅ PASS | `go test ./tests/integration/... -count=1` |
|
||
| Static Analysis | ✅ PASS | `go vet ./...` |
|
||
| Formatting | ✅ PASS | `gofmt -l .` 空输出 |
|
||
| Core Coverage | ✅ PASS | `go test -cover ./internal/...`；access 77.3%, pack 72.7%, provision 74.6%（sqlite 61.3% 仅作信息项） |
|
||
| 控制面 API 计划缺口 | ✅ CLOSED | 已补 `/api/hosts/{hostID}/probe`、`/api/providers/{providerID}/import-batches`、`/api/import-batches/{batchID}/rollback` |
|
||
| 状态一致性 | ✅ CLOSED | rollback-by-batch 回写 `rolled_back/failed`；assign-subscriptions 同步 `import_batches.access_status` |
|
||
| provider 消歧 | ✅ CLOSED | pack 维度精确解析，避免同名 provider 跨 pack 误命中 |
|
||
| access 语义 | ✅ CLOSED | access preview 改为按 `subscription_ready/self_service_ready/fully_ready/broken` 判定 |
|
||
| OpenAPI | ✅ SYNCED | `docs/openapi.yaml` 已补当前控制面端点 |
|
||
| Local runtime smoke | ✅ PASS | `go build ./cmd/{server,cli}`、`GET /healthz`、`GET /api/hosts` |
|
||
| Local OCI image | ✅ PASS | `docker build -f Dockerfile.local -t sub2api-cn-relay-manager:local .` |
|
||
| Real-host acceptance tooling | ✅ READY | `docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md` + `scripts/real_host_acceptance.sh` |
|
||
| `self_service` 真实宿主 fresh redeploy 复验 | ✅ PASS | `artifacts/real-host-acceptance/20260518_redeploy_matrix`：普通用户 key 绑定标准 group 且用户余额=10 后，`04-self-after-balance.headers.txt` 显示 `HTTP/1.1 200 OK` |
|
||
| `subscription` 真实宿主 fresh redeploy 复验 | ✅ PASS | `artifacts/real-host-acceptance/20260518_redeploy_matrix`：subscription group + 用户订阅分配 + key 绑定后，`06-subscription-after-assign.headers.txt` 显示 `HTTP/1.1 200 OK` |
|
||
| `self_service`/`subscription` reconcile host-scope 复验 | ✅ PASS | `artifacts/real-host-acceptance/20260518_reconcile_hostscope_self_service` / `artifacts/real-host-acceptance/20260518_reconcile_hostscope_subscription`：已补齐 host-scoped `07/08/08a/09/10/11` 证据链，batch detail / status / resources 不再跨宿主串台 |
|
||
|
||
## 本轮已关闭项
|
||
|
||
1. 补齐实现计划 API 缺口
|
||
- `POST /api/hosts/{hostID}/probe`
|
||
- `GET /api/providers/{providerID}/import-batches`
|
||
- `POST /api/import-batches/{batchID}/rollback`
|
||
|
||
2. 修复生产级语义问题
|
||
- rollback/provider 与 assign/access 改为 pack 维度精确定位 provider，避免同名 provider 误操作
|
||
- `assign-subscriptions` 在写 access closure 后同步更新 `import_batches.access_status`
|
||
- `access preview` 改为按目标 mode 判定，不再把任意非 broken 状态误报为可用
|
||
- host capability 支持判定纳入 `plans` 能力
|
||
|
||
3. 补齐验证
|
||
- app/sqlite 新增回归测试覆盖以上行为
|
||
- 全量 race/integration/vet/gofmt 已复跑通过
|
||
- 本地 HTTP smoke 与 `Dockerfile.local` 容器构建已验证通过
|
||
|
||
4. 补齐上线前执行工具
|
||
- 新增 `scripts/build_local_image.sh`，固化本地/代理环境的镜像构建路径
|
||
- 新增 `docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md`
|
||
- 新增 `scripts/real_host_acceptance.sh`，把真实宿主验收固化为可落盘 artifact 的流程
|
||
|
||
5. 最新真实宿主复验事实
|
||
- `artifacts/real-host-acceptance/20260518_redeploy_matrix` 已在 fresh redeploy host 上确认两条访问链路都可打通
|
||
- `self_service` 通过条件：普通用户 key 绑定标准 group，且用户具备可用余额
|
||
- `subscription` 通过条件：subscription 类型 group + 普通用户订阅分配 + key/group 绑定
|
||
- 当前真实差异已经收敛为“宿主运营前置条件”而不是“代码级阻塞”
|
||
- `artifacts/real-host-acceptance/20260518_reconcile_hostscope_self_service` / `20260518_reconcile_hostscope_subscription` 进一步补强了 reconcile / batch detail 的 host-scope 语义证据
|
||
|
||
## 剩余项（P2 / 运营前置，不阻塞按 PRD 首版范围上线）
|
||
|
||
### 运营前置
|
||
- 真实宿主初始化不会自动创建普通用户；上线前必须显式创建普通用户并留存可复用凭据
|
||
- `self_service` 需要普通用户 key 绑定目标标准 group，且通常还需要可用余额
|
||
- `subscription` 需要 subscription 类型 group + 普通用户订阅分配 + key/group 绑定
|
||
|
||
### P2 已接受技术债务
|
||
- access 模块仍未按 implementation plan 拆到 `planner.go / subscription_service.go / self_service_checker.go`
|
||
- reconcile 仍内联在 `internal/provision/`，未拆到 `internal/reconcile/*`
|
||
- 无内置 scheduler/jobs；当前通过手动 reconcile + 外部 cron 补偿
|
||
- CLI `run*` 真实链路函数未做系统性 mock 单测
|
||
- 标准多阶段 `Dockerfile` 在受限网络下仍依赖容器内联网拉取 Go modules；本地部署默认走 `scripts/build_local_image.sh`
|
||
|
||
## 最短上线闭环
|
||
|
||
1. 按 `docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md` 准备真实宿主普通用户与可复用凭据
|
||
2. 按目标模式完成 key/group/billing(or subscription) 绑定
|
||
3. 使用 `scripts/build_local_image.sh` 与 `scripts/real_host_acceptance.sh` 复跑并归档现场 artifact
|
||
4. 对于符合这些前置条件的单宿主场景，本项目已可按 PRD 首版范围放行
|
||
|
||
## 禁止错误结论
|
||
|
||
- ❌ 历史失败/成功 artifact 不能脱离时间点复用；当前以 `20260518_redeploy_matrix` 为最新真相
|
||
- ❌ `HTTP 200` ≠ 宿主初始化会自动准备普通用户/订阅/余额；这些仍是显式运营前置
|
||
- ❌ `APPROVED` 表示“按 PRD 首版范围可上线”，不表示已变成多宿主自治平台
|
||
- ❌ 同名 provider 跨 pack 现在已避免误命中，但前提是调用方提供正确 pack path / pack_id
|