稳定工程基线指南

更新时间：2026-09-04
目标：让工作区处于可继续开发核心功能的可信状态。

1. 基线定义

当前阶段的稳定基线不是完整产品完成，而是满足以下条件：

Git 仓库可用，git status --short --branch 能正常执行。
根目录只保留入口文档和工程配置。
旧报告归档，且不再和当前状态混淆。
Rust workspace 成员显式列出。
Go 正式入口为 bat-api 资源 bootstrap/分发服务；Makefile 不把实验性 CLI 骨架误报为完整产品。
当前缺口有集中清单和关闭顺序。
架构边界有 ADR 记录。
基础验证命令通过。
Rust 官方资源同步入口有明确运行文档和生产边界。

2. 当前验证命令

提交前的只读统一门禁必须通过：

make ci-check

该命令等价覆盖：

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

说明：

默认 Go 测试只覆盖正式 bat-api 依赖的纯 Go 包：internal/api 和 internal/backendrpc；make test-go-ffi / make test-go-all 才会包含 FFI 和试验 CLI。
golangci-lint 当前仍是 optional gate；命令可用时执行并失败即阻断，不可用时明确输出 skipped 及原因。
make format / make fmt 会修改工作树；make ci-check、make check、make test 和 make lint 不应格式化源码。
官方同步相关修改必须额外运行 cargo test -p bat-infrastructure --bin bat -- --nocapture。

如果构建环境的默认 Go cache 不可写，可将 GOCACHE 指向工作区外的临时目录，例如 GOCACHE=/tmp/bat-go-cache。

3. Git 基线

当前工作区以现有 Git 分支和提交为基线；原项目历史未恢复。提交前应确认工作区只包含本次有意修改，并核对文档、源码和测试状态。

提交前检查：

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. 不纳入基线的内容

以下内容应继续忽略：

target/
.env
*.db
*.sqlite
logs/
node_modules/
构建压缩包
本地 CAS 数据目录

5. 当前开发入口

当前开发优先推进：

继续 AssetBundle 复杂对象解析、真实 fixture 和发布级重打包。
基于 translation.worker.run 继续扩展 TM/Glossary，并补充复杂 AssetBundle 的真实 fixture 与发布验证。
扩展 ResourceRepository 查询面：更丰富的 TextUnit/TM 查询和 generic manifest 发布所需资源视图。
按 docs/guides/official-full-pull-smoke.md 在隔离目录执行真实官方网络全量下载 smoke，并保留运行报告。
在资源和翻译契约稳定后推进完整 Web 协作后台和完整游戏业务 API。

优先阅读：

PROJECT_PLAN.md
CURRENT_STATUS.md
docs/reports/CURRENT_GAPS.md
docs/guides/official-resource-test-pull.md
docs/guides/official-full-pull-smoke.md
docs/architecture/official-resource-backend.md
docs/architecture/adr/0001-engine-and-application-boundaries.md
docs/architecture/adr/0002-cas-v1-design-boundary.md

3.5 KiB Raw Blame History Unescape Escape