mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-07-22 04:06:44 +08:00
docs: align project status with official sync pipeline
Update the authoritative docs, guides, architecture notes, gap list, deployment guidance, handoff notes, and changelog to reflect the current Rust official resource sync boundary.
This commit is contained in:
+14
-9
@@ -1,7 +1,7 @@
|
||||
# 稳定工程基线指南
|
||||
|
||||
**更新时间**：2026-06-28
|
||||
**目标**：让工作区处于可继续开发核心功能的可信状态。
|
||||
- **更新时间**：2026-07-06
|
||||
- **目标**：让工作区处于可继续开发核心功能的可信状态。
|
||||
|
||||
---
|
||||
|
||||
@@ -17,6 +17,7 @@
|
||||
6. 当前缺口有集中清单和关闭顺序。
|
||||
7. 架构边界有 ADR 记录。
|
||||
8. 基础验证命令通过。
|
||||
9. Rust 官方资源同步入口有明确运行文档和生产边界。
|
||||
|
||||
---
|
||||
|
||||
@@ -40,9 +41,10 @@ cargo clippy --workspace -- -D warnings
|
||||
|
||||
说明：
|
||||
|
||||
1. 当前没有 Go package，因此 Go build/test/check/fmt/lint 会明确跳过。
|
||||
1. 当前没有 Go 产品入口，因此 Go build/test/check/fmt/lint 会在空 Go 阶段明确跳过。
|
||||
2. 如果后续新增 Go package，必须让 `go test ./...` 和 `go vet ./...` 纳入硬性验证。
|
||||
3. 当前 `golangci-lint` 可选；当 Go 代码进入主要开发阶段后，应纳入 CI。
|
||||
4. 官方同步相关修改必须额外运行 `cargo test -p bat-infrastructure --bin bat-official-sync -- --nocapture`。
|
||||
|
||||
---
|
||||
|
||||
@@ -84,16 +86,19 @@ git check-ignore -v Cargo.lock CLAUDE.md
|
||||
|
||||
## 5. 下一阶段入口
|
||||
|
||||
CAS V1 完成后，下一阶段优先推进：
|
||||
CAS V1 和 Rust 官方同步闭环完成后，下一阶段优先推进：
|
||||
|
||||
1. Manifest 真实解析。
|
||||
2. Go CLI 的 `doctor` 和基础命令框架。
|
||||
3. Resource Repository 持久化 schema。
|
||||
1. Go CLI 的 `doctor` 和基础命令框架。
|
||||
2. 真实官方网络全量下载 smoke 记录。
|
||||
3. 官方同步结果接入 CAS + ResourceRepository。
|
||||
4. AssetBundle UnityFS 解析。
|
||||
|
||||
优先阅读：
|
||||
|
||||
1. `PROJECT_PLAN.md`
|
||||
2. `CURRENT_STATUS.md`
|
||||
3. `docs/reports/CURRENT_GAPS.md`
|
||||
4. `docs/architecture/adr/0001-engine-and-application-boundaries.md`
|
||||
5. `docs/architecture/adr/0002-cas-v1-design-boundary.md`
|
||||
4. `docs/guides/official-resource-test-pull.md`
|
||||
5. `docs/architecture/official-resource-backend.md`
|
||||
6. `docs/architecture/adr/0001-engine-and-application-boundaries.md`
|
||||
7. `docs/architecture/adr/0002-cas-v1-design-boundary.md`
|
||||
|
||||
@@ -2,11 +2,11 @@
|
||||
|
||||
## 架构概览
|
||||
|
||||
BlueArchive Toolkit 支持多种部署模式：
|
||||
BlueArchive Toolkit 的部署文档分为当前可用模式和目标模式：
|
||||
|
||||
1. **本地开发模式**：代码在本地，连接远程数据库
|
||||
2. **单机部署**：所有组件运行在一台服务器
|
||||
3. **分布式部署**：多实例 API Server + 独立数据库服务器
|
||||
1. **本地开发模式**：代码在本地，连接本地或远程数据库。
|
||||
2. **官方资源同步生产任务**：当前可用，运行 Rust `bat-official-sync --watch`。
|
||||
3. **完整单机/分布式部署**：目标模式，等待 API Server、数据库迁移和 Web 实现后补齐。
|
||||
|
||||
---
|
||||
|
||||
@@ -98,9 +98,98 @@ REDIS_PORT=6379
|
||||
|
||||
---
|
||||
|
||||
## 模式 3：生产环境部署
|
||||
## 模式 3：官方资源同步生产任务
|
||||
|
||||
待补充（Phase 6 实现 API Server 后）
|
||||
当前可部署的生产任务是 Rust 官方资源同步 binary。API Server 和 Web 尚未实现，不能按完整服务端产品部署。
|
||||
|
||||
### 构建
|
||||
|
||||
```bash
|
||||
cargo build --release -p bat-infrastructure --bin bat-official-sync
|
||||
```
|
||||
|
||||
产物：
|
||||
|
||||
```text
|
||||
target/release/bat-official-sync
|
||||
```
|
||||
|
||||
### 目录约定
|
||||
|
||||
推荐生产状态目录：
|
||||
|
||||
```text
|
||||
/var/lib/bluearchive-toolkit/official/
|
||||
```
|
||||
|
||||
该目录会保存：
|
||||
|
||||
- `official-sync-snapshot.json`
|
||||
- `official-bootstrap-cache.json`
|
||||
- `official-download-manifest.json`
|
||||
- `.official-sync.lock`
|
||||
- 下载得到的官方资源文件
|
||||
|
||||
不要把输出目录设为：
|
||||
|
||||
- 已安装游戏客户端目录
|
||||
- 官方启动器安装目录
|
||||
- 开发机现有资源目录，例如 `/home/wanye/D/BlueArchive`
|
||||
- Git 工作区目录
|
||||
|
||||
### 一次性检查
|
||||
|
||||
```bash
|
||||
/opt/bluearchive-toolkit/bin/bat-official-sync \
|
||||
--auto-discover \
|
||||
--platforms Windows,Android \
|
||||
--output /var/lib/bluearchive-toolkit/official \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
### 常驻自动更新
|
||||
|
||||
```bash
|
||||
/opt/bluearchive-toolkit/bin/bat-official-sync \
|
||||
--auto-discover \
|
||||
--platforms Windows,Android \
|
||||
--output /var/lib/bluearchive-toolkit/official \
|
||||
--watch
|
||||
```
|
||||
|
||||
`--watch` 是 Rust 内部持久检查模式，默认每 1 小时执行一次检查。远端和本地一致时默认静默；有远端变化或本地文件损坏时自动下载或 repair，并输出 JSON report。
|
||||
|
||||
### systemd service 示例
|
||||
|
||||
systemd 只负责进程守护，不负责定时逻辑：
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=BlueArchiveToolkit official resource sync
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=bat
|
||||
Group=bat
|
||||
ExecStart=/opt/bluearchive-toolkit/bin/bat-official-sync --auto-discover --platforms Windows,Android --output /var/lib/bluearchive-toolkit/official --watch
|
||||
Restart=on-failure
|
||||
RestartSec=30
|
||||
StateDirectory=bluearchive-toolkit
|
||||
NoNewPrivileges=true
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
如果业务层需要热更新、热重载或发布新资源，应该由上层服务在观察到 JSON report 或 snapshot 变化后决定。Rust 同步进程只负责拉取、校验和维护本地状态。
|
||||
|
||||
---
|
||||
|
||||
## 模式 4：完整生产环境部署
|
||||
|
||||
待补充（API Server、数据库迁移和 Web 实现后）
|
||||
|
||||
---
|
||||
|
||||
@@ -172,4 +261,4 @@ docker exec bat-redis redis-cli ping
|
||||
|
||||
---
|
||||
|
||||
更多问题请查看 [故障排查指南](./troubleshooting.md)（待创建）
|
||||
更多当前状态请查看 `CURRENT_STATUS.md`、`docs/reports/CURRENT_GAPS.md` 和本文件中的健康检查命令。
|
||||
|
||||
+32
-16
@@ -104,26 +104,45 @@ git push origin feature/your-feature-name
|
||||
|
||||
## 测试
|
||||
|
||||
### 单元测试
|
||||
### 当前必跑测试
|
||||
|
||||
```bash
|
||||
# Go
|
||||
go test ./...
|
||||
|
||||
# Rust
|
||||
cargo test
|
||||
cargo test -p bat-adapters -- --nocapture
|
||||
cargo test -p bat-ffi -- --nocapture
|
||||
cargo test -p bat-infrastructure -- --nocapture
|
||||
cargo test -p bat-infrastructure --bin bat-official-sync -- --nocapture
|
||||
```
|
||||
|
||||
Go CLI 尚未实现时，`go test ./...` 可能没有产品级 package 可运行；Makefile 会在空 Go 阶段清晰跳过。
|
||||
|
||||
### 集成测试
|
||||
|
||||
```bash
|
||||
# 需要先启动数据库
|
||||
make dev
|
||||
|
||||
# 运行集成测试
|
||||
go test -tags=integration ./...
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
带真实本地资源的测试默认不应启用。只有在明确需要时，才通过对应 `BAT_REAL_*` 环境变量读取隔离样本路径。不要默认读取 `/home/wanye/D/BlueArchive` 或任何已有客户端目录。
|
||||
|
||||
### 官方资源同步手动检查
|
||||
|
||||
查看参数：
|
||||
|
||||
```bash
|
||||
cargo run -p bat-infrastructure --bin bat-official-sync -- --help
|
||||
```
|
||||
|
||||
dry-run：
|
||||
|
||||
```bash
|
||||
cargo run -p bat-infrastructure --bin bat-official-sync -- \
|
||||
--auto-discover \
|
||||
--platforms Windows,Android \
|
||||
--output /tmp/ba-official-dev \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
开发环境真实下载必须使用 `/tmp` 或其他隔离目录，不要写入现有资源目录。
|
||||
|
||||
### 基准测试
|
||||
|
||||
```bash
|
||||
@@ -161,10 +180,7 @@ cargo fetch
|
||||
|
||||
### 2. 测试失败
|
||||
|
||||
确保数据库已启动：
|
||||
```bash
|
||||
make dev
|
||||
```
|
||||
先确认失败是否来自真实网络或本地资源路径。默认测试应使用 fixture/mock，不应依赖官方线上资源或开发机已有资源目录。
|
||||
|
||||
### 3. FFI 绑定问题
|
||||
|
||||
@@ -176,4 +192,4 @@ cargo build
|
||||
|
||||
---
|
||||
|
||||
更多问题请查看 [FAQ](./faq.md)（待创建）或提交 Issue。
|
||||
更多当前状态请查看 [当前状态](../../CURRENT_STATUS.md) 和 [当前缺口清单](../reports/CURRENT_GAPS.md)。
|
||||
|
||||
@@ -15,6 +15,42 @@
|
||||
- 任何本地客户端目录
|
||||
- 任何已安装的官方启动器或 Windows 客户端
|
||||
|
||||
## 0. 快速入口
|
||||
|
||||
查看命令参数：
|
||||
|
||||
```bash
|
||||
cargo run -p bat-infrastructure --bin bat-official-sync -- --help
|
||||
```
|
||||
|
||||
构建生产 binary：
|
||||
|
||||
```bash
|
||||
cargo build --release -p bat-infrastructure --bin bat-official-sync
|
||||
```
|
||||
|
||||
使用 release binary 做一次 dry-run：
|
||||
|
||||
```bash
|
||||
target/release/bat-official-sync \
|
||||
--auto-discover \
|
||||
--platforms Windows,Android \
|
||||
--output /var/lib/bluearchive-toolkit/official \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
常驻自动更新：
|
||||
|
||||
```bash
|
||||
target/release/bat-official-sync \
|
||||
--auto-discover \
|
||||
--platforms Windows,Android \
|
||||
--output /var/lib/bluearchive-toolkit/official \
|
||||
--watch
|
||||
```
|
||||
|
||||
生产输出目录必须是独立状态目录。不要使用已有游戏客户端目录、官方启动器安装目录、人工维护资源目录，或开发机上的 `/home/wanye/D/BlueArchive`。
|
||||
|
||||
## 1. 当前流程
|
||||
|
||||
Linux 生产运行时链路只走官方日服 HTTP 资源，不安装、不启动、不依赖官方启动器二进制：
|
||||
|
||||
Reference in New Issue
Block a user