kt-template-online-api/docs/superpowers/specs/2026-06-14-api-full-module-architecture-schema-plugin-platform-design.md

API 全模块架构、全库表设计与 QQBot 插件平台设计

背景

kt-template-online-api 已经从一个相对紧凑的 NestJS 后端，演进为承接 Admin、Blog、WordPress、MinIO、QQBot、NapCat、Loki 运行期事件和线上部署 观测的多领域服务。第一期 Runtime Foundation 已经补上 /health/runtime、 运行时配置检查和证据格式，为后续重构提供了基础观测能力。

第二期不是继续只修 QQBot 或 NapCat，而是进入 API 全模块架构规划。当前线上 数据不重要，因此后续实现阶段允许从头设计数据库表，允许重命名表、删除旧字段、 拆分或合并旧表，并重建初始化 SQL。即便允许破坏式重建，实现阶段仍必须保留 备份、回滚和线上 smoke，避免线上动作不可追踪。

范围决策

本阶段是用户确认的 B 阶段：先完成全局规划，不写业务实现代码。

规划范围：

1. 定义 API 目标模块架构。
2. 从头设计全库 schema。
3. 设计 QQBot 插件平台，支持 worker/child process 隔离、线上安装、热插拔和 CLI 脚手架。
4. 定义后续 C 阶段的迁移矩阵和实施顺序。

本文件不实现代码、SQL、Admin 页面或运行时行为。用户 review 通过后，下一步 进入 Superpowers writing-plans。完整 C 阶段迁移开始前，必须重新走一轮 Superpowers brainstorming。

目标

• 明确每个 controller、use case、entity、repository、外部集成和测试的模块归属。
• 用干净的新 schema 替代当前补丁式表历史。
• 默认保持外部 API 兼容，确实需要破坏兼容时提前列入 breaking changes。
• 将 QQBot 插件从硬编码 Nest provider 集合升级为统一插件平台。
• 通过 CLI 脚手架让插件创建、校验、打包和本地安装可重复。
• 支持线上插件安装、校验、启用、禁用、升级和卸载，不重启整个 API 进程。
• 将现有 BangDream、FF14 Market、FFLogs、Repeater 按统一插件契约重写。
• 继承第一期 Runtime Foundation 的可靠性和证据模型，作为后续模块迁移的验证底座。

非目标

• 本规划阶段不写实现代码。
• 不为了旧数据迁移方便而保留旧表结构。
• 不把 Jenkins/K8s rollout 成功当作功能成功。
• 本阶段不改 Admin 前端。Admin 联动只在本文规划，后续实现前重新 brainstorming。
• 不绕过 QQ 或腾讯安全校验。NapCat 验证码和新设备验证仍然由用户驱动。
• 不允许线上安装的插件代码直接访问后端真实密钥、TypeORM Repository 或任意 Nest DI。

目标架构

目标源码结构按平台基础、通用能力和业务模块拆分：

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

runtime 负责运行时基础能力：

• 类型化运行时配置 profile。
• 带超时、安全摘要和错误分类的 HTTP/process client。
• 健康检查和 /health/runtime。
• 运行证据记录。
• 清理语义。

common 只保留稳定通用能力：

• Vben 响应和错误工具。
• 全局 filter/interceptor。
• 时间字段装饰器和序列化工具。
• Snowflake ID。
• 低层文本、对象工具。
• 非业务专属的日志基础能力。

业务模块内部统一结构：

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

分层职责

contract：Controller、请求 DTO、响应 DTO、Swagger 元信息和现有路由兼容适配。

application：用例编排、事务边界、权限检查和状态流转。可以依赖 domain、 repository 和 integration port，但不能直接拼外部 HTTP、Docker 脚本或临时 SQL。

domain：纯业务规则、状态机、策略和值对象。Domain 代码应能脱离 Nest、TypeORM、 Docker、HTTP 和外部凭据做单元测试。

infrastructure/persistence：TypeORM Entity、Repository 实现、查询模型和 schema mapper。

infrastructure/integration：WordPress HTTP、MinIO SDK、Loki query、OneBot WebSocket、 NapCat WebUI、插件 worker RPC 和 runtime process 适配器。

schema：模块表设计说明、初始化 SQL 归属、重建脚本和验证 SQL。

tests：模块级 unit、contract、repository 和 integration smoke。跨模块用户流程测试可以 继续放在根 test/ 下。

兼容规则

• 外部 route path 默认保持稳定，除非实现计划明确列入 breaking changes。
• Admin-facing 业务接口继续使用当前 Vben success/error wrapper，stream、file、WebSocket 和 plain JSON 接口除外。
• /health/runtime 继续返回 plain JSON。
• Snowflake ID 在 MySQL 中继续使用 BIGINT，在 JavaScript/API 边界按字符串语义处理。
• 时间字段继续使用 KtDateTime extends Date 和 KT 时间装饰器。
• 后续实现阶段可以替换旧 SQL 文件为全量新库初始化文件，但本规划阶段不改 SQL 实现。

全库表设计

后续实现阶段允许从头重建 schema。由于当前数据不重要，目标 schema 优先服务清晰 数据域和模块所有权，而不是旧表兼容。实现阶段仍必须在破坏式数据库动作前备份， 并提供回滚或恢复命令。

全局表约定

• 主键使用 Snowflake BIGINT。
• 外键列命名为 *_id 并建立索引。
• 稳定关系表使用组合唯一约束。
• 高频日志和事件表避免硬数据库外键，减少 retention 和清理成本。
• 只有可恢复、可隐藏的业务配置使用软删。
• 运行事件、命令日志、消息日志、插件运行事件使用 append-only 加 retention。
• 通用时间字段使用 create_time、update_time，需要软删时加 delete_time。
• 状态字段使用明确的 varchar 枚举，并在 schema 说明中列出允许值。
• JSON 字段只承载外部原始 payload、插件 metadata、低频配置或证据详情；可查询字段必须结构化。
• 有 UI 或存储长度限制的文本字段必须写明截断规则。
• 新初始化 SQL 应是干净的全量 schema，不再累积历史 ALTER TABLE 补丁。

数据域表规划

数据域	目标表	说明
Admin Identity	admin_user、admin_role、admin_permission、admin_menu、admin_department、admin_user_role、admin_role_permission、admin_role_menu	保持 Admin 登录和菜单行为稳定，同时拆清路由菜单与权限原子。部门为树结构。头像、时区和首页路径属于用户 profile。
Platform Config	platform_dict_group、platform_dict_item、platform_component_template、platform_setting	字典和组件模板从 Admin 杂项中抽离。字典用 group/item 替代当前扁平重载行。
Blog Content	blog_post、blog_taxonomy、blog_term、blog_post_term、blog_theme_profile、blog_import_job	分类、标签使用关系表，不再依赖逗号或长文本字段。主题配置改为可命名 profile。
WordPress Mirror	wordpress_site、wordpress_auth_session、wordpress_remote_post、wordpress_remote_term、wordpress_sync_job、wordpress_sync_mapping	远端 WordPress 状态与本地 Blog 内容分离。mapping 表连接远端 ID 和本地 post/term。
Asset/MinIO	asset_bucket、asset_object、asset_reference、asset_access_grant	统一记录对象归属、来源模块、MIME/type 元数据和临时访问授权，避免 MinIO URL 散落在业务表。
System Event	system_notice、system_event、system_event_dedupe、system_event_delivery	Loki 仍是日志查询源。MySQL 只保存可处理通知、去重状态和通知投递状态。
Runtime Evidence	runtime_evidence_index	只存重要运行证据文件的安全索引，不存完整日志和 secrets。大 JSON 证据仍保留在 .kt-workspace/test-artifacts 或部署产物存储。
QQBot Core	qqbot_account、qqbot_connection_session、qqbot_capability_binding、qqbot_permission_policy、qqbot_command、qqbot_command_alias、qqbot_rule、qqbot_conversation、qqbot_message、qqbot_send_task、qqbot_send_log、qqbot_dedupe_event	拆分账号身份、连接态、权限、路由、会话、消息历史和发送队列/历史。
NapCat Runtime	napcat_container、napcat_device_identity、napcat_account_binding、napcat_login_session、napcat_login_challenge、napcat_runtime_cleanup	设备身份是一等表，记录 MAC、hostname、machine-id 路径、data dir 和验证状态。登录 challenge 覆盖验证码和新设备验证。清理记录用于阻断假成功。
QQBot Plugin Platform	qqbot_plugin、qqbot_plugin_version、qqbot_plugin_installation、qqbot_plugin_operation、qqbot_plugin_event_handler、qqbot_plugin_account_binding、qqbot_plugin_config、qqbot_plugin_asset、qqbot_plugin_runtime_event	插件 metadata、版本、operation、event、账号绑定、配置、资产和运行事件属于平台，不属于某个插件硬编码。
Plugin-Owned Data	qqbot_plugin_data_* 或插件命名空间表	插件 migration 可创建命名空间表。表名必须以 plugin key 或已注册 namespace 开头，避免冲突。

破坏式重建策略

实现阶段可按以下流程重建数据库：

1. 对线上数据库做带时间戳的备份。
2. 在破坏式 schema 动作期间停止或限制 API 写流量。
3. 按已批准脚本 drop 或 rename 旧 API 表。
4. 应用新的全量初始化 SQL。
5. 初始化必要 Admin 用户、角色、菜单、平台设置、字典、核心 QQBot 插件 metadata 和默认在线命令。
6. 让 API 使用新 schema 启动。
7. 运行本地或线上 smoke：Admin 登录、菜单加载、Blog 公开读取、MinIO check、QQBot command registry、plugin registry、NapCat 账号状态、/health/runtime。
8. 关键 smoke 失败时，恢复备份或重新应用旧 schema bundle，并回滚到上一个 API 镜像。

QQBot 插件平台

QQBot 插件升级为平台能力，不再是硬编码 Nest service 注册。命令插件、事件插件、 渲染插件、外部查询插件和自动化插件使用同一套 contract。

插件包结构

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

plugin.json 是插件元信息的单一来源：

• plugin key、名称、描述、版本、作者、license 和主页。
• 最低 API plugin SDK 版本。
• 请求的 host 权限。
• operations 和 event handlers。
• config schema 和默认值。
• assets 声明。
• migrations 声明。
• runtime 要求，例如 timeout、memory limit 和 worker type。

Worker 隔离运行时

已确认的运行模型是进程隔离：

• API 主进程负责安装包、校验 manifest、维护 registry、路由 command/event。
• 插件代码运行在独立 worker 或 child process 中。
• 插件崩溃只将插件实例标记为 degraded 或 offline，不拖垮 API 主进程。
• 启用、禁用、升级、卸载会启动或停止 worker，并在运行时刷新 registry。
• Worker 和 API 通过窄 RPC 协议通信。

RPC 协议至少支持：

• load：加载 manifest 和编译入口。
• activate：初始化运行态。
• deactivate：停止接收新任务。
• executeOperation：执行命令或查询能力。
• handleEvent：处理消息或账号事件。
• health：返回插件健康状态。
• dispose：关闭前释放资源。

RPC 消息携带 operation ID、correlation ID、timeout budget、脱敏后的输入和结构化输出。 超时由 host 统一控制。

插件 SDK 边界

插件代码不能访问 Nest DI、TypeORM 原始 Repository、后端原始环境变量或任意文件路径。 插件只能拿到受控 SDK：

• 通过 host 发送队列发送 QQBot 消息。
• 通过插件配置服务读写插件配置。
• 读写插件自有 storage。
• 发送插件运行事件。
• 请求 host 提供的 runtime HTTP 能力，带 timeout 和安全证据。
• 从插件 asset root 加载已声明静态资源。
• 读取当前 operation 或 event context。

插件必须在安装前声明权限。Manifest 请求未支持权限，或代码包 hash 与校验记录不一致时， host 必须拒绝安装或启用。

CLI 脚手架

仓库应新增插件作者 CLI：

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

create 自动生成：

• plugin.json。
• 带 createPlugin() 的 src/index.ts。
• 一个 operation handler 模板。
• 一个 event handler 模板。
• config schema 和默认值。
• migration/schema 模板。
• contract tests。
• package metadata。
• README/API 片段草稿。

validate 校验 manifest shape、operation key、event key、权限、schema 文件、migrations、 包大小、禁用路径和基础测试是否存在。

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

install-local 使用与线上安装相同的校验链路，将插件包安装到本地开发插件根目录。

线上安装和热插拔状态机

插件安装状态流转：

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

Admin 上传插件包后，API 校验 manifest、包 hash、版本兼容、权限、migration 和 assets。 插件包保存到受控运行时插件目录，不能写入 src/。

启用插件时启动 worker，注册 operations 和 event handlers，并记录运行状态。禁用插件时 停止 worker，并从路由中移除 active operation/event，不删除数据。卸载插件时停止 worker、 移除 registry、解绑 command/event，然后按数据策略处理插件数据：默认保留，只有管理员 明确选择清理时才删除。

现有插件重写计划

BangDream 作为大型参考插件。现有业务能力拆分可以保留在插件包内：

bangDream/
  operations/
  song/
  card/
  character/
  event/
  gacha/
  player/
  cutoff/
  provider/
  renderer/
  theme/
  assets/

现有 BangDream operation registry 改为由 manifest 支撑 operation metadata。 handlerName 仍作为 worker 内部实现细节。现有图片 smoke 预期继续保留，包括 event stage 拆图输出行为。

FF14 Market 改为外部查询插件，通过 host runtime HTTP SDK 调用 XIVAPI 和 Universalis。

FFLogs 改为外部查询插件，通过 host runtime HTTP SDK 调用 GraphQL/token，并通过插件 config 引用客户端凭据。

Repeater 改为事件插件，由 host 管理账号绑定，由插件持有 transient state，且必须走 host 发送队列，不能直接绕过限流和发送排队。

模块迁移矩阵

后续实现阶段拆成可审计批次：

批次	范围	结果
0	迁移准备	新 schema map、全量初始化 SQL 计划、破坏式重建脚本计划、备份/恢复命令、验证 SQL、模块模板和 breaking-change 清单。
1	Runtime/Common	保持 runtime foundation 稳定，补齐模块 adapter 需要的 runtime client/evidence 原语，收缩 common 到稳定共享能力。
2	Admin/Auth/Platform Config	重建身份、菜单、权限、字典、组件模板和系统通知模型。Admin 登录和菜单加载必须先通过。
3	Blog/WordPress/Asset	重建 Blog 内容关系、WordPress mirror/sync 和 MinIO asset 归属。Blog 公开读取和 Admin Blog 管理必须通过。
4	QQBot Core	重建账号、连接、权限、命令、规则、会话、消息和发送队列模型。命令匹配和发送队列测试必须通过。
5	QQBot Plugin Platform	新增插件 manifest 校验、数据库 registry、CLI 脚手架、worker runtime、RPC、线上安装、热插拔状态和 Admin/API 管理契约。
6	Existing Plugin Rewrite	将 BangDream、FF14 Market、FFLogs、Repeater 重写为隔离插件包。现有命令 smoke 行为必须继续可用。
7	NapCat Runtime	在新 QQBot/NapCat 模型上实现容器设备持久化、登录 session 状态机、验证码/新设备流程和清理证据。
8	线上闭环	发布后观察 Jenkins/K8s，运行 /health/runtime、Admin smoke、Blog smoke、插件安装/启用 smoke、QQBot command smoke 和真实 NapCat 账号登录 smoke。

NapCat 故意排在 QQBot Core 和 Plugin Platform 后面。它依赖新账号模型，并和 command/event 路由共同参与线上验证，但它本身不是插件。

契约和破坏兼容策略

默认保持外部 API 兼容。任何实现任务如果改变 route path、请求字段、响应字段、状态语义、 SSE 事件名、Admin API wrapper 或 SQL seed 标识，都必须在编码前写入 breaking-change 表。

允许的计划内破坏：

• 数据库表名、字段、索引和初始化 SQL 可以自由改变，因为 schema 从头设计。
• Admin 页面可能需要在实现阶段同步 API wrapper。
• 插件管理接口是新增能力，可以使用新的 route shape。

必须保护的行为：

• Admin 登录和菜单加载。
• 业务 API 的 Vben 响应 wrapper。
• /health/runtime plain JSON。
• Blog public article list/detail。
• QQBot command test flow。
• QQBot 账号状态继续区分 OneBot 连接、容器、WebUI 和 QQ 登录态。
• NapCat 登录安全校验、验证码回交、新设备验证和运行态密码清理失败阻断成功语义。

验证策略

本规划阶段验证：

• spec 自检：未决标记、内部矛盾和模糊范围。
• git diff --check。
• KT 文档同步检查。
• KT global review 扫描变更文件。

后续实现阶段必须包含：

• domain policy 和状态机的定向单测。
• 新 SQL 和 TypeORM mapping 的 repository/schema 测试。
• CLI 生成的插件 contract tests。
• worker runtime 的 load、activate、execute、health、deactivate 和崩溃隔离测试。
• 变更接口的真实本地 API 请求。
• Admin caller 变化时的 Admin UI smoke。
• 破坏式线上数据库动作前，本地数据库重建 dry run。
• 线上备份、重建、恢复路径、Jenkins/K8s 观测和功能 smoke。

本规划阶段验收标准

本阶段完成条件：

1. 设计文档写入 docs/superpowers/specs/。
2. 设计文档已提交。
3. 用户 review 已提交文档。
4. 下一步进入 Superpowers writing-plans，不是直接实现代码。
5. 后续完整迁移开始前，重新走 Superpowers brainstorming。

交接到下一阶段

用户 review 通过后，writing-plans 阶段应产出计划文档，把本文转换成可执行 work packages、 schema 文档、插件平台任务和验证清单。

后续完整实现必须重新 brainstorming，因为它会涉及破坏式 schema 工作、Admin/API 契约决策、 插件运行时安全边界和线上闭环。