docs: 校正文档分类与当前边界

DOCS_INDEX.md

@@ -1,129 +1,135 @@
-# BlueArchiveToolkit 文档索引
+# BlueArchive Toolkit 文档分类索引
 
-- **更新时间**：2026-09-02
-- **说明**：本索引用于快速定位当前权威文档和历史资料。
+- **更新时间**：2026-09-04
+- **用途**：按用途、时效性和权威级别定位文档。
+- **原则**：目录是物理归档方式，不能单独代表文档权威性；当前源码、测试和下列当前文档优先于历史报告。
 
----
+## 1. 项目入口与协作规则
 
-## 1. 权威入口
+这些文件位于仓库根目录，是项目级入口或协作规则：
+
+- `README.md`：项目概览、当前能力和快速开始。
+- `USERGUIDE.md`：`bat` 用户指南、命令、配置、错误码和常用 RPC 说明。
+- `CURRENT_STATUS.md`：当前实现状态，使用源码和测试复核后维护。
+- `PROJECT_PLAN.md`：长期目标、里程碑和后续路线图。
+- `CONTRIBUTING.md`：贡献流程、提交规范和验证要求。
+- `CHANGELOG.md`：版本变更记录，不作为当前实现的唯一依据。
+- `CLAUDE.md`：旧工具兼容入口，不承载独立规则。
+- `AGENTS.md`：AI agent 长期协作规则。
+
+## 2. 当前状态、计划与缺口
+
+这些文件描述当前项目，不应写入未经源码或测试证明的完成状态：
+
+- `CURRENT_STATUS.md`：全项目当前状态总览。
+- `docs/reports/GO_STATUS.md`：Go `bat-api` 边界和组件进度的权威文档。
+- `docs/reports/CURRENT_GAPS.md`：当前缺口、影响和推进顺序。
+- `PROJECT_PLAN.md`：目标和路线图；其中的计划项不等于已实现。
+- `docs/reports/BAT_API_CONTRACT_FIXTURE_HANDOFF.md`：Rust 输出、Go contract fixture 和联调的当前交接说明。
+
+## 3. 架构、决策与稳定契约
+
+### 3.1 架构总览和专题
+
+- `docs/architecture/README.md`：总体架构和目标边界；当前实现以 `CURRENT_STATUS.md` 为准。
+- `docs/architecture/official-resource-backend.md`：官方资源发现、清单、下载、发布和导入边界。
+- `docs/architecture/resource-release-layout.md`：release 目录、URL 映射、seed 和 `bat-api` 分发契约。
+- `docs/architecture/assetbundle.md`：Addressables、UnityFS、Serialized File、TextUnit、CAS 和 Patch 的解析路线图。
+
+### 3.2 架构决策记录
+
+- `docs/architecture/adr/0001-engine-and-application-boundaries.md`：Rust 引擎与 Go 应用层边界。
+- `docs/architecture/adr/0002-cas-v1-design-boundary.md`：CAS V1 设计边界。
+- `docs/architecture/adr/0003-cas-core-interface-and-error-boundary.md`：CAS 核心接口和错误边界。
+- `docs/architecture/adr/0004-rust-bat-go-bat-api-resource-boundary.md`：当前 Rust `bat` 与 Go `bat-api` 资源控制面边界。
+
+### 3.3 对外接口规范
 
-- `README.md`：项目概览、当前可用能力和快速开始。
-- `PROJECT_PLAN.md`：完整开发计划和最终目标路线图。
-- `CURRENT_STATUS.md`：当前工作区真实状态。
-- `docs/reports/CURRENT_GAPS.md`：当前实现缺口和关闭顺序。
-- `docs/reports/GO_STATUS.md`：Go 侧边界、约定与组件进度（权威）。
-- `docs/guides/official-resource-test-pull.md`：官方资源拉取与自动更新用户指南。
-- `docs/guides/official-full-pull-smoke.md`：真实官方全量拉取 smoke runbook 和可重复命令。
-- `docs/guides/bat-api-local-live-smoke.md`：同机 Rust `bat` / Go `bat-api` live socket 联调 runbook。
-- `docs/guides/bat-workflows.md`：Rust `bat` 的 `res` / `parse` / `i18n` 工作流、调度计划和 `bat-api` dashboard 接口。
-- `docs/architecture/official-resource-backend.md`：官方资源后端职责、工作原理和审核说明。
-- `docs/architecture/resource-release-layout.md`：release 布局、URL 映射、seed 规则、bat-api 分发契约（资源侧逆向权威）。
-- `docs/architecture/assetbundle.md`：AssetBundle、Addressables、Serialized File、文本提取和 Patch 前置解析路线图。
 - `docs/reference/rpc-backend-api.md`：Rust Resource Backend JSON-RPC 稳定 contract。
-- `CHANGELOG.md`：版本变更记录。
-- `AGENTS.md`：AI agent 和自动化开发助手长期规则。
-- `CONTRIBUTING.md`：贡献者协作、提交和验证要求。
-- `CLAUDE.md`：Claude Code 等旧工具的兼容入口。
+- `api/openapi/bat-api.yaml`：`bat-api` HTTP OpenAPI 静态规范。
+- `docs/api/README.md`：API 文档入口及规范索引。
 
----
+契约文档涉及字段、状态码、错误码、release layout 或路径语义时，必须与源码测试和 `internal/api/testdata/contract/` 一起复核。
 
-## 2. 架构与指南
+## 4. 用户、开发与运维指南
 
-- `docs/architecture/README.md`：总体架构设计。
-- `docs/api/README.md`：API 设计入口。
-- `api/openapi/bat-api.yaml`：当前 `bat-api` 资源 bootstrap/分发、内嵌 dashboard 和管理控制面 HTTP OpenAPI 静态规范。
-- `docs/reference/rpc-backend-api.md`：Rust Resource Backend JSON-RPC 稳定 contract。
-- `docs/guides/development.md`：开发指南。
-- `docs/guides/deployment.md`：部署指南。
-- `deployments/systemd/`：官方资源同步生产 systemd unit 和环境文件示例。
-- `docs/guides/official-resource-test-pull.md`：官方资源拉取与自动更新用户指南。
-- `docs/guides/official-full-pull-smoke.md`：真实官方全量拉取 smoke runbook 和可重复命令。
-- `docs/guides/bat-api-local-live-smoke.md`：同机 Rust `bat` / Go `bat-api` live socket 联调。
-- `docs/guides/baseline.md`：稳定工程基线指南。
-- `docs/architecture/adr/0001-engine-and-application-boundaries.md`：Rust/Go 边界决策。
-- `docs/architecture/adr/0002-cas-v1-design-boundary.md`：CAS V1 边界决策。
-- `docs/architecture/adr/0003-cas-core-interface-and-error-boundary.md`：CAS 核心接口和错误边界冻结。
+这些文件描述如何使用或验证已经存在的能力：
 
-后续建议新增：
+- `docs/guides/development.md`：本地开发、测试、调试和代码质量流程。
+- `docs/guides/deployment.md`：部署、systemd、Docker 和运维说明。
+- `docs/guides/official-resource-test-pull.md`：官方资源拉取与自动更新运行指南。
+- `docs/guides/official-full-pull-smoke.md`：真实官方全量拉取 smoke runbook。
+- `docs/guides/bat-api-local-live-smoke.md`：Rust `bat` 与 Go `bat-api` 同机 live 联调。
+- `docs/guides/bat-workflows.md`：`res`、`parse`、`i18n` 工作流和调度接口。
+- `docs/guides/baseline.md`：稳定工程基线和合并前检查。
+- `scripts/check-doc-status.sh`：当前状态、占位目录和关键契约文字门禁。
+- `scripts/check-doc-links.sh`：全仓库 Markdown 本地链接门禁。
 
-- `docs/architecture/cas.md`：CAS 生产级设计。
-- `docs/architecture/translation.md`：翻译系统设计。
+`deployments/` 下的 systemd、Docker、环境文件和数据库配置是部署材料，不作为独立架构文档；其行为说明以本节指南和当前源码为准。
 
----
+## 5. 分析资料和机器产物
 
-## 3. 分析资料
+以下资料用于分析或测试，不是当前能力声明：
 
-- `docs/assetbundle_analysis.json`：AssetBundle 分析资料。
-- `docs/textassets_analysis.json`：TextAsset 分析资料。
-- `docs/archive/BLUE_ARCHIVE_TECHNICAL_ANALYSIS.md`：历史技术分析。
-- `docs/archive/ARCHITECTURE_REVIEW.md`：历史架构审查。
-- `docs/archive/ARCHITECTURE_REVIEW_SUMMARY.md`：历史架构审查摘要。
-- `docs/archive/READY_FOR_PHASE_1.md`：历史 Phase 1 准备文档。
-- `docs/archive/REFACTOR_CHECKLIST.md`：历史重构清单。
+- `docs/assetbundle_analysis.json`：AssetBundle 分析数据。
+- `docs/textassets_analysis.json`：TextAsset 分析数据。
+- `adapters/tests/fixtures/`、`adapters/tests/golden/`：Manifest / Addressables fixture 和 golden。
+- `infrastructure/tests/fixtures/`、`infrastructure/tests/golden/`：官方同步和导入 fixture。
+- `internal/api/testdata/contract/`：Rust-Go contract mirror 和 Go contract tests 输入。
+- `internal/api/testdata/release/`：`bat-api` 本地 release fixture。
 
----
+测试 fixture 可以证明特定行为，但不能单独证明对所有真实官方格式的完整支持；真实样本和运行 smoke 仍需单独标注。
 
-## 4. 历史报告
+## 6. 模块状态说明
 
-历史报告已按来源和主题归档，供追溯使用，不再代表当前状态。
+以下 README 是模块占位或边界说明，不是完整实现文档：
 
+- `api/README.md`
+- `api/proto/README.md`
+- `api/openapi/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`
+
+这些目录的实现状态以 `docs/reports/GO_STATUS.md`、对应源码和测试为准；不能因为目录或 README 存在就视为模块已完成。
+
+## 7. 历史归档
+
+以下内容只用于追溯，不能作为当前实现、当前优先级或当前测试结果的证据：
+
+- `docs/archive/`：早期架构审查、技术分析、重构清单和 Phase 1 准备材料。
 - `docs/reports/historical/root/`：原根目录阶段报告。
-- `docs/reports/historical/current-stage/`：已被 `CURRENT_STATUS.md` 和当前指南取代的阶段交接、推送前核查报告。
-- `docs/reports/historical/week2/`：Week 2 相关报告。
-- `docs/reports/historical/week3/`：Week 3 相关报告。注意：这些报告中存在“完成”和“回滚”的冲突描述。
-- `docs/reports/historical/build-logs/`：历史构建、测试、Clippy 输出。
+- `docs/reports/historical/current-stage/`：已被当前状态和指南取代的阶段交接报告。
+- `docs/reports/historical/week2/`：Week 2 报告和当时的构建/测试输出。
+- `docs/reports/historical/week3/`：Week 3 报告；其中存在互相冲突的完成描述。
+- `docs/reports/historical/build-logs/`：历史构建、测试和 Clippy 输出。
 - `docs/reports/historical/quality/`：历史质量报告。
-- `docs/reports/historical/nested-docs/`：从误嵌套 `docs/docs` 移出的报告。
+- `docs/reports/historical/nested-docs/`：从旧目录结构迁移出来的历史报告。
 
----
+## 8. 推荐阅读顺序
 
-## 5. 当前阅读顺序
-
-新开发者或新会话建议按以下顺序阅读：
-
-1. `CURRENT_STATUS.md`
-2. `PROJECT_PLAN.md`
-3. `docs/guides/official-resource-test-pull.md`
-4. `docs/guides/official-full-pull-smoke.md`
-5. `docs/guides/bat-api-local-live-smoke.md`
-6. `docs/guides/bat-workflows.md`
-7. `docs/architecture/official-resource-backend.md`
+1. `README.md`
+2. `CURRENT_STATUS.md`
+3. `PROJECT_PLAN.md`
+4. `docs/reports/CURRENT_GAPS.md`
+5. `docs/reports/GO_STATUS.md`
+6. `docs/architecture/official-resource-backend.md`
+7. `docs/architecture/resource-release-layout.md`
 8. `docs/reference/rpc-backend-api.md`
-9. `docs/reports/CURRENT_GAPS.md`
-10. `docs/guides/baseline.md`
-11. `docs/architecture/README.md`
+9. `docs/architecture/assetbundle.md`
+10. `docs/guides/official-resource-test-pull.md`
+11. `docs/guides/bat-workflows.md`
 12. `docs/guides/development.md`
 13. `CONTRIBUTING.md`
 14. `AGENTS.md`
 
----
-
-## 6. 状态摘要
-
-当前总体完成度不再固定写单一百分比，以 `CURRENT_STATUS.md` 和 `CURRENT_GAPS.md` 的模块状态为准。
-
-已完成：
-
-- Rust 领域模型和仓储接口骨架。
-- Unity/Manifest/Client 适配器框架。
-- CAS V1：原子写入、BLAKE3 校验、引用计数、GC、并发测试和损坏检测。
-- 文档整理和路线图重制。
-- Rust 官方资源同步闭环：`bat`、`--auto-discover`、`--watch`、`--daemon`、Unix socket JSON-RPC 后台控制、`status`、`stop`、`restart`、`reload`、`refresh`、`logs`、`verify`、`repair`、`doctor`、`clean-stable`、北京时间固定强制刷新、snapshot、manifest audit/repair、官方 seed `.hash` 校验。
-- 官方 release 历史文件与 CAS 对象复用：复用前执行 size、BLAKE3 和 ZIP 结构校验，失败回退网络，引用写入版本化清单并由清理流程回收。
-- 官方原版资源与汉化产物目录分离：`./bat-resources` 只承载原版 release，`./bat-localized` 承载后续汉化 release；当前官方同步报告 `not_localized`，Patch 发布完成后才进入 `localized`。
-- 官方 release 会维护 `official-parse-cache.json`，用于跳过未变化资源的重复解析。
-- `bat-api/internal/backendrpc` typed Unix socket JSON-RPC client。
-- `cmd/bat-api` 资源分发 HTTP MVP 与内嵌 dashboard（进度见 `docs/reports/GO_STATUS.md`）。
-- 真实官方网络全量拉取 smoke 已固化为 `scripts/official-full-pull-smoke.sh` 和 `make official-smoke`，默认写入 `/tmp` 隔离目录并输出本地运行报告。
-- `bat-api` 同机 live smoke 已固化为 `scripts/bat-api-local-live-smoke.sh` 和 `make bat-api-local-live-smoke`，覆盖真实 `bat.sock`、release 切换、未 ready、恢复和 CDN 读路径。
-- `bat` 运行时 progress log 已覆盖下载已完成计数、单文件下载进度和校验结果摘要。
-- `bat` 前台结果渲染与终端诊断输出已分别收敛到 `report_output.rs` 和 `terminal_output.rs`，CLI 流程模块只负责编排。
-- Addressables 当前真实形态 fixture/golden 覆盖。
-- 解析补全路线图已固化到 `docs/architecture/assetbundle.md`：解析缓存、Addressables、UnityFS、Serialized 字段级解析、文本提取、CAS 接入和 Patch 发布前置。
-- SQLite Resource Repository 和可选无状态 `bat-ffi` JSON 兼容接口。
-
-优先待办：
-
-- `bat-api` 与完整官方网络长期运行（独立于 issue #19 的 `make official-smoke` 跟踪）。
-- 扩展 CAS + ResourceRepository 的用户级查询、翻译记忆和通用 Patch 发布资源视图。
-- 推进 AssetBundle UnityFS 引擎级解析。
+阅读顺序中的状态和契约结论必须回到当前源码、测试和实际命令验证；历史报告只用于解释演进过程。