02-技术-制度原件检索口径体检与刷新SOP
> 阶段：02 技术（流程）｜版本 v1.0｜固化日期 2026-10-16
> 一句话：方案 B 之后制度权威源只有 Word 原件；先用只读体检判定"是真缺口还是口径误判"，确认后再 --apply 写库。
一、适用场景
- 制度检索为空、或"索引 N 条 vs 源 M 份对不上"，需要判定是否真漏登记。
- 制度文件批量增删、版本升版、跨机迁移之后的一致性体检。
- 备份清单里出现
docs_files=0 / word_dirs=0，怀疑制度源丢失。
二、操作步骤
- 先定口径（这一步决定后面所有判断）：
- 权威源 =config.WORD_LIB（即客户数据源）下的 Word 原件；
-db.seed_inst_docs()（db.py:362-386）按制度编号 upsert，把绝对路径写进documents.source_path；
- 取真实路径db.doc_real_path()（db.py:335-339）：绝对路径直接用，相对路径才拼DOCS_ROOT。 - 记住旧口径遗留：
DOCS_ROOT=制度文档/extracted是方案 B 之前的产物目录，
为空或不存在完全不影响检索——不要据此判故障，更不要去改配置。 - 只读体检（默认不改库）：
python tools/inst_extract.py # 体检 python tools/inst_extract.py --db <快照里的 hfms.db> # 线上库被占用/沙箱受限时
-inst_extract.py:40-45扫原件 → 域目录数与编号数；
-inst_extract.py:66-112三向比对：待新增（原件有、库里无）、路径失效（登记了但文件没了）、无可指原件；
-inst_extract.py:100-107按域输出「原件数 / 已登记 / 待新增」明细。 - 口径先自查（可选，不开库）：
scripts/inst_guard_check.py打印 WORD_LIB 在位情况、域目录与编号数、
以及DOCS_ROOT为空属预期的提示。 - 确认有缺口才写库：
python tools/inst_extract.py --apply（inst_extract.py:48-64）
→ 调seed_inst_docs()，随后打印documents行数 / 空路径行数 / 路径失效行数。 - 比对基准态：2026-10-15 实测基准 = 10 域 / 75 编号 / documents 76 行 / 待新增 0 / 路径失效 0。
与基准偏离即需人工确认是新增制度还是路径搬移。 - 结论句：无缺口时工具直接打印「登记与原件已一致，无需重跑抽取」（
inst_extract.py:109-110）——不要例行重跑。
三、注意边界
--db的赋值必须发生在import config之前（inst_extract.py:27-29），否则环境变量不生效。seed_inst_docs()是 upsert 幂等的，重复执行不会灌重复行；但也不要把它当日常任务跑。- 线上库被占用或沙箱禁写时，用
--db指向备份快照里的hfms.db，不要直接开线上库。 - 备份 MANIFEST 里
docs_files=0 / word_dirs=0不是故障，是口径遗留；真正的风险是
制度 Word 原件本身不在快照覆盖范围内（另行决策，不属本流程）。
四、反例避雷
- ✗ 见
docs_files=0就去改DOCS_ROOT→ 2026-10-15 已定口径，属旧路径遗留；改配置不但无益还会误判制度检索故障。 - ✗ 不加
--db直接跑体检 → 线上库被占用/沙箱拦截时打开失败，工具只给提示就退出，容易被误读成"检索坏了"。 - ✗ 一上来就
--apply→ 没看体检明细就写库，掩盖了"路径失效"这类真问题。 - ✗ 把 76 vs 140 的差直接当漏登记 → 先做口径分解（备份副本 / 域内参考稿 / 域汇编都计入递归全量），
详见05-测试-制度索引覆盖核对SOP。 - ✗ 在服务器上另建一份制度副本当权威源 → 违反一数一源；权威源只能是 Word 原件目录。
五、代码锚点 / 实战战绩
锚点：
- 程序源代码/tools/inst_extract.py:21-29（main / --apply / --db 与 env 前置）、
40-45（扫原件）、48-64（写库与统计）、66-112（只读三向比对）、109-110（结论句）
- 程序源代码/db.py:335-339（doc_real_path）、362-386（seed_inst_docs）
- 程序源代码/config.py：WORD_LIB、DOCS_ROOT
- 程序源代码/instlib.py：word_map(refresh=True)（域目录与编号识别）
战绩：
- 2026-10-15 实测确认权威源口径：WORD_LIB 在位，检索直读原件绝对路径；DOCS_ROOT 为空不影响检索。
基准态 10 域 / 75 编号 / documents 76 行 / 待新增 0 / 路径失效 0。
- 2026-10-16 scripts/inst_guard_check.py 首跑 PASS：10 域 / 75 份，与基准态一致。
六、关联笔记
05-测试-制度索引覆盖核对SOP：讲"索引 vs 源"的覆盖核对与召回抽样；本技能讲"登记 vs 原件"的体检与刷新，两者互补。03-设计-一数一源架构原则：权威源唯一的依据。06-成品-跨机数据迁移先校验后写入SOP：迁移后用本技能做一次登记体检。
七、版本记录
- v1.0（2026-10-16）：首版。口径定义 + 只读体检 +
--apply写库 + 基准态 + 只读口径自检脚本，附五条反例。
