flight-portal-probe

name	flight-portal-probe
description	IEB/飞行门户专用 Playwright 探测和批量自动化流程，覆盖人工扫码登录、资质管理/飞行训练/技术资料/资料管理入口、员工号逐人查询、个人技术等级和运行资格表格、跨 frame 与 rowspan/colspan 解析、样例核对、Excel 逐人即时写回、中断恢复和证据留存。用户提到 https://ieb.csair.com、飞行门户、员工号查询、技术等级、运行资格、区域航线资格、单飞资质、录制脚本稳定化或相关 Python 自动化时使用。

飞行门户探针

以用户当次录制路径和真实页面为第一事实，以仓库成熟脚本为实现基线。先探测、再小样本核对、最后批量；页面没有被真实读取前不猜 DOM、表头或业务规则。

先看现有实现

• 技术等级/运行资格：public/tool/app/qualification-query-helper/app.py
• 飞行经历查询循环：public/tool/app/flight-stats-helper/app.py
• 其他浏览器接管模式：public/tool/app/lock-entry-helper/app.py、public/tool/app/oa-read-helper/app.py
• 技术资料 DOM 和表格详情：references/technical-materials.md

涉及 Excel 日期、员工号、表头或导出时同时使用 excel-dev。

固定执行顺序

1. 启动 headless=False 浏览器，先进入登录页。
2. 点击 #scanLogin，等待人工扫码；自动等待失败时保留浏览器并允许人工完成。
3. 进入目标业务页面并证明搜索框或目标容器已可用。
4. 页面就绪后才提示或读取 Excel 路径。登录、菜单或页面未就绪时，不创建结果文件。
5. 用 1 至 3 个用户已知样例探测：保存页面截图、主 frame/子 frame HTML、可见文本和简短结构摘要。
6. 按表头和同行单元格定义抽取规则，向 owner 说明筛选列、读取列和日期口径。
7. 样例逐字段一致后才批量。每处理一人立即追加明细、写处理报告并保存关闭 workbook。
8. 结束时输出总数、成功、失败、输入错误和是否中断；清理临时探针，不删除用户输入和最终结果。

已验证入口

page.goto("https://ieb.csair.com/login")
page.locator("#scanLogin").click()
# 人工扫码后进入首页
page.goto("https://ieb.csair.com/index/index")
page.get_by_text("资质管理").nth(1).click()
page.get_by_text("飞行训练").nth(1).click()
page.get_by_role("link", name="技术资料").click()
page.get_by_role("link", name="资料管理").click()
page.get_by_role("textbox", name="员工号或姓名简拼").wait_for(state="visible")

用户录制脚本可能直接点击两次“飞行训练”。先复现用户路径；成熟脚本可为入口准备多个真实候选 locator，但不能在没到达页面时假定成功。

单人查询闭环

1. 获取 textbox，执行 click()、fill("")，再 type(emp_id, delay=20)。
2. 点击“查询”，等待 name=emp_id, exact=True 的员工号链接。
3. 在结果同行读取页面姓名，点击精确员工号链接。
4. 读取“技术等级”和“运行资格”两个标签页；标签或容器慢加载时等待并重试一次。
5. 校验结果员工号属于当前查询人；输入提供姓名时，同时记录姓名一致性，不用姓名替代员工号主校验。
6. 点击 .pilotInfo-dialog-close 关闭弹窗，确认回到列表页，再查询下一人。

不要每人重新进入首页；不要只 fill(emp_id) 而省略清空；不要用非精确员工链接；不要在弹窗未关闭时开始下一人。

表格解析

技术等级容器：#qualList。

运行资格容器：#showSingleEmpOperQualList。

容器可能位于任一 frame。遍历 page.frames 查找容器，不把主 frame 当作固定事实。页面通常把表头和数据拆成两个 table；按表头构造数据对象，不按固定列号写业务判断。

解析必须把 rowspan 和 colspan 展开成规则网格。运行资格“类型”常使用 rowspan，延续行必须继承类型，不能因当前 td 为空而整体错列。

标签页读取后检查必需表头集合。表头异常时保存证据并失败，不用旧列位置继续抓取。

Excel 与中断

• 输入至少包含“员工号”或“工号”，姓名可选。员工号按文本处理并校验格式，重复员工只处理一次并记录输入错误。
• 页面成功后才创建结果 workbook。
• 每个人独立 try/finally；无论成功失败都尝试关闭个人弹窗。
• 每人完成后重新打开 workbook、追加、保存、关闭。失败也写员工号、状态、错误、时间。
• Excel/WPS 占用导致 PermissionError 时明确提示关闭文件，不覆盖原始输入。
• 遇到 Target page, context or browser has been closed 立即中断循环，不给剩余人员批量写同一错误。
• KeyboardInterrupt 保留已写结果并在汇总标记中断。

业务规则边界

门户抓取层只输出页面事实，不内置业务筛选。固定代码、机型、资格名称和日期窗口只能来自用户当前明确规则，并以 hook/筛选函数注入。

已验证过的 777 责任名单口径记录在 references/technical-materials.md，仅供同类任务复用；它不是所有门户任务的默认规则。录制脚本中的 CAPT、CAPB、员工号或页面示例也不能成为全集特判。

失败证据

以下任一情况先保存截图、相关 frame HTML、可见文本和当前员工号，再判断失败：

• 搜索后没有精确员工号链接。
• 员工号或姓名与当前结果不一致。
• 标签点击后容器未出现。
• 容器 table 数量或必需表头异常。
• 表格为空但页面看似有数据。
• 页面关闭、登录失效或菜单状态丢失。

不能仅凭截图猜表格值；能读取 DOM 时以 DOM 和结构化行列为准。