跳转至

页面范围重命名计划

日期:2026-06-16

目标

将 doclib 中使用 pages 表示页码范围字符串的字段和参数重命名为 page_range。

这仅是一次命名清理。它不会更改 CLI 面向用户的 --pages 选项,也不会重命名 Middle JSON 的 pages。

命名规则

  • CLI 选项仍为 --pages。
  • 表示页码范围字符串的代码、接口和数据库字段应使用 page_range。
  • pages 应保留给 list[PageInfo] 和 Middle JSON 数组:
{
  "pages": []
}
  • 不要引入 raw_page_range。
  • 一个 page_range 是原始输入还是规范存储,由层契约定义,而非字段名。

范围

数据库模式

重命名:

  • parses.pages -> parses.page_range
  • parsing_rules.pages -> parsing_rules.page_range

由于 NEXT 仍在开发中,且没有兼容性负担,请直接更新 001_init.sql。不要为此重命名添加迁移脚本。

Doclib 类型与接口

重命名范围字符串字段:

  • ParseRequest.pages -> ParseRequest.page_range
  • ParseResponse.pages -> ParseResponse.page_range
  • ParseInfo.pages -> ParseInfo.page_range
  • TierParseInfo.pages -> TierParseInfo.page_range
  • ParsingRuleRequest.pages -> ParsingRuleRequest.page_range
  • ParsingRuleInfo.pages -> ParsingRuleInfo.page_range
  • DocContentRequest.pages -> DocContentRequest.page_range
  • DocContentExportRequest.pages -> DocContentExportRequest.page_range
  • ContentRequestScope.pages -> ContentRequestScope.page_range
  • ContentRange.pages -> ContentRange.page_range
  • ContentNextRequest.pages -> ContentNextRequest.page_range

Doclib 服务、服务器与客户端

重命名表示页码范围字符串的函数参数和局部变量:

  • request_parse(..., pages=...) -> request_parse(..., page_range=...)
  • request_pages_str -> request_page_range
  • default_pages -> default_page_range
  • initial_pages -> initial_page_range
  • rule_pages -> rule_page_range
  • uncovered_str -> uncovered_page_range

重命名辅助函数:

  • expand_pages() -> expand_page_range()
  • _pages_set_to_str() -> _page_numbers_to_range_str()
  • pages_covered() -> page_range_covered()
  • pages_uncovered() -> page_range_uncovered()

parse_range_set() 在将页码范围字符串解析为从 1 开始的页码时,应变为 parse_page_range_set()。

CLI

保留公共选项:

pages: str | None = typer.Option(None, "-p", "--pages", ...)

在构造 doclib 请求时,将其映射到 page_range:

ParseRequest(page_range=pages)

人类可读的 CLI 文本如果对用户更清晰,可以继续打印 pages=...。JSON 输出应优先使用 page_range。

解析器 SDK 与 V1 API

无需重大重命名:

  • DocumentParser.parse(page_range=...) 已经是正确的。
  • MinerUApiParser 已经使用 page_range。
  • v1 API 已经使用 files[].page_range。
  • api_server.py 应继续使用 page_range。

不要重命名 Middle JSON:

  • ParseResult.pages
  • PageInfo 列表
  • 输出 JSON { "pages": [...] }

测试

更新引用页码范围字段的测试:

  • ParseRequest(..., pages=...) -> ParseRequest(..., page_range=...)
  • result.pages == "1~10" -> result.page_range == "1~10"
  • 针对 parses.pages 的数据库插入/查询改为 parses.page_range
  • 针对 parsing_rules.pages 的数据库插入/查询改为 parsing_rules.page_range

不要修改那些 pages 为 list[PageInfo] 或 Middle JSON 键的测试。

文档

更新 docs/next 下描述 doclib/接口字段的文档:

  • 将范围字符串 pages 字段替换为 page_range
  • 保留使用 --pages 的 CLI 示例
  • 说明 CLI 的 --pages 映射到请求字段 page_range

docs/next/api/ 下的统一 API 文档已针对 v1 解析任务使用 page_range。仅当其中出现 doclib 特有的 pages 范围字段时才需要调整它们。

执行顺序

  1. 更新数据库模式与行类型字典。
  2. 更新 doclib/types.py 中的请求/响应模型。
  3. 更新 doclib/base.py、doclib/client.py 和 doclib/server.py 中的签名与路由调用。
  4. 更新 doclib/services/parse_svc.py、config_svc.py、压缩及相关 SQL。
  5. 更新 CLI 请求构造与 JSON 输出。
  6. 更新测试。
  7. 全局搜索 pages,并对每个剩余匹配项进行分类。
  8. 更新文档。
  9. 运行针对性测试和 ruff。

验收标准

重命名后,剩余的 pages 用法应主要为:

  • CLI 选项 --pages
  • ParseResult.pages
  • PageInfo 列表变量
  • Middle JSON { "pages": [...] }
  • 普通行文中 pages 表示文档页面

以下内容不再使用 pages 来表示页码范围字符串:

  • 数据库 parses
  • 数据库 parsing_rules
  • doclib 接口请求/响应模型
  • 解析批次记录
  • 覆盖范围字段
  • 内容请求范围
  • 内容范围
  • 内容续接 next_request

验证

至少运行以下命令:

.venv/bin/python -m pytest -o addopts='' tests/unittest/test_doclib_interface_contract.py tests/unittest/test_doclib_cache_semantics.py tests/unittest/test_cli_next_command_design.py -q
.venv/bin/python -m ruff check mineru/doclib mineru/cli_next tests/unittest/test_doclib_interface_contract.py tests/unittest/test_doclib_cache_semantics.py tests/unittest/test_cli_next_command_design.py

然后运行一次有针对性的全局检查:

rg -n "\\bpages\\b" mineru/doclib mineru/cli_next tests docs/next

所有剩余将 pages 用作范围字符串的用法,要么是有意面向用户的 CLI 措辞,要么应被重命名。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 mi/MinerU