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 | 匠厂 | 初版需求文档，骨架就位 |