diff --git a/DOCS_INDEX.md b/DOCS_INDEX.md index 824d5a3..07e7bd0 100644 --- a/DOCS_INDEX.md +++ b/DOCS_INDEX.md @@ -111,6 +111,7 @@ - `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/`:从旧目录结构迁移出来的历史报告。 diff --git a/PROJECT_PLAN.md b/PROJECT_PLAN.md index 49f92e7..5e16368 100644 --- a/PROJECT_PLAN.md +++ b/PROJECT_PLAN.md @@ -325,12 +325,14 @@ BlueArchiveToolkit 不是一次性脚本,也不是演示项目。最终交付 交付物: -1. Go CLI 主入口和命令体系。 +1. 正式 Rust `bat` CLI 和命令体系;Go 侧面向 `bat-api`、SDK 和服务集成发展。 2. 配置系统:项目级、用户级、环境变量、密钥管理。 3. Go SDK:Manifest、Sync、CAS、Extract、Translate、Patch。 4. REST API Server:认证、权限、统一错误码、OpenAPI。 5. 后台任务系统:同步、提取、翻译、补丁构建。 +当前边界:正式同步与运维 CLI 继续由 Rust `bat` 承担;Go `cmd/bat` 仅为试验入口,Go 产品化工作集中在 `bat-api`、SDK 和服务集成。 + 验收标准: 1. CLI 命令风格统一,支持 JSON 输出和人类可读输出。 diff --git a/README.md b/README.md index 4599531..3be450d 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,7 @@ - 官方同步会维护 `/official-version-state.json`,明确记录当前已完成版本、正在拉取版本、上一个可用版本和失败版本。 - 资源导入链路可配置为在官方 release 发布后写入 CAS + `ResourceRepository`,资源 metadata 会记录 release、平台、bundle path、parse status、TextAsset 名称和 TextUnit 数量/格式,TextAsset/Table/Media 会按类型分类索引;`resource.index` RPC/CLI 可按类型、hash、路径模式、官方 release ID、平台、destination、bundle path、archive entry、parse status 和 TextUnit format 分页查询索引,常用 metadata 过滤会下推到 SQLite;历史 release 复用会重新校验 size、BLAKE3 和 ZIP 结构,失败时按历史 release、CAS、网络顺序回退,CAS 引用记录在 `official-cas-reuse-references.json` 中;`bat doctor cas` 可只读诊断既有 CAS 目录、对象数、对象字节数和元数据库文件状态。 - 新 release 发布后会生成 `official-resource-changes.json`、`official-parse-cache.json`、`official-textunit-index.json`、`official-textunit-tasks.json`、`crowdin-translation-handoff.json`、`crowdin-textunit-queue.json`、`translation-tasks.sqlite` 和 `translation-handoff.json`;其中 TextUnit/Crowdin 队列只使用 Added/Modified 资源,不调用 Crowdin 网络 API,离线 TextUnit 翻译任务可通过 `translation.tasks` / `translation.handoff` RPC 或 CLI 查询状态、跳过/失败原因和 provider run 交接。 +- `translation.worker.run` 已提供 Rust `bat` 的 mock/Crowdin provider worker,支持 lease、失败重试和 TextUnit 译文结果落库;尚缺 Translation Memory、Glossary 和完整 Provider 扩展体系。 - `LocalizedPatchService` 已具备受支持的 UnityFS localized patch 发布/回滚能力:在 `--localized-output` / `BAT_LOCALIZED_OUTPUT` 配置的独立汉化目录 staging 中复制官方 release、应用 TextAsset、TypeTree string field 或 managed-reference string field patch、写入带 TextUnit/provider/review/rollback trace 的 `localized-patch-manifest.json`,校验后发布到 `versions/` 并切换 `current`,也可显式 rollback。 - `bat-patch` 已具备通用 Patch 基础:确定性 Binary hunk diff/apply、RFC 6902 JSON Patch apply、UTF-8 Text Patch、Patch manifest、BLAKE3/size 完整性校验和 rollback 元数据;文件级 `patch.apply` RPC / `patch-apply` CLI 与 UnityFS TextAsset / TypeTree string / TypeTree 语义字段写入入口已开放,TypeTree 语义字段支持基础标量、固定 Unity float/int/hash 值类型的 leaf/direct-child 形态、PPtr、managed-reference registry payload 字符串、object 字段组合、unknown fixed-size raw bytes 同长度替换和 TypeTree schema 支撑的 array/vector/map 整体替换;TextUnit 提取会把 managed-reference 类型信息保留为上下文而非翻译文本,受支持 localized 发布通过独立 manifest/staging/current 流程完成。 - `bat-ffi` 可选无状态 C ABI 兼容层:仅保留 Manifest inspect 和官方 sync plan 的粗粒度 JSON helper,不作为 Go CLI 或生产同步的主集成边界。 @@ -29,8 +30,8 @@ - `bat-api` 完整游戏业务 API / launcher 安装包更新全链仍未完成;资源 CDN、HTTP 控制面、launcher 资源引导兼容和内嵌 dashboard MVP 已可用。 - 完整 AssetBundle 对象级解析(UnityFS 解包、object table、TypeTree node 元数据、TextAsset bytes、MonoBehaviour/ScriptableObject 基础 TypeTree 字段级解析已起步;复杂字段覆盖、发布级重打包和 Patch 发布统一仍未完成)。 -- 复杂 AssetBundle 重打包和真实翻译构建 worker;当前通用 Binary/JSON/Text Patch 基础已在 crate 层可用,localized 发布仅开放已验证 TextUnit 对应的 UnityFS 文本字段。 -- Translation Memory、Glossary、AI Provider。 +- 复杂 AssetBundle 重打包和完整翻译资产编排仍未完成;当前通用 Binary/JSON/Text Patch 基础已在 crate 层可用,localized 发布仅开放已验证 TextUnit 对应的 UnityFS 文本字段。 +- Translation Memory、Glossary 和完整 Provider 扩展体系仍未实现。 - SDK、完整 Web 协作后台。 详细状态见: diff --git a/deployments/.env.example b/deployments/.env.example index 0421832..548393c 100644 --- a/deployments/.env.example +++ b/deployments/.env.example @@ -10,9 +10,9 @@ DB_MODE=remote # PostgreSQL 配置 # 本地模式:使用 localhost:5432 -# 远程模式:填写远程服务器的公网 IP 和端口 -DB_HOST=your.remote.server.com # 远程服务器地址(或 localhost 用于本地) -DB_PORT=5432 +# 远程模式:优先使用私网/VPN;SSH tunnel 时填写本地转发地址和端口 +DB_HOST=127.0.0.1 # 本地或 SSH tunnel 地址 +DB_PORT=15432 DB_USER=bat_user DB_PASSWORD=your_secure_password_here DB_NAME=bluearchive_toolkit @@ -32,9 +32,9 @@ DB_SSL_MODE=prefer # Redis 配置 # 本地模式:使用 localhost:6379 -# 远程模式:填写远程服务器的公网 IP 和端口 -REDIS_HOST=your.remote.server.com # 远程服务器地址(或 localhost 用于本地) -REDIS_PORT=6379 +# 远程模式:优先使用私网/VPN;SSH tunnel 时填写本地转发地址和端口 +REDIS_HOST=127.0.0.1 # 本地或 SSH tunnel 地址 +REDIS_PORT=16379 REDIS_PASSWORD=your_redis_password_here REDIS_DB=0 diff --git a/deployments/docker-compose.dev.yml b/deployments/docker-compose.dev.yml index b64a2dd..7e3f93f 100644 --- a/deployments/docker-compose.dev.yml +++ b/deployments/docker-compose.dev.yml @@ -19,7 +19,7 @@ services: POSTGRES_PASSWORD: bat_dev_password POSTGRES_INITDB_ARGS: "-E UTF8 --locale=C" ports: - - "0.0.0.0:5432:5432" + - "127.0.0.1:5432:5432" volumes: - postgres_data:/var/lib/postgresql/data - ./postgres-init:/docker-entrypoint-initdb.d @@ -41,7 +41,7 @@ services: profiles: ["local-db"] # 只有指定 --profile local-db 才启动 command: redis-server /usr/local/etc/redis/redis.conf ports: - - "0.0.0.0:6379:6379" + - "127.0.0.1:6379:6379" volumes: - redis_data:/data - ./redis.conf:/usr/local/etc/redis/redis.conf diff --git a/deployments/docker-compose.remote-db.yml b/deployments/docker-compose.remote-db.yml index a9d8ae6..92cc20b 100644 --- a/deployments/docker-compose.remote-db.yml +++ b/deployments/docker-compose.remote-db.yml @@ -5,7 +5,7 @@ # 1. 将此文件和相关配置上传到远程服务器 # 2. 复制 .env.example 为 .env 并配置密码 # 3. 运行:docker compose -f docker-compose.remote-db.yml up -d -# 4. 确保防火墙开放 5432 和 6379 端口 +# 4. 默认仅绑定宿主机回环地址;远程开发使用私网、VPN 或 SSH tunnel version: '3.9' @@ -20,7 +20,7 @@ services: POSTGRES_PASSWORD: ${REMOTE_DB_POSTGRES_PASSWORD} POSTGRES_INITDB_ARGS: "-E UTF8 --locale=C" ports: - - "0.0.0.0:5432:5432" # 监听所有网络接口 + - "127.0.0.1:5432:5432" # 不直接暴露到公网 volumes: - postgres_data:/var/lib/postgresql/data - ./postgres-init:/docker-entrypoint-initdb.d @@ -44,7 +44,7 @@ services: container_name: bat-redis command: redis-server /usr/local/etc/redis/redis.conf ports: - - "0.0.0.0:6379:6379" # 监听所有网络接口 + - "127.0.0.1:6379:6379" # 不直接暴露到公网 volumes: - redis_data:/data - ./redis-remote.conf:/usr/local/etc/redis/redis.conf diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 7e4a2e8..caed03f 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -192,7 +192,7 @@ pub struct ParserRegistry { --- -### 4. 翻译系统 (目标设计,Go) +### 4. 翻译系统(目标扩展,Go;当前 worker 由 Rust `bat` 承担) 当前已实现的是 Rust `bat` 的离线 TextUnit 队列、mock/Crowdin provider worker、 lease/retry 和结果落库;Translation Memory、Glossary 和完整 Provider 体系仍属 @@ -214,7 +214,11 @@ type TranslationProvider interface { } ``` -**实现**: +**当前实现**: +- Rust `bat` 的 mock provider worker +- Rust `bat` 的 Crowdin provider worker + +**目标 Provider**: - DeepL Provider - OpenAI Provider - Anthropic Provider @@ -233,7 +237,7 @@ type TranslationProvider interface { **职责**:生成和应用补丁 **支持的 Patch 类型**: -1. **Binary Patch**:使用 bsdiff 算法 +1. **Binary Patch**:确定性 Binary hunk diff/apply(当前实现) 2. **JSON Patch**:RFC 6902 标准 3. **Text Patch**:基于 diff 算法 diff --git a/docs/guides/deployment.md b/docs/guides/deployment.md index 5a2d8d6..f3eba6e 100644 --- a/docs/guides/deployment.md +++ b/docs/guides/deployment.md @@ -4,98 +4,78 @@ BlueArchive Toolkit 的部署文档分为当前可用模式和目标模式: -1. **本地开发模式**:代码在本地,连接本地或远程数据库。 +1. **本地开发模式**:当前 Rust `bat` 和 Go `bat-api` 不依赖 PostgreSQL/Redis; + 本地资源状态使用文件和 SQLite。 2. **官方资源同步生产任务**:当前可用,运行 Rust `bat --watch` 或 RPC/daemon 模式。 3. **bat-api 资源 bootstrap / 分发服务**:当前可用,和 Rust `bat` 在同一服务器/容器环境运行,经 `bat.sock` RPC 获取当前 `resource_root`。 -4. **完整单机/分布式部署**:尚未提供。完整游戏业务 API、数据库迁移和 Web 未实现前,不把它作为可执行部署方案。 +4. **可选数据库开发环境**:PostgreSQL/Redis 只服务于未来的 Go 服务层、Translation + Memory、Glossary 和完整 Provider 扩展,不是当前 `bat` / `bat-api` 的生产运行依赖。 +5. **完整单机/分布式部署**:尚未提供。完整游戏业务 API、数据库迁移和 Web 未实现前,不把它作为可执行部署方案。 --- -## 模式 1:本地开发 + 远程数据库 +## 模式 1:本地开发(当前推荐) -适用场景:本地开发,数据库部署在有公网 IP 的远程服务器 - -### 步骤 - -#### 1. 在远程服务器上部署数据库 +当前实现不要求启动 PostgreSQL 或 Redis。建议先运行 Rust/Go 自身的门禁: ```bash -# SSH 登录到服务器 -ssh user@your.server.com - -# 创建部署目录 -mkdir -p ~/bat/deployments -cd ~/bat/deployments - -# 上传配置文件(在本地执行) -scp -r deployments/* user@your.server.com:~/bat/deployments/ - -# 配置环境变量 -cp .env.example .env -nano .env # 设置强密码 - -# 启动数据库 -docker compose -f docker-compose.remote-db.yml up -d - -# 查看状态 -docker compose -f docker-compose.remote-db.yml ps +cargo check --workspace --locked +make test-go-api +make build-go-api +make check-docs ``` -#### 2. 配置防火墙 +只有在开发未来 Go 服务层或目标数据库适配时,才需要启动可选的本地数据库: ```bash -# 开放 PostgreSQL 端口 -sudo ufw allow 5432/tcp - -# 开放 Redis 端口 -sudo ufw allow 6379/tcp - -# 查看状态 -sudo ufw status +docker compose -f deployments/docker-compose.dev.yml --profile local-db up -d ``` -#### 3. 本地连接配置 +本地数据库端口默认只绑定 `127.0.0.1`,不应改为 `0.0.0.0`。 -在本地项目根目录创建 `.env`: +--- + +## 模式 2:可选数据库开发环境(目标能力) + +PostgreSQL 和 Redis 不是当前 `bat` / `bat-api` 的生产运行依赖。本模式只用于未来 +服务层、Translation Memory、Glossary 或 Provider 扩展的开发验证,不能作为当前 +资源同步或资源分发的部署前置条件。 + +### 远程开发连接 + +远程开发默认使用私网地址、VPN 或 SSH tunnel。不要为开发方便把 PostgreSQL +`5432` 或 Redis `6379` 暴露到公网;尤其不得把 Redis 公网暴露作为推荐方案。 + +在远程主机上启动可选数据库后,优先通过 SSH tunnel 连接: + +```bash +ssh -N \ + -L 15432:127.0.0.1:5432 \ + -L 16379:127.0.0.1:6379 \ + user@db-host +``` + +本地开发进程只连接 tunnel 的回环端口: ```env -DB_HOST=your.server.ip.address -DB_PORT=5432 -DB_USER=bat_user -DB_PASSWORD=your_secure_password -DB_NAME=bluearchive_toolkit - -REDIS_HOST=your.server.ip.address -REDIS_PORT=6379 -REDIS_PASSWORD=your_redis_password +DB_HOST=127.0.0.1 +DB_PORT=15432 +REDIS_HOST=127.0.0.1 +REDIS_PORT=16379 ``` -#### 4. 测试连接 +如果使用 VPN 或私网直连,应限制数据库服务仅监听明确的私网接口和允许的来源 +网段,并继续使用认证与 TLS。不要添加面向全网的 `5432` / `6379` 防火墙放行规则。 + +远程主机上的可选 Compose 服务: ```bash -# 测试 PostgreSQL 连接 -psql -h your.server.ip.address -U bat_user -d bluearchive_toolkit - -# 测试 Redis 连接 -redis-cli -h your.server.ip.address -p 6379 -a your_redis_password ping +docker compose -f deployments/docker-compose.remote-db.yml up -d +docker compose -f deployments/docker-compose.remote-db.yml ps ``` ---- - -## 模式 2:本地数据库(开发) - -适用场景:完全本地开发,不需要远程服务器 - -```bash -# 启动本地数据库 -docker compose -f deployments/docker-compose.dev.yml --profile local-db up -d - -# 配置 .env -DB_HOST=localhost -DB_PORT=5432 -REDIS_HOST=localhost -REDIS_PORT=6379 -``` +该 Compose 配置默认仅在远程主机回环地址发布端口,远程访问应通过 SSH tunnel、 +VPN 或受控私网,不通过公网端口直连。 --- @@ -504,71 +484,42 @@ BAT_API_SKIP_ENV_FILE=1 go run ./cmd/bat-api \ --- -## 数据库备份 +## 可选数据库环境的备份与监控 -### 手动备份 +以下内容只适用于未来服务层使用的可选 PostgreSQL/Redis 环境,不属于当前 +`bat` / `bat-api` 生产部署步骤。 + +### 备份 + +备份应在数据库主机或受控私网内执行,也可以通过 SSH 在远程主机上运行容器内工具: ```bash -# PostgreSQL -pg_dump -h your.server.com -U bat_user -d bluearchive_toolkit > backup.sql - -# Redis -redis-cli -h your.server.com -p 6379 -a password BGSAVE -``` - -### 自动备份 - -启动备份服务: -```bash +ssh user@db-host \ + 'docker exec bat-postgres pg_dump -U bat_user bluearchive_toolkit' \ + > backup.sql docker compose -f deployments/docker-compose.remote-db.yml --profile backup up -d ``` -备份文件位置:`deployments/backups/` +Redis 备份使用数据库主机或容器内的受控备份工具。不要在脚本或文档中使用带公网 +主机名的 `redis-cli -h ... -p 6379` 连接,也不要把密码放进公开命令行参数或提交文件。 ---- - -## 监控 - -### 查看日志 +### 监控 ```bash -# 数据库日志 -docker logs bat-postgres - -# Redis 日志 -docker logs bat-redis +ssh user@db-host 'docker compose -f deployments/docker-compose.remote-db.yml ps' +ssh user@db-host 'docker logs bat-postgres' +ssh user@db-host 'docker logs bat-redis' ``` -### 健康检查 +### 故障排查 -```bash -# 检查容器状态 -docker compose -f deployments/docker-compose.remote-db.yml ps +当前 `bat` / `bat-api` 无需数据库连接;资源同步故障应先检查 `bat.sock`、发布目录、 +SQLite 索引和 Rust daemon 状态。未来服务层出现数据库连接问题时,按以下顺序检查: -# 检查 PostgreSQL -docker exec bat-postgres pg_isready -U bat_user - -# 检查 Redis -docker exec bat-redis redis-cli ping -``` - ---- - -## 故障排查 - -### 无法连接数据库 - -1. 检查防火墙是否开放端口 -2. 检查 `pg_hba.conf` 配置 -3. 检查密码是否正确 -4. 检查数据库是否启动 - -### 性能问题 - -1. 查看数据库连接数 -2. 检查慢查询日志 -3. 优化索引 -4. 调整数据库参数 +1. 私网、VPN 或 SSH tunnel 是否可用; +2. 本地连接端口是否为 tunnel 映射或受控私网端口; +3. 数据库认证、TLS 和允许网段配置; +4. 数据库容器是否运行。 --- diff --git a/docs/reports/historical/PARSER_FREEZE.md b/docs/reports/historical/PARSER_FREEZE.md new file mode 100644 index 0000000..481a60c --- /dev/null +++ b/docs/reports/historical/PARSER_FREEZE.md @@ -0,0 +1,91 @@ +# 解析模块维护冻结(历史记录) + +**状态**:历史记录,已解除 +**生效时间**:2026-07-30 +**解除时间**:2026-09-04 + +本文保留解析模块维护冻结期间的原始规则和例外说明。冻结已于 +2026-09-04 解除,以下内容不构成当前开发约束;当前解析开发以源码、测试、 +`CURRENT_STATUS.md` 和 `docs/architecture/assetbundle.md` 为准。 + +--- + +## 原冻结记录 + +原记录发布时状态:**生效中** + +冻结目标:停止继续扩大 UnityFS / AssetBundle / Addressables / TypeTree 解析能力,把当前工作重心切换到运行稳定性、代码审核问题、文档一致性和发布链路可靠性。 + +## 冻结范围 + +冻结覆盖以下 Rust 解析相关模块和对外入口: + +- `crates/bat-assetbundle` +- `adapters/src/unity*` +- `infrastructure/src/official_parse.rs` +- `infrastructure/src/resources.rs` 中解析缓存、TextUnit 索引和解析状态相关逻辑 +- `unityfs.*`、`parse.*`、`text.*` 相关 RPC / CLI 契约 +- Addressables catalog、UnityFS、serialized file、TypeTree、TextUnit、AssetBundle patch 相关文档声明 + +## 允许变更 + +冻结期只允许以下解析相关变更: + +- 修复编译失败、格式化失败、clippy 报错和测试失败。 +- 修复真实运行中已经复现的 panic、错误状态污染、重复解析、缓存失效、状态不一致或诊断误导。 +- 补充回归测试,前提是测试覆盖的是已存在能力的稳定性问题,不宣称新增解析能力。 +- 修正文档、CLI 帮助、RPC 参考和状态文件中与当前实现不一致的解析能力声明。 +- 改善错误信息、日志字段、状态记录和失败恢复,但不得改变解析输出契约,除非是修复错误契约且同步迁移说明。 + +## issue 43 的明确例外 + +本次 issue 43 经用户明确授权,允许新增 `bat` 的工作流编排入口: + +- `parse run` 只刷新已有解析输出、TextUnit 索引和翻译队列; +- `parse repack` 只调用已有 TextAsset、TypeTree string 和受支持语义字段 patch 实现; +- `i18n` 工作台和 `publish` 只消费已有 TextUnit 输出,并发布独立汉化 release。 + +该例外不解冻解析器,不新增 UnityFS/AssetBundle/Addressables/TypeTree 解析类型、字段覆盖、catalog 结构或合成 fixture 能力。后续任何扩大解析覆盖的变更仍需单独解冻授权。 + +## issue 2/3 的开发例外 + +授权时间:2026-08-19 + +用户明确授权将 issue #2/#3 作为解析开发进展继续推进。本次例外允许: + +- Addressables JSON/compact catalog 的 provider、bundle name、hash、size、CRC、资源类型和依赖关系字段补全,以及对应 SQLite/fixture 回归; +- UnityFS 已有 header、block、directory、压缩和 alignment 能力的校验加固,以及隔离真实 bundle 回归; +- 更新解析路线图、状态和 RPC/CLI 资源索引字段说明。 + +本次例外不包含发布级复杂对象重打包、完整 Unity 版本兼容承诺或新的汉化发布控制面;这些仍按后续 Patch/发布路线单独验收。 + +## 禁止变更 + +冻结期禁止以下解析相关变更: + +- 新增 TypeTree 语义类型、字段族、managed reference 变体、Unity 内建结构体覆盖或 Addressables catalog 结构覆盖。 +- 用纯合成 fixture 推进“完整解析”并把它记录为已支持能力。 +- 开放新的写入型 `unityfs.*` / `patch.*` RPC 或 CLI。 +- 修改解析结果 schema、TextUnit schema、patch field JSON 语义或缓存状态格式,除非它是阻断级 bug 修复并附带兼容策略。 +- 将解析器和官方同步、汉化发布、Go API、Crowdin 或客户端流程进一步耦合。 + +## 解冻条件 + +解析扩展重新启动前必须同时满足: + +- Rust `bat` 官方同步、daemon、status、校验、断点续传、增量更新和解析缓存链路稳定。 +- 当前 P0/P1 维护 issue 已关闭或被明确降级。 +- `bat-api` 与 Rust RPC / CLI 契约完成字段统一和联调验证。 +- 真实资源 fixture、验证命令和验收标准已写入文档,不能只依赖合成样本。 + +## 冻结期验证 + +解析相关维护变更至少运行: + +```bash +cargo fmt --check +cargo test -p bat-assetbundle --locked +cargo clippy -p bat-assetbundle --all-targets --locked -- -D warnings +``` + +如果变更影响 `bat` CLI、RPC、官方解析缓存或 TextUnit 索引,还必须补充对应 `bat-infrastructure` 测试或说明未运行原因。 diff --git a/docs/reports/historical/README.md b/docs/reports/historical/README.md index 9d4ac96..f1ab20d 100644 --- a/docs/reports/historical/README.md +++ b/docs/reports/historical/README.md @@ -1,6 +1,8 @@ # 历史报告归档说明 -本目录只保存追溯资料,不代表当前项目状态。当前状态以根目录 `CURRENT_STATUS.md`、`PROJECT_PLAN.md`、`DOCS_INDEX.md` 和 `docs/reports/CURRENT_GAPS.md` 为准。 +本目录只保存追溯资料,不代表当前项目状态。当前实现以源码、测试、根目录 +`CURRENT_STATUS.md` 和对应专项状态文档为准;`PROJECT_PLAN.md` 只描述目标和路线图, +`DOCS_INDEX.md` 只负责文档分类,`docs/reports/CURRENT_GAPS.md` 只记录当前缺口。 归档分类: @@ -10,5 +12,6 @@ - `quality/`:早期质量状态报告。 - `build-logs/`:历史构建、测试和 Clippy 输出。 - `nested-docs/`:从误嵌套 `docs/docs` 移出的历史报告。 +- `PARSER_FREEZE.md`:2026-07-30 生效、2026-09-04 解除的解析模块维护冻结记录。 新增运行产物、smoke 输出、质量扫描输出和本地分析报告不要放入本目录;这些文件应写入 `/tmp`、显式的隔离输出目录,或被 `.gitignore` 覆盖的本地生成报告目录。 diff --git a/scripts/check-doc-status.sh b/scripts/check-doc-status.sh index dddb7df..47291c0 100644 --- a/scripts/check-doc-status.sh +++ b/scripts/check-doc-status.sh @@ -44,6 +44,7 @@ required_docs=( "docs/reports/CURRENT_GAPS.md" "docs/reports/GO_STATUS.md" "docs/reports/BAT_API_CONTRACT_FIXTURE_HANDOFF.md" + "docs/reports/historical/PARSER_FREEZE.md" "api/openapi/bat-api.yaml" "internal/api/openapi.go" "internal/api/testdata/contract/README.md" @@ -56,7 +57,7 @@ done [[ ! -e "Agents.md" ]] || fail "stale agent document path exists: Agents.md" [[ ! -e "CHECK.md" ]] || fail "obsolete CHECK.md still exists" [[ ! -e "docs/reports/PARSER_FREEZE.md" ]] || - fail "obsolete parser freeze document still exists" + fail "active parser freeze document still exists" go_version="$(sed -n 's/^go[[:space:]]\{1,\}//p' go.mod | head -n 1)" [[ -n "${go_version}" ]] || fail "go.mod is missing a Go version" @@ -68,6 +69,22 @@ require_contains "DOCS_INDEX.md" "## 7. 历史归档" require_contains "DOCS_INDEX.md" "docs/reports/historical/" require_contains "docs/architecture/README.md" "目标设计" require_contains "docs/architecture/README.md" "实际实现状态以源码、测试和根目录 \`CURRENT_STATUS.md\` 为准;\`PROJECT_PLAN.md\` 只描述目标和路线图" +require_contains "docs/architecture/README.md" "确定性 Binary hunk diff/apply" +if grep -Fq "bsdiff" docs/architecture/README.md; then + fail "docs/architecture/README.md still describes Binary Patch as bsdiff" +fi +require_contains "docs/architecture/README.md" "Rust \`bat\` 的 mock provider worker" +require_contains "docs/architecture/README.md" "**目标 Provider**" +require_contains "docs/architecture/README.md" "DeepL Provider" +require_contains "README.md" "mock/Crowdin provider worker" +require_contains "README.md" "Translation Memory、Glossary 和完整 Provider 扩展体系" +require_contains "PROJECT_PLAN.md" "正式 Rust \`bat\` CLI 和命令体系;Go 侧面向 \`bat-api\`、SDK 和服务集成发展" +if grep -Fq "Go CLI 主入口和命令体系" PROJECT_PLAN.md; then + fail "PROJECT_PLAN.md still presents Go CLI as the primary CLI" +fi +require_contains "docs/reports/historical/PARSER_FREEZE.md" "**状态**:历史记录,已解除" +require_contains "docs/reports/historical/PARSER_FREEZE.md" "**生效时间**:2026-07-30" +require_contains "docs/reports/historical/PARSER_FREEZE.md" "**解除时间**:2026-09-04" require_contains "docs/architecture/adr/0004-rust-bat-go-bat-api-resource-boundary.md" 'Rust `bat` 是官方资源生产者和状态拥有者' require_contains "docs/architecture/adr/0001-engine-and-application-boundaries.md" "资源同步职责已由 ADR 0004 取代" @@ -102,6 +119,23 @@ require_contains "CURRENT_STATUS.md" "不提供官方账号登录、游戏网关 if grep -Fq "响应只来自已发布 snapshot/RPC,不提供登录、网关、鉴权" CURRENT_STATUS.md; then fail "CURRENT_STATUS.md contradicts its documented bat-api token authentication" fi +if grep -Fq "ufw allow 5432/tcp" docs/guides/deployment.md || + grep -Fq "ufw allow 6379/tcp" docs/guides/deployment.md; then + fail "deployment guide recommends opening database ports" +fi +require_contains "docs/guides/deployment.md" "PostgreSQL 和 Redis 不是当前 \`bat\` / \`bat-api\` 的生产运行依赖" +require_contains "docs/guides/deployment.md" "私网、VPN 或 SSH tunnel" +require_contains "docs/guides/deployment.md" "尤其不得把 Redis 公网暴露作为推荐方案" +require_contains "deployments/docker-compose.remote-db.yml" '"127.0.0.1:5432:5432"' +require_contains "deployments/docker-compose.remote-db.yml" '"127.0.0.1:6379:6379"' +require_contains "deployments/docker-compose.dev.yml" '"127.0.0.1:5432:5432"' +require_contains "deployments/docker-compose.dev.yml" '"127.0.0.1:6379:6379"' +if grep -Fq '"0.0.0.0:5432:5432"' deployments/docker-compose.remote-db.yml || + grep -Fq '"0.0.0.0:6379:6379"' deployments/docker-compose.remote-db.yml || + grep -Fq '"0.0.0.0:5432:5432"' deployments/docker-compose.dev.yml || + grep -Fq '"0.0.0.0:6379:6379"' deployments/docker-compose.dev.yml; then + fail "database compose files still publish ports on all interfaces" +fi 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"