BlueArchiveToolkit/DOCS_INDEX.md

# BlueArchive Toolkit 文档分类索引

- **更新时间**：2026-09-13
- **用途**：按用途、时效性和权威级别定位文档。
- **原则**：目录是物理归档方式，不能单独代表文档权威性；当前源码、测试和下列当前文档优先于历史报告。

## 1. 项目入口与协作规则

这些文件位于仓库根目录，是项目级入口或协作规则：

- `README.md`：项目概览、当前能力和快速开始。
- `USERGUIDE.md`：`bat` 用户指南、命令、配置、错误码和常用 RPC 说明。
- `CURRENT_STATUS.md`：当前实现状态，使用源码和测试复核后维护。
- `PROJECT_PLAN.md`：长期目标、里程碑和后续路线图。
- `CONTRIBUTING.md`：贡献流程、提交规范和验证要求。
- `CHANGELOG.md`：版本变更记录，不作为当前实现的唯一依据。
- `CLAUDE.md`：旧工具兼容入口，不承载独立规则。
- `AGENTS.md`：AI agent 长期协作规则。
- `TODO.md`：具体工程任务、优先级、依赖与完成条件的仓库内任务账本；不作为当前实现事实来源。
- `DESIGN.md`：Dashboard 的主要视觉参考与设计灵感来源；涉及 Dashboard/Web UI/布局/视觉/组件/交互任务时必须先阅读。

## 2. 当前状态、计划与缺口

这些文件描述当前项目，不应写入未经源码或测试证明的完成状态：

- `CURRENT_STATUS.md`：全项目当前状态总览。
- `docs/reports/GO_STATUS.md`：Go `bat-api` 边界和组件进度的权威文档。
- `docs/reports/CURRENT_GAPS.md`：当前缺口、影响和推进顺序。
- `PROJECT_PLAN.md`：目标和路线图；其中的计划项不等于已实现。
- `TODO.md`：当前可执行工程任务、优先级、依赖与验收条件；条目状态不高于源码、测试和 current-status 文档。
- `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 对外接口规范

- `docs/reference/rpc-backend-api.md`：Rust Resource Backend JSON-RPC 稳定 contract。
- `api/openapi/bat-api.yaml`：`bat-api` HTTP OpenAPI 静态规范。
- `docs/api/README.md`：API 文档入口及规范索引。

契约文档涉及字段、状态码、错误码、release layout 或路径语义时，必须与源码测试和 `internal/api/testdata/contract/` 一起复核。


### 3.4 Dashboard 设计参考

- `DESIGN.md`：用户 Dashboard 与运营 Dashboard 的主要视觉参考和设计灵感来源，描述应延续的色彩关系、排版、空间、边框、层级、组件形态和交互气质。它不定义后端事实、权限或业务状态，也不要求复制参考来源的页面结构或品牌内容。
- Dashboard 的稳定产品职责、信息边界和设计执行规则见 `AGENTS.md` 的“Dashboard 开发与设计”。用户 Dashboard 与运营 Dashboard 共享基础视觉语言和组件体系，但拥有不同的信息架构、信息密度和权限边界。
- Dashboard 设计必须以当前真实 API/RPC contract 和数据结构为依据。若所需信息尚无后端 contract，应记录缺口，而不是在前端维护第二份业务状态或伪造指标。

发生冲突时遵循：`AGENTS.md` 与稳定产品/接口契约 > 当前明确任务需求 > `DESIGN.md` > Agent 自身设计偏好。

## 4. 用户、开发与运维指南

这些文件描述如何使用或验证已经存在的能力：

- `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 本地链接门禁。

`deployments/` 下的 systemd、Docker、环境文件和数据库配置是部署材料，不作为独立架构文档；其行为说明以本节指南和当前源码为准。

## 5. 分析资料和机器产物

以下资料用于分析或测试，不是当前能力声明：

- `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 仍需单独标注。

## 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/`：已被当前状态和指南取代的阶段交接报告。
- `docs/reports/historical/week2/`：Week 2 报告和当时的构建/测试输出。
- `docs/reports/historical/week3/`：Week 3 报告；其中存在互相冲突的完成描述。
- `docs/reports/historical/PARSER_FREEZE.md`：已解除的解析模块维护冻结历史记录，不构成当前开发约束。
- `docs/reports/historical/build-logs/`：历史构建、测试和 Clippy 输出。
- `docs/reports/historical/quality/`：历史质量报告。
- `docs/reports/historical/nested-docs/`：从旧目录结构迁移出来的历史报告。

## 8. 推荐阅读顺序

### 8.1 项目与开发者通用阅读顺序

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/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`

### 8.2 AI / Agent 开发接管顺序

Agent 进入仓库进行开发时优先按以下顺序建立上下文：

1. `AGENTS.md`：先确定长期规则、状态所有权和开发边界；
2. `DOCS_INDEX.md`：确认当前任务应阅读的权威文档；
3. `CURRENT_STATUS.md` 与对应专项状态文档：确认当前已经实现的事实；
4. `TODO.md`：确认当前具体任务、优先级、依赖和完成条件；
5. 当前任务直接相关的源码、tests、稳定 contract 和架构文档；
6. `docs/reports/CURRENT_GAPS.md` / `PROJECT_PLAN.md`：需要判断能力缺口或后续路线时再读取。

涉及 Dashboard、Web UI、页面布局、视觉样式、组件或交互体验时，在设计或修改前额外必须阅读 `DESIGN.md`。

阅读顺序中的状态和契约结论必须回到当前源码、测试和实际命令验证；`TODO.md`、`CURRENT_GAPS.md` 和 `PROJECT_PLAN.md` 均不能把计划项提升为已实现事实；历史报告只用于解释演进过程。