v1.0.1: 合同到期智能预警与续聘辅助 - 初版骨架

基于匠厂 skill-template 主仓 v1.0.108 派生的业务技能。核心业务： - 每日凌晨定时扫描全校教职工合同电子台账 - 距到期日 90 / 60 / 30 天分级预警（黄 / 橙 / 红） - 自动生成个人版《续聘准备任务书》与单位版《本月到期人员清单》 - 30 天红色预警自动抄送分管校领导输出形态： - 个人版 HTML 任务书 + 单位版 PDF 清单 + 三级预警通知预期提效：因合同逾期未续签导致的劳动纠纷降为 0；人事处年终集中突击签合同的工作量减少 60%。业务行生命周期：可续聘 → 预警中（黄 / 橙 / 红）→ 已续签 / 已驳回 / 已过期 Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-09-14 12:19:11 +08:00
commit e2b45d690e
21 changed files with 1502 additions and 0 deletions
--- a/development/REQUIREMENTS.md
+++ b/development/REQUIREMENTS.md
@@ -0,0 +1,220 @@
+# 合同到期智能预警与续聘辅助 — 技能需求文档
+
+> 派生自匠厂 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 | 匠厂 | 初版需求文档，骨架就位 |