页面范围重命名计划¶
日期:2026-06-16
目标¶
将 doclib 中使用 pages 表示页码范围字符串的字段和参数重命名为 page_range。
这仅是一次命名清理。它不会更改 CLI 面向用户的 --pages 选项,也不会重命名 Middle JSON 的 pages。
命名规则¶
- CLI 选项仍为
--pages。 - 表示页码范围字符串的代码、接口和数据库字段应使用
page_range。 pages应保留给list[PageInfo]和 Middle JSON 数组:
- 不要引入
raw_page_range。 - 一个
page_range是原始输入还是规范存储,由层契约定义,而非字段名。
范围¶
数据库模式¶
重命名:
parses.pages->parses.page_rangeparsing_rules.pages->parsing_rules.page_range
由于 NEXT 仍在开发中,且没有兼容性负担,请直接更新 001_init.sql。不要为此重命名添加迁移脚本。
Doclib 类型与接口¶
重命名范围字符串字段:
ParseRequest.pages->ParseRequest.page_rangeParseResponse.pages->ParseResponse.page_rangeParseInfo.pages->ParseInfo.page_rangeTierParseInfo.pages->TierParseInfo.page_rangeParsingRuleRequest.pages->ParsingRuleRequest.page_rangeParsingRuleInfo.pages->ParsingRuleInfo.page_rangeDocContentRequest.pages->DocContentRequest.page_rangeDocContentExportRequest.pages->DocContentExportRequest.page_rangeContentRequestScope.pages->ContentRequestScope.page_rangeContentRange.pages->ContentRange.page_rangeContentNextRequest.pages->ContentNextRequest.page_range
Doclib 服务、服务器与客户端¶
重命名表示页码范围字符串的函数参数和局部变量:
request_parse(..., pages=...)->request_parse(..., page_range=...)request_pages_str->request_page_rangedefault_pages->default_page_rangeinitial_pages->initial_page_rangerule_pages->rule_page_rangeuncovered_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¶
保留公共选项:
在构造 doclib 请求时,将其映射到 page_range:
人类可读的 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.pagesPageInfo列表- 输出 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 范围字段时才需要调整它们。
执行顺序¶
- 更新数据库模式与行类型字典。
- 更新
doclib/types.py中的请求/响应模型。 - 更新
doclib/base.py、doclib/client.py和doclib/server.py中的签名与路由调用。 - 更新
doclib/services/parse_svc.py、config_svc.py、压缩及相关 SQL。 - 更新 CLI 请求构造与 JSON 输出。
- 更新测试。
- 全局搜索
pages,并对每个剩余匹配项进行分类。 - 更新文档。
- 运行针对性测试和 ruff。
验收标准¶
重命名后,剩余的 pages 用法应主要为:
- CLI 选项
--pages ParseResult.pagesPageInfo列表变量- 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
然后运行一次有针对性的全局检查:
所有剩余将 pages 用作范围字符串的用法,要么是有意面向用户的 CLI 措辞,要么应被重命名。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 mi/MinerU