BlueArchiveToolkit/docs/archive/ARCHITECTURE_REVIEW_SUMMARY.md

架构审查执行摘要

日期：2026-06-27
状态：🔴 需要立即重构
完整报告：ARCHITECTURE_REVIEW.md

---

🎯 核心结论

当前架构存在严重缺陷，不适合长期维护。必须立即启动重构。

关键问题

1. ❌ 缺少游戏客户端集成层设计（Critical）

   • 整个项目没有定义如何与 Blue Archive 客户端集成
   • 这是项目的核心业务逻辑，但完全缺失

2. ❌ 缺少 Unity 版本适配抽象层（Critical）

   • AssetBundle 解析器假设格式稳定，但 Unity 升级会导致格式完全改变
   • 官方升级 Unity 时，整个解析系统将失效

3. ❌ 缺少 Manifest 格式适配层（High）

   • Manifest 格式可能变化，但没有设计适配机制

4. ❌ 模块职责边界不清晰（High）

   • Storage 和 RefCounter 分离，没有事务保证
   • 可能导致数据不一致

5. ❌ 工作流自动化设计缺失（High）

   • 规划了技术模块，但没有设计完整的业务工作流
   • 官方更新后如何自动适配？流程完全空白

---

📊 风险评估

高风险（必然发生 + 影响极大）

风险	发生概率	影响程度	当前设计维护成本
Unity 版本升级	90%	极高（整个解析系统失效）	极高（需要重写）
Manifest 格式变化	70%	高（资源同步失败）	高（需要大规模修改）
官方反破解机制	50%	极高（工具完全失效）	极高

---

🛠️ 推荐的重构方案

1. 建立清晰的领域模型

// 核心领域对象
pub struct GameClient {
    region: GameRegion,
    version: GameVersion,
    install_path: PathBuf,
    resources: ResourceIndex,
}

pub struct GameVersion {
    major: u32,
    minor: u32,
    patch: u32,
    unity_version: UnityVersion,  // 关键：记录 Unity 版本
}

2. 实施适配器架构

pub trait UnityAdapter {
    fn supported_versions(&self) -> VersionRange;
    fn can_handle(&self, bundle: &RawAssetBundle) -> bool;
    fn parse(&self, bundle: &RawAssetBundle) -> Result<ParsedAssetBundle>;
}

// 新增 Unity 版本 = 新增适配器，不修改已有代码
pub struct Unity2021_3Adapter { }
pub struct Unity2022_3Adapter { }

3. 设计客户端集成层

pub trait ClientIntegration {
    fn discover_installation(&self) -> Result<Vec<GameClient>>;
    fn backup_resources(&self, client: &GameClient) -> Result<BackupId>;
    fn apply_translation(&self, client: &GameClient, patch: &Patch) -> Result<()>;
    fn rollback(&self, client: &GameClient, backup_id: BackupId) -> Result<()>;
}

4. 建立自动化工作流

官方更新 → 版本检测 → Manifest 差异分析 → 资源同步 → 
文本提取 → 差异对比 → 翻译记忆库查询 → AI 翻译 → 
术语替换 → 人工审核 → Patch 生成 → 自动发布

目标：90% 的更新可以在 1 小时内自动完成

---

📁 新目录结构

BlueArchiveToolkit/
├── core/                    # 核心领域层（Rust）
│   ├── domain/             # 领域模型
│   ├── repositories/       # 仓储接口
│   └── services/           # 领域服务
├── adapters/               # 适配器层（Rust）
│   ├── unity/              # Unity 版本适配
│   ├── manifest/           # Manifest 格式适配
│   └── client/             # 客户端平台适配
├── infrastructure/         # 基础设施层（Rust）
│   ├── cas/                # CAS 存储实现
│   ├── downloader/         # 下载器
│   └── parser/             # 底层解析器
├── application/            # 应用服务层（Go）
│   ├── workflows/          # 工作流
│   ├── commands/           # 命令处理器
│   └── queries/            # 查询处理器
└── api/                    # API 层（Go）
    ├── http/               # HTTP API
    └── cli/                # CLI 入口

关键改进：

• ✅ 清晰的分层架构
• ✅ 领域模型独立于技术实现
• ✅ 适配器隔离变化
• ✅ 依赖关系清晰

---

📅 重构时间线

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

Week 1：领域建模

• 定义核心领域对象
• 设计仓储接口
• 实现领域服务

Week 2：适配器架构

• 设计 Unity Adapter 接口
• 实现第一个 Unity 适配器
• 设计 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 版本

---

⚠️ 关键决策

决策 1：采用资源替换方案

选择：直接替换客户端的 AssetBundle 文件（推荐 ⭐）

其他方案：

• ❌ 代理服务器模式：维护成本高，用户体验差
• ❌ 内存补丁模式：技术复杂度极高，容易被检测

理由：

• ✅ 维护成本低
• ✅ 兼容性好
• ✅ 安全性高
• ✅ 易于回滚

决策 2：Rust 核心 + Go 应用层

理由：

• Rust：性能关键路径（解析、Patch、CAS）
• Go：业务编排、HTTP API、CLI
• 优势互补

决策 3：插件化架构

理由：

• Unity 版本必然升级
• Manifest 格式可能变化
• 必须支持扩展

权衡：

• ✅ 长期可维护
• ⚠️ 初期开发成本略高
• ✅ 但避免未来大规模重构

---

💰 成本收益分析

重构成本

• 时间成本：8-10 周（2-2.5 个月）
• 代码成本：约 30-40% 的现有代码需要重构或重写
• 学习成本：需要理解新的架构模式

不重构的后果

1 年内：

• 发现无法适配实际客户端需求
• 官方升级 Unity 导致系统失效
• 需要大量临时方案和 workaround

3 年内：

• 积累大量技术债务
• 代码质量急剧下降
• 维护成本呈指数增长

5 年内：

• 维护成本过高
• 项目陷入停滞
• 可能需要推倒重来

结论

现在重构的成本是最低的，收益是最大的。

---

✅ 下一步行动

立即行动（本周）

1. 审查本架构报告

   • 确认重构方向
   • 确认时间线
   • 确认资源投入

2. 准备重构

   • 备份当前代码
   • 创建 refactor 分支
   • 准备测试环境

3. 开始领域建模

   • 定义核心领域对象
   • 编写领域层代码
   • 编写单元测试

第一周目标

交付物：

• ✅ 完整的领域模型（Rust）
• ✅ 核心接口定义
• ✅ 通过测试的领域层

---

📚 相关文档

• 完整架构审查报告（1900+ 行）
• 当前架构文档
• 开发指南 - 当前开发流程
• Agent 开发规则 - AI agent 长期规则

---

🎓 关键教训

1. 先做对，再做快

   • 不要为了快速实现功能而妥协架构质量

2. 业务领域优先

   • 先理解业务，再选择技术
   • 技术是为业务服务的

3. 拥抱变化

   • Unity 会升级，Manifest 会变化
   • 架构必须能够适应变化

4. 测试驱动

   • 每个模块都要有测试
   • 重构时测试是安全网

5. 文档同步

   • 代码和文档必须保持一致

---

状态：🔴 等待确认后启动重构
负责人：Claude (Chief Architect)
优先级：P0 (最高优先级)