| name | excel-dev |
| description | ohmyflight 仓库内开发、修改或排查 Excel 读取、Excel 导出、表头映射、日期解析、批量导入、SheetJS/openpyxl 数据处理和相关测试时使用；尤其适用于修复日期偏移、Excel serial、JS Date 字符串泄漏、超链接导出、表格解析口径不一致等问题。 |
Excel 开发
在 ohmyflight 仓库处理 Excel 工具时使用本 skill。先读 AGENTS.md 和 .agents/skills/ohmyflight-dev/SKILL.md，再执行本文件约束。
核心原则
- 在 Excel 读取边界统一归一数据，不把原始单元格对象一路传到渲染、匹配或导出层。
- 日期必须按“业务日期”处理，不按 JavaScript
Date 的字符串表现处理。
- 表头、字段名、列名优先用结构化映射定位，不依赖示例文件名、固定 sheet 名或硬编码列号，除非 spec 明确要求。
- 导出给人工核对的 Excel 要保留必要上下文、异常说明和可点击超链接。
- 修改解析、日期、导出结构或业务口径时，先补核心测试，再改实现。
读取策略
浏览器 SheetJS 工具：
- 需要保留类型时，可以用
raw: true，但读取后必须立即把值转成业务层稳定类型。
- 需要显示预览时，可以用
raw: false, dateNF: 'yyyy-mm-dd'，但不能只靠显示文本完成核心规则判断。
- 使用
cellDates: true 时，Excel 日期单元格会变成 JS Date，不得直接 String(value)。
- 读取超链接时单独从单元格
cell.l.Target 或 HYPERLINK() 公式提取，导出时用真正的 hyperlink cell，不把多个链接拼成不可点击文本。
Python openpyxl 工具：
- 用
load_workbook(..., data_only=True) 读取业务值。
datetime 或 date 必须在读取边界格式化成 YYYY-MM-DD 或业务需要的格式。- 员工号、证件号、编号等字段要防止被 Excel 读成数字后丢前导零；读取后用专门的 normalize 函数处理。
日期策略
推荐实现一组小函数，不在业务逻辑里散落 new Date(...)：
isValidDate(value)：判断有效日期对象。makeLocalDate(year, month, day)：用本地中午构造日期，避免 UTC 和夏令时边界。excelSerialToDate(serial)：优先用 XLSX.SSF.parse_date_code(serial) 或明确的 Excel epoch 转换。parseDate(value)：只支持明确格式。formatDate(value)：统一输出 YYYY-MM-DD 或 spec 要求的格式。
解析顺序：
- 空值返回空。
Date 只取年月日，必要时处理 SheetJS 读出的 23:59:59.999 边界。- 数字在日期字段中按 Excel serial 处理。
YYYYMMDD 优先按 8 位日期处理，不能先当 serial。YYYY/M/D、YYYY-M-D、YYYY.M.D 按年月日处理。- 拒绝
5/11/26、11/5/26 这类地区歧义短日期，除非 spec 明确写明业务口径。
禁止：
- 禁止用
String(date)、模板字符串或隐式拼接输出 Date。
- 禁止依赖浏览器
new Date('2026/5/11')、new Date('5/11/26') 兜底解析。
- 禁止用
toISOString().slice(0, 10) 生成本地业务日期或文件名日期；中国时区早上 8 点前会变成前一天。
- 禁止把普通数字文本字段自动转日期；编号、员工号、金额、序号可能也是数字。
导出策略
- Excel 导出要明确单元格类型，文本字段用字符串，数值字段用数值，日期字段按业务确认格式输出。
- 多个可点击链接要拆成多列或多行，不能把显示文字简单拼接到一个不可点击单元格。
- 文件名日期使用本地年月日函数，例如
YYYY-MM-DD，不要使用 UTC ISO 日期。
- 导出结果需要人工核对时，保留来源行号、状态、说明和异常原因。
测试策略
Excel 日期相关修改至少覆盖：
- Excel
Date 对象输入。
- Excel serial 数字输入。
YYYYMMDD 字符串和数字输入。YYYY/M/D 或 YYYY-M-D 文本输入。- 歧义短日期应拒绝或按 spec 明确解析。
- 文本字段收到 Date 对象时不得输出
GMT、中国标准时间、Invalid Date。
- 普通数字文本字段不得被误转成日期。
表格解析和导出相关修改至少覆盖：
- 表头别名或字段名映射。
- 空行、缺列、异常值。
- 超链接读取和导出保持可点击。
- 导出 workbook 的 sheet 名、表头、关键单元格值和链接结构。
验证命令
先跑相关局部测试，再按 ohmyflight-dev 收尾要求运行：
npm.cmd run build
npm.cmd run typecheck
npm.cmd test
浏览器工具测试如果从 dist/ 读取脚本，改完 src/ 后必须先 npm.cmd run build 再跑对应 vitest。
