KTeam/kt-template-online-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
0273493ab4
kt-template-online-api/docs/qqbot-bangdream-module-structure-refactor-plan.md

18 KiB
Raw Blame History

QQBot BangDream 模块化文件结构重构方案

生成日期：2026-06-07

目标

基于 docs/qqbot-bangdream-tsugu-reference.md 的重构后现状，继续推进文件结构治理。本方案已落地为源码、测试、脚本和文档迁移记录。

目标是：

  • 去掉 src/qqbot/plugins/bangDream/tsugu 这一层目录，BangDream 内嵌能力直接归入 src/qqbot/plugins/bangDream。
  • 不再按 models、render-blocks、command-renderers、canvas 这类技术能力横向堆文件。
  • 改成按 BangDream 业务模块聚合文件，例如 song、card、event、gacha、player、cutoff。
  • 对真正跨模块的大能力单独抽出，例如 hook、provider、policy、registry、theme。
  • 控制单个文件夹文件数，避免再次出现 render-blocks=66、models=46 的大桶目录。
  • 保持现有 15 个在线命令兼容，迁移期间不改变用户命令文本、返回图片数量和线上 smoke 方式。

迁移前问题

迁移前 tsugu 源码 168 个 TS 文件分布如下：

目录 文件数 问题
render-blocks 66 渲染规格、列表块、详情块、图表和资源 repository 混在一起，目录过大
models 46 领域模型、resource repository、policy、protocol、主数据 store 混在一起
command-renderers 19 以命令输出能力聚合，但和业务模块、模型、渲染块分离太远
canvas 11 底层画布能力独立存在合理，但和 theme/asset manifest 分散
data-clients 10 provider 能力已经清晰，可以作为横切大能力保留
runtime 9 registry、hook、dictionary、config、asset manifest 混在同一目录
search 6 跨模块搜索能力清晰，可以作为横切能力保留
calculations 1 只有档线预测，适合归入 cutoff 或 calculation

迁移前最大的问题不是层级太深，而是“按技术能力横切后文件越来越多”。例如歌曲相关文件散落在 models/song.ts、song-resource-repository.ts、command-renderers/song-*、render-blocks/list-song-*、render-blocks/song-chart-preview-*。后续维护查歌或谱面时需要跨多个目录来回跳。

设计原则

  1. bangDream 插件目录即模块根目录，不再保留 tsugu 子目录。
  2. 业务域模块按用户和上游数据实体命名，不按技术能力命名。
  3. 横切能力只有在多个业务模块共享时才单独成目录。
  4. 每个业务模块内文件直接平铺，默认不再建 model/render/repository 子目录。
  5. 单个目录建议不超过 20 个 TS 文件，超过时优先拆业务子模块，不回退到 models 或 render-blocks 大桶。
  6. 文件名用职责后缀表达角色，例如 song.model.ts、song.repository.ts、song-search.renderer.ts、song-chart.layout.ts。
  7. Jest 测试仍放在 test/qqbot/plugins/bangDream，按源码目标模块同步改路径，不放回源码目录。
  8. 静态资源和静态配置保留 assets、static-config，不跟 TS 源码迁移节奏绑定。

实际落地结构

完整文件职责以 docs/qqbot-bangdream-tsugu-reference.md 为准，当前源码已经去掉 tsugu 子目录，实际顶层结构如下：

src/qqbot/plugins/bangDream/
  application/    Nest 客户端、应用服务、渲染 facade、operation pipeline
  registry/       operation key、handlerName、在线命令别名、冷却和说明
  hook/           生命周期 hook 和命令执行日志 hook
  provider/       Bestdori、HHWX、静态修正、缓存、重试和 URL 解析
  policy/         服务器、国服活动时间、档线、抽卡等跨模块规则
  theme/          Canvas 基础能力、布局 token、资源 manifest 和视觉主题
  config/         运行时配置、环境变量 key、服务器默认值和档线 tier
  dictionary/     默认字典和 API 字典加载
  search/         模糊搜索、关系表达式、搜索字典和实体列表匹配
  song/           查曲、谱面、随机曲、分数表、歌曲资源 repository
  card/           查卡、卡面、卡牌图标、稀有度、技能、综合力渲染
  character/      查角色、角色详情、角色列表和角色资源 repository
  event/          查活动、活动详情、试炼、活动时间和活动数据 repository
  gacha/          查卡池、抽卡模拟、卡池概率、Pick Up 和卡池资源 repository
  player/         查玩家、卡组、乐队等级、角色等级、难度完成和排名
  cutoff/         档线、全档线、近期档线、图表和预测算法
  catalog/        服务器、乐队、属性、区域道具、服装、称号、道具、技能、颜色
  shared/         协议常量、主数据、通用详情块、数据块、列表框架
  commands/       QQBot 在线命令定义桥接
  assets/         本地图片、字体和静态视觉资源
  static-config/  搜索配置、昵称表、CN 修正表和玩家编号表

测试目录按源码模块同步拆分：

test/qqbot/plugins/bangDream/
  application/ card/ catalog/ character/ cutoff/ dictionary/ event/
  gacha/ hook/ player/ policy/ provider/ registry/ search/ shared/ song/ theme/

资源和静态配置同步从旧层级上移，Nest 构建复制路径已改为 qqbot/plugins/bangDream/assets/**/* 和 qqbot/plugins/bangDream/static-config/**/*。

横切能力说明

application

承接 Nest 边界和插件内部 facade：

  • bangdream-client.service.ts：替代当前根部 qqbot-bangdream-client.service.ts，只暴露 execute、checkHealth 和少量明确 API。
  • bangdream-application.service.ts：替代 renderer/tsugu-application.service.ts，唯一应用入口。
  • bangdream-renderer.facade.ts：替代 renderer/qqbot-bangdream-renderer.service.ts，只做 handler 分发、输入归一化、字典解析和 CQ 输出。

registry

只放注册表和注册表类型：

  • operation key
  • handlerName
  • 在线命令别名
  • 冷却
  • 命令说明

不放字典、hook、provider 或 renderer。

hook

只放生命周期 hook：

  • hook context
  • hook registry
  • log hook
  • 后续 metrics/output summary hook

业务决策不放 hook。会改变业务结果的逻辑放 policy 或模块 renderer。

provider

只放外部数据源和缓存下载能力：

  • Bestdori provider
  • HHWX tracker provider
  • static patch provider
  • cache path/policy/client
  • retry/cache/timing decorator

任何模块需要外部 JSON、asset 或 tracker 数据，都通过 provider 或本模块 repository 调用，不直接拼完整 URL。

policy

只放跨模块业务规则：

  • 服务器时区和优先级
  • 国服活动时间预估
  • 档线预测窗口和档位规则
  • 抽卡概率和卡池过滤

单模块私有规则可以先留在模块文件，只有跨模块复用或会独立测试时才移动到 policy。

theme

承接视觉基础能力：

  • 渲染主题 token
  • 本地 asset manifest
  • 通用 layout token
  • Canvas 基础工具

不再使用 canvas 和 render-blocks 作为顶层大桶。各业务模块自己的布局文件放回模块内部，例如 song/song-chart-preview.layout.ts、card/card-stat.layout.ts。

业务模块说明

song

聚合查曲、歌曲详情、随机曲、分数表和谱面预览。现有散落来源：

  • models/song.ts
  • models/song-repository.ts
  • models/song-resource-repository.ts
  • command-renderers/song-*
  • render-blocks/list-song*
  • render-blocks/list-difficulty*
  • render-blocks/song-chart-preview*

card

聚合查卡、卡牌详情、卡面、卡牌图标、插画、稀有度、综合力、技能文字和 SD 缩略图。现有散落来源：

  • models/card.ts
  • models/card-repository.ts
  • models/card-resource-repository.ts
  • command-renderers/card-*
  • render-blocks/card-*
  • render-blocks/list-card-*
  • render-blocks/list-rarity*
  • render-blocks/list-stat*
  • render-blocks/skill-text*

character

聚合角色查询、角色详情、角色列表和玩家详情里的角色等级列表。现有散落来源：

  • models/character.ts
  • models/character-resource-repository.ts
  • command-renderers/character-*
  • render-blocks/list-character*

event

聚合查活动、活动详情、活动列表、试炼和活动时间展示。现有散落来源：

  • models/event.ts
  • models/event-repository.ts
  • models/event-data-repository.ts
  • models/event-stage.ts
  • models/event-stage-data-repository.ts
  • command-renderers/event-*
  • render-blocks/event-stage*
  • render-blocks/list-event-stage.ts
  • render-blocks/list-time*

gacha

聚合查卡池、抽卡模拟、卡池列表、概率和 pick up 展示。抽卡规则本身放 policy/gacha.policy.ts，模块只消费 policy。

player

聚合玩家详情、玩家数据 repository、玩家卡组、乐队等级、角色等级、难度完成情况和排名展示。

cutoff

聚合档线模型、前十榜、单档线、全档线、历史档线、档线图表、时间线图表和预测算法。档线规则本身放 policy/cutoff.policy.ts，模块只消费 policy。

catalog

聚合不直接对应一个 QQBot 命令、但多个模块共享的静态目录实体：

  • 服务器
  • 乐队
  • 属性
  • 区域道具
  • 服装
  • 称号
  • 道具
  • 技能
  • 颜色

这些不再放进 models 大桶。

shared

只放真正跨多个模块的轻量工具、协议和通用渲染块：

  • Bestdori 协议枚举和兼容常量
  • 主数据 store/repository
  • 模型工具函数
  • 通用详情块、数据块、列表框架
  • 图片栈工具

shared 不能成为新的大桶。超过 20 个 TS 文件时必须继续拆模块。

当前到目标迁移映射

当前路径 目标路径
tsugu/runtime/operation-registry.ts registry/operation-registry.ts
tsugu/runtime/hook-registry.ts hook/hook-registry.ts、hook/log-hook.ts
tsugu/runtime/config.ts config/runtime-config.ts
tsugu/runtime/runtime-options.ts config/runtime-options.ts
tsugu/runtime/default-dictionary.ts dictionary/default-dictionary.ts
tsugu/runtime/dictionary-loader.ts dictionary/dictionary-loader.ts
tsugu/runtime/asset-manifest.ts theme/asset-manifest.ts
tsugu/data-clients/* provider/*
tsugu/models/*-policy.ts policy/*.policy.ts
tsugu/search/* search/*
tsugu/canvas/* theme/canvas-*.ts
tsugu/models/song*、command-renderers/song-*、render-blocks/*song*、render-blocks/*difficulty* song/*
tsugu/models/card*、command-renderers/card-*、render-blocks/card-*、render-blocks/list-card-*、render-blocks/list-rarity*、render-blocks/list-stat*、render-blocks/skill-text* card/*
tsugu/models/character*、command-renderers/character-*、render-blocks/list-character* character/*
tsugu/models/event*、command-renderers/event-*、render-blocks/event-stage*、render-blocks/list-event-stage.ts、render-blocks/list-time* event/*
tsugu/models/gacha*、command-renderers/gacha-*、render-blocks/gacha-*、render-blocks/list-gacha-* gacha/*
tsugu/models/player*、command-renderers/player-detail.ts、render-blocks/list-player-*、render-blocks/deck-rank-* player/*
tsugu/models/cutoff*、command-renderers/cutoff-*、render-blocks/*cutoff*、render-blocks/timeline-chart*、calculations/cutoff-predictor.ts cutoff/*
tsugu/models/attribute*、band*、area-item*、costume*、degree*、item*、server*、skill*、color.ts catalog/*
tsugu/render-blocks/detail-block*、data-block*、list-frame*、list-entity*、image-stack.ts shared/*

命名规则

后缀 含义 示例
.model.ts 领域实体和值对象 song.model.ts
.repository.ts 主数据、资源或外部数据读取 song-resource.repository.ts
.renderer.ts 生成图片或组合图片区块 song-chart.renderer.ts
.layout.ts 视觉布局规格、纯布局计算 song-chart-preview.layout.ts
.policy.ts 跨模块业务规则 cutoff.policy.ts
.provider.ts 外部数据源实现 bestdori.provider.ts
.client.ts 缓存、下载或外部客户端 asset-cache.client.ts
.registry.ts 注册表 operation-registry.ts
.types.ts 类型集合 fuzzy-search.types.ts

不再新增：

  • *-spec.ts 作为源码布局文件后缀。后续使用 .layout.ts，避免和 Jest *.spec.ts 语义混淆。
  • models/、render-blocks/、command-renderers/、data-clients/、runtime/、canvas/ 顶层目录。
  • 巨型 index.ts barrel。只允许模块内少量显式 re-export，避免循环依赖。

迁移批次

Phase 0：结构迁移准备

目标：只建立可验证的迁移边界，不移动文件。

任务：

  • 用脚本生成当前文件清单和 import 图。
  • 冻结 15 个 operation 的 smoke 用例。
  • 新增结构守卫脚本：禁止新增 tsugu/ 引用，统计目标目录文件数。
  • 在文档里确认目录预算和命名规则。

验证：

  • 文件清单 168 个 TS 文件全部有目标位置。
  • operation 表 15/15 保持一致。
  • git diff --check、global-review。

Phase 1：横切能力先迁移

目标：先迁移不会改变业务输出的共享能力。

迁移：

  • runtime/operation-registry.ts -> registry/operation-registry.ts
  • runtime/hook-registry.ts -> hook/*
  • runtime/config.ts、runtime/runtime-options.ts -> config/*
  • runtime/default-dictionary.ts、runtime/dictionary-loader.ts -> dictionary/*
  • runtime/asset-manifest.ts、canvas/*、render-blocks/theme.ts、render-blocks/layout-spec.ts -> theme/*
  • data-clients/* -> provider/*
  • models/*-policy.ts -> policy/*
  • search/* -> search/*

验证：

  • pnpm run typecheck
  • registry、hook、dictionary、provider、policy、search 相关 Jest
  • 本地 /查谱面 136 expert 和 /ycx 100 50 cn smoke

Phase 2：低耦合业务模块迁移

目标：迁移文件数量可控、依赖较清晰的模块。

建议顺序：

  1. song
  2. character
  3. gacha
  4. cutoff

验证：

  • 每迁移一个模块跑对应 Jest 和一条图片 smoke。
  • 不推远程，等本批模块全部完成后一次性提交、构建、线上验证。

Phase 3：高耦合业务模块迁移

目标：迁移涉及共享块较多的模块。

建议顺序：

  1. card
  2. event
  3. player
  4. catalog
  5. shared

验证：

  • card：/查卡 472
  • event：/查活动 50、/查试炼 310
  • player：/查玩家 26591455 jp
  • catalog/shared：跑上面三类 smoke 复验

Phase 4：删除旧层级

目标：彻底去掉 tsugu 目录和旧大桶目录。

任务：

  • 删除空的 tsugu 目录。
  • 全局替换 import。
  • 更新 scripts/bangdream-render-smoke.ps1。
  • 更新测试路径。
  • 更新 reference 文档。
  • 更新本方案迁移结果。

验收：

rg -n "plugins/bangDream/tsugu|\\.\\/tsugu|\\.\\.\\/tsugu" src test scripts docs

源码、测试、脚本不能再依赖 tsugu 路径。历史文档允许在“旧路径说明”中出现，但必须明确是旧路径。

Phase 5：完整发布验证

目标：只在批量迁移完成后做一次发布闭环。

必跑：

  • git diff --check
  • pnpm run typecheck
  • BangDream scoped ESLint
  • BangDream 全量 Jest
  • pnpm run build
  • local smoke：查曲、查卡、查活动、查试炼、抽卡、档线、谱面
  • global-review
  • push 后 Jenkins/K8s rollout
  • 线上 /qqbot/command/test smoke 拉图、展示图片、查 operation 日志、清理远程临时目录

目录预算

目录 预算 超过后的处理
song 16 拆出 song-chart 作为业务子模块，不回退到 render-blocks
card 20 拆出 card-art 或 card-detail 作为业务子模块
event 18 拆出 event-stage 作为业务子模块
gacha 14 保持单模块
player 16 拆出 player-ranking 作为业务子模块
cutoff 16 保持单模块
catalog 20 拆出 catalog-degree 或 catalog-server
shared 20 能归业务模块就归业务模块，不能扩成新大桶
provider 14 cache client 可拆 provider-cache
theme 18 canvas 基础可拆 theme-canvas

预算不是硬编译规则，但用于 review：如果一个目录继续增长，先问“这是业务模块太大，还是又按能力堆成大桶了”。

风险点

风险 影响 控制方式
import 路径大规模替换出错 typecheck/Jest 失败 分批迁移，每批只移动一个边界或少数模块
循环依赖被 barrel 放大 运行时 undefined 不建巨型 index.ts，保留显式 import
layout 文件改名导致测试误判 Jest pattern 或 import 失败 源码布局后缀改 .layout.ts，测试仍 .spec.ts
smoke 卡进程 验证耗时不可控 继续使用 bounded smoke 脚本
线上命令误匹配 preview selfId 未绑定命令 线上 smoke 必须按 operationKey 查 commandId
大图 OOM 回归 /查试炼 310 风险最高 保留分页拆图测试和线上 imageCount=5 验证

不做的事

  • 不拆独立 Tsugu 服务。
  • 不引入新仓库。
  • 不为了目录漂亮改业务逻辑。
  • 不把布局像素、资源文件名和协议字段放进字典表。
  • 不把 shared、theme 或 catalog 变成新的 models/render-blocks 大桶。
  • 不在结构迁移之外改 BangDream 命令文本、返回图片数量或业务结果。

完成标准

本次闭环完成时按以下标准验收：

  • src/qqbot/plugins/bangDream/tsugu 不再存在。
  • models、render-blocks、command-renderers、data-clients、runtime、canvas 不再作为 BangDream 顶层源码目录存在。
  • 15 个 operation key、在线命令别名和 handler 绑定保持一致。
  • 每个业务模块能在一个目录内看到模型、repository、renderer 和 layout。
  • hook、provider、policy、registry、theme 是明确横切能力，不包含业务命令编排。
  • 没有目录明显超过预算且未解释。
  • 本地全量验证和线上 smoke 均通过。