diff --git a/.gitea/workflows/bat.yml b/.gitea/workflows/bat.yml index 1f6d0a9..29bab96 100644 --- a/.gitea/workflows/bat.yml +++ b/.gitea/workflows/bat.yml @@ -238,3 +238,10 @@ jobs: source /var/lib/act_runner/env.sh go build -o /tmp/bat-api ./cmd/bat-api + + - name: Run documentation status gate + shell: bash + run: | + set -euo pipefail + + make check-docs diff --git a/CURRENT_STATUS.md b/CURRENT_STATUS.md index 8d77b19..f289a80 100644 --- a/CURRENT_STATUS.md +++ b/CURRENT_STATUS.md @@ -218,7 +218,7 @@ Rust 侧官方日服资源链路已经从实验验证推进到正式入口： | 空目录 `api/` `pkg/` 等 | 占位 | 无实现 | | Web | `web/` | 空（G-010） | -默认 Go 门禁：`make test-go-api`、`make build-go-api`（无 FFI）。 +默认 Go/docs 门禁：`make test-go-api`、`make build-go-api`、`make check-docs`（无 FFI）。 --- @@ -243,6 +243,7 @@ cargo test --offline -p bat-infrastructure localized_patch --quiet env GOCACHE=/tmp/bat-go-cache GOMODCACHE=/tmp/bat-go-modcache make test-go-api env GOCACHE=/tmp/bat-go-cache GOMODCACHE=/tmp/bat-go-modcache make build-go-api env GOCACHE=/tmp/bat-go-cache GOMODCACHE=/tmp/bat-go-modcache go vet ./internal/api/... ./internal/backendrpc/... ./cmd/bat-api/... +make check-docs ``` 未执行 / 后置： diff --git a/Makefile b/Makefile index 3781e4c..cb120f4 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: help build build-ffi test clean check fmt lint install dev docker-build docker-up docker-down official-smoke build-go build-go-api build-go-cli test-go test-go-api test-go-ffi test-go-all +.PHONY: help build build-ffi test clean check check-docs fmt lint install dev docker-build docker-up docker-down official-smoke build-go build-go-api build-go-cli test-go test-go-api test-go-ffi test-go-all # 默认目标 .DEFAULT_GOAL := help @@ -86,7 +86,7 @@ official-smoke: ## 运行真实官方全量拉取 smoke（默认写入 /tmp 隔 # 代码质量 # ============================================================================ -check: check-rust check-go ## 检查代码（不编译） +check: check-rust check-go check-docs ## 检查代码和状态文档（不编译） check-rust: ## 检查 Rust 代码 @echo "$(BLUE)Checking Rust code...$(NC)" @@ -100,6 +100,10 @@ check-go: ## 检查 Go 代码 echo "$(YELLOW)No Go packages yet, skipping...$(NC)"; \ fi +check-docs: ## 检查权威状态文档与占位目录声明 + @echo "$(BLUE)Checking documentation status claims...$(NC)" + bash scripts/check-doc-status.sh + fmt: fmt-rust fmt-go ## 格式化所有代码 fmt-rust: ## 格式化 Rust 代码 diff --git a/PROJECT_PLAN.md b/PROJECT_PLAN.md index 9b8fdab..e490894 100644 --- a/PROJECT_PLAN.md +++ b/PROJECT_PLAN.md @@ -202,6 +202,8 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付 ### Milestone 4：Unity AssetBundle 解析 +维护冻结细则见 [`docs/reports/PARSER_FREEZE.md`](docs/reports/PARSER_FREEZE.md)；冻结期只接受稳定性、诊断、真实回归和文档一致性修复。 + **目标**：建立可扩展 AssetBundle 解析框架，并首先支持文本相关资源。 交付物： diff --git a/docs/architecture/assetbundle.md b/docs/architecture/assetbundle.md index 6479d83..716f906 100644 --- a/docs/architecture/assetbundle.md +++ b/docs/architecture/assetbundle.md @@ -3,6 +3,7 @@ - **更新时间**：2026-07-26 - **适用范围**：Rust 解析引擎、官方同步后的解析缓存、CAS/ResourceRepository 接入、后续文本提取和 Patch 发布。 - **权威关联**：`PROJECT_PLAN.md` Milestone 3/4/5/8，`docs/reports/CURRENT_GAPS.md` G-005/G-007/G-011/G-011D。 +- **维护冻结**：解析扩展遵循 [`docs/reports/PARSER_FREEZE.md`](../reports/PARSER_FREEZE.md)，冻结期只接受稳定性、诊断、真实回归和文档一致性修复。 --- diff --git a/docs/guides/development.md b/docs/guides/development.md index 4c22ed3..e5e7eea 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -33,9 +33,10 @@ rustc --version cargo --version rustfmt --version cargo clippy --version +go version ``` -该 workflow 会用 `GITHUB_SERVER_URL`、`GITHUB_REPOSITORY`、`GITHUB_REF` 和 `GITHUB_SHA` 手动 `git fetch` 当前提交，再执行 Rust workspace 的格式化、检查、构建、clippy 和测试。这样可以避免自托管 runner 在准备阶段通过代理克隆第三方 action 仓库。 +该 workflow 会用 `GITHUB_SERVER_URL`、`GITHUB_REPOSITORY`、`GITHUB_REF` 和 `GITHUB_SHA` 手动 `git fetch` 当前提交，再执行 Rust workspace 的格式化、检查、构建、clippy 和测试，以及 Go API 门禁和文档状态门禁。这样可以避免自托管 runner 在准备阶段通过代理克隆第三方 action 仓库。 #### Docker ```bash @@ -148,6 +149,7 @@ cargo clippy --workspace --all-targets -- -D warnings make test-go-api make build-go-api go vet ./internal/api/... ./internal/backendrpc/... ./cmd/bat-api/... +make check-docs ``` Go 边界与进度以 `docs/reports/GO_STATUS.md` 为准： diff --git a/docs/reports/CURRENT_GAPS.md b/docs/reports/CURRENT_GAPS.md index 1633f24..bb7e0ea 100644 --- a/docs/reports/CURRENT_GAPS.md +++ b/docs/reports/CURRENT_GAPS.md @@ -482,9 +482,9 @@ 处理结果： - 明确决策：本项目不加入 GitHub Workflows，也不引入其他托管 CI。 -- 目前补充了自托管 Gitea linux-runner workflow（`.gitea/workflows/bat.yml`），仅用于 Rust workspace 的构建和测试，不改变“不引入托管 CI”的决策。 -- workflow 不使用外部 GitHub Action；它通过 runner 环境变量手动 `git fetch` 当前提交，并要求 runner 预装 `git`、Rust stable、rustfmt 和 clippy，避免准备阶段因第三方 action 仓库代理或网络限制失败。 -- 质量门禁由本地默认验证命令和自托管 workflow 共同承担：提交前执行 `cargo fmt` / `cargo clippy --workspace --all-targets -- -D warnings` / `cargo test --workspace`（见 `docs/guides/development.md` 与 `docs/guides/baseline.md`）。 +- 目前补充了自托管 Gitea linux-runner workflow（`.gitea/workflows/bat.yml`），覆盖 Rust workspace 构建/测试、Go API 门禁和文档状态门禁，不改变“不引入托管 CI”的决策。 +- workflow 不使用外部 GitHub Action；它通过 runner 环境变量手动 `git fetch` 当前提交，并要求 runner 预装 `git`、Rust stable、rustfmt、clippy 和 Go，避免准备阶段因第三方 action 仓库代理或网络限制失败。 +- 质量门禁由本地默认验证命令和自托管 workflow 共同承担：提交前执行 `cargo fmt` / `cargo clippy --workspace --all-targets -- -D warnings` / `cargo test --workspace`、Go API 门禁和 `make check-docs`（见 `docs/guides/development.md` 与 `docs/guides/baseline.md`）。 - 发布类检查（build、smoke）由 `Makefile` 与 `scripts/` 下的可重复脚本承担（如 `make official-smoke`）。 限制： diff --git a/docs/reports/GO_STATUS.md b/docs/reports/GO_STATUS.md index d37562d..152cdda 100644 --- a/docs/reports/GO_STATUS.md +++ b/docs/reports/GO_STATUS.md @@ -86,7 +86,7 @@ | O | 权威文档与 `go list` 一致，禁止「API 完全没有」等过时句 | | P | 试验 CLI 产物 **`bin/bat-go`**，禁止 `bin/bat` | | Q | 空目录标明 reserved empty | -| R | 默认门禁：`make test-go-api` + `make build-go-api`（无 FFI） | +| R | 默认门禁：`make test-go-api` + `make build-go-api` + `make check-docs`（无 FFI） | --- @@ -119,6 +119,7 @@ make test-go-api make build-go-api go vet ./internal/api/... ./internal/backendrpc/... ./cmd/bat-api/... +make check-docs # 可选：改 FFI 或试验 CLI 时 make build-ffi diff --git a/scripts/check-doc-status.sh b/scripts/check-doc-status.sh new file mode 100644 index 0000000..8ed8180 --- /dev/null +++ b/scripts/check-doc-status.sh @@ -0,0 +1,99 @@ +#!/usr/bin/env bash +set -euo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +cd "${repo_root}" + +fail() { + printf 'doc status check failed: %s\n' "$*" >&2 + exit 1 +} + +require_file() { + local file="$1" + [[ -f "${file}" ]] || fail "missing file: ${file}" +} + +require_contains() { + local file="$1" + local needle="$2" + grep -Fq -- "${needle}" "${file}" || fail "${file} missing required text: ${needle}" +} + +require_regex() { + local file="$1" + local pattern="$2" + grep -Eiq -- "${pattern}" "${file}" || fail "${file} missing required pattern: ${pattern}" +} + +required_docs=( + "CURRENT_STATUS.md" + "USERGUIDE.md" + "PROJECT_PLAN.md" + "docs/architecture/assetbundle.md" + "docs/guides/development.md" + "docs/reference/rpc-backend-api.md" + "docs/reports/CURRENT_GAPS.md" + "docs/reports/GO_STATUS.md" + "docs/reports/PARSER_FREEZE.md" + "internal/api/testdata/contract/README.md" +) + +for file in "${required_docs[@]}"; do + require_file "${file}" +done + +placeholder_readmes=( + "api/README.md" + "api/proto/README.md" + "internal/config/README.md" + "internal/downloader/README.md" + "internal/extractor/README.md" + "internal/manifest/README.md" + "internal/storage/README.md" + "pkg/README.md" + "pkg/cas/README.md" + "pkg/translator/README.md" + "pkg/types/README.md" + "web/README.md" + "web/admin/README.md" + "web/shared/README.md" +) + +for file in "${placeholder_readmes[@]}"; do + require_file "${file}" + require_regex "${file}" "not implemented" + require_contains "${file}" "docs/reports/GO_STATUS.md" +done + +parser_freeze_docs=( + "CURRENT_STATUS.md" + "PROJECT_PLAN.md" + "docs/architecture/assetbundle.md" + "docs/guides/development.md" + "docs/reports/CURRENT_GAPS.md" +) + +for file in "${parser_freeze_docs[@]}"; do + require_contains "${file}" "docs/reports/PARSER_FREEZE.md" +done + +require_contains "USERGUIDE.md" "scope=resource_bootstrap_only" +require_contains "USERGUIDE.md" "package_update_manifest=false" +require_contains "docs/reports/GO_STATUS.md" "resource bootstrap + CDN path" +require_contains "docs/reports/GO_STATUS.md" "internal/api/testdata/contract/" +require_contains "CURRENT_STATUS.md" "cmd/bat-api" +require_contains "CURRENT_STATUS.md" "internal/api/testdata/contract/" +require_contains "docs/reports/CURRENT_GAPS.md" "非完整官方游戏 API" +require_contains "docs/reports/CURRENT_GAPS.md" "daemon.clean-stable" +require_contains "docs/reference/rpc-backend-api.md" "daemon.restart" +require_contains "docs/reference/rpc-backend-api.md" "daemon.clean-stable" +require_contains "docs/reference/rpc-backend-api.md" "localized_release_status" + +require_contains "Makefile" "check-docs:" +require_contains ".gitea/workflows/bat.yml" "make check-docs" +require_contains ".gitea/workflows/bat.yml" "make test-go-api" +require_contains ".gitea/workflows/bat.yml" "go vet ./internal/api/... ./internal/backendrpc/... ./cmd/bat-api/..." +require_contains ".gitea/workflows/bat.yml" "go build -o /tmp/bat-api ./cmd/bat-api" + +printf 'doc status check ok\n' diff --git a/web/admin/README.md b/web/admin/README.md index e048ab3..2b63180 100644 --- a/web/admin/README.md +++ b/web/admin/README.md @@ -7,4 +7,5 @@ and OpenAPI. The production panel must reuse the same HTTP authentication, rate limiting, access logging, reverse-proxy handling, and no-store dynamic response policy as -the resource API. Static frontend assets are not implemented yet. +the resource API. Static frontend assets are not implemented yet. See +`docs/reports/GO_STATUS.md` for the current component boundary and status.