alert-contract-expiring-hr/development/REQUIREMENTS.md

合同到期智能预警与续聘辅助 — 技能需求文档

派生自匠厂 skill-template 主仓 development/REQUIREMENTS.md，对应规格书第 4.2 节「🟡 人事处 Skill 002 —— 合同到期"智能预警与续聘辅助"」。

---

0. 技能标识

• 拟定 slug（英文）：alert-contract-expiring-hr
• 中文 name：合同到期智能预警与续聘辅助
• 中文 description（一句话）：每日凌晨扫描全校教职工合同电子台账，对距离到期日 90/60/30 天的合同分级预警，并自动生成《续聘准备任务书》和《本月合同到期人员清单》
• account-manager platform_key（如有）：N/A
• 命名形态：标准型（动词-名词-部门缩写）
• 目标 OEM 市场 brands（可选）：未写则发布后仅挂匠厂（jiangchang）
• 网页 RPA（如有）— 登录策略：不适用（本技能不涉及网页 RPA）

0.1 宿主入口定位（必填）

主能力（Action id / CLI）	对话	数据管理	定时	教程章节	不挂理由
health / version / config-path	挂	不挂	不挂	入口二	默认必备
scan-expiring-contracts	挂	toolbar（合同台账）	挂（每日凌晨 02:00）	入口一/入口二/入口三	真用 cron
generate-renewal-task	挂	row（合同台账）	不挂	入口一/入口二	sync
dispatch-task-notice	挂	batch（合同台账/预警记录）	不挂	入口一/入口二	sync
mark-contract-renewed	不挂	row（合同台账）	不挂	入口一	写状态，不需 Agent
render-html	挂	skill-detail	不挂	入口二	HTML 报告预览

0.1.1 用户市场文档（与入口表一致）

• README.md（说明 Tab）：能力 / 场景 / 边界
• TUTORIAL.md（教程 Tab）：覆盖三入口（数据管理 / 对话 / 定时）
• 入口三已写「已启用定时扫描」，与本表一致

0.2 AI + RPA 协作与授权边界

Agent 设计

• 用户会怎样描述本任务：「张老师的合同什么时候到期？」「本月一共要办多少份续聘？」「帮我扫描一下全校合同到期」
• 支持的用户意图 → Action 映射：
  • 触发扫描 → scan-expiring-contracts
  • 给某教师生成任务书 → generate-renewal-task
  • 下发单位清单 → dispatch-task-notice
  • 标记已续签 → mark-contract-renewed
  • 预览任务书 → render-html
• 每种意图必须提取的参数：contract_id / unit_id / month / material_id
• 缺少参数时必须追问：「请告诉我教师姓名 / 工号 / 合同 ID」
• 哪些动作必须先展示对象、数量和影响，再取得明确确认：
  • mark-contract-renewed 状态变更（确认行 + 续签材料）
  • dispatch-task-notice 提示将推送至 N 位人事秘书
• Agent 最终如何解释成功、部分成功、失败、等待人工和停止：
  • 成功：「已扫描全校 X 份合同，发现 Y 份 90 天内到期，其中 Z 份 30 天红色预警」
  • 部分成功：「已完成扫描，但 N 位教师的考核数据缺失，已标记为数据待补」
  • 失败：「人事系统 API 调用失败（错误码 XXX），已停止扫描并保留上一次的预警记录」

授权与平台边界

• 目标浏览器 / 桌面软件 / 手机 App：N/A（本技能不涉及 RPA）
• 账号、设备、数据和业务权限由谁授权：人事处统一授权；考核 / 师德数据由党委教师工作部统一开通
• 是否有获得授权的官方 API：人事系统 API（合同台账）、党委教师工作部 API（考核 + 师德）、企业微信推送 API（教师与人事秘书通讯）
• 目标平台规则、合同或客户约定中的自动化边界：不得越权读取非本校教职工数据；不得向教师个人透露 AI 续聘建议（仅单位版清单展示）
• 明确禁止的实现路线：所有破解 / 反编译 / 逆向 / 私有协议 / 抓包拼隐藏接口 / Hook 或注入 / 验证码破解 / 设备指纹伪造 / 自动换号 均禁止
• 正常界面无法闭环时的上报与停止条件：人事系统 API 不可用超过 60 分钟 → 停止扫描并向人事处合同管理员上报

RPA 风控设计

• 执行端：N/A

0.3 业务行生命周期

本技能对「合同台账」表中的每一份合同，遵守 references/WORK_ITEM_STATUS.md 角色约束：

角色	本技能状态值	说明
可操作（operable）	可续聘	默认唯一可被 scan-expiring-contracts 捞起
进行中（in_progress）	预警中（黄/橙/红）	抢占后、结束前
成功类终态	已续签	人事处确认续签材料齐全
失败类终态	已驳回 / 已过期	默认不可再处理；失败原因字段：驳回理由 / 过期说明
跳过类终态	已撤回	教师或单位主动撤回续聘申请

重做靠人工将"已续签 / 已驳回 / 已过期"改回"可续聘"，不靠 AI 自动覆盖。

---

1. 文档目标

本文档用于明确 alert-contract-expiring-hr 的研发范围、交付标准、依赖关系和验收要求。

2. 业务背景

当前用户在「全校教职工合同管理」场景中：

• 现状：人事处合同管理员每月需人工翻查 1000+ 份合同，年度考核结果出后才仓促通知续签
• 痛点：
  • 效率低：1 份合同的预警与材料准备需人工 2~3 小时
  • 容易遗漏：试用期合同、跨年度合同尤其容易漏检
  • 劳动纠纷风险：合同逾期未续签导致劳动争议
  • 年终突击：每年 12 月人事处集中突击签合同，工作量暴增
• 目标：自动完成「合同到期扫描 + 三级预警 + 任务书预填 + 单位清单派发」，输出「个人版任务书 + 单位版清单 + 预警通知」

3. 开发目标

• 解析合同电子台账（含合同类型、起止日期、聘任岗位、试用期）
• 拉取教师近 3 年年度考核结果 + 师德师风考评记录
• 按距到期日 90/60/30 天分级，触发三级预警
• 自动生成个人版《续聘准备任务书》（含业绩摘要 + AI 续聘建议 + 材料清单）
• 自动生成单位版《本月合同到期人员清单及续聘建议》
• 30 天红色预警自动抄送分管校领导
• 写入业务表（合同台账 / 预警记录 / 续聘任务 / 派发日志）
• 支持失败可诊断（稳定错误码 + 中文 message）
• 完成 CLI 入口与 health / version / init-db 最小可运行验证
• 完成正式环境发布与安装验证

4. 功能范围

必须实现

• 支持 python scripts/main.py health / version / config-path / init-db
• 支持 python scripts/main.py scan-expiring-contracts --thresholds 90,60,30（async）
• 支持 python scripts/main.py generate-renewal-task --contract-id <id>
• 支持 python scripts/main.py dispatch-task-notice --unit-id <id> --month <YYYY-MM>
• 支持 python scripts/main.py mark-contract-renewed --contract-id <id> --material-id <id>
• 支持 python scripts/main.py render-html --task-id <id>
• 完成 §0.1 入口定位表，并按表落实已挂入口
• 定时任务接入宿主 cron 调度系统

可后续扩展

• 试用期合同不通过的特殊处理流程
• 续聘材料 OCR 自动归档
• 多语言合同（中英双语）支持

5. 非功能要求

• 目录结构必须符合当前 skill-template 规范
• 入口必须统一为 scripts/main.py
• 用户市场四 Tab 写在根 README.md / TUTORIAL.md / DEMO.md / CHANGELOG.md
• 输出格式应尽量机读友好；错误前缀统一为 ERROR:
• Windows 环境下需保证 UTF-8 输出兼容
• 必须具备基本日志能力；敏感字段脱敏（教师身份证号、银行卡号等不写入日志）
• 全校 1000+ 份合同扫描耗时 ≤ 2 分钟

6. 输入输出要求

输入

• contract_id：合同主键（必填，字符串）
• unit_id：二级单位主键（仅 dispatch-task-notice 必填）
• month：月份（仅 dispatch-task-notice 必填，格式 YYYY-MM）
• material_id：续签材料 ID（仅 mark-contract-renewed 必填）
• thresholds：扫描阈值（默认 90,60,30，可配置）
• 依赖系统：
  • 人事系统 API：合同电子台账
  • 党委教师工作部 API：考核 + 师德数据
  • 企业微信推送 API：教师与人事秘书通讯
• 环境变量（.env）：
  • HR_API_BASE_URL：人事系统 API 入口
  • HR_API_TOKEN：调用凭证
  • TEACHER_AFFAIRS_API_BASE_URL：党委教师工作部 API 入口
  • TEACHER_AFFAIRS_API_TOKEN：调用凭证
  • WECOM_API_BASE_URL：企业微信 API 入口
  • WECOM_API_TOKEN：调用凭证

输出

• 成功结果：scan-expiring-contracts 返回结构化 JSON {scanned_count, alert_yellow_count, alert_orange_count, alert_red_count, generated_task_count}
• 错误输出：ERROR: 稳定码 + 中文 message（如 ERROR: HR_API_TIMEOUT 合同台账读取超时）
• 数据库记录：写入 合同台账 / 预警记录 / 续聘任务 / 派发日志
• HTML 报告：个人版《续聘准备任务书》落到 html/

7. 依赖的兄弟技能或外部系统

兄弟技能依赖

• 无强制依赖

外部系统依赖

• 人事系统 API（合同电子台账）：必须
• 党委教师工作部 API（考核 + 师德）：必须
• 企业微信推送 API：必须

Python 包依赖（requirements.txt）

• HTTP 请求：requests>=2.31.0,<3
• 日期处理：python-dateutil>=2.8.0,<3
• HTML 渲染：jinja2>=3.1.0,<4
• jiangchang-platform-kit、playwright 等公共能力由宿主共享 runtime 提供

8. 不在本次范围内的内容

• 本次不实现试用期合同不通过的自动化处分流程
• 本次不集成续聘材料 OCR 识别
• 本次不做合同电子签署（仍走线下 OA 流程）
• 本次不兼容旧模板历史结构

9. 验收标准

• 代码结构符合模板规范；SKILL.md slug 与 constants.SKILL_SLUG 一致
• health / version / config-path / init-db 命令执行正常
• scan-expiring-contracts 在含 1000+ 份合同的样例库中完成一次完整扫描，耗时 ≤ 2 分钟
• 业务表写入和查询符合 references/SCHEMA.md
• 30 天红色预警自动抄送分管校领导功能验证通过
• SKILL.md 的 developer_ids 已配置为开发者本人匠厂用户 ID
• 已人工核验授权与技术路线：无破解、逆向、私有协议、验证码绕过、Hook / 注入、自动换号
• 安装后按 §0.1 入口定位表完成宿主多入口验收
• cron 每日定时扫描稳定运行 7 天无故障

10. 开发注意事项

• 只修改当前 skill 仓库，不要改动无关兄弟项目
• 人事系统 API 不可用时停止并上报；不得擅自改走破解或绕过鉴权的路线
• 教师身份证号、银行卡号等敏感字段严禁写入日志
• 不得向教师个人透露 AI 续聘建议（仅单位版清单展示）
• cli 只做参数解析；核心逻辑在 service；兄弟 skill 调用集中封装

11. 变更记录

日期	版本	变更人	变更内容
2026-09-14	v1.0.1	匠厂	初版需求文档，骨架就位