mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-09-18 07:24:55 +08:00
108 lines
3.5 KiB
Markdown
108 lines
3.5 KiB
Markdown
# 稳定工程基线指南
|
||
|
||
- **更新时间**：2026-09-04
|
||
- **目标**：让工作区处于可继续开发核心功能的可信状态。
|
||
|
||
---
|
||
|
||
## 1. 基线定义
|
||
|
||
当前阶段的稳定基线不是完整产品完成，而是满足以下条件：
|
||
|
||
1. Git 仓库可用，`git status --short --branch` 能正常执行。
|
||
2. 根目录只保留入口文档和工程配置。
|
||
3. 旧报告归档，且不再和当前状态混淆。
|
||
4. Rust workspace 成员显式列出。
|
||
5. Go 正式入口为 `bat-api` 资源 bootstrap/分发服务；Makefile 不把实验性 CLI 骨架误报为完整产品。
|
||
6. 当前缺口有集中清单和关闭顺序。
|
||
7. 架构边界有 ADR 记录。
|
||
8. 基础验证命令通过。
|
||
9. Rust 官方资源同步入口有明确运行文档和生产边界。
|
||
|
||
---
|
||
|
||
## 2. 当前验证命令
|
||
|
||
提交前的只读统一门禁必须通过：
|
||
|
||
```bash
|
||
make ci-check
|
||
```
|
||
|
||
该命令等价覆盖：
|
||
|
||
```bash
|
||
cargo fmt --all -- --check
|
||
cargo check --workspace --locked
|
||
cargo clippy --workspace --all-targets --locked -- -D warnings
|
||
cargo test --workspace --locked
|
||
go test ./internal/api/... ./internal/backendrpc/... ./cmd/bat-api/...
|
||
go vet ./internal/api/... ./internal/backendrpc/... ./cmd/bat-api/...
|
||
go build -o /tmp/bat-api ./cmd/bat-api
|
||
make check-docs
|
||
```
|
||
|
||
说明：
|
||
|
||
1. 默认 Go 测试只覆盖正式 `bat-api` 依赖的纯 Go 包：`internal/api` 和 `internal/backendrpc`；`make test-go-ffi` / `make test-go-all` 才会包含 FFI 和试验 CLI。
|
||
2. `golangci-lint` 当前仍是 optional gate；命令可用时执行并失败即阻断，不可用时明确输出 skipped 及原因。
|
||
3. `make format` / `make fmt` 会修改工作树；`make ci-check`、`make check`、`make test` 和 `make lint` 不应格式化源码。
|
||
4. 官方同步相关修改必须额外运行 `cargo test -p bat-infrastructure --bin bat -- --nocapture`。
|
||
|
||
如果构建环境的默认 Go cache 不可写，可将 `GOCACHE` 指向工作区外的临时目录，例如
|
||
`GOCACHE=/tmp/bat-go-cache`。
|
||
|
||
---
|
||
|
||
## 3. Git 基线
|
||
|
||
当前工作区以现有 Git 分支和提交为基线；原项目历史未恢复。提交前应确认工作区
|
||
只包含本次有意修改，并核对文档、源码和测试状态。
|
||
|
||
提交前检查：
|
||
|
||
```bash
|
||
git status --short --branch
|
||
git check-ignore -v Cargo.lock CLAUDE.md AGENTS.md CONTRIBUTING.md
|
||
```
|
||
|
||
`Cargo.lock`、`CLAUDE.md`、`AGENTS.md` 和 `CONTRIBUTING.md` 必须纳入版本控制。
|
||
|
||
---
|
||
|
||
## 4. 不纳入基线的内容
|
||
|
||
以下内容应继续忽略：
|
||
|
||
1. `target/`
|
||
2. `.env`
|
||
3. `*.db`
|
||
4. `*.sqlite`
|
||
5. `logs/`
|
||
6. `node_modules/`
|
||
7. 构建压缩包
|
||
8. 本地 CAS 数据目录
|
||
|
||
---
|
||
|
||
## 5. 当前开发入口
|
||
|
||
当前开发优先推进：
|
||
|
||
1. 继续 AssetBundle 复杂对象解析、真实 fixture 和发布级重打包。
|
||
2. 基于 `translation.worker.run` 继续扩展 TM/Glossary，并补充复杂 AssetBundle 的真实 fixture 与发布验证。
|
||
3. 扩展 ResourceRepository 查询面：更丰富的 TextUnit/TM 查询和 generic manifest 发布所需资源视图。
|
||
4. 按 `docs/guides/official-full-pull-smoke.md` 在隔离目录执行真实官方网络全量下载 smoke，并保留运行报告。
|
||
5. 在资源和翻译契约稳定后推进完整 Web 协作后台和完整游戏业务 API。
|
||
|
||
优先阅读：
|
||
|
||
1. `PROJECT_PLAN.md`
|
||
2. `CURRENT_STATUS.md`
|
||
3. `docs/reports/CURRENT_GAPS.md`
|
||
4. `docs/guides/official-resource-test-pull.md`
|
||
5. `docs/guides/official-full-pull-smoke.md`
|
||
6. `docs/architecture/official-resource-backend.md`
|
||
7. `docs/architecture/adr/0001-engine-and-application-boundaries.md`
|
||
8. `docs/architecture/adr/0002-cas-v1-design-boundary.md`
|