OpenFlare/docs/superpowers/specs/2026-08-30-openflare-cordis-alignment-design.md

# OpenFlare Cordis 对齐设计

- **文档状态**: 已敲定 (Approved)
- **版本**: v1.0.0 (2026-08-30)
- **范围**: 后端。禁止修改前端源码。禁止修改金标准树。
- **取代**: `2026-08-29-openflare-cordis-refactor-design.md` 中尚未落地或与本文冲突的部分（装配旁路、server 内平台副本、rsync 长期同步、在 server 上挂 health/self/cap 别名）。
- **Wavelet**: `/Users/ryan/Code/Go/Wavelet`
- **OpenFlare Cordis 工作树**: `/Users/ryan/Code/Go/OpenFlare-cordis`（分支 `cordis`）
- **金标准（未改造旧框架）**: `/Users/ryan/Code/Go/OpenFlare` @ `9f79fb99`（v3.5.4，与工作树 `main` 同 SHA）

---

## 1. 目标

OpenFlare 是 Wavelet 的下游产品。框架层与 Wavelet 一致，便于此后用 `git merge wavelet/main` 吸收上游。OpenFlare 只做 OpenFlare 业务，不再承担与 Wavelet 同类的职责。

Wavelet 提供框架与平台能力（微内核、infra、drivers、auth/admin/user/cap/upload/message_gateway/risk_control/system）。缺能力时改 Wavelet，且必须通用，禁止把 OpenFlare 业务写进框架。

---

## 2. 决策记录

| # | 决策 | 理由 |
| :--- | :--- | :--- |
| D1 | 前端 HTTP 契约冻结 | 禁止改 `frontend/`。路径可超集，不可删改金标准已有 path+method 的响应形状。 |
| D2 | 同一轮删除全部平台副本 | `cap` / `admin` / `infra` / `oauth` / `user` / `upload` / `config` / `health` / `admin/push` / `w_*` model+repository。留两套会双注册路由。 |
| D3 | 完整 stamp 桥接 | 现网 `goose_db_version` 76 链不重跑；新装走 Wavelet 每插件迁移 + `of_*` initial。 |
| D4 | 兼容靠 Wavelet 补通用能力，不靠 server 包装同类 HTTP | health / user/self / cap 路径差由拥有该功能的 Wavelet 插件多挂入口。 |
| D5 | Wavelet 作为 git 上游，merge 不改写历史 | 接线后废弃 rsync。禁止 rebase / filter-repo / force-push OpenFlare。 |
| D6 | OpenFlare 不承担同类职责 | 同一张 `w_*` 表、同一类鉴权/用户/验证码/上传/管理端/推送/任务/配置/健康检查/HTTP 引擎/关系库 migrator，均属 Wavelet。 |
| D7 | 金标准树只读 | `/Users/ryan/Code/Go/OpenFlare` @ `9f79fb99` 零改动。升级与对拍以它现跑现导为准。 |
| D8 | 先对齐代码，再第一次 unrelated merge | 半成品 merge 会把分叉和 Wavelet 前端搅进 OpenFlare。 |

---

## 3. 职责铁律

判定「同类职责」：Wavelet 已经覆盖的平台能力，OpenFlare **不得再实现一份**，也不得在 `server` 里用别名/包装再挂一套同类 HTTP。缺口（路径、中间件、贡献点）→ 改 Wavelet。

OpenFlare 只拥有：`of_*`、边缘协议、节点/Pages/WAF/TLS/Cloudflare 等产品逻辑；以及通过契约 **注册** 自己的事件与公共配置贡献（不是再写一套推送或配置服务）。

---

## 4. 目标结构与装配根

单 module `Wavelet`，与上游同构：

```
backend/
├── core/  pkg/  plugins/     【Wavelet】merge 进来，OpenFlare 不留私补丁
├── cmd/                      【Wavelet 骨架 + OpenFlare 持久 diff】
│   ├── app.go                即 Wavelet newWaveletApp，多 app.Use(server.New())
│   ├── api.go / worker.go / scheduler.go / all.go / root.go
│   └── {agent,relay,flared}/ OpenFlare 额外守护进程
├── main.go
└── OpenFlare/                占据上游 downstream/ 的位置
    ├── plugins/server        只留 OpenFlare 业务
    ├── plugins/{agent,relay,flared}
    └── share/
```

控制面 `newOpenFlareApp(profile)` 的 `app.Use` 顺序与 Wavelet `newWaveletApp` 相同：

1. infra：`database`、`logger`、`storage`
2. `cache` / `cache_memory`，`asynq` / `inproc` worker+cron（配置门控不变）
3. domain：`admin`、`user`、`auth`、`message_gateway`、`risk_control`、`upload`、`cap`、`system`
4. `OpenFlare/plugins/server.New()`
5. `SetMigrationEngine`（Wavelet 那份 `w_schema_versions` goose 引擎，不复制第二套）
6. `core.WithMigrationBaseline(stampFn)`：stamp 函数本体在 `OpenFlare/` 内，装配根只传入回调。与 `server.New()` 同属 cmd 允许的持久 diff。
7. `driver_http.New()`，**不再** `WithEngine(router.BuildEngine())`

`api` / `worker` / `scheduler` / `all` 全部 `runProfileApp(profile)`。删除：

- `bootstrap.RegisterAPI` / `Init` 进程级副作用链
- Cobra `PreRun` 本地 `migrator.Migrate()`
- `all.go` 自行拉起 `worker.StartWorker` / `scheduler.StartScheduler`
- 全局 `infra/config.Config` 单例；host 配置抄 Wavelet `root.go` 的 `config.NewSource()` + `hostConfig`

`cmd` 允许的持久 diff 仅：`app.Use(server.New())`、`WithMigrationBaseline(stampFn)`、agent/relay/flared 子命令、swagger 标题。禁止在 cmd 里自己拉起 DB/worker/migrator，禁止在 cmd 里实现 stamp 细节。

agent / relay / flared 入口已经是 `core.NewApp` + 单插件，本轮不改 CLI 形态。

---

## 5. Wavelet 通用扩展点（W1–W9）

先在 `/Users/ryan/Code/Go/Wavelet` 落地并进入其主线，再进入 OpenFlare。接口与实现禁止出现 OpenFlare / `of_` / 边缘节点等业务词。

### W1. `HandleRaw`

`Handle()` 经 `cleanPath` 会剥尾斜杠。需要 `HandleRaw`（保留尾斜杠）与 `BasePath()`。本地补丁已在 OpenFlare `upstream-patches.md` 与 Wavelet 分支 `feat/cordis-router-raw-routes`。合并进 Wavelet main 后清空补丁清单。

### W2. `contracts.CaptchaService`

Wavelet 已有 `cap.login_enabled`，但 `user` 的 login/register/send-email-code 未挂验证码。跨插件禁止 import `cap`。

```go
type CaptchaService interface {
    VerifyMiddleware(scope string) any // gin.HandlerFunc
    ChallengeHandler() any
    RedeemHandler() any
}
```

`cap.Apply` 中 `Provide`；`user` 在上述三路由上 `Inject`，有实现则包一层，没有则保持裸路由。`cap` 同时再挂 `POST /api/cap/{challenge,redeem}`（原 `/api/v1/cap/*` 保留）。pow 留在 `cap` 内，不抽到 `pkg/pow`。

### W3. 可选 `PublicConfigProvider`

`GET /api/v1/config/public` 路径相同。Wavelet 默认 `{configs, app}`；金标准前端消费扁平 `map[string]string`。

```go
type PublicConfigProvider interface {
    PublicConfig(ctx context.Context) (any, error)
}
```

`system` 在 handler 里 `Inject`：有 provider 用其 payload，没有走默认。OpenFlare `server` Provide 扁平 map。默认 Wavelet 行为不变。

### W4. `driver_http` 引擎选项

已有 Recovery / CORS / session / otelgin / 错误处理，以及 `embed_frontend` 的 SPA `NoRoute`。再增加配置项控制 `RedirectTrailingSlash`（默认 `true`，Wavelet 行为不变）。OpenFlare 通过配置关闭尾斜杠重定向。前端静态资源走 Wavelet `embed_frontend`（Makefile 拷贝目标改到 `driver_http/dist`，不改 `frontend/` 源码）。去掉 `WithEngine` 旁路。

### W5. upload 补挂已有 handler

`ListMyFiles` / `UpdateMyFile` / `DownloadFile` 已实现，测试已用 `GET /my`，但 `plugin.go` 未全部挂到用户组。在 `/api/v1/upload` 用户组补上 `GET /my`、`PUT /:id`、`GET /download/:id`、`POST /download/batch`（只增不改）。原 `GET ""`、`POST /batch-download` 保留。

### W6. `contracts.PushRegistry`

`RegisterBuiltInEvent` / `SyncEvents` 已在 `message_gateway` 存在，但是包级函数。收到契约上，下游只 `Inject` 注册自己的事件，禁止 import 域插件。

### W7. `system` 增加 `GET /api/health`

与现有 `/healthz`、`/api/healthz` 同一 handler。金标准调用 `/api/health`。响应保持金标准 `{error_msg, data: null}` 信封（`response.OKNil()`），不得只返回 `{status: ok}` 却让金标准路径变成另一种 JSON。若 `/healthz` 维持 Wavelet 原 JSON，`/api/health` 必须是金标准形状。

### W8. `user` 增加 `GET /api/v1/user/self`

内部 `AuthService.GetCurrentUser`。鉴权中间件与其它需登录的 user 路由相同。

### W9. Migration Baseline 钩子

`MigrationEngine` 在创建 `w_schema_versions` 之后、`Up` 之前调用可选 Baseline 回调（`core.WithMigrationBaseline`）。任何有历史库的下游可用。引擎接口禁止出现产品名。OpenFlare 的 stamp 实现放在 `OpenFlare/` 内，由 cmd 传入。并发保护（PG advisory lock / sqlite 单写者）加在 Wavelet 引擎上，不在 OpenFlare 再写迁移框架。

---

## 6. 清理后的 `server` 边界

### 删除（改走上游）

| 现路径 | 改走 |
| :--- | :--- |
| `admin/`（除 updater） | `plugins/domain/admin` |
| `oauth/` | `plugins/domain/auth` |
| `cap/`、`pkg/cap/` | `plugins/domain/cap` + `CaptchaService` |
| `user/` | `plugins/domain/user` |
| `upload/` | `plugins/domain/upload` |
| `config/` | `system` + `PublicConfigProvider` |
| `health/` | Wavelet `system` 的 `GET /api/health` |
| `admin/push/`、`pkg/push/` | `message_gateway` + `PushRegistry` |
| `infra/config`、`persistence`、`task`、`objectstore`、`diskcache`、`idgen` | 上游 infra / drivers / `pkg/idgen` |
| `infra/persistence/migrator`（关系库引擎与 76 链执行） | Wavelet 引擎 + stamp |
| `model` / `repository` 中所有 `w_*` | 对应上游域插件 |
| `listener/` | `ctx.Events().On` |
| `platform/bootstrap` 的任务/推送/进程初始化 | 各插件 `Apply` + 上游驱动 |
| ClickHouse 链中的 `w_user_access_logs` | `risk_control` |

删除后禁止再 import 这些包。业务只通过 `core/contracts`、`ctx.Config()`、`ctx.Events()`、`ctx.Task()`、`ctx.Router()` 协作。

### 保留

- `openflare/`（zone、node、origin、pages、waf、tls、cloudflare、agent/relay/flared 接入、websocket、dashboard、option 等）
- `of_*` 的 model / repository（含节点访问日志、可观测性、`chwriter`）
- `admin/updater`（三段式 Prepare/Apply/Finish；上游只有 GetUpdateStatus/ApplyUpdate）
- `integration/githubrelease`（仅 server 使用则留 server；多插件再用再进 `share/`）
- ClickHouse `of_node_*` 链（不并入 `w_schema_versions`）
- `share/`（protocol、wsclient、geoip、edge；本轮不搬）

`server.Apply` **不**注册 `/api/health`、`/api/v1/user/self`、`/api/cap/*`。这些由 Wavelet 插件声明。

`Apply` 职责：绑定 OpenFlare 自有配置；注册 `of_*` 迁移；Provide `PublicConfigProvider`；Inject 契约并注册 `of_*` 业务路由/任务/设置；经 `PushRegistry` 注册 OpenFlare 自己的事件。拆掉 `router/v1` 里把平台路由和业务编在一起的接线。SPA 兜底交给 `driver_http` + `embed_frontend`。

---

## 7. 迁移与 stamp

OpenFlare **不再自建关系库 migrator**。迁移即 Wavelet `cmd/app.go` 的 `w_schema_versions` + 每插件 goose。

### 表所有权

| 表 | 谁建、谁改 |
| :--- | :--- |
| `w_*` | Wavelet 各 domain `migrations/` |
| `of_*` | `OpenFlare/plugins/server/migrations/{postgres,sqlite}` |
| `w_schema_versions` | Wavelet 引擎 |
| ClickHouse `of_node_*` | `server` 自有 CH 链 |
| ClickHouse `w_user_access_logs` | Wavelet `risk_control` |

76 条历史 SQL 混着 `w_*` 与 `of_*`，**停止执行**。仅暂时留作与金标准 schema 对拍的夹具；门禁通过后可靠 git 历史，不再注册到引擎。

### 新装

1. Wavelet 各插件 `00001_initial`（`CREATE IF NOT EXISTS` / seed `ON CONFLICT DO NOTHING`）建 `w_*`，并补金标准没有的 `w_message_channels` / `w_message_bindings` / `w_message_pairing_codes`。
2. `server` 只含 `of_*` 的 `00001_initial`（当前 schema 压缩版，postgres/sqlite 文件名与版本号对齐），全部 `IF NOT EXISTS`。
3. 禁止 `DROP TABLE` / `DROP COLUMN` / `TRUNCATE`。

### 升级（金标准库：已有 `goose_db_version`，最大版本 `202608090003`）

Baseline 回调（幂等，`ON CONFLICT DO NOTHING`）：

1. 按与 Wavelet 逐字相同的 DDL 确保 `w_schema_versions` 存在。
2. 写入 `(openflare/legacy, 0)` 与 `(openflare/legacy, MAX(goose_db_version))`，76 条历史不再跑。
3. 写入 `(server, 1)`，压缩版 `of_*` initial 视为已应用。
4. **不 stamp Wavelet 插件**，让其 `00001` 以 `IF NOT EXISTS` 补缺口表。
5. 仅当老库版本落在 `[202607120002, 202607130001)` 时调用 `zone.ImportLegacyTx`。金标准已在 `202608090003`，此步为空操作。
6. ClickHouse 仍走 `goose_clickhouse_version`，只保留 `of_node_*`。

删除 `infra/persistence/migrator` 整包（关系库 `Migrate()`、Cobra `PreRun`、进程级 goose）。CH 升级保留为 `server` 内小函数，不是第二套通用 migrator。

---

## 8. Git 上游

两边目前没有共同祖先（OpenFlare 从 `init` 起 1064 提交；Wavelet 根提交为历史压缩）。禁止 rebase / filter-repo / force-push OpenFlare。

| 路径 | 所有权 | merge |
| :--- | :--- | :--- |
| `backend/{core,pkg,plugins}` | Wavelet | 三路合并，无私补丁 |
| `backend/cmd`、`backend/main.go` | Wavelet 骨架 + 第 4 节所述 diff | 三路合并 |
| `backend/OpenFlare/` | OpenFlare | `merge=ours` |
| `frontend/` | OpenFlare | `merge=ours` |
| `docs/changelog`、`docs/superpowers` | OpenFlare | `merge=ours` |

`.gitattributes`：

```gitattributes
backend/OpenFlare/**    merge=ours
frontend/**             merge=ours
docs/changelog/**       merge=ours
docs/superpowers/**     merge=ours
```

接线（对齐完成且第 9 节三层门禁全绿之后）：

```text
git remote add wavelet <Wavelet.git>
git fetch wavelet
git merge --allow-unrelated-histories wavelet/main   # 仅此一次
# 框架目录以 Wavelet 为准；ours 路径保持 OpenFlare
```

此后：`git fetch wavelet && git merge wavelet/main`。删除 `scripts/sync-upstream.sh`。接线前为导入 W1–W9 可使用一次 rsync。接线后 OpenFlare 不得再改 `core/pkg/plugins`。

成功判据：`git merge-base HEAD wavelet/main` 非空；`git log --first-parent` 仍是 OpenFlare 提交链；`frontend/` 与 `backend/OpenFlare/` 的历史 SHA 不被重写。

---

## 9. 验证门禁

金标准目录 `/Users/ryan/Code/Go/OpenFlare` @ `9f79fb99`，本轮零改动。Cordis 仓只读它。

### L1 — 金标准自身绿

在金标准树：`go test ./...` 全过。失败则停。

### L2 — Cordis 仓绿

在 `/Users/ryan/Code/Go/OpenFlare-cordis`：

- `go test ./...`
- Wavelet 仓 `go test ./...`（W1–W9 落地后）
- `make swagger`：金标准 swagger 的 path+method 一条不删、形状不改；允许超集
- 路由：金标准引擎表 ⊆ 完整 `newOpenFlareApp` 路由表。`plugin_parity_test` 必须对完整装配断言子集，不再只 `server.New().Apply`，不再要求精确相等
- `git diff --name-only -- frontend/` 为空

金标准必须包含且不得丢失的路径：`GET /api/health`、`GET /api/v1/user/self`、`POST /api/cap/challenge`、`POST /api/cap/redeem`、`GET /api/v1/config/public`（扁平 map）。

`docs/superpowers/specs/baseline/*` 必须与金标准二进制 **现跑现导** 一致；不一致以金标准为准改夹具。

### L3 — 从金标准库升级

用金标准二进制在空库跑完 76 链得库 A（sqlite 必做，Postgres 必做）：

1. 记录 `goose_db_version` 最大版本（`202608090003`）、表清单、`of_*` / `w_*` 行数抽样。
2. 同一份库文件启动 Cordis `api`。
3. 断言：已有表不丢列、不丢行；76 链不重跑；`w_schema_versions` 含 `openflare/legacy` 与 `server`；允许补 `w_message_*`；对升级后进程请求金标准关键 API，HTTP 与 JSON 形状与金标准一致。

| 路径 | 断言 |
| :--- | :--- |
| A 金标准二进制 + 76 链 | 与现导 schema 一致 |
| B Cordis 空库新装 | `of_*` 与 A 一致；`w_*` 允许 Wavelet 多表，禁止少列、禁止改已有列 |
| C 恢复 A 再启 Cordis | 数据仍在；关系库无重放历史 |

升级路径必须是 `go test`（夹具来自金标准迁移产物或测试内生成），禁止只手测一次。

B/C 失败即改造未完成。只测空库新装、未测金标准升级，算失败。改了金标准树，算失败。

---

## 10. 落地顺序

1. Wavelet 落地 W1–W9，`go test ./...` 绿。
2. OpenFlare-cordis 同步 `core/pkg/plugins`（接线前可用一次 `sync-upstream.sh`），与 Wavelet 零差，清空 `upstream-patches.md`。
3. 装配根同构：`runProfileApp` + `server.New()`；删除 bootstrap / 本地 migrator / `WithEngine`。
4. 删除平台副本；`server` 收敛到第 6 节边界。
5. stamp + `of_*` 压缩 initial；删除关系库 `migrator` 包。
6. 第 9 节 L1/L2/L3 全绿。
7. 第一次 `git merge --allow-unrelated-histories wavelet/main`；此后只 merge。

---

## 11. 明确不做

- 修改 `/Users/ryan/Code/Go/OpenFlare`
- 修改 `frontend/` 源码
- 在 OpenFlare 实现鉴权/用户/验证码/上传/管理端（updater 除外）/推送实现/健康检查/HTTP 引擎/关系库 migrator
- 在 `server` 再挂 `/api/health`、`/api/v1/user/self`、`/api/cap/*`
- 把 pow 抽到 `pkg/pow`
- 把 OpenFlare 业务写进 Wavelet
- rebase / filter-repo / force-push 改写 OpenFlare 历史
- 本轮改变 agent/relay/flared 的 CLI 形态
- 把 ClickHouse `of_node_*` 并进 `w_schema_versions`

---

## 12. 完成定义

以下同时成立才算完成：

- 金标准库能升到 Cordis，数据还在，76 链不重跑
- 金标准路由 ⊆ Cordis 路由；`GET /api/v1/config/public` 仍为扁平 map
- 金标准 `/Users/ryan/Code/Go/OpenFlare` 上 `go test ./...` 绿
- Cordis `go test ./...` 绿；Wavelet `go test ./...` 绿
- `frontend/` 无 diff
- 第 7 步之后 `git merge-base HEAD wavelet/main` 非空；`git log --first-parent` 仍是 OpenFlare 提交