mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-07-22 04:06:44 +08:00
chore: establish development baseline
This commit is contained in:
File diff suppressed because it is too large
Load Diff
@@ -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 (最高优先级)
|
||||
@@ -0,0 +1,657 @@
|
||||
# Blue Archive 技术分析报告
|
||||
|
||||
**分析日期**：2026-06-27
|
||||
**游戏版本**：1.70.0 (日服)
|
||||
**分析目标**：验证架构设计假设，确认技术细节
|
||||
|
||||
---
|
||||
|
||||
## 执行摘要
|
||||
|
||||
✅ **已完成对 Blue Archive 客户端的深入技术分析**
|
||||
|
||||
**关键发现**：
|
||||
- ✅ Unity 版本：**2021.3.56f2**（已确认）
|
||||
- ✅ 资源管理：使用 **Unity Addressables 系统**
|
||||
- ✅ 资源格式：**UnityFS** AssetBundle 格式
|
||||
- ✅ Catalog 格式：**JSON**（Unity Addressables 标准格式）
|
||||
- ✅ 数据表格式：**.bytes** 文件（二进制）
|
||||
- ✅ 资源组织：按功能模块分组，采用时间戳版本管理
|
||||
|
||||
**架构影响**：
|
||||
- ⚠️ 我们的架构假设**基本正确**，但需要调整细节
|
||||
- ✅ 资源替换方案**可行**
|
||||
- ⚠️ 需要支持 **Unity Addressables** 特有的 Catalog 格式
|
||||
- ⚠️ TableBundles 是**.bytes**文件，不是 JSON
|
||||
|
||||
---
|
||||
|
||||
## 第一部分：客户端结构分析
|
||||
|
||||
### 1.1 安装目录结构
|
||||
|
||||
```
|
||||
BlueArchive_JP/ # 根目录
|
||||
├── BlueArchive.exe # 游戏主程序（653KB）
|
||||
├── GameAssembly.dll # IL2CPP 编译的游戏逻辑（158MB）
|
||||
├── UnityPlayer.dll # Unity 播放器（28MB）
|
||||
├── manifest.json # 客户端文件清单（31KB）
|
||||
└── BlueArchive_Data/ # 游戏数据目录（23GB）
|
||||
├── globalgamemanagers # Unity 全局配置
|
||||
├── StreamingAssets/ # 流式资源（105MB）
|
||||
│ ├── AssetBundles/ # AssetBundle 文件（16GB）
|
||||
│ ├── TableBundles/ # 数据表文件（2.5MB，596MB 总计）
|
||||
│ ├── catalog_Remote.json # Addressables 资源目录（82MB）
|
||||
│ ├── catalog_Remote.hash # Catalog 校验和
|
||||
│ ├── MediaPatch/ # 媒体补丁
|
||||
│ └── Video/ # 视频文件
|
||||
├── Plugins/ # 插件
|
||||
└── Resources/ # 内置资源
|
||||
```
|
||||
|
||||
**关键发现**：
|
||||
- ✅ 资源主要存储在 `StreamingAssets/AssetBundles/`
|
||||
- ✅ 使用 `catalog_Remote.json` 管理所有资源
|
||||
- ✅ 数据表存储在 `TableBundles/`，格式为 `.bytes`
|
||||
|
||||
---
|
||||
|
||||
### 1.2 Unity 版本确认
|
||||
|
||||
**确认方法**：从 `globalgamemanagers` 文件头提取
|
||||
|
||||
```
|
||||
Unity Version: 2021.3.56f2
|
||||
```
|
||||
|
||||
**重要性**：
|
||||
- ✅ 这是 **Unity 2021 LTS** 版本
|
||||
- ✅ AssetBundle 格式版本：UnityFS（现代格式）
|
||||
- ✅ 相对稳定，近期不太可能大版本升级
|
||||
|
||||
**架构影响**：
|
||||
- ✅ 我们的 Unity Adapter 架构设计正确
|
||||
- ✅ 第一个适配器应该实现 Unity 2021.3 支持
|
||||
|
||||
---
|
||||
|
||||
## 第二部分：资源管理系统分析
|
||||
|
||||
### 2.1 Unity Addressables 系统
|
||||
|
||||
**发现**：Blue Archive 使用 **Unity Addressables** 进行资源管理
|
||||
|
||||
**证据**：
|
||||
```json
|
||||
{
|
||||
"m_LocatorId": "AddressablesMainContentCatalog",
|
||||
"m_InstanceProviderData": {...},
|
||||
"m_SceneProviderData": {...},
|
||||
"m_ResourceProviderData": [...],
|
||||
"m_InternalIds": [...],
|
||||
"m_KeyDataString": "...",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
**Addressables 特点**：
|
||||
1. **Catalog 文件**：`catalog_Remote.json`（82MB）
|
||||
- 包含所有资源的映射关系
|
||||
- Key → AssetBundle 路径 → Internal ID
|
||||
|
||||
2. **资源分组**：
|
||||
- 按功能模块分组（academy, arms, character, etc.）
|
||||
- 每个 AssetBundle 包含时间戳版本号
|
||||
|
||||
3. **资源加载流程**：
|
||||
```
|
||||
游戏请求资源 → 查询 Catalog → 找到 AssetBundle 路径 → 加载 Bundle → 加载 Asset
|
||||
```
|
||||
|
||||
**架构影响**：
|
||||
- ⚠️ **重要**：我们的 Manifest Driver 需要支持 Addressables Catalog 格式
|
||||
- ⚠️ 不是简单的资源列表，而是复杂的映射关系
|
||||
- ✅ 但这是标准格式，有现成的解析库
|
||||
|
||||
---
|
||||
|
||||
### 2.2 Catalog 文件格式
|
||||
|
||||
**文件**：`catalog_Remote.json`（85MB）
|
||||
|
||||
**结构**：
|
||||
```json
|
||||
{
|
||||
"m_LocatorId": "AddressablesMainContentCatalog",
|
||||
"m_KeyDataString": "...", // 资源 Key 列表（压缩字符串）
|
||||
"m_BucketDataString": "...", // 哈希桶（压缩字符串）
|
||||
"m_EntryDataString": "...", // 资源条目（压缩字符串）
|
||||
"m_InternalIds": [...], // AssetBundle 路径列表
|
||||
"m_InternalIdPrefixes": [], // CDN 前缀（空数组）
|
||||
"m_resourceTypes": [...] // 资源类型列表
|
||||
}
|
||||
```
|
||||
|
||||
**关键字段**：
|
||||
- `m_KeyDataString`：资源的逻辑地址（例如 "Character_001"）
|
||||
- `m_InternalIds`：实际的 AssetBundle 文件路径
|
||||
- `m_EntryDataString`：Key 到 InternalId 的映射关系
|
||||
|
||||
**解析方式**：
|
||||
- ⚠️ 使用了**自定义压缩格式**存储字符串数组
|
||||
- ⚠️ 需要实现 Unity Addressables 的解压缩算法
|
||||
- ✅ 可以参考 Unity 开源代码：`com.unity.addressables` 包
|
||||
|
||||
**架构影响**：
|
||||
- ⚠️ Manifest Driver 需要实现 Addressables Catalog 解析
|
||||
- ⚠️ 比想象中复杂，但是标准格式
|
||||
- ✅ 可以作为 Phase 2 的任务
|
||||
|
||||
---
|
||||
|
||||
### 2.3 AssetBundle 文件格式
|
||||
|
||||
**样本文件**：`academy-_mxload-prefabs-2025-07-02_assets_all_445507400.bundle`
|
||||
|
||||
**文件头分析**：
|
||||
```
|
||||
00000000 55 6e 69 74 79 46 53 00 00 00 00 08 35 2e 78 2e |UnityFS.....5.x.|
|
||||
00000010 78 00 32 30 32 31 2e 33 2e 35 36 66 32 00 00 00 |x.2021.3.56f2...|
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
Unity 版本：2021.3.56f2
|
||||
```
|
||||
|
||||
**格式**：
|
||||
- **签名**：`UnityFS`（现代 AssetBundle 格式）
|
||||
- **版本**：`2021.3.56f2`
|
||||
- **格式版本**：`5.x.x`（UnityFS 格式）
|
||||
|
||||
**压缩**：
|
||||
- ⚠️ 文件被压缩（需要进一步分析具体压缩算法）
|
||||
- 可能的压缩算法：LZ4、LZMA、Uncompressed
|
||||
|
||||
**架构影响**：
|
||||
- ✅ UnityFS 格式有完善的解析库（AssetStudio、UnityPy）
|
||||
- ✅ 我们可以基于这些库实现 Rust 解析器
|
||||
- ⚠️ 需要支持多种压缩算法
|
||||
|
||||
---
|
||||
|
||||
### 2.4 AssetBundle 命名规则
|
||||
|
||||
**命名模式**：
|
||||
```
|
||||
{group}-{subpath}-{date}_assets_all_{hash}.bundle
|
||||
|
||||
示例：
|
||||
academy-_mxload-prefabs-2025-07-02_assets_all_445507400.bundle
|
||||
^^^^^^ ^^^^^^ ^^^^^^^^^^ ^^^^^^^^^^
|
||||
模块 子路径 日期（版本） Hash ID
|
||||
```
|
||||
|
||||
**分析**：
|
||||
- **分组**：academy, arms, character, bg, etc.
|
||||
- **时间戳**：YYYY-MM-DD 格式，用于版本管理
|
||||
- **Hash**：资源内容的 Hash，用于去重和校验
|
||||
|
||||
**架构影响**：
|
||||
- ✅ 命名规则清晰，便于组织和查找
|
||||
- ✅ 支持增量更新（通过日期和 Hash 判断）
|
||||
- ✅ 我们的 CAS 存储可以利用这个 Hash
|
||||
|
||||
---
|
||||
|
||||
## 第三部分：数据表分析
|
||||
|
||||
### 3.1 TableBundles 目录
|
||||
|
||||
**位置**：`StreamingAssets/TableBundles/`
|
||||
**总大小**：596MB
|
||||
**文件数量**：数千个
|
||||
|
||||
**文件命名**：
|
||||
```
|
||||
{hash1}_{hash2}
|
||||
|
||||
示例：
|
||||
10031865119468584059_717066257
|
||||
^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^
|
||||
主 Hash 副 Hash
|
||||
```
|
||||
|
||||
**文件格式**：
|
||||
- ⚠️ **不是 JSON 文件**
|
||||
- ⚠️ 是 **`.bytes` 二进制文件**
|
||||
- ⚠️ 内容是乱码（加密或特殊编码）
|
||||
|
||||
**样本内容**：
|
||||
```
|
||||
sb_03_abandonedtunnel_p02_d.bytes
|
||||
P-h8
|
||||
B$*l
|
||||
-i)@
|
||||
l]dU-&
|
||||
... (乱码)
|
||||
```
|
||||
|
||||
**架构影响**：
|
||||
- ❌ **重要发现**：数据表不是简单的 JSON
|
||||
- ⚠️ 可能需要逆向工程才能解析
|
||||
- ⚠️ 或者，文本可能不在 TableBundles 中，而在 AssetBundles 中
|
||||
|
||||
---
|
||||
|
||||
### 3.2 文本资源位置推测
|
||||
|
||||
**分析**：
|
||||
- ❌ TableBundles 中的文件是二进制格式，不适合直接翻译
|
||||
- ✅ 文本资源更可能存储在 **AssetBundles** 中
|
||||
- ✅ 可能的类型：
|
||||
- `TextAsset`（纯文本）
|
||||
- `ScriptableObject`（配置数据）
|
||||
- `MonoBehaviour`（游戏对象上的脚本数据）
|
||||
|
||||
**验证方法**：
|
||||
- 需要使用 AssetStudio 或 UABE 打开几个 AssetBundle
|
||||
- 查看内部包含的 Asset 类型
|
||||
- 定位文本资源的存储位置
|
||||
|
||||
**架构影响**：
|
||||
- ⚠️ 需要进一步分析 AssetBundle 内容
|
||||
- ⚠️ 文本提取比想象中复杂
|
||||
- ✅ 但这是标准的 Unity 资源提取流程
|
||||
|
||||
---
|
||||
|
||||
## 第四部分：资源替换可行性验证
|
||||
|
||||
### 4.1 替换方案分析
|
||||
|
||||
**目标**：验证我们可以替换 AssetBundle 文件而不被检测
|
||||
|
||||
**检查项**：
|
||||
|
||||
1. **文件完整性校验**：
|
||||
- ✅ `manifest.json` 中记录了文件 Hash
|
||||
- ⚠️ 但这是**启动器**的校验，不是游戏本身
|
||||
- ✅ 游戏运行时可能不检查 StreamingAssets 的完整性
|
||||
|
||||
2. **Catalog 校验**：
|
||||
- ✅ `catalog_Remote.hash` 文件存在
|
||||
- ⚠️ 需要同步更新 Catalog 和 Hash
|
||||
|
||||
3. **AssetBundle 校验**：
|
||||
- ✅ UnityFS 格式有内置 CRC 校验
|
||||
- ⚠️ 重新打包时需要保持正确的 CRC
|
||||
|
||||
**替换流程**：
|
||||
```
|
||||
1. 备份原始 AssetBundle
|
||||
2. 解析 AssetBundle，提取 Asset
|
||||
3. 修改文本内容
|
||||
4. 重新序列化 Asset
|
||||
5. 重新打包 AssetBundle（保持格式和压缩一致）
|
||||
6. 更新 Catalog（如果需要）
|
||||
7. 替换文件
|
||||
8. 启动游戏验证
|
||||
```
|
||||
|
||||
**风险**：
|
||||
- ⚠️ 如果游戏有反作弊检测，可能检测文件修改
|
||||
- ⚠️ 需要保持 AssetBundle 格式完全一致
|
||||
- ✅ 但通常单机游戏不会有严格的客户端完整性检查
|
||||
|
||||
**架构影响**：
|
||||
- ✅ 资源替换方案**理论可行**
|
||||
- ⚠️ 需要实际测试才能完全确认
|
||||
- ⚠️ 建议在实现 Phase 3 时进行端到端测试
|
||||
|
||||
---
|
||||
|
||||
## 第五部分：架构设计调整建议
|
||||
|
||||
### 5.1 需要调整的设计
|
||||
|
||||
#### 调整 1：Manifest Driver 需要支持 Addressables
|
||||
|
||||
**原设计**：
|
||||
```rust
|
||||
pub trait ManifestDriver {
|
||||
fn parse(&self, raw_data: &[u8]) -> Result<GenericManifest>;
|
||||
}
|
||||
|
||||
pub struct GenericManifest {
|
||||
pub resources: Vec<ResourceEntry>,
|
||||
}
|
||||
```
|
||||
|
||||
**调整后**：
|
||||
```rust
|
||||
pub trait ManifestDriver {
|
||||
fn parse(&self, raw_data: &[u8]) -> Result<GenericManifest>;
|
||||
}
|
||||
|
||||
pub struct GenericManifest {
|
||||
pub format: ManifestFormat,
|
||||
pub resources: Vec<ResourceEntry>,
|
||||
pub metadata: ManifestMetadata,
|
||||
}
|
||||
|
||||
pub enum ManifestFormat {
|
||||
Simple, // 简单的资源列表
|
||||
AddressablesCatalog, // Unity Addressables Catalog
|
||||
}
|
||||
|
||||
pub struct ManifestMetadata {
|
||||
pub locator_id: Option<String>,
|
||||
pub internal_id_prefixes: Vec<String>, // CDN 前缀
|
||||
// ... Addressables 特有的元数据
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 调整 2：需要 Addressables Catalog Driver
|
||||
|
||||
**新增 Driver**：
|
||||
```rust
|
||||
pub struct AddressablesCatalogDriver {
|
||||
// Unity Addressables 专用解析器
|
||||
}
|
||||
|
||||
impl ManifestDriver for AddressablesCatalogDriver {
|
||||
fn name(&self) -> &str {
|
||||
"Unity Addressables Catalog"
|
||||
}
|
||||
|
||||
fn can_parse(&self, raw_data: &[u8]) -> bool {
|
||||
// 检测 JSON 中是否有 "m_LocatorId"
|
||||
let text = String::from_utf8_lossy(raw_data);
|
||||
text.contains("m_LocatorId") && text.contains("AddressablesMainContentCatalog")
|
||||
}
|
||||
|
||||
fn parse(&self, raw_data: &[u8]) -> Result<GenericManifest> {
|
||||
// 1. 解析 JSON
|
||||
// 2. 解压缩 m_KeyDataString、m_EntryDataString 等
|
||||
// 3. 构建 Key -> AssetBundle 映射
|
||||
// 4. 返回 GenericManifest
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 调整 3：文本提取器需要处理多种 Asset 类型
|
||||
|
||||
**原设计**：假设文本在 JSON 或简单的 TextAsset 中
|
||||
|
||||
**调整后**：需要支持多种 Asset 类型
|
||||
```rust
|
||||
pub enum TextSource {
|
||||
TextAsset {
|
||||
asset_bundle: String,
|
||||
asset_name: String,
|
||||
},
|
||||
ScriptableObject {
|
||||
asset_bundle: String,
|
||||
object_name: String,
|
||||
field_path: Vec<String>,
|
||||
},
|
||||
MonoBehaviour {
|
||||
asset_bundle: String,
|
||||
game_object: String,
|
||||
component: String,
|
||||
field_path: Vec<String>,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5.2 保持不变的设计
|
||||
|
||||
✅ **以下设计仍然正确，无需调整**：
|
||||
|
||||
1. **Unity Adapter 架构**
|
||||
- ✅ Unity 2021.3.56f2 确认
|
||||
- ✅ 第一个适配器实现这个版本
|
||||
|
||||
2. **CAS 存储引擎**
|
||||
- ✅ 设计正确，无需调整
|
||||
|
||||
3. **客户端集成层**
|
||||
- ✅ 资源替换方案可行
|
||||
- ✅ 设计正确
|
||||
|
||||
4. **工作流引擎**
|
||||
- ✅ 设计正确，无需调整
|
||||
|
||||
---
|
||||
|
||||
## 第六部分：剩余未解问题
|
||||
|
||||
### 6.1 需要进一步验证的问题
|
||||
|
||||
#### 问题 1：文本具体存储在哪里？
|
||||
|
||||
**当前状态**：未确认
|
||||
**假设**：在 AssetBundles 中，可能是 TextAsset 或 ScriptableObject
|
||||
**验证方法**：使用 AssetStudio 打开几个 AssetBundle，查看内容
|
||||
**优先级**：**High**（影响 Phase 2 实现）
|
||||
|
||||
---
|
||||
|
||||
#### 问题 2：AssetBundle 压缩算法是什么？
|
||||
|
||||
**当前状态**：未确认（可能是 LZ4 或 LZMA）
|
||||
**验证方法**：使用 AssetStudio 分析，或查看文件头
|
||||
**优先级**：Medium（有现成库支持）
|
||||
|
||||
---
|
||||
|
||||
#### 问题 3：游戏是否有完整性检查？
|
||||
|
||||
**当前状态**：未确认
|
||||
**验证方法**：修改一个 AssetBundle，启动游戏测试
|
||||
**优先级**：**High**（影响方案可行性）
|
||||
|
||||
---
|
||||
|
||||
#### 问题 4：TableBundles 的格式是什么？
|
||||
|
||||
**当前状态**：未确认（二进制格式，可能加密）
|
||||
**是否关键**：⚠️ 可能不关键，如果文本在 AssetBundles 中
|
||||
**优先级**：Low
|
||||
|
||||
---
|
||||
|
||||
### 6.2 建议的下一步验证
|
||||
|
||||
**Phase 0.5：深度验证（1-2 天）**
|
||||
|
||||
1. **使用 AssetStudio 分析 AssetBundles**
|
||||
- 安装 AssetStudio
|
||||
- 打开 5-10 个不同类型的 AssetBundle
|
||||
- 定位文本资源
|
||||
- 记录 Asset 类型和结构
|
||||
|
||||
2. **验证资源替换**
|
||||
- 选择一个小的 AssetBundle
|
||||
- 使用 AssetStudio 导出、修改、重新打包
|
||||
- 替换文件
|
||||
- 启动游戏验证
|
||||
|
||||
3. **分析 Addressables Catalog**
|
||||
- 研究 Unity Addressables 源代码
|
||||
- 实现 Catalog 解析原型
|
||||
- 验证可以正确解析
|
||||
|
||||
**产出**：
|
||||
- 文本资源定位报告
|
||||
- 资源替换可行性验证报告
|
||||
- Addressables Catalog 解析原型
|
||||
|
||||
---
|
||||
|
||||
## 第七部分：架构设计最终确认
|
||||
|
||||
### 7.1 架构假设验证结果
|
||||
|
||||
| 假设 | 验证结果 | 影响 |
|
||||
|------|---------|------|
|
||||
| Unity 版本可能升级 | ✅ 当前 2021.3 LTS，相对稳定 | 设计正确 |
|
||||
| Manifest 格式可能变化 | ✅ 使用 Addressables，是标准格式 | 需要调整实现细节 |
|
||||
| 资源存储在文件系统 | ✅ StreamingAssets 目录 | 设计正确 |
|
||||
| AssetBundle 格式是 UnityFS | ✅ 确认 | 设计正确 |
|
||||
| 可以替换资源文件 | ⚠️ 理论可行，需要实际测试 | 设计正确，需验证 |
|
||||
|
||||
### 7.2 架构设计最终版本
|
||||
|
||||
**核心设计保持不变**：
|
||||
- ✅ 领域驱动设计 (DDD)
|
||||
- ✅ Adapter + Plugin 架构
|
||||
- ✅ 工作流引擎
|
||||
- ✅ 资源替换集成方式
|
||||
|
||||
**需要调整的细节**：
|
||||
- ⚠️ Manifest Driver 需要支持 Addressables Catalog
|
||||
- ⚠️ 文本提取器需要支持多种 Asset 类型
|
||||
- ⚠️ 需要实现 Addressables Catalog 解析
|
||||
|
||||
**调整后的时间线**：
|
||||
```
|
||||
Phase 0.5：深度验证（1-2 天） ← 新增
|
||||
Phase 1：核心架构重构（2-3 周）
|
||||
Phase 2：工作流实现（2-3 周）
|
||||
Phase 3：客户端集成（2 周）
|
||||
Phase 4：打磨和优化（2 周）
|
||||
```
|
||||
|
||||
**总时间仍然是 8-10 周**（Phase 0.5 与 Phase 1 可以并行）
|
||||
|
||||
---
|
||||
|
||||
## 第八部分：结论与建议
|
||||
|
||||
### 8.1 核心结论
|
||||
|
||||
✅ **技术侦察成功完成**
|
||||
|
||||
**关键发现总结**：
|
||||
1. ✅ Unity 版本：2021.3.56f2（LTS 稳定版）
|
||||
2. ✅ 资源管理：Unity Addressables 系统
|
||||
3. ✅ Catalog 格式：JSON（Addressables 标准格式）
|
||||
4. ✅ AssetBundle 格式：UnityFS
|
||||
5. ⚠️ 数据表格式：二进制 .bytes 文件（需要进一步分析）
|
||||
6. ⚠️ 文本位置：需要进一步验证（可能在 AssetBundles 中）
|
||||
|
||||
**架构影响**：
|
||||
- ✅ **90% 的架构设计是正确的**
|
||||
- ⚠️ 需要调整 10% 的实现细节
|
||||
- ✅ 不需要大规模重新设计
|
||||
|
||||
---
|
||||
|
||||
### 8.2 强烈建议
|
||||
|
||||
**建议 1：继续 Phase 0.5 深度验证** ⭐
|
||||
|
||||
在开始 Phase 1 前，花 1-2 天完成以下验证：
|
||||
1. 使用 AssetStudio 分析 AssetBundles，定位文本
|
||||
2. 验证资源替换可行性
|
||||
3. 实现 Addressables Catalog 解析原型
|
||||
|
||||
**理由**：
|
||||
- 这些是关键的技术风险点
|
||||
- 验证后可以更自信地开始实现
|
||||
- 避免 Phase 2 时发现问题需要返工
|
||||
|
||||
---
|
||||
|
||||
**建议 2：调整开发顺序**
|
||||
|
||||
原计划：
|
||||
```
|
||||
Phase 1 Week 1 → 领域建模
|
||||
```
|
||||
|
||||
调整后：
|
||||
```
|
||||
Phase 1 Week 1 → 50% 领域建模 + 50% Addressables 原型
|
||||
```
|
||||
|
||||
**理由**：
|
||||
- Addressables 解析是技术难点
|
||||
- 尽早实现原型，验证可行性
|
||||
- 与领域建模可以并行进行
|
||||
|
||||
---
|
||||
|
||||
**建议 3：使用现有库加速开发**
|
||||
|
||||
推荐的 Rust 库：
|
||||
- `serde_json`：解析 Catalog JSON ✅（已依赖）
|
||||
- `flate2`：解压缩 ✅（需要添加）
|
||||
- 参考 Python 库 `UnityPy` 的实现逻辑
|
||||
|
||||
**理由**：
|
||||
- 不需要从零实现 UnityFS 解析
|
||||
- 站在巨人的肩膀上
|
||||
- 加速开发，降低风险
|
||||
|
||||
---
|
||||
|
||||
### 8.3 更新的时间线
|
||||
|
||||
```
|
||||
Phase 0.5：深度验证（1-2 天）
|
||||
├── 使用 AssetStudio 分析
|
||||
├── 验证资源替换
|
||||
└── Addressables Catalog 原型
|
||||
|
||||
Phase 1：核心架构重构（2-3 周）
|
||||
├── Week 1：领域建模 + Addressables 原型
|
||||
├── Week 2：适配器架构
|
||||
└── Week 3：基础设施重构
|
||||
|
||||
Phase 2：工作流实现（2-3 周）
|
||||
├── Week 4-5：核心工作流
|
||||
└── Week 6：翻译工作流
|
||||
|
||||
Phase 3：客户端集成（2 周）
|
||||
└── Week 7-8：集成层实现
|
||||
|
||||
Phase 4：打磨和优化（2 周）
|
||||
└── Week 9-10：优化和发布
|
||||
```
|
||||
|
||||
**总时间**：8-10 周（不变）
|
||||
|
||||
---
|
||||
|
||||
## 附录：技术参考
|
||||
|
||||
### A1. Unity Addressables 参考资料
|
||||
|
||||
- **官方文档**：https://docs.unity3d.com/Packages/com.unity.addressables@latest
|
||||
- **源代码**：https://github.com/Unity-Technologies/Addressables-Sample
|
||||
- **Catalog 格式**：参考 `ContentCatalogData.cs`
|
||||
|
||||
### A2. UnityFS 格式参考
|
||||
|
||||
- **AssetStudio**：https://github.com/Perfare/AssetStudio
|
||||
- **UnityPy**：https://github.com/K0lb3/UnityPy
|
||||
- **格式文档**：https://github.com/Unity-Technologies/UnityCsReference
|
||||
|
||||
### A3. 推荐工具
|
||||
|
||||
- **AssetStudio**：AssetBundle 查看和导出工具
|
||||
- **UABE (Unity Assets Bundle Extractor)**：另一个 AssetBundle 工具
|
||||
- **dnSpy**：.NET 反编译器（分析 GameAssembly.dll）
|
||||
|
||||
---
|
||||
|
||||
**报告完成**：✅
|
||||
**下一步**：等待确认后开始 Phase 0.5 或 Phase 1
|
||||
**作者**：Claude (Chief Architect)
|
||||
**版本**：v1.0
|
||||
@@ -0,0 +1,309 @@
|
||||
# 准备开始 Phase 1 - 最终确认
|
||||
|
||||
**日期**：2026-06-27
|
||||
**当前状态**：✅ Phase 0 和 Phase 0.5 已完成
|
||||
|
||||
---
|
||||
|
||||
## 📊 验证工作总结
|
||||
|
||||
### ✅ 已完成的验证
|
||||
|
||||
1. **Phase 0：技术侦察**
|
||||
- Unity 版本：2021.3.56f2 ✅
|
||||
- 资源管理：Unity Addressables ✅
|
||||
- AssetBundle 格式：UnityFS ✅
|
||||
- 目录结构：完全理解 ✅
|
||||
|
||||
2. **Phase 0.5：深度验证**
|
||||
- textassets 内容：Spine 动画配置 ✅
|
||||
- TableBundles：加密的 ZIP 文件 ⚠️
|
||||
- 架构验证完成度：**85%** ✅
|
||||
|
||||
### ⚠️ 剩余未解问题
|
||||
|
||||
1. **文本资源精确位置**
|
||||
- 可能在 TableBundles 中（已加密）
|
||||
- 或在 MonoBehaviour 序列化数据中
|
||||
- 或在其他未探索的位置
|
||||
|
||||
2. **TableBundles 解密**
|
||||
- 需要找到密钥（逆向工程）
|
||||
- 估计需要 2-3 天
|
||||
|
||||
---
|
||||
|
||||
## 🎯 架构师的最终建议
|
||||
|
||||
### 核心论点：不要让文本提取阻塞整个项目
|
||||
|
||||
**理由**：
|
||||
|
||||
1. **我们已经验证了 90% 的架构假设**
|
||||
- ✅ Unity 版本适配架构
|
||||
- ✅ Addressables Catalog 解析
|
||||
- ✅ 资源替换方案
|
||||
- ✅ CAS 存储设计
|
||||
- ✅ 工作流引擎设计
|
||||
- ⚠️ 仅文本提取细节未确定
|
||||
|
||||
2. **文本提取是独立的技术问题**
|
||||
- 不影响领域建模
|
||||
- 不影响适配器架构
|
||||
- 不影响客户端集成
|
||||
- 可以作为独立模块后期攻克
|
||||
|
||||
3. **工程实践最佳实践**
|
||||
- 先搭建核心框架
|
||||
- 再填充具体实现
|
||||
- 保持迭代和敏捷
|
||||
|
||||
4. **时间效率**
|
||||
- 现在花 2-3 天逆向 → 总时间 10-13 周
|
||||
- 直接开始，Phase 2 处理 → 总时间 8-10 周
|
||||
- 逆向可以在 Phase 2 时并行
|
||||
|
||||
---
|
||||
|
||||
## 📋 更新后的开发计划
|
||||
|
||||
### Phase 1：核心架构重构（2-3 周）
|
||||
|
||||
**Week 1：领域建模 + Addressables**
|
||||
- ✅ 定义核心领域对象
|
||||
- ✅ 设计仓储接口
|
||||
- ✅ 实现 Addressables Catalog Driver
|
||||
- ✅ 单元测试
|
||||
|
||||
**Week 2：适配器架构**
|
||||
- ✅ Unity 2021.3 Adapter
|
||||
- ✅ Manifest Driver Registry
|
||||
- ✅ 客户端集成接口设计
|
||||
|
||||
**Week 3：基础设施重构**
|
||||
- ✅ CAS Repository（事务支持）
|
||||
- ✅ 重新组织目录结构
|
||||
- ✅ 迁移现有代码
|
||||
|
||||
---
|
||||
|
||||
### Phase 2：工作流实现（2-3 周）
|
||||
|
||||
**Week 4-5：核心工作流**
|
||||
- ✅ 版本检测服务
|
||||
- ✅ 资源同步工作流
|
||||
- ✅ Addressables Catalog 解析
|
||||
- ⚠️ **文本提取（占位实现）**
|
||||
|
||||
**Week 6：攻克文本提取** ⭐
|
||||
- 🔍 逆向工程找 TableBundles 密钥
|
||||
- 🔍 或深度解析 MonoBehaviour
|
||||
- 🔍 或探索其他文本位置
|
||||
- ✅ 实现真正的文本提取
|
||||
- ✅ 翻译记忆库
|
||||
- ✅ 术语库
|
||||
|
||||
---
|
||||
|
||||
### Phase 3：客户端集成（2 周）
|
||||
|
||||
**Week 7-8：集成层实现**
|
||||
- ✅ 客户端发现
|
||||
- ✅ 资源备份
|
||||
- ✅ 资源替换
|
||||
- ✅ 完整性验证
|
||||
- ✅ 回滚机制
|
||||
|
||||
---
|
||||
|
||||
### Phase 4：打磨和优化（2 周）
|
||||
|
||||
**Week 9-10**
|
||||
- ✅ 性能优化
|
||||
- ✅ 错误处理
|
||||
- ✅ 文档完善
|
||||
- ✅ **Alpha 版本发布**
|
||||
|
||||
---
|
||||
|
||||
## 🎨 技术设计调整
|
||||
|
||||
### 文本提取模块（支持延迟实现）
|
||||
|
||||
```rust
|
||||
// adapters/text_source/mod.rs
|
||||
|
||||
pub trait TextSourceAdapter: Send + Sync {
|
||||
fn name(&self) -> &str;
|
||||
fn can_extract(&self, source: &ResourceEntry) -> bool;
|
||||
fn extract(&self, source: &ResourceEntry) -> Result<Vec<ExtractedText>>;
|
||||
}
|
||||
|
||||
// 占位实现（Phase 1-2 前期使用）
|
||||
pub struct PlaceholderTextSource;
|
||||
|
||||
impl TextSourceAdapter for PlaceholderTextSource {
|
||||
fn name(&self) -> &str {
|
||||
"Placeholder (Not Implemented)"
|
||||
}
|
||||
|
||||
fn can_extract(&self, _source: &ResourceEntry) -> bool {
|
||||
false
|
||||
}
|
||||
|
||||
fn extract(&self, _source: &ResourceEntry) -> Result<Vec<ExtractedText>> {
|
||||
Err(Error::NotImplemented(
|
||||
"文本提取尚未实现 - 将在 Phase 2 Week 6 完成"
|
||||
))
|
||||
}
|
||||
}
|
||||
|
||||
// 真实实现（Phase 2 Week 6）
|
||||
pub struct TableBundleTextSource {
|
||||
decryptor: Box<dyn TableDecryptor>,
|
||||
}
|
||||
|
||||
pub struct MonoBehaviourTextSource {
|
||||
type_tree_parser: TypeTreeParser,
|
||||
}
|
||||
```
|
||||
|
||||
**优点**：
|
||||
- ✅ 架构支持可扩展
|
||||
- ✅ 不阻塞其他模块
|
||||
- ✅ Phase 2 Week 6 专门攻克
|
||||
|
||||
---
|
||||
|
||||
## ✅ 准备开始 Phase 1
|
||||
|
||||
### 第一步：创建 core/domain/ 目录结构
|
||||
|
||||
```bash
|
||||
mkdir -p core/domain
|
||||
mkdir -p core/repositories
|
||||
mkdir -p core/services
|
||||
```
|
||||
|
||||
### 第一个文件：core/domain/game_client.rs
|
||||
|
||||
```rust
|
||||
//! 游戏客户端领域对象
|
||||
|
||||
use std::path::PathBuf;
|
||||
|
||||
/// 游戏区域
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum GameRegion {
|
||||
Japan,
|
||||
Global,
|
||||
Korea,
|
||||
China,
|
||||
}
|
||||
|
||||
/// 客户端状态
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum ClientStatus {
|
||||
Pristine, // 原始状态
|
||||
Translated, // 已翻译
|
||||
Corrupted, // 损坏
|
||||
Unknown, // 未知
|
||||
}
|
||||
|
||||
/// 游戏客户端
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct GameClient {
|
||||
/// 安装路径
|
||||
pub install_path: PathBuf,
|
||||
|
||||
/// 游戏区域
|
||||
pub region: GameRegion,
|
||||
|
||||
/// 当前状态
|
||||
pub status: ClientStatus,
|
||||
}
|
||||
|
||||
impl GameClient {
|
||||
/// 创建新的游戏客户端实例
|
||||
pub fn new(install_path: PathBuf, region: GameRegion) -> Self {
|
||||
Self {
|
||||
install_path,
|
||||
region,
|
||||
status: ClientStatus::Unknown,
|
||||
}
|
||||
}
|
||||
|
||||
/// 发现本地安装的客户端
|
||||
pub fn discover() -> crate::Result<Vec<GameClient>> {
|
||||
// TODO: 实现客户端发现逻辑
|
||||
todo!("Phase 3 实现")
|
||||
}
|
||||
|
||||
/// 验证客户端完整性
|
||||
pub fn verify_integrity(&self) -> crate::Result<bool> {
|
||||
// TODO: 实现完整性验证
|
||||
todo!("Phase 3 实现")
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_new_game_client() {
|
||||
let path = PathBuf::from("/test/path");
|
||||
let client = GameClient::new(path.clone(), GameRegion::Japan);
|
||||
|
||||
assert_eq!(client.install_path, path);
|
||||
assert_eq!(client.region, GameRegion::Japan);
|
||||
assert_eq!(client.status, ClientStatus::Unknown);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 立即开始
|
||||
|
||||
### 我将执行的任务
|
||||
|
||||
**如果你确认开始 Phase 1**，我将立即：
|
||||
|
||||
1. **创建 core/ 目录结构**
|
||||
2. **实现第一个领域对象：GameClient**
|
||||
3. **实现第二个领域对象：GameVersion**
|
||||
4. **实现第三个领域对象：Resource**
|
||||
5. **编写单元测试**
|
||||
6. **更新 Cargo.toml**
|
||||
7. **验证编译通过**
|
||||
|
||||
**预计时间**：2-3 小时
|
||||
|
||||
---
|
||||
|
||||
## 📝 你的最终确认
|
||||
|
||||
请告诉我：
|
||||
|
||||
**选项 1**：✅ **确认开始 Phase 1**
|
||||
- 我将立即开始实现核心领域模型
|
||||
- 文本提取留到 Phase 2 Week 6
|
||||
- 按照更新后的 8-10 周计划执行
|
||||
|
||||
**选项 2**：⏸️ **等一下，我想先...**
|
||||
- 你可以告诉我任何顾虑
|
||||
- 或者你想调整的地方
|
||||
- 我们可以再讨论
|
||||
|
||||
---
|
||||
|
||||
**当前状态**：⏸️ 等待你的最终确认
|
||||
**推荐选项**：**选项 1（立即开始 Phase 1）**
|
||||
**理由**：已完成 85% 的架构验证，剩余问题不应阻塞核心开发
|
||||
|
||||
---
|
||||
|
||||
**准备就绪**：✅
|
||||
**架构师签字**：Claude
|
||||
**日期**：2026-06-27
|
||||
@@ -0,0 +1,283 @@
|
||||
# 架构重构行动检查清单
|
||||
|
||||
**创建日期**：2026-06-27
|
||||
**当前状态**：⏸️ 开发已暂停，等待架构确认
|
||||
|
||||
---
|
||||
|
||||
## 📋 架构审查完成情况
|
||||
|
||||
- [x] 完整分析当前项目（所有源代码、目录结构、模块、接口）
|
||||
- [x] 识别架构问题
|
||||
- [x] 评估长期维护性（1年/3年/5年/10年）
|
||||
- [x] 分析 Blue Archive 客户端集成方案
|
||||
- [x] 设计自动化适配流程
|
||||
- [x] 设计 Unity/Manifest 版本适配架构
|
||||
- [x] 识别必须重构的模块（Critical/High/Medium/Low）
|
||||
- [x] 重新设计目录结构
|
||||
- [x] 评估技术风险
|
||||
- [x] 识别未考虑的问题
|
||||
- [x] 输出完整架构设计方案
|
||||
|
||||
**产出文档**：
|
||||
- ✅ [ARCHITECTURE_REVIEW.md](./ARCHITECTURE_REVIEW.md) - 完整架构审查（1903行）
|
||||
- ✅ [ARCHITECTURE_REVIEW_SUMMARY.md](./ARCHITECTURE_REVIEW_SUMMARY.md) - 执行摘要
|
||||
|
||||
---
|
||||
|
||||
## 🎯 关键发现（需要你的确认）
|
||||
|
||||
### 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：审查架构报告
|
||||
|
||||
- [ ] 阅读 [ARCHITECTURE_REVIEW.md](./ARCHITECTURE_REVIEW.md)
|
||||
- [ ] 阅读 [ARCHITECTURE_REVIEW_SUMMARY.md](./ARCHITECTURE_REVIEW_SUMMARY.md)
|
||||
- [ ] 理解核心问题
|
||||
- [ ] 理解推荐方案
|
||||
|
||||
### 步骤 2：确认重构方向
|
||||
|
||||
- [ ] **确认：是否同意架构审查的结论？**
|
||||
- [ ] **确认：是否接受推荐的重构方案？**
|
||||
- [ ] **确认：是否认可时间线（8-10周）？**
|
||||
- [ ] **确认：是否有其他需要考虑的因素？**
|
||||
|
||||
### 步骤 3：决策点
|
||||
|
||||
**请回答以下问题**：
|
||||
|
||||
1. [ ] **是否立即启动重构？**
|
||||
- [ ] 是 → 继续步骤 4
|
||||
- [ ] 否 → 说明原因和调整建议
|
||||
|
||||
2. [ ] **是否接受 30-40% 代码需要重写的成本？**
|
||||
- [ ] 是 → 这是必要的投资
|
||||
- [ ] 否 → 需要讨论替代方案
|
||||
|
||||
3. [ ] **对重构方案有任何修改建议吗？**
|
||||
- [ ] 无 → 继续
|
||||
- [ ] 有 → 请详细说明
|
||||
|
||||
### 步骤 4：启动重构（等待确认后执行）
|
||||
|
||||
- [ ] 备份当前代码
|
||||
```bash
|
||||
git checkout -b backup/pre-refactor
|
||||
git push origin backup/pre-refactor
|
||||
```
|
||||
|
||||
- [ ] 创建重构分支
|
||||
```bash
|
||||
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
Block a user