中石油档案数据表格批量填写技能
概述
本技能把中石油档案项目的 卷内目录（Excel，每卷一个“数字表名”的工作表）批量转换为
中国石油档案系统 E6 批量导入数据（.xlsx 模板），自动填写其中两张核心表：
- 建设项目类-卷内件：逐件登记，每件一行。
- 建设项目类-卷：逐卷汇总，每卷一行。
建设项目类-件 工作表不填写（保持模板原样）。
模板中的全宗号、类别号、阶段号、项目代号、单项工程编号、归档单位等辅助表也保持原样。
输入
- 卷内目录（必需）：
.xls或.xlsx。每个“表名是数字”的工作表视为一卷，按数字升序处理。
表名识别具有容错性：自动去除首尾空格（如1）、兼容前导零（如01）；卷的数量不固定，3 卷、50 卷、200 卷均可处理。
表内结构（与 E6 导出格式一致）： - B 列第 2 行有“案卷题名”标签，其值在其右侧相邻列；
- M 列有项目信息块（项目名称 / 项目代号 / 单项工程名称 / 单项工程编号 / 单位工程名称 /
单位工程编号 / 归档单位 / 监理单位 / 设计单位 / 总承包单位 / 主项名称 / 立卷单位 / 阶段号 /
专业 / 改造次数），值在各自右侧相邻列； - 文件清单表头行含“序号”“文件材料题名”（或“题名”）等列，其下为逐件数据。
- 技能是否依赖卷内目录格式：是，但是“半结构化契约”——不依赖固定行号/列序，只要求下表结构
（详见「输入契约与模板使用」一节）。已实测兼容 V6.1 / V6.2 / V6.6 等多个版本。
对没有卷内目录的使用者，技能包references/目录内置两份底表： 卷内目录_填写模板_空白.xlsx——空白模板：表头、项目信息标签、自动生成公式列均在，数据已清空。他人使用时复制一份，按自己项目的数据填写即可；卷内目录_填写样例_V6.2.xlsx——填写样例（43 卷 / 320 件的真实数据），可对照查看“填完应该长什么样”。- E6 批量导入模板（可选）：缺省使用技能自带
assets/中国石油档案系统E6批量导入数据.xlsx。
该默认模板即 DES_建设项目类_GDSH_20261019142018.xlsx（E6 导出的新版模板，全宗号 GDSH），
自带「全宗号 / 类别号 / 阶段号 / 项目代号 / 单项工程编号 / 归档单位 / 专业」等辅助表；
旧版模板备份在同目录中国石油档案系统E6批量导入数据_旧版.xlsx，需要时用--template指定。
目标表按“列名”映射、不按列序：新版「卷内件」的列序与旧版不同（如题名在 D 列而非 F 列），
只要表头列名一致即可正确写入。 - 输出文件名：
中国石油档案系统E6批量导入数据{日期}-{序号}.xlsx（如…20261019-001.xlsx）。
输入契约与模板使用
1. 卷内目录格式契约（脚本对源文件的要求）
| 契约项 | 要求 | 容错性 |
|---|---|---|
| 工作表命名 | 每个卷对应一个工作表，表名必须是数字（1、2…43，表名即卷号） |
自动去首尾空格（1→1）、兼容前导零（01→1）；卷数任意；含清单表头但表名非数字的工作表告警跳过（防静默丢失） |
| 表头行 | 行号不固定，在前 50 行内自动查找「同时含 序号 + 文件材料题名/题名」的行（V6.x 在第 4 行） | 兼容“文件材料题名”/“题名”别名 |
| 清单列 | 按列名匹配，不依赖列序。必需：序号、题名；建议：日期、页数、保管期限、页号、文件编号、责任者、电子关联 | 缺非必需列时对应字段留空并告警，不崩溃 |
| 案卷题名 | 标签「案卷题名」右侧相邻单元格（兼容带换行的 案卷\n题名） |
|
| 卷级汇总 | 不依赖源里的“件数/总页数/起止日期”汇总块——一律由明细行重算（件数=最大序号、页数=各件页数和、起止=最早/最晚日期） | 源“总页数”字段与求和不符时告警，采用求和值 |
| 项目信息 | 标签右侧相邻值（如 M 列标签、N 列值）；优先本卷表，回退独立「项目信息」表（A 列标签→B 列值） | 占位符（XXXX…/待填）视作未填，留空 |
| 电子文件关联项 | 取自卷内目录「电子关联」列（由“地址”单元格 + 公式自动生成完整路径） | 纯占位串、无盘符的断裂路径（\…）会被拦下并告警；含 XXXX 但结构完整的路径保留 |
2. 他人使用：从空白模板开始（推荐流程）
① 复制技能包 references/卷内目录_填写模板_空白.xlsx → 另存为"我的项目卷内目录.xlsx"
② 用 Excel / WPS 打开，按自己项目填写：
- 每个数字表 = 一卷（表名即卷号；不需要的表删掉，不够的复制表改数字名）
- 清单区（第 5 行起）：序号 / 文件编号 / 责任者 / 文件材料题名 / 日期 / 页数 / 保管期限 逐件填写
- 右上角：填写“地址”（电子文件实际根目录，如 D:\我的项目\…）、“案卷题名”
- 项目信息块：项目名称 / 项目代号 / 单项工程名称 / 编号 / 单位工程名称 / 编号（没有的留空即可）
- “页号 / 止页码 / 原文件名 / 电子关联”等列为公式，填完数据后自动生成，勿手改
③ 保存（务必经 Excel/WPS 保存，让公式列重算出缓存值）
④ 运行本技能生成 E6 批量导入数据
> ⚠️ 必须用 Excel / WPS 填写并保存：脚本按公式缓存值读取「页号 / 电子关联」等公式列，
> 用代码工具（如 openpyxl）直接改数据不会重算公式，会导致这些列为空。
> 空白模板中各表“地址”（R1）已清空，填写后「电子关联」才会生成完整路径；
> 若忘填地址，运行时会告警提示多少条电子文件关联项因断裂路径未写入。
3. 对照样例
references/卷内目录_填写样例_V6.2.xlsx 是填好的真实样例（43 卷 / 320 件，桩基工程），
可直接运行本技能复现结果，用于核对“填成什么样算合格”。
工作流程
- 载入卷内目录，找出所有“数字表名”工作表（容错：去空格、兼容前导零）并升序排序（一卷一表）。
对“含文件清单表头但表名非数字”的工作表，明确告警并跳过（不会静默丢数据）；卷号重复也告警。 - 对每个卷：
a. 定位文件清单表头，提取逐件数据（序号、文件编号、责任者、题名、日期、页号、保管期限、页数）。
b. 计算卷级汇总：起日期=最早日期，止日期=最晚日期，件数=最大序号，
页数=各件页数之和，保管期限=最长值（永久 > 30年/长期 > 10年/短期）。
c. 读取“案卷题名”（标签右侧列）。
d. 读取项目信息：先在当前卷表的项目信息块取值；为空则回退到独立的“项目信息”工作表。
e. 向“建设项目类-卷内件”写入该卷全部件行。
f. 向“建设项目类-卷”写入该卷汇总行。 - 保存为命名规则指定的输出文件。
字段映射
卷内件（建设项目类-卷内件）
| 目标列 | 来源 | 说明 |
|---|---|---|
| 卷序号 | 卷内目录表名（数字） | 同卷统一 |
| 临时序号 | 卷内目录各表的“序号” | |
| 文件编号 | 文件编号 | 1:1 对应 |
| 责任者 | 责任者 | 1:1 对应 |
| 题名 | 文件材料题名（别名“题名”） | |
| 文件日期 | 日期 | 兼容“真日期”与文本型日期（如 2020/10/19、2020-10-19、2020年10月19日） |
| 页号 | 页号 | 1:1 对应 |
| 保管期限 | 保管期限 | 1:1 对应 |
| 密级 | 固定值 | 无密级 |
| 保密期限 | 固定值 | 空 |
| 载体类型 | 固定值 | 纸质 |
| 电子文件关联项 | 卷内目录“电子关联”列（完整路径） | 1:1 对应，如 D:\项目\...\1-内封面-P1.PDF |
| 电子文件数量 | 不填 | 按用户要求留空 |
| 单项工程名称 | 项目信息·单项工程名称 | 同卷统一，写为字面值 |
| 单项工程编号 | 项目信息·单项工程编号 | 同上 |
| 单位工程名称 | 项目信息·单位工程名称 | 同上 |
| 单位工程编号 | 项目信息·单位工程编号 | 同上 |
> 备注、来源、数量、电子文件数量 等列保持模板原有公式/留空，不额外填写。电子文件关联项（取自卷内目录“电子关联”列的完整路径）现已填写；卷表（建设项目类-卷）的“电子文件关联项”按用户要求保持为空。
> 关于单项工程/单位工程 4 列：模板本身用 INDIRECT 公式按“卷序号”自动取数，但直接交 E6 导入时若未经 Excel 重算会为空，故此处改写为字面值，保证导入文件自包含、不依赖公式重算。
卷（建设项目类-卷）
| 目标列 | 来源 |
|---|---|
| 序号 | 卷内目录表名（数字） |
| 临时序号 | 卷内目录表名（数字） |
| 题名 | “案卷题名”标签右侧列内容 |
| 起日期 | 该卷最早日期 |
| 止日期 | 该卷最晚日期 |
| 密级 | 无密级 |
| 保密期限 | 空 |
| 载体类型 | 纸质 |
| 保管期限 | 该卷保管期限最长值 |
| 件数 | 序号最大值 |
| 页数 | 各件“页数”列之和（确定性求和，不直接采用源“总页数”公式字段） |
| 项目名称 / 项目代号 / 单项工程名称 / 单项工程编号 / 单位工程名称 / 单位工程编号 / 归档单位 / 监理单位 / 设计单位 / 总承包单位 / 主项名称 / 立卷单位 / 阶段号 / 专业 / 改造次数 | 项目信息（优先本卷表，回退“项目信息”表） |
已确认的设计决策（用户拍板，长期有效）
- 项目信息残缺可不填：项目信息字段（名称/代号/单位工程等）在源文件中缺失、为空、或仅为占位符（如
XXXX单位工程、XX、待填）时，一律视作“未填写”而留空，不强行编造。脚本已内置占位符识别，写 E6 时不填这些列。 - 单位工程名称不从案卷题名中提取：单位工程名称/编号、单项工程名称/编号一律只取自源文件自身的“项目信息”块（或独立“项目信息”表），绝不从“案卷题名”反推拼凑（案卷题名描述的是不同子项，反推会引入错误）。
- “2 件”卷无需合并：每一个“数字表名”的工作表即为一卷，各卷独立成卷、互不合并；即便某卷只有 2 件（或少件、多件），也保持一表一卷原样输出。
用法
python scripts/fill_e6.py --source <卷内目录.xlsx> [--template <E6模板.xlsx>] \
[--output <输出.xlsx>] [--date 20261019] [--seq 001]
参数：
- --source：卷内目录文件（必填，支持 .xls/.xlsx）。
- --template：E6 模板路径，缺省用技能自带 assets/ 模板。
- --output：输出路径，缺省在源文件同目录生成 中国石油档案系统E6批量导入数据{日期}-{序号}.xlsx。
- --date：日期戳 YYYYMMDD，缺省取当天。
- --seq：序号批次号，缺省 001。
依赖
openpyxl（读/写 .xlsx，必需）。xlrd（仅当源文件为.xls时需要）：pip install xlrd。
注意事项与边界
- 工作表数量不固定：脚本遍历源文件全部工作表，凡是“表名是数字”的即视为一卷，故卷数可变（3、50、200 均可）；非数字表（如“项目信息”）被忽略或仅作回退数据源。
- 表名容错与防静默丢失：表名首尾空格会被自动去除（
1→ 1），前导零兼容（01→ 1）。若某工作表“含文件清单表头但表名非数字”（如卷1、第1卷、卷一），脚本会打印告警并跳过该表，提示用户将其重命名为数字——避免数据被悄悄漏掉；卷号重复（如同时有1与01）同样会告警。 - 表头兼容别名：题名列兼容“文件材料题名”与“题名”；保管期限兼容“保管期限”与带换行变体。
- 若某卷未识别到文件清单表头，则该卷被跳过并提示。
- 模板中“单项工程名称/编号/单位工程名称/编号”等列自带 INDIRECT 公式，但本技能已改写为字面值写入（见上表），保证未经过 Excel 重算也能直接导入 E6。
- 日期兼容真日期与文本型日期（
2020/10/19、2020-10-19、2020年10月19日等），避免文本日期被漏填。 - 卷页数字段是公式且可能错列，不直接采用：卷内目录右上角的“总页数”常为
=MAX(L5:L110)这类公式，部分模板甚至引用了“止页码”列（L）而非“页数”列（K），其缓存值还会随 Excel 重算漂移。因此卷的“页数”一律按各件“页数”列确定性求和得到（可复核）；若源文件自带的“总页数/件数”字段与计算值不一致，运行时会打印告警提示，但不覆盖计算值。 - V6.1“单位工程”版变体已验证兼容：该版案卷题名标签为带换行的
案卷\n题名（已兼容）、项目信息块标签在 M 列、值在 N 列；其项目信息仅含 6 个字段（项目名称/项目代号/单项工程名称/编号/单位工程名称/编号），不含 归档单位/监理单位/设计单位/总承包单位/主项名称/立卷单位/阶段号/专业/改造次数，故 E6“卷”表中这些列将留空（符合“无匹配标题不填”约定）。如需这些列也有值，须另提供来源或补全卷内目录。 - 目标模板列完整性校验：载入模板后会核对「卷内件」（16 列）与「卷」（26 列）应有列是否齐全，
缺列时明确告警列出缺失列名（防静默丢失）；齐全时打印确认信息。 - 电子文件关联项护栏：该列值若为纯占位串（如
XXXX）或无盘符的断裂路径（\…，通常是卷内目录
“地址”单元格未填），将留空并在结束时统一告警条数；含XXXX但结构完整的路径（样例文件的脱敏写法）会保留。 - 公式列依赖缓存值：脚本以
data_only=True读取源文件，「页号 / 止页码 / 电子关联」等公式列取的是
Excel 上次保存时的缓存值。因此卷内目录必须用 Excel/WPS 填写并保存后再运行本技能；
用程序（如 openpyxl）改数据不会重算公式，会导致这些列读为空。 - 不修改模板的辅助表（全宗号、类别号、阶段号、项目代号、单项工程编号、归档单位、专业）。
