chore(docs): 增加状态一致性门禁

2026-09-18 05:34:55 +08:00 · 2026-08-01 10:55:43 +08:00
parent 80e6718e8a
commit 8d930bf4d7
10 changed files with 127 additions and 9 deletions
@@ -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
@@ -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
 ```

 未执行 / 后置：
@@ -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 代码
@@ -202,6 +202,8 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付

 ### Milestone 4：Unity AssetBundle 解析

+维护冻结细则见 [`docs/reports/PARSER_FREEZE.md`](docs/reports/PARSER_FREEZE.md)；冻结期只接受稳定性、诊断、真实回归和文档一致性修复。
+
 **目标**：建立可扩展 AssetBundle 解析框架，并首先支持文本相关资源。

 交付物：
@@ -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)，冻结期只接受稳定性、诊断、真实回归和文档一致性修复。

 ---

@@ -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` 为准：
@@ -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`）。

 限制：
@@ -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
@@ -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'
@@ -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.