kt-template-online-api/docs/superpowers/specs/2026-06-15-api-admin-architecture-convergence-v3-design.md

API/Admin 第三期架构收敛批次设计

背景

第三期全量重构已经完成了基础能力、schema、插件平台、NapCat 登录链路和线上闭环，但当前源码结构仍没有完全兑现第三期目标架构：API 业务实现仍散落在 src/admin、src/blog、src/minio、src/wordpress、src/qqbot，src/modules/** 仍大量反向导入旧根。用户已确认本批次选择“方案 A：强门禁全收敛”。

本批次目标不是“继续能跑”，而是让第三期目标架构在当前代码里变成事实：旧根删除，业务实现归入 src/modules/**，结构测试阻止回退，API/Admin 全模块按功能域整理，并在迁移过程中全面清理无用代码、废话代码和重复胶水，同时保持现有功能一致。瘦身不是 QQBot 专项，而是覆盖 Admin/Auth、Platform Config、Blog、WordPress、Asset、QQBot Core、NapCat、Plugin Platform、现有插件、Admin 所有相关 caller 和页面状态的通用门禁。

已确认原则

• 先清干净工作区，再开始架构收敛。
• 清理前必须分类：旧产物可删除，当前目标产物才提交，不确定的改动先停下来确认。
• 不做无意义备份、临时日志提交、根目录临时文件或为了“保险”留下的补丁文件。
• API 与 Admin 使用开发分支，不使用 .worktree。
• 本批次必须覆盖父级模块、子模块、插件目录和 Admin 页面/caller/state，不只移动父级目录。
• 全面瘦身是每个模块迁移的完成条件：每个模块都要扫描旧产物、重复类型、重复状态文案、无引用文件、纯转发胶水和可复用边界，不允许只在 QQBot 上做。
• 功能行为保持一致，内部结构可以破坏式收敛。
• 完成条件必须由结构测试、typecheck、Jest、真实接口 smoke、Admin typecheck/page smoke 和 review 共同证明。

当前状态证据

清理后工作区状态：

• 根仓库 D:\MyFiles\KT：main，干净。
• API 仓库 D:\MyFiles\KT\Node\kt-template-online-api：dev-api-architecture-convergence-v3，干净。
• Admin 仓库 D:\MyFiles\KT\Vue\kt-template-admin：dev-admin-architecture-convergence-v3，干净。
• 其他 KT 子仓库：干净。

API 当前旧结构计数：

路径	文件数	目录数	本批次结论
src/admin	42	11	旧根，必须迁入 src/modules/admin/** 后删除。
src/blog	13	0	旧根，必须迁入 src/modules/blog/** 后删除。
src/minio	5	0	旧根，必须迁入 src/modules/asset/** 后删除。
src/wordpress	9	0	旧根，必须迁入 src/modules/wordpress/** 后删除。
src/qqbot	55	14	旧根，必须迁入 src/modules/qqbot/** 后删除。
src/modules	293	52	目标业务根，但当前仍依赖旧根。
src/common	26	11	允许保留，仅限跨模块基础能力。
src/runtime	13	5	允许保留，仅限运行时基础能力。

src/modules/** 当前反向导入旧根计数：

禁止导入	当前命中数	本批次结论
@/admin/	37	必须归零。
@/blog/	7	必须归零。
@/minio/	3	必须归零。
@/wordpress/	7	必须归零。
@/qqbot/	50	必须归零。

Admin 当前结构证据：

• apps/web-antdv-next/src/api/qqbot 目前有 index.ts、napcat.ts、plugin.ts 和测试文件，caller 初步拆分但仍需按 Core、Plugin Platform、NapCat 的契约边界收敛类型和复用请求模型。
• apps/web-antdv-next/src/views/qqbot 已按 account、command、conversation、dashboard、message、permission、plugin、rule、sendLog 等页面散开，但页面状态、状态标签、登录进度、插件操作和 QQBot 基础管理仍需要统一复用边界。

范围

API

必须完成：

• 删除旧根：src/admin、src/blog、src/minio、src/wordpress、src/qqbot。
• 所有业务实现迁入 src/modules/**：
  • src/modules/admin/**
  • src/modules/blog/**
  • src/modules/wordpress/**
  • src/modules/asset/**
  • src/modules/qqbot/core/**
  • src/modules/qqbot/napcat/**
  • src/modules/qqbot/plugin-platform/**
  • src/modules/qqbot/plugins/**
• src/modules/** 不再导入 @/admin/*、@/blog/*、@/minio/*、@/wordpress/*、@/qqbot/*。
• src/app.module.ts 只注册目标模块，不注册旧根 shim。
• Entity、DTO、Controller、Service、domain policy、integration client、plugin implementation、tests 按实际模块归属移动。
• src/common 只保留真正跨模块基础能力，例如响应、错误、时间、Snowflake、日志、装饰器、通用工具。
• src/runtime 只保留运行时基础能力，例如 HTTP/process/Docker adapter、runtime evidence、health。
• 删除或合并迁移后无引用的重复类型、重复常量、临时兼容胶水、空目录和纯转发文件。
• 对每个 API 模块执行瘦身扫描，输出删除、合并、保留和不确定项的证据；Admin/Auth、Blog、WordPress、Asset、Runtime/Common、QQBot、NapCat、Plugin Platform、插件目录全部适用。

Admin

必须完成：

• 按功能域同步 API caller 和类型：
  • Admin/Auth/Platform Config。
  • Blog/WordPress/Asset。
  • QQBot Core。
  • QQBot Plugin Platform。
  • NapCat 登录与设备。
• QQBot 页面按 Core、Plugin Platform、NapCat 三条边界整理状态和组件，避免账号页、插件页、登录页各自复制状态标签、进度文案、错误归一化和请求处理。
• System、Blog、WordPress、Asset 页面也要做同样瘦身：清理无引用 caller、重复请求包装、重复表格列定义、过时类型、无路由页面、无菜单入口页面和没有复用价值的中间组件。
• 插件管理、NapCat 登录进度、QQBot 账号/命令/规则/消息/发送队列现有功能保持一致。
• 清理无引用组件、重复枚举、过时类型、临时兼容 caller 和只包一层的无意义函数。

测试与文档

必须补齐：

• API 结构测试：旧根不存在、src/modules/** 禁止导入旧根、目标模块边界存在。
• API 行为验证：typecheck、聚焦 Jest、核心接口真实本地 smoke。
• Admin 行为验证：typecheck、关键 QQBot/插件/NapCat 页面 smoke。
• 文档同步：架构收敛说明、必要 API/Admin 契约说明、TASKS.md 简短记录。
• KT global review 与 Superpowers code review。

非目标

• 不新增业务功能。
• 不重新发明第三期 schema，除非迁移 Entity 暴露出当前 schema 与代码不一致；若发现，必须单独列为修复项并有验证。
• 不为了目录好看创建空的 domain/application/infrastructure 文件夹。
• 不保留旧根作为“兼容层”。
• 不把功能保持一致理解为保留内部旧路径。
• 不清理与本批次无关的其他 KT 子仓库。
• 不推送、不部署、不做线上数据库操作，除非后续用户明确要求进入上线闭环。

目标架构

API 目标顶层：

src/
  app.module.ts
  common/
  runtime/
  modules/
    admin/
    asset/
    blog/
    wordpress/
    qqbot/

允许的业务模块内部结构按实际复杂度使用：

module/
  contract/
  application/
  domain/
  infrastructure/
  tests/

规则：

• contract 放 Controller、DTO、SSE event、外部 API 适配。
• application 放用例编排、事务、跨服务状态流转。
• domain 放不依赖 Nest/TypeORM/Docker/HTTP 的规则和值对象。
• infrastructure 放 Entity、Repository、外部集成 client、Docker/NapCat/WordPress/MinIO/worker adapter。
• 小模块可以少层，但不能通过一个大 *.module.ts 继续导入旧根。
• 插件代码仍在 src/modules/qqbot/plugins/**，但插件内部也要按业务能力瘦身，不能把旧顶层 bucket 迁回插件内部。

Admin 目标：

apps/web-antdv-next/src/
  api/
    system/
    blog/
    qqbot/
      core or index
      plugin
      napcat
  views/
    system/
    blog/
    qqbot/
      account/
      command/
      message/
      permission/
      plugin/
      napcat/
      shared/

Admin 允许沿用现有 Vben/Antdv/Vue TSX 组织方式，但状态文案、状态 tag、SSE 进度映射、插件操作按钮和 API 错误解析必须抽到可复用边界。

全模块瘦身门禁

瘦身门禁和目录收敛同级，不能作为后续优化延期。每个模块迁移任务都必须同时回答三件事：删掉了什么，合并了什么，为什么保留。

API 瘦身范围

每个 API 域都要执行：

• Admin/Auth/Platform Config：清理旧 guard/module 转发、重复 DTO、无菜单入口 controller、过时 example、重复 dict/component/notice 类型。
• Blog：清理旧 article/term/theme 类型重复、只为旧路径存在的 service wrapper、无引用 Markdown helper。
• WordPress：清理重复远端 DTO、旧 REST fallback 胶水中无测试保护的分支、无引用 sync helper。
• Asset/MinIO：清理旧 minio 命名遗留中只表达路径而不表达资产域的 wrapper；保留对外路由兼容，但内部命名收敛到 asset。
• Runtime/Common：清理模块私有工具误放 common 的代码；common 只保留跨两个以上业务域复用且有当前引用的能力。
• QQBot Core：清理旧 registry、旧状态别名、重复权限/发送/消息类型和只转发旧服务的 shell。
• NapCat：清理重复登录状态映射、重复 Docker 环境拼装、过期 QR/captcha/new-device 兼容分支；保留已验证的设备持久化和安全校验语义。
• Plugin Platform：清理旧 @/qqbot/plugin 平台依赖、重复 manifest/operation 类型、绕过 SDK 的直接调用。
• 现有插件：BangDream、FF14 Market、FFLogs、Repeater 都要扫内部无用 bucket、重复 provider、重复 layout/theme/helper、过期 legacy key 胶水和直接 HTTP 绕过。

API 瘦身完成证据：

• 每个旧根删除前后都有 rg 引用扫描。
• 删除文件必须有无引用证据；反射、Nest DI、SQL seed、manifest 或外部路由入口必须用测试或 smoke 证明。
• src/common 新增或保留的能力必须至少被两个业务域引用，单模块私有能力迁回模块内。
• 没有仅做旧路径转发的 module/controller/service。

Admin 瘦身范围

Admin 瘦身覆盖所有相关功能域：

• System：登录、菜单、权限、用户、角色、部门、字典、通知、设置页面清理重复类型、重复表格配置、旧路由残留和无入口页面。
• Blog/WordPress/Asset：清理重复 caller、重复列表状态、重复上传/下载/导入状态、无引用组件和旧 API 类型。
• QQBot Core：账号、命令、规则、消息、权限、发送队列共享状态标签、错误解析和表格动作。
• Plugin Platform：插件安装、启用、禁用、配置、健康、事件、账号绑定共享操作状态和表单模型。
• NapCat：设备、登录 session、验证码、新设备二维码和 SSE 进度共享中文状态映射。

Admin 瘦身完成证据：

• rg 证明删除的 caller、组件、类型没有引用。
• 菜单、路由和页面文件一致；不存在有路由无页面、有页面无入口且无测试覆盖的旧页面。
• 重复状态文案和 tag 映射收敛到共享模块，System、Blog/Asset、QQBot/Plugin/NapCat 各自不复制同一套逻辑。
• Admin typecheck 和关键页面 smoke 证明功能保持一致。

清理分类标准

每个待处理文件必须归类后再改：

分类	判断标准	动作
旧产物	位于旧根、只为旧路径存在、迁移后无调用、过渡 shim、重复兼容类型、临时胶水。	迁移必要逻辑后删除，不提交保留副本。
应提交	新目标结构、结构测试、必要行为修复、文档同步、验证脚本或真实复用抽象。	分批提交。
需保留	src/common/src/runtime 中真实跨模块能力、Admin/Vben 框架基础能力、功能保持所需兼容输入输出。	保留并把 import 改到目标边界。
不确定	看起来无引用但可能由反射、Nest DI、路由、SQL seed、插件 manifest 或外部入口调用。	先加搜索证据；只有测试或真实 smoke 证明无活入口后才能删除。

无意义内容包括：

• 单纯转发旧根的 shell module。
• 迁移后没人引用的 DTO/type/entity。
• 与当前功能无关的 demo 页面或临时测试入口。
• 只重复包一层 request、没有统一错误/状态价值的 Admin helper。
• 空目录、重复常量、重复中文状态文案。
• 生成日志、截图、patch 备份、临时 JSON。

收敛顺序

1. RED 结构门禁

先新增失败的结构测试，明确最终架构：

• src/admin、src/blog、src/minio、src/wordpress、src/qqbot 必须不存在。
• src/modules/** 不得导入旧根。
• src/modules/{admin,asset,blog,wordpress,qqbot} 必须存在。
• src/modules/qqbot/{core,napcat,plugin-platform,plugins} 必须存在。
• src/app.module.ts 不得导入旧根。

这些测试在迁移前应失败，迁移结束必须通过。

2. Admin/Auth/Platform Config

把 src/admin/** 迁入 src/modules/admin/**：

• identity：auth、user、role、menu、dept、guard、JWT。
• platform-config：dict、component、notice、timezone、system-log；example 只有在菜单、路由或测试仍证明它是现有功能入口时才迁移，否则删除。
• 清理重复 DTO、过渡 module、旧 import。
• Admin system caller/page 只做必要同步，保持登录、菜单、字典、通知等现有行为。

3. Blog/WordPress/Asset

把 src/blog/**、src/wordpress/**、src/minio/** 迁入目标模块：

• Blog 内容、术语、主题配置进入 src/modules/blog/**。
• WordPress 授权、远端文章/分类/标签/主题进入 src/modules/wordpress/**。
• MinIO controller/service 进入 src/modules/asset/**，对外路由保持兼容。
• 清理只为旧路径存在的 module 和 import。
• Admin blog/asset caller 保持现有页面行为。

4. QQBot Core 与 NapCat

把 src/qqbot/account、command、connection、dashboard、dedupe、message、mqtt、permission、rule、send、config 等核心能力迁入 src/modules/qqbot/core/**。

把 src/qqbot/napcat/** 和登录相关服务迁入 src/modules/qqbot/napcat/**，保持：

• Docker 设备身份持久化。
• quick -> password -> captcha -> new-device -> manual QR 登录顺序。
• GetNewDeviceQRCode -> PollNewDeviceQR -> NewDeviceLogin。
• SSE/Admin 中文进度。
• QQ 登录态、OneBot、WebUI、容器状态继续拆开。

5. Plugin Platform 与现有插件

收敛 src/modules/qqbot/plugin-platform/** 与 src/modules/qqbot/plugins/**：

• 插件平台不得继续依赖旧 @/qqbot/plugin registry。
• 插件接口类型从目标平台 contract 或 SDK 引入。
• BangDream、FF14 Market、FFLogs、Repeater 插件内部扫描无用 bucket、重复 provider、旧 key 胶水和直接 HTTP 绕过。
• legacyKeys 只作为外部数据兼容语义保留；不能成为保留旧源码根的理由。

6. Admin 全域瘦身

整理 Admin 管理面，不只整理 QQBot：

• System 管理：登录、菜单、权限、用户、角色、部门、字典、通知、设置。
• Blog/WordPress/Asset 管理：文章、术语、主题配置、远端同步、上传下载和对象引用。
• Core 管理：账号、命令、规则、消息、权限、发送队列。
• Plugin Platform：插件安装、启用、禁用、配置、健康、事件、账号绑定。
• NapCat：设备身份、登录 session、验证码、新设备二维码、扫码/确认/成功/失败进度。
• 抽取共享状态映射、tag 渲染、SSE 进度解析、API 错误归一化、表格动作模型和上传/导入状态。
• 删除全域无引用页面、组件、重复类型和临时兼容函数。

7. 旧根删除与最终验证

删除旧根后运行完整门禁：

• rg --files src/admin src/blog src/minio src/wordpress src/qqbot 必须找不到路径。
• rg '@/admin/|@/blog/|@/minio/|@/wordpress/|@/qqbot/' src/modules 必须无命中。
• API pnpm run typecheck 通过。
• API 聚焦 Jest 通过；删除旧根后的最终批次运行 API 全量 Jest。
• API 本地真实 smoke 覆盖 /health/runtime、Admin 登录/菜单、Blog public、Asset 上传/下载、QQBot command test、插件平台、NapCat 模拟登录状态机。
• Admin typecheck 通过。
• Admin 关键页面 smoke 通过。
• KT global review 与 Superpowers review 无阻断。

提交策略

本批次提交必须表达真实进展：

1. test/refactor: 增加架构收敛门禁。
2. refactor: 收敛Admin与平台配置模块。
3. refactor: 收敛Blog WordPress Asset模块。
4. refactor: 收敛QQBot核心与NapCat模块。
5. refactor: 收敛QQBot插件平台与现有插件。
6. refactor: 收敛Admin全域管理边界。
7. test: 完成架构收敛验证闭环。

实际执行时可按风险拆得更细，但每个提交都必须满足：

• 没有混入生成产物或备份文件。
• 没有不相关仓库改动。
• 提交前 git status 已确认。
• 若删除文件，已经用搜索、类型检查或测试证明不是活入口。

验收标准

本批次完成必须同时满足：

• API 旧根 src/admin、src/blog、src/minio、src/wordpress、src/qqbot 全部不存在。
• src/modules/** 对旧根导入为 0。
• API 全模块完成瘦身门禁，Admin/Auth、Blog、WordPress、Asset、Runtime/Common、QQBot、NapCat、Plugin Platform 和现有插件没有只为旧结构存在的无引用旧代码。
• Admin 全域页面和 caller 完成边界瘦身，System、Blog/WordPress/Asset、QQBot/插件/NapCat 没有重复状态文案、重复请求胶水和明显无引用旧代码。
• 现有 API 路由和 Admin 功能保持一致。
• 插件平台和现有插件仍可安装、启用、执行、查看健康和运行事件。
• NapCat 登录链路仍覆盖设备持久化、验证码、新设备验证、手动 QR fallback 和中文进度。
• 所有计划中的验证命令有当前证据。
• 代码 review 门禁通过。
• 工作区最终干净。

交接到 writing-plans

用户审阅并确认本 spec 后，下一步进入 Superpowers writing-plans。计划必须把本 spec 拆成可执行任务，尤其要写清：

• 结构测试的 RED/GREEN 步骤和精确文件路径。
• 每个旧根迁移到哪个目标模块。
• 每批删除前的引用扫描命令。
• 每个 API/Admin 模块的全模块瘦身检查项。
• 每批需要保留的行为 smoke。
• Admin 共享状态/进度/错误处理抽取位置。
• 插件和 NapCat 的功能保持验证。
• 每批提交前的干净度检查和 review 门禁。