nyaKazuha/BlueArchiveToolkit
1
0
Fork 0
mirror of https://github.com/Yuyi-Oak/BlueArchiveToolkit.git synced 2026-07-22 06:28:00 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity
Files
adc1cd5b91b8b244c6734b723fcf249782c73509
BlueArchiveToolkit/docs/archive/REFACTOR_CHECKLIST.md
T

7.7 KiB
Raw Blame History

架构重构行动检查清单

创建日期：2026-06-27
当前状态：⏸️ 开发已暂停，等待架构确认

📋 架构审查完成情况

  • 完整分析当前项目（所有源代码、目录结构、模块、接口）
  • 识别架构问题
  • 评估长期维护性（1年/3年/5年/10年）
  • 分析 Blue Archive 客户端集成方案
  • 设计自动化适配流程
  • 设计 Unity/Manifest 版本适配架构
  • 识别必须重构的模块（Critical/High/Medium/Low）
  • 重新设计目录结构
  • 评估技术风险
  • 识别未考虑的问题
  • 输出完整架构设计方案

产出文档：

🎯 关键发现（需要你的确认）

Critical 问题（必须立即解决）

  • C1: 缺少游戏客户端集成层设计

    • 问题：整个项目没有定义如何与 Blue Archive 客户端集成
    • 影响：这是项目的核心业务逻辑，完全缺失
    • 建议：立即设计并实现客户端集成层

  • C2: 缺少 Unity 版本适配抽象层

    • 问题：AssetBundle 解析器假设格式稳定
    • 影响：官方升级 Unity 时，整个解析系统将失效
    • 建议：实施 Adapter 架构

  • C3: 缺少 Manifest 格式适配层

    • 问题：没有设计格式适配机制
    • 影响：Manifest 格式变化时，资源同步失败
    • 建议：实施 Driver 架构

High 问题（第一个迭代必须解决）

  • H1: 模块职责边界不清晰

    • 问题：Storage 和 RefCounter 分离，没有事务保证
    • 影响：可能导致数据不一致
    • 建议：重构为统一的 CAS Repository

  • H2: 工作流自动化设计缺失

    • 问题：没有设计完整的业务工作流
    • 影响：无法实现官方更新后的自动适配
    • 建议：建立工作流引擎

📐 推荐的架构方案

方案 1：客户端集成方式

  • 已确认采用：资源替换方案 ⭐

    • 直接替换客户端的 AssetBundle 文件
    • 优点：维护成本低、兼容性好、安全性高
    • 缺点：需要深入理解 Unity AssetBundle 格式

  • 已排除：代理服务器模式

    • 理由：维护成本高，用户体验差

  • 已排除：内存补丁模式

    • 理由：技术复杂度极高，容易被检测

方案 2：技术栈选择

  • 已确认：Rust 核心 + Go 应用层
    • Rust：性能关键路径（解析、Patch、CAS）
    • Go：业务编排、HTTP API、CLI

方案 3：架构模式

  • 已确认：领域驱动设计 (DDD)

    • 领域层：核心业务逻辑
    • 适配器层：隔离变化
    • 应用层：编排业务流程

  • 已确认：插件化架构

    • Unity 适配器：支持多版本
    • Manifest Driver：支持多格式

🗓️ 重构时间线（需要你的确认）

Phase 1：核心架构重构（2-3 周）

  • Week 1：领域建模

    • 定义核心领域对象（GameClient, GameVersion, Resource, Translation）
    • 设计仓储接口
    • 实现领域服务
    • 编写领域层测试

  • Week 2：适配器架构

    • 设计 Unity Adapter 接口
    • 实现第一个 Unity 适配器（当前版本）
    • 设计 Manifest Driver 接口
    • 实现第一个 Manifest Driver
    • 设计客户端集成接口

  • Week 3：基础设施重构

    • 重构 CAS 为统一的 Repository
    • 实现事务支持
    • 重新组织目录结构
    • 迁移现有代码到新架构

Phase 2：工作流实现（2-3 周）

  • Week 4-5：核心工作流

    • 实现版本检测服务
    • 实现资源同步工作流
    • 实现文本提取工作流
    • 实现差异分析器

  • Week 6：翻译工作流

    • 实现翻译记忆库
    • 实现术语库
    • 实现翻译管道
    • 实现审核队列

Phase 3：客户端集成（2 周）

  • Week 7-8：集成层实现
    • 实现客户端发现
    • 实现资源备份
    • 实现资源替换
    • 实现完整性验证
    • 实现回滚机制

Phase 4：打磨和优化（2 周）

  • Week 9-10
    • 性能优化
    • 错误处理完善
    • 日志和监控
    • 文档完善
    • 用户指南
    • 发布 Alpha 版本

总时间估算：8-10 周（2-2.5 个月）

✅ 立即行动项（等待你的确认）

步骤 1：审查架构报告

步骤 2：确认重构方向

  • 确认：是否同意架构审查的结论？
  • 确认：是否接受推荐的重构方案？
  • 确认：是否认可时间线（8-10周）？
  • 确认：是否有其他需要考虑的因素？

步骤 3：决策点

请回答以下问题：

  1. 是否立即启动重构？

    • 是 → 继续步骤 4
    • 否 → 说明原因和调整建议

  2. 是否接受 30-40% 代码需要重写的成本？

    • 是 → 这是必要的投资
    • 否 → 需要讨论替代方案

  3. 对重构方案有任何修改建议吗？

    • 无 → 继续
    • 有 → 请详细说明

步骤 4：启动重构（等待确认后执行）

  • 备份当前代码

    git checkout -b backup/pre-refactor
git push origin backup/pre-refactor

  • 创建重构分支

    git checkout -b refactor/architecture-redesign

  • 开始 Phase 1 Week 1：领域建模

    • 创建 core/domain/ 目录
    • 定义 GameClient 类型
    • 定义 GameVersion 类型
    • 定义 Resource 类型
    • 编写单元测试

📊 成功标准（如何验证重构成功）

技术标准

  • 代码编译通过，无警告
  • 测试覆盖率 > 80%
  • 所有 Critical 问题已解决
  • 所有 High 问题已解决
  • 架构文档完整且与代码一致

业务标准

  • 能够完成一次完整的官方更新适配流程
  • 翻译质量达标（人工审核通过率 > 90%）
  • 用户可以正常使用（端到端测试通过）

可维护性标准

  • 新增 Unity 版本只需要添加适配器（不修改核心代码）
  • 新增 Manifest 格式只需要添加 Driver（不修改核心代码）
  • 代码易读、易测试、易扩展（Code Review 通过）

⚠️ 风险提示

已识别的风险

  1. 重构时间可能超出预期

    • 缓解措施：采用迭代方式，保持可运行状态

  2. 需求理解可能有偏差

    • 缓解措施：尽早实现端到端原型，快速验证

  3. 技术难点可能卡住

    • 缓解措施：预留缓冲时间，准备备选方案

📝 决策记录

请在确认后填写：

  • 决策人：________________
  • 决策日期：________________
  • 是否批准重构：[ ] 是 / [ ] 否
  • 预期开始日期：________________
  • 预期完成日期：________________
  • 其他说明：________________

🎯 下一步

如果你同意架构审查的结论和重构方案：

请回复："确认，开始重构"

我将立即：

  1. 创建重构分支
  2. 开始 Phase 1 Week 1：领域建模
  3. 每天汇报进度

如果你需要修改或讨论：

请告诉我：

  1. 哪些部分需要调整？
  2. 你的顾虑是什么？
  3. 有没有其他想法？

当前状态：⏸️ 等待你的确认
报告作者：Claude (Chief Architect)
文档版本：v1.0

Reference in New Issue View Git Blame Copy Permalink