# API/Admin 第三期全量重构设计

## 背景

第一期已经完成 Runtime Foundation 与线上部署观测铺底，第二期完成了 API 全模块架构、全库表设计、QQBot 插件平台和 NapCat Runtime 的中文规划。第三期不再只修 QQBot，也不是继续追加局部补丁，而是进入用户确认的 C 阶段：按第二期规划完整迁移 API 全模块，并同步重构 Admin 管理端。

当前业务数据不重要，因此第三期允许从头设计数据库表，允许破坏式重建 schema，允许重写旧初始化 SQL 和旧模块结构。破坏式不等于无保护：本阶段必须把备份、回滚、验证 SQL、本地 dry run、线上发布观测和真实功能 smoke 作为同一条闭环的一部分。

本文件是 KT requirements and design review 的第三期设计落地文档。它只固化设计和执行边界，不创建实现分支，不清理 Admin 旧产物，不写业务实现。用户 review 本文件后，下一步进入 KT workflow `KT plan writing`。

## 已确认决策

- 第三期范围是完整 C 阶段迁移，必须覆盖 API 全模块，不只做 Batch 0-2。
- API 与 Admin 一起重构。API 仓库使用 `dev/api-full-refactor-v3`，Admin 仓库使用 `dev/admin-full-refactor-v3`。
- 当前 Admin 仓库未提交改动属于旧产物，用户已授权在实现准备阶段放弃；设计阶段先不清理。
- 每个批次在本地完成 TDD、验证、review 和提交，不按批次推送。
- Batch 0-8 全部完成并通过本地闭环后，再统一推送、重建数据库、观察 Jenkins/K8s、执行线上完整 smoke。
- 数据库按全新 schema 设计，可破坏式重建，但必须有备份、恢复路径、验证 SQL 和 API 镜像回滚策略。
- QQBot 插件平台是统一平台能力，必须支持 manifest、CLI 脚手架、线上安装、热插拔、worker 或 child process 隔离、配置、健康、运行事件和账号绑定。
- NapCat Runtime 不是插件。它属于 QQBot/NapCat 基础运行时，必须独立实现设备身份持久化和登录状态机。
- NapCat 新设备验证必须实现 `GetNewDeviceQRCode -> PollNewDeviceQR -> NewDeviceLogin`，不能只把 `jumpUrl` 透给 Admin。
- SSE/Admin 必须展示完整中文进度：快速登录、密码登录、验证码、新设备二维码、已扫码、确认中、登录成功、登录失败。

## 范围

### API 仓库

第三期 API 重构覆盖：

- `runtime` 和 `common` 基础层。
- Admin/Auth/Platform Config。
- Blog/WordPress/Asset。
- QQBot Core。
- QQBot Plugin Platform。
- 现有 QQBot 插件重写。
- NapCat Runtime。
- 全量初始化 SQL、schema 文档、验证 SQL、备份和恢复脚本。
- 本地、发布、线上 smoke 和 KT global review 证据。

### Admin 仓库

第三期 Admin 重构覆盖：

- 登录、菜单、权限、用户、角色、部门等身份和权限页面。
- 平台设置、字典、组件模板、系统通知。
- Blog/WordPress/Asset 管理页。
- QQBot 账号、连接、命令、规则、消息、发送队列管理页。
- QQBot 插件管理页：上传、校验、安装、启用、禁用、升级、卸载、配置、健康、运行事件、账号绑定。
- NapCat 登录管理页：设备身份、登录 session、验证码、新设备二维码、SSE 中文进度、清理失败提示。

Admin 不做独立产品改版。UI 调整服务于新 API 契约、状态语义和管理流程。

## 非目标

- 本设计阶段不写实现代码。
- 本设计阶段不创建 `dev/api-full-refactor-v3` 或 `dev/admin-full-refactor-v3` 分支。
- 本设计阶段不清理 Admin 旧未提交改动。
- 不保留旧表结构来迁就旧数据。
- 不把 NapCat 登录安全校验做成自动绕过。
- 不允许线上插件直接访问后端真实密钥、TypeORM Repository、Nest DI 或任意宿主文件路径。
- 不把 Jenkins/K8s 成功当成功能完成。线上真实 smoke 是完成条件的一部分。

## 分支和仓库策略

实现准备阶段按顺序处理：

1. 确认 API 仓库状态，基于当前 `main` 创建 `dev/api-full-refactor-v3`。
2. 确认 Admin 仓库状态，放弃用户已授权的旧未提交产物后，基于当前 `main` 创建 `dev/admin-full-refactor-v3`。
3. API 与 Admin 分别提交，提交信息使用英文 type 前缀加中文说明。
4. 每个批次可以产生 API 提交、Admin 提交或两者都有的提交。
5. Batch 8 本地闭环完成前不推送。
6. 统一推送前再次确认两仓 diff、提交序列、数据库破坏式操作范围和回滚入口。

跨仓依赖以 API 契约为中心：API 批次先定义 contract、schema 和状态语义，Admin 同批次或紧随其后完成 caller、页面状态和 smoke。任何 breaking change 必须在批次开始前写入 breaking-change 清单。

## 目标模块架构

API 目标结构继承第二期规划：

```text
src/
  runtime/
  common/
  modules/
    admin/
    blog/
    wordpress/
    asset/
    qqbot/
```

模块内部使用稳定分层：

```text
module/
  contract/
  application/
  domain/
  infrastructure/
    persistence/
    integration/
  schema/
  tests/
```

- `contract`：Controller、DTO、Swagger、SSE 事件和外部兼容适配。
- `application`：用例编排、事务、权限、状态流转和跨端契约。
- `domain`：纯规则、状态机、策略和值对象，不依赖 Nest、TypeORM、Docker 或 HTTP。
- `infrastructure/persistence`：Entity、Repository、查询模型和 schema mapper。
- `infrastructure/integration`：WordPress、MinIO、Loki、OneBot、NapCat WebUI、Docker、插件 worker RPC。
- `schema`：表设计、初始化 SQL、验证 SQL、备份恢复说明和批次迁移记录。
- `tests`：unit、contract、repository、integration smoke 和回归用例。

Admin 目标结构以功能域组织 API caller、页面、组件和状态适配，避免把 QQBot、插件平台、NapCat 状态继续塞进单一大页面。

## 全库表重建设计

第三期以全新 schema 为目标，不做旧表兼容迁移。表设计必须在 Batch 0 冻结第一版，并在每个后续批次按模块补齐实现。

全局约定：

- 主键使用 Snowflake `BIGINT`，API 边界按字符串语义处理。
- 外键列使用 `*_id`，查询路径必须建索引。
- 业务强关系使用唯一约束，日志和事件类表避免强外键。
- 时间字段使用 `create_time`、`update_time`，软删使用 `delete_time`。
- 状态字段使用明确 varchar 枚举，允许值写入 schema 文档。
- JSON 字段只放外部原始 payload、低频配置、插件 metadata 或证据详情；需要查询的字段必须结构化。
- 初始化 SQL 是全量干净 schema，不继续堆叠历史 `ALTER TABLE`。

核心数据域：

| 数据域 | 表设计方向 |
| --- | --- |
| Admin Identity | 用户、角色、权限、菜单、部门、用户角色、角色权限、角色菜单分离，菜单路由和权限原子拆清。 |
| Platform Config | 字典组、字典项、组件模板、平台设置、系统通知独立成域。 |
| Blog Content | 文章、分类法、术语、文章术语关系、主题 profile、导入 job 分离。 |
| WordPress Mirror | 站点、认证会话、远端文章、远端术语、同步 job、远近端 mapping 分离。 |
| Asset/MinIO | bucket、object、reference、access grant 记录对象归属、MIME、来源模块和临时授权。 |
| System Event | notice、event、dedupe、delivery 保存可处理事件和投递状态，Loki 仍是日志查询源。 |
| Runtime Evidence | 保存重要运行证据索引，不把大日志和 secrets 放入 MySQL。 |
| QQBot Core | 账号、连接 session、能力绑定、权限策略、命令、别名、规则、会话、消息、发送任务、发送日志、去重事件分离。 |
| NapCat Runtime | 容器、设备身份、账号绑定、登录 session、登录 challenge、清理记录分离。 |
| QQBot Plugin Platform | 插件、版本、安装、operation、event handler、账号绑定、配置、资产、运行事件分离。 |
| Plugin-Owned Data | 插件自有表必须带 plugin key 或注册 namespace 前缀。 |

破坏式重建流程必须包含：

1. 本地空库 dry run：应用全量 SQL、seed、验证 SQL、API 启动、关键接口 smoke。
2. 线上备份：备份当前 API 数据库，记录备份路径、时间、库名和恢复命令。
3. 写流量限制：在 drop 或 rename 旧表前停止或限制 API 写流量。
4. 应用新 schema：按批准脚本重建表、索引、seed、插件 metadata 和菜单权限。
5. 绑定 API 镜像：schema 版本和 API 镜像作为同一回滚单元。
6. 线上验证：Admin、Blog、Asset、QQBot、插件平台、NapCat、`/health/runtime` smoke。
7. 失败恢复：恢复备份或切回旧 schema bundle，并回滚 API/Admin 镜像。

## QQBot 插件平台设计

插件平台是第三期独立核心能力。它不是把现有插件目录挪位置，而是建立统一 contract、安装链路、运行隔离和 Admin 管理面。

### 插件包结构

```text
plugins/<pluginKey>/
  plugin.json
  src/
    index.ts
    operations/
    events/
    config/
    migrations/
    assets/
    tests/
```

`plugin.json` 是单一事实来源，包含：

- plugin key、名称、描述、版本、作者、license、主页。
- 最低 API plugin SDK 版本。
- 权限声明。
- operations、event handlers、config schema、assets、migrations。
- runtime 要求：timeout、memory limit、worker type、并发策略。

### CLI 脚手架

API 仓库提供插件 CLI：

```bash
pnpm qqbot-plugin create <pluginKey>
pnpm qqbot-plugin validate <path>
pnpm qqbot-plugin pack <path>
pnpm qqbot-plugin install-local <package>
```

`create` 生成初始插件模块结构、manifest、入口、operation 模板、event 模板、config schema、migration 模板、contract tests 和说明草稿。

`validate` 校验 manifest shape、operation key、event key、权限声明、migration、assets、包大小、禁用路径和基础测试。

`pack` 输出带版本和 content hash 的插件包。

`install-local` 走与线上安装相同的校验链路，避免本地与线上行为分叉。

### 运行隔离

插件代码运行在 worker 或 child process 中。API 主进程只负责安装包、校验、registry、路由、权限和受控 SDK。

RPC 协议必须支持：

- `load`
- `activate`
- `deactivate`
- `executeOperation`
- `handleEvent`
- `health`
- `dispose`

插件崩溃、超时或健康失败只影响对应插件 installation，不能拖垮 API 主进程。Host 记录插件 runtime event，并把状态暴露给 Admin。

插件 SDK 只能提供受控能力：

- 走 host 发送队列发送 QQBot 消息。
- 读写插件配置。
- 读写插件自有 storage。
- 发送插件运行事件。
- 通过 host runtime HTTP client 调外部 API。
- 从声明 asset root 读取资源。
- 读取当前 operation 或 event context。

插件不得读取真实环境变量、任意宿主文件、Nest DI、TypeORM 原始 Repository 或跨插件私有数据。

### 线上安装和热插拔

状态机：

```text
uploaded -> validated -> installed -> enabled
enabled -> disabled
installed -> uninstalled
enabled -> upgrading -> enabled
enabled -> failed
```

Admin 上传插件包后，API 负责校验 manifest、hash、版本兼容、权限、migration 和 assets。启用时启动 worker 并注册 operation/event。禁用时停止 worker 并从 active registry 移除。卸载时停止 worker、移除 registry 和绑定，默认保留插件数据，只有管理员明确选择清理才删除插件自有数据。

### 现有插件重写

- BangDream：作为大型参考插件重写，保留 song、card、character、event、gacha、player、cutoff、provider、renderer、theme、assets 等能力边界，operation metadata 由 manifest 支撑，图片 smoke 行为必须保留。
- FF14 Market：外部查询插件，通过 host runtime HTTP SDK 调用 XIVAPI 和 Universalis。
- FFLogs：外部查询插件，通过 host runtime HTTP SDK 调 GraphQL/token，凭据来自插件 config 的受控引用。
- Repeater：事件插件，由 host 管理账号绑定和发送队列，插件只维护自身策略状态，不能绕过限流和队列。

## NapCat Runtime 设计

NapCat Runtime 排在 QQBot Core 和插件平台之后实现，但它不是插件。它属于账号、容器、设备身份和登录安全流程的基础运行时。

目标：

- Docker 设备状态持久化，避免每次重建容器都被 QQ 识别成新设备。
- 设备身份是一等数据：容器名、data dir、hostname、machine-id、MAC、账号绑定、验证状态和最后登录证据必须可追踪。
- 登录状态机保持清晰：快速登录、密码登录、验证码、新设备验证、二维码 fallback、成功、失败、清理失败各自独立。
- 新设备验证按 NapCat 上游流程完成：`GetNewDeviceQRCode -> PollNewDeviceQR -> NewDeviceLogin`。
- SSE/Admin 全中文进度可观察，用户能知道当前卡在扫码、确认、验证码、清理失败还是最终失败。
- 运行态密码清理失败必须阻断成功或二维码 fallback，并写入明确错误，不被普通离线原因覆盖。

登录顺序：

```text
quick login -> saved password login -> captcha challenge -> new device QR challenge -> manual QR fallback
```

验证码处理：

- `proofWaterUrl` 只作为用户完成腾讯验证码的入口。
- 用户提交 `ticket`、`randstr`、`sid` 后，API 调 NapCat `CaptchaLogin`。
- 不伪造验证码票据，不绕过腾讯安全校验。
- 一旦 session 进入 captcha pending，后续状态缺少 URL 也不能直接失败，必须保留 challenge 语义。

新设备验证处理：

- `CaptchaLogin` 或登录状态返回 `needNewDevice` 时，API 创建或更新 new-device challenge。
- API 调 NapCat `GetNewDeviceQRCode` 获取新设备二维码，不只透传 `jumpUrl`。
- API 周期调用 `PollNewDeviceQR`，把未扫码、已扫码、确认中、过期、失败状态映射为中文 SSE/Admin 状态。
- 用户确认后 API 调 `NewDeviceLogin`，同一登录 session 继续完成登录。
- 新设备验证成功后保留设备身份证据，后续容器重建复用持久化设备状态。

SSE/Admin 状态至少覆盖：

- 正在快速登录。
- 快速登录失败，进入密码登录。
- 正在密码登录。
- 需要验证码。
- 验证码已提交，等待 NapCat 确认。
- 需要新设备验证二维码。
- 新设备二维码待扫码。
- 新设备二维码已扫码。
- 新设备确认中。
- 新设备验证成功，继续登录。
- 正在生成手动二维码。
- 登录成功。
- 登录失败。
- 运行态清理失败。

## 执行批次

### Batch 0：迁移准备

产物：

- API/Admin 双仓分支准备方案。
- Admin 旧产物清理记录。
- 全库 schema map。
- 全量初始化 SQL 草案。
- 破坏式重建脚本设计。
- 备份和恢复命令。
- 验证 SQL。
- 模块模板。
- breaking-change 清单。
- API/Admin 契约矩阵。

验收：

- 空库 schema dry run 可执行。
- 初始 seed 覆盖 Admin 登录、菜单、基础设置、插件 metadata 和 QQBot 基础命令。
- KT plan writing 输出的任务能够映射到 Batch 1-8。

### Batch 1：Runtime/Common

范围：

- 稳定 runtime profile、runtime client、evidence、timeout、process/Docker adapter、错误分类。
- 收缩 common，只保留通用响应、错误、时间、Snowflake、日志基础能力。

验收：

- `/health/runtime` 行为稳定。
- 现有 runtime tests 继续通过。
- 下游模块可以通过统一 adapter 接入外部 HTTP、process、Docker 和证据记录。

### Batch 2：Admin/Auth/Platform Config

范围：

- 重建身份、角色、权限、菜单、部门、字典、组件模板、平台设置和系统通知模型。
- Admin 登录、菜单、权限页面同步新 contract。

验收：

- 本地真实登录接口通过。
- Admin 菜单加载和页面路由通过。
- 权限、菜单、字典、设置的增删改查通过 scoped smoke。

### Batch 3：Blog/WordPress/Asset

范围：

- 重建 Blog 内容、分类法、术语关系、主题 profile。
- 重建 WordPress mirror、sync job、mapping。
- 重建 MinIO asset 归属、引用和临时授权。
- Admin Blog、WordPress、Asset 页面同步新 contract。

验收：

- Blog public list/detail 本地真实请求通过。
- Admin Blog 管理 smoke 通过。
- WordPress 同步 dry run 或受控 smoke 通过。
- Asset 上传、引用和读取 smoke 通过。

### Batch 4：QQBot Core

范围：

- 重建账号、连接 session、能力绑定、权限策略、命令、别名、规则、会话、消息、发送任务、发送日志和去重事件。
- 拆清 OneBot 连接、容器、WebUI 和 QQ 登录态。
- Admin QQBot 基础管理页同步新 contract。

验收：

- 命令 registry 和 command SQL 测试通过。
- 发送队列、去重、权限策略单测通过。
- `/qqbot/command/test` 本地真实请求通过。
- Admin QQBot 账号和命令页面 smoke 通过。

### Batch 5：QQBot Plugin Platform

范围：

- 插件 manifest schema。
- 插件 registry 数据库。
- CLI `create/validate/pack/install-local`。
- worker 或 child process runtime。
- RPC 协议。
- 线上安装、启用、禁用、升级、卸载。
- 插件配置、健康、运行事件、账号绑定。
- Admin 插件管理页面。

验收：

- CLI 创建插件并通过 validate。
- pack 产物含 hash，install-local 走统一校验链路。
- worker load、activate、execute、health、deactivate、崩溃隔离测试通过。
- Admin 插件上传、安装、启用、禁用 smoke 通过。

### Batch 6：现有插件重写

范围：

- BangDream 重写为平台插件。
- FF14 Market 重写为平台插件。
- FFLogs 重写为平台插件。
- Repeater 重写为平台插件。
- 旧硬编码插件 registry 退出。

验收：

- BangDream 现有核心命令和图片 smoke 通过。
- FF14 Market 查询 smoke 通过。
- FFLogs 查询 smoke 通过。
- Repeater 事件策略和发送队列 smoke 通过。
- Admin 能查看插件 operation、配置、健康和运行事件。

### Batch 7：NapCat Runtime

范围：

- Docker 设备状态持久化。
- NapCat 容器、设备身份、账号绑定、登录 session、challenge、cleanup 记录。
- 快速登录、密码登录、验证码、新设备验证、二维码 fallback 状态机。
- `GetNewDeviceQRCode -> PollNewDeviceQR -> NewDeviceLogin`。
- SSE/Admin 中文进度。
- 清理失败阻断成功。

验收：

- 本地 NapCat login session 状态机单测通过。
- API 真实本地请求覆盖验证码和新设备 challenge 模拟。
- Admin 登录页面进度 smoke 通过。
- 容器重建后设备身份持久化证据可查询。

### Batch 8：统一上线闭环

范围：

- API/Admin 最终本地验证。
- 两仓统一推送。
- 数据库备份、重建、seed、验证 SQL。
- Jenkins/K8s 观测。
- 线上完整 smoke。
- 真实 QQBot/NapCat 账号闭环验证。

验收：

- Jenkins build number、commit hash、镜像 tag、Deployment generation、Pod image、restart count 和日志证据齐全。
- `/health/runtime` 线上通过。
- Admin 登录、菜单、关键管理页线上通过。
- Blog public 线上通过。
- 插件安装、启用、健康、命令线上通过。
- `/qqbot/command/test` 线上按 operationKey 查询 commandId 后通过。
- NapCat 真实账号完成登录闭环，包含设备持久化和新设备验证链路。

## 每批验证和提交节奏

每个批次必须按同一节奏执行：

1. RED：先写或定位失败检查，包括单测、schema 验证、contract smoke 或 Admin smoke。
2. GREEN：做最小足够实现。
3. 本地验证：按批次风险运行 typecheck、scoped lint、scoped Jest、真实 API 请求和 Admin smoke。
4. 文档同步：更新 schema、README/API、TASKS 或相关 docs。
5. KT global review。
6. KT global review。
7. 批次提交，API/Admin 分仓提交。

接口变化必须真实本地调用一次。发布或线上功能必须通过对应线上 self-test 后才能声明完成。

## 推送和上线策略

第三期本地实现期间不推送。Batch 0-8 全部本地完成后，统一执行：

1. 双仓最终 `git status` 和 diff 复核。
2. 本地完整轻量验证矩阵。
3. 用户确认推送和破坏式数据库动作窗口。
4. 推送 API 和 Admin 分支或目标分支。
5. 确认 Jenkins build number 和 commit hash。
6. 观察 K8s Deployment、Pod、image tag、restart count 和日志。
7. 线上数据库备份、重建、seed、验证 SQL。
8. 线上 API/Admin/Blog/QQBot/插件/NapCat smoke。

如果线上 smoke 失败，按 schema 与 API 镜像绑定回滚：恢复数据库备份或旧 schema bundle，回滚 API/Admin 镜像，记录失败点和稳定解法。

## 风险和控制

- 范围过大：通过 Batch 0-8 拆分，每批有独立 RED/GREEN、review、commit 和验收。
- 数据库破坏式重建风险：本地空库 dry run、线上备份、恢复命令、验证 SQL 和镜像绑定回滚。
- API/Admin 契约漂移：每批维护 contract matrix，接口变化必须真实调用，Admin 同步 smoke。
- 插件安全风险：manifest 权限、hash 校验、受控 SDK、worker 隔离、运行事件和禁用路径校验。
- NapCat 状态混淆：QQ 登录态、OneBot 连接、容器、WebUI、验证码、新设备、清理失败分别建模。
- 线上成功误判：Jenkins/K8s 只算部署证据，功能完成必须有线上 smoke。

## 本设计验收标准

本设计阶段完成条件：

1. 本文件写入 `docs/specs/`。
2. 本文件通过占位、矛盾、范围和模糊性自检。
3. `TASKS.md` 记录第三期设计上下文。
4. API 和根仓库文档变更分别提交。
5. 用户 review 本文件。
6. 用户确认后进入 KT workflow `KT plan writing`，再产出可执行计划。

## 交接到 KT plan writing

`KT plan writing` 必须把本设计转换为可执行计划，至少包含：

- Batch 0-8 逐批任务清单。
- 每批 RED/GREEN 测试入口。
- API/Admin 双仓文件范围。
- 表设计和初始化 SQL 产物路径。
- 破坏式重建、备份、恢复、验证 SQL 细节。
- 插件 CLI、worker runtime、Admin 插件管理页任务拆分。
- NapCat 设备持久化和新设备验证任务拆分。
- 每批提交、review、清理、文档同步和最终上线闭环门禁。

在用户 review 本文件前，不进入实现，也不进入分支清理或 Admin 旧产物处理。