chore: establish development baseline

2026-07-22 04:15:14 +08:00 · 2026-06-28 01:27:09 +08:00
commit dd53e3054e
131 changed files with 19327 additions and 0 deletions
@@ -0,0 +1,320 @@
+# 架构审查执行摘要
+
+**日期**：2026-06-27  
+**状态**：🔴 **需要立即重构**  
+**完整报告**：[ARCHITECTURE_REVIEW.md](./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. 建立清晰的领域模型
+
+```rust
+// 核心领域对象
+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. 实施适配器架构
+
+```rust
+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. 设计客户端集成层
+
+```rust
+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）
+- ✅ 核心接口定义
+- ✅ 通过测试的领域层
+
+---
+
+## 📚 相关文档
+
+- [完整架构审查报告](./ARCHITECTURE_REVIEW.md)（1900+ 行）
+- [当前架构文档](./architecture/README.md)
+- [CLAUDE.md](../CLAUDE.md) - 项目开发指南
+
+---
+
+## 🎓 关键教训
+
+1. **先做对，再做快**
+   - 不要为了快速实现功能而妥协架构质量
+
+2. **业务领域优先**
+   - 先理解业务，再选择技术
+   - 技术是为业务服务的
+
+3. **拥抱变化**
+   - Unity 会升级，Manifest 会变化
+   - 架构必须能够适应变化
+
+4. **测试驱动**
+   - 每个模块都要有测试
+   - 重构时测试是安全网
+
+5. **文档同步**
+   - 代码和文档必须保持一致
+
+---
+
+**状态**：🔴 等待确认后启动重构  
+**负责人**：Claude (Chief Architect)  
+**优先级**：P0 (最高优先级)