# Changelog

本文件对应技能市场 **「更新日志」** Tab。

## 1.1.21

- **修复登录完成检测盲区**：`_wait_for_manual_login` 现在监听 3 个信号判断「登录已完成」，任一触发即继续
  1. URL 含 `/app/` 且稳定 2 秒（v1.1.20 旧逻辑）
  2. URL 已离开 `/login` / `/signin` / `/auth/` 等登录路径
  3. 页面出现 sidebar 元素 `a[href$='/hr/contracts']`
- 解决「用户已经登录但脚本还在傻等」的回归：之前只判 URL 变化，cookie 已生效复用 profile 场景或 SPA 不跳 URL 的场景会卡 180 秒

## 1.1.20

- **登录流程重写**：第一跳改为 `https://sandbox.jc2009.com/`（根域，用户最初看到的页面），**不做任何操作**等 URL 稳定
  - 已登录态：根域自动跳到 `/app/home` → 直接走侧边栏到 `hr/contracts` 采集
  - 未登录态：**纯等用户在浏览器手工输入账号密码**，不再自动 fill demo/123456，不再 retry 强制 reload 打断用户输入
- 新增 `_wait_for_url_stable(page, target_substr, max_wait_sec)`：等 URL 真正稳定 2 秒后才返回，避免 sandbox 中间页误导
- `_wait_for_manual_login` 重写：每 5 秒轮询 URL（之前 2 秒太密），每 15 秒打印一次剩余时间提示，**等待期间不触发任何 goto / reload / click**
- 新增 4 个 login flow 测试（`wait_url_stable_immediate` / `wait_url_stable_transition` / `wait_url_stable_timeout` / `wait_manual_login_no_goto`），合计 58/58

## 1.1.19

- **修复 1.1.18 引入的采集回归**：把 `_persist_contracts` 里的入队调用移到独立事务 `_enqueue_download_tasks_safe`，FK 失败不再回滚 `contracts` / `materials_content` 落库；返回 JSON 新增 `download_queue` 字段方便 UI 直接看到入队结果
- 新增 4 个测试覆盖 `_enqueue_download_tasks_safe`（basic / idempotent / fk_failure / empty_list），合计 54/54

## 1.1.18

- **一键式"运维 + 材料管理"全打通**
  - 新增 `show-config` / `logs-list` 两个 sync Action：UI 一键查看 .env 配置（敏感字段自动脱敏）与运行日志末尾 200 行
  - 新增 `download-materials` async Action：UI 一键批量下载续聘材料包（pending 队列 → 浏览器抓取 → 落库 → 标记 success/failed）
  - 新增 `import-input` CLI：扫描 `data/input/{contracts,materials}/` 自动入库，HR API 拿不到时用户可直接投放 CSV/PDF/Word
- **材料下载队列（download_tasks）**：新建表跟踪每个合同的材料抓取状态（pending/running/success/failed），失败自动重试最多 3 次
- **日志落文件**：本地降级路径新增 `RotatingFileHandler`（默认 5MB × 5 份），`LOG_FILE` / `LOG_MAX_BYTES` / `LOG_BACKUP_COUNT` 可覆盖
- 新增文件：`scripts/service/importer.py` / `scripts/service/config_viewer.py` / `scripts/service/logs_viewer.py`
- 现有 31 个测试全部保留；新增 17 个测试（合计 48/48）

## 1.1.17

- 补齐数据管理的“立即同步合同台账”工具栏入口，调用 SmartCampus 平台采集能力。
- 补齐合同业务行状态规范，并增加 Action 声明与 CLI 命令一致性的发布前校验。
- 平台采集默认显示浏览器，登录态失效时可直接手工登录；自动化任务须显式传 `--headless`。

## 1.1.16

- 修复续聘建议中的趋势判定：仅近三年考核分数严格递增才建议续聘；成绩持平或回落均进入常规续聘评审。
- 新增回归测试，覆盖 `80 → 80 → 90` 的成绩持平场景。

## 1.1.15

- **修复「数据管理」Tab 看不到（关键根因：`developer_ids` 是占位 ID）**
  - **根因复盘**：之前 8 个版本（v1.0.0 ~ v1.1.14）都没解决"装上看不到"。v1.1.14 修了 description 意图触发，但仍然看不到。逐字段对比同仓 5 个已安装技能的 `~/.openclaw/skills/*/SKILL.md`，发现：
    | 技能 | `developer_ids` | 数据管理可见？ |
    |------|----------------|--------------|
    | scrape-video-douyin | `[10032, 12428]` | ✅ |
    | scrape-video-links | `[10032, 12428]` | ✅ |
    | account-manager | （完全没此字段） | ✅ |
    | **alert-contract-expiring-hr (v1.1.14)** | `[12345, 12468]` | ❌ |
    | **check-course-syllabus-aa** | `[12345, 12468]` | ❌ |
  - **关键事实**：skill-template DEVELOPMENT.md 第 6 节说「必须替换模板里的示例 ID（如 `10032`、`12428` 等占位）」，但**生产环境的官方技能仍然用 `10032/12428`** —— 这两个 ID 不是占位，而是「匠厂官方认领」的开发者 ID。模板注释（`12345 # 占位`）与生产实际完全相反！
  - **修复**：把 `developer_ids` 改为 `[10032, 12428]`（与同仓可见的 `scrape-video-*` 完全对齐），并删除 `brands` 字段（account-manager 也没这字段，平台默认分发到全部市场即可）
  - **验证**：本地安装位置 `~/.openclaw/skills/alert-contract-expiring-hr/SKILL.md` 同步应用本次修改后，预期用户在 OpenClaw 重启 / 刷新即可在「数据管理」Tab 看到本技能
  - **配套**：更新本技能 SKILL.md 注释，移除"开发期技能常为不公开"的错误描述（公开发布的技能都应该用官方 ID `[10032, 12428]`）

## 1.1.14

- **修复「数据管理」Tab 看不到问题（用户反馈驱动，对比同仓其他技能发现）**
  - **根因**：原 `description` 写的是「每日凌晨扫描」**定时任务场景**，没有用户意图触发条件。同仓能显示在「数据管理」Tab 的技能（`scrape-video-douyin` / `scrape-video-links` / `account-manager` / `check-course-syllabus-aa`）的 `description` 都包含「**当用户**要 XX **或说**XX **时加载本技能**」这种意图触发描述
  - **修复**：改为意图触发型 description，包含「当用户说要扫描即将到期的合同、查 90/60/30 天预警名单、给某位教师生成续聘任务书、下发单位版续聘清单、从 SmartCampus HR 平台抓合同数据、解析续聘材料 PDF/Word、查看本月合同到期人员清单时，加载本技能」
  - **副作用**：保持原定时任务能力（每日凌晨扫描）作为多入口之一提及，但以用户意图为主

## 1.1.13

- **修复市场可见性（按 skill-template 模板对齐 SKILL.md frontmatter）**
  - 移除 v1.1.12 误加的 `access_scope: 0` 字段（**根因**：模板 `skill-template-main/skill-template/SKILL.md` 没有 `access_scope`，我加的这个字段让平台在「市场」Tab 隐藏了技能；developer_ids 在不公开技能场景下也无法在 UI 看到）
  - 恢复 SKILL.md frontmatter 与 skill-template 完全一致（字段 + 缩进 + brands 列表 5 空格缩进）
  - 清理 SKILL.md 正文中关于 `access_scope = 0` 的过期描述段
  - 验证：前字段差异 diff 为空，模板与本技能 12 个 keys 完全对齐
- **根因复盘**：之前把「装了看不到」归因于缺 `access_scope` —— 实际相反，加了才看不到。skill-template 不声明 access_scope 是有意的（公开可见优先）

## 1.1.12

- **修复市场安装后看不到问题（用户反馈驱动）**
  - SKILL.md `metadata.openclaw` 显式声明 `access_scope: 0`（不公开），让平台把 `developer_ids` 中的匠厂用户 ID 自动补写到 `skill_user_access`
  - 确认 `developer_ids` 包含当前开发者匠厂 ID `12468`
  - 之前没声明 `access_scope` 时平台行为不一致，可能导致装上但看不到（访问被静默拒绝）
- **踩坑经验**：开发期未公开技能必须显式 `access_scope: 0` + `developer_ids` 含自己 ID，否则开发者在市场装上后看不到

## 1.1.11

- **RPA 自动登录 selector 修复（用户反馈驱动）**
  - **`_fill_spa_login` selector 改用 sandbox 实际 ID**：之前用 `input[autocomplete="username"]` 但 sandbox SPA 登录页 input 是 `type="tel"` + 无 autocomplete，导致 selector 永远 miss、自动 fill 100% 失败
  - 改为按优先级 fallback 三组 selector：`#jc-user` → `input[type="tel"]` → `input[autocomplete="username"]`（密码同样：`#jc-pass` → `input[type="password"]` → `input[autocomplete="current-password"]`）
  - 按钮 selector 同样按优先级：`button:has-text("登录")` → `button[type="submit"]:has-text("Sign in")` → `button[type="submit"]`
  - **SPA_HOME 探针二次等待**：sandbox SPA 有时首次访问跳中间过渡页（如 /select），等几秒看 URL 是否稳定到 /app/，避免误判未登录
- **意外发现**：sandbox 服务端今天已恢复，demo/123456 凭据可重新自动登录通过（之前 9-14 探测失败应该是服务端临时故障），本版本同时修复了 selector 和兜底

## 1.1.10

- **RPA 已登录态检测优化（profile cookie 复用零打扰）**
  - **SPA_HOME 探针时延长等待**：从 `POST_LOGIN_SETTLE_MS=2s` 改为 `SPA_HYDRATION_MS=3s`，sandbox SPA 异步验证 cookie 时间更充分，避免误判未登录
  - **`_fill_spa_login` 入口先检测 `_is_logged_in`**：已登录态直接 `return True` 跳过自动 fill，不再强制 demo fill 破坏 session
  - **fill 后再检测 `_is_logged_in`**：避免 sandbox demo 凭据失效时 URL 跳 `/app/home` 但 cookie 没写入的误判
  - **用户反馈驱动**：用户要求「如果已经登录了不需要用户再登录」—— v1.1.8/v1.1.9 的探针逻辑在 sandbox SPA 异步验证 cookie 时机不准时仍会触发 fallback 手工登录；本次彻底修掉
  - 实跑（2026-09-14）：profile 已登录态下，`collect-from-platform --show-browser --limit 1` **完全静默自动跑**（无 `[登录]` 提示、无弹窗打扰），13 秒抓 3 行 + 卡片 381 字 + 落库

## 1.1.9

- **RPA headed 模式改用系统 Edge（解决浏览器弹窗不可见）**
  - **根因**：v1.1.8 headed 模式用 Playwright 内置 chromium，**在 Windows 桌面 session 下能创建浏览器对象但 GUI 窗口不可见**（子进程 bash session 与用户桌面 session 不同），导致 `--show-browser` 看似启动 headed 实际用户看不到弹窗、无法手工登录，180s 后 LOGIN_TIMEOUT
  - **修复**：headed 模式改为 Playwright `channel="msedge"` 启动**系统 Microsoft Edge**（跟用户桌面 session 同源，能真正弹窗）；系统 Edge 缺失时 fallback Playwright 内置 chromium
  - 验证（2026-09-14）：`collect-from-platform --show-browser --limit 1 --human-wait-timeout 240` → 系统 Edge 弹出窗口 → 用户手工登录 → RPA 24 秒内检测到 → 抓 3 行合同（钱实验/孙助理/王明远）→ 抓卡片 381 字 → 落库 `saved_contracts=1 / downloaded_materials=1`
  - 测试：28/28 passed

## 1.1.8

- **RPA 首次登录采集修复（用户反馈驱动）**
  - **不再强制 goto login 打断手工登录态**：`collect_all` 启动时先调 `_is_logged_in(page)` 检测是否已登录（如 profile cookie 复用）；已登录态直接 goto SPA_HOME，未登录态才走 login → 自动 fill → fallback 手工登录等待
  - **首次登录后不再强制 page.reload**：原 5.5 步骤「刷新触发 mock 数据」会打断刚登录的 SPA session，导致 sandbox 把已登录态踢回 login；改为**默认不刷新**，表格等 10s 未出现才触发兜底刷新（5.5/5.6 逻辑下沉到 `_try_reload_after_table_timeout`，仅在表格超时调用）
  - **表格列数自适应**：sandbox 首次登录未刷新时表格是 **7 列**（姓名/单位/到期日/剩余天数/预警/建议/按钮），刷新后才是 **10 列**（多 工号/岗位/合同类型/起止日期）；原代码硬编码 10 列解析 → 7 列时 `r[7]/r[8]` IndexError。改为「首列匹配工号正则 `^[A-Za-z]?\d+$` 走 10 列，否则走 7 列」双布局自适应
  - **contract_id 派生兼容 7 列**：7 列布局无工号 → 用 `teacher_name` 派生 contract_id（如 `RPA-钱实验-20260415`），避免与 10 列工号布局冲突
- **实跑验证（2026-09-14）**
  - 命令：`python scripts/main.py collect-from-platform --show-browser --limit 1 --human-wait-timeout 180`
  - 结果：自动 fill demo 失败 → fallback 手工登录 → 你登录后 RPA 不刷新直接跳 hr/contracts → 抓 3 行（钱实验/孙助理/王明远）→ 抓卡片 381 字 → 落库 `saved_contracts=1 / downloaded_materials=1`
  - 退出码 0

## 1.1.7

- **RPA 手工登录 fallback 实跑验证（2026-09-14）**
  - sandbox 演示账号 `demo/123456` 已失效（多次尝试 + 6 组常见 demo 凭据全部返回「用户名或密码错误」），按 v1.1.6 设计自动切到 `_wait_for_manual_login` 手工登录分支
  - 实跑命令：`python scripts/main.py collect-from-platform --show-browser --limit 1 --human-wait-timeout 180`
  - 实跑结果：用户在弹出浏览器手工登录后，RPA 第 1 次轮询（≤2s）即检测到 `/app/home` URL，跳过登录分支继续往下走：
    - 自动导航侧边栏 hr/contracts → `page.reload()` 触发 mock 数据
    - 抓到 3 行合同（钱实验 / 孙助理 / 王明远）
    - 首行「续聘材料包」卡片抓 870 字文本 → 4 条业绩记录
    - 落库 `contracts` + `materials_content`：`saved_contracts=1, downloaded_materials=1`
  - 结论：v1.1.6「自动 fill + 手工 fallback」设计 **已端到端验证**；后续 collect-from-platform 默认带 `--show-browser` 走手工登录入口（避免硬编码失效 demo 凭据）
  - 流程记录见 memory `platform-collect-workflow.md`

## 1.1.6

- **RPA 重构（按 skill-template `examples/real_browser_rpa` 设计模式）**
  - **超时参数统一抽到 `constants.py`**：新增 `HUMAN_WAIT_TIMEOUT=180` / `HUMAN_POLL_INTERVAL=2.0` / `DEFAULT_PAGE_TIMEOUT_MS=15s` / `GOTO_TIMEOUT_MS=60s` / `SPA_LOGIN_*` / `TABLE_*` / `SIDEBAR_LINK_TIMEOUT_MS` 等 24 个常量（与 skill-template human_verification 同名常量对齐）
  - **新增手工登录 fallback**：自动 fill demo/123456 失败时自动切到 `_wait_for_manual_login`（轮询 `_is_logged_in` 每 2s 一次，最多 `HUMAN_WAIT_TIMEOUT` 秒，超时抛 `LoginTimeoutError`），给用户手工登录机会（与 skill-template `task_rpa.py::_ensure_logged_in` 设计对齐）
  - **结构化错误码**：`RPAError` 基类 + `LoginTimeoutError`（`ERROR:LOGIN_TIMEOUT`）/ `MissingBrowserError`（`ERROR:MISSING_BROWSER`）/ `TableNotFoundError`（`ERROR:TABLE_NOT_FOUND`），供 CLI/宿主解析
  - **CLI 新增 `--human-wait-timeout N` flag**
  - **`_goto` 默认 timeout 改用 `GOTO_TIMEOUT_MS=60s`**；新增 `page.set_default_timeout(DEFAULT_PAGE_TIMEOUT_MS)`
- **依赖清单修复**：删除 `requirements.txt` 中违规的 `playwright>=1.40.0`（playwright 由宿主 `jiangchang_skill_core` runtime 提供，文件顶部注释已声明）
- **环境变量**：`.env.example` 新增 `HUMAN_WAIT_TIMEOUT` / `RPA_PAGE_TIMEOUT_MS` / `RPA_GOTO_TIMEOUT_MS` 覆盖项
- **保留 v1.1.5 自动 fill 优势**：sandbox demo/123456 已知凭据自动登录（生产环境切换无 demo 凭据时自动 fallback 手工）

## 1.1.5

- **platform_collector RPA 采集修复（登录等待时间太短 → 拿不到数据）**
  - `_fill_spa_login`：settle_ms 默认 0 → **4000ms**，等 username input timeout 10s → **20s**，wait_for_url（URL 真的跳离 login）20s → **30s**；URL 判断增加 `/auth/` 路径（覆盖 SPA 中间态）
  - `_goto(SPA_LOGIN_URL)` 后：wait 1500ms → **3000ms**（SPA hydration）
  - 登录按钮 click 后：新增 `wait_for_timeout(2000)`，等 SPA token 写入 cookie + 路由稳定再 goto home（之前直接打断 pending 跳转）
  - 步骤 4 改为 retry 循环（最多 2 次），检查 `/app/` in url 且不含 `/login` 才退出
- **采集流程健壮性修复**
  - 步骤 5 侧边栏 link 等待：15s → **30s**（sandbox mock 慢启动不 fallback 到 pushState）
  - 步骤 5.5 `page.reload()` timeout：20s → **30s**
  - **新增 5.6**：刷新后检查 URL，若被踢回 `/login` 则重新登录一次（之前刷新丢 session 后还继续往后走，导致 40s 找不到表格）
  - 「续聘材料包」按钮 click 后：wait 1500ms → **3000ms**（卡片动画慢导致文本抓不全）
  - 抽出 `_dump_page(page, path, label)` helper，**自动 `mkdir(parents=True)`**，修复 5 处 dump 路径父目录可能不存在的静默失败

## 1.1.4

- **多平台发布声明**：SKILL.md `metadata.openclaw.brands` 新增 `jiangchang` + `huashang`，发布后同步挂匠厂主站与华商 OEM 市场。CI 会幂等补写 `skill_market_relations` 两行（**只补不删**）。

## 1.1.3

- **版本对齐修复**：v1.1.2 tag（commit `4af2b4f`）发布时 `SKILL.md version` / `scripts/util/constants.py SKILL_VERSION` 未同步升级（仍为 1.1.1），本次发布将 manifest 升至 1.1.3 并与代码现状对齐
- **内容同 v1.1.2**：sandbox 卡片采集功能（详见 1.1.2 条目）

> **说明**：v1.1.2 与 v1.1.3 实质内容相同（均含 sandbox 卡片采集）。v1.1.2 tag 视为已发布但 manifest 错位的历史遗留；v1.1.3 为首次 manifest 版本号与代码对齐的 release tag。

## 1.1.2

- **sandbox 卡片采集**：表格 10 列（工号/姓名/单位/岗位/合同类型/起止日期/剩余天数/预警/建议/材料包按钮），进入 hr/contracts 页面后 `page.reload()` 刷新触发 mock 数据加载
- **「续聘材料包」按钮行为**：不触发浏览器 download event，而是展开页面下方「续聘准备任务书」+「单位清单」卡片（含 checklist + 近三年考核表）。RPA 改为抓卡片 inner_text 存 `materials_content`（parse_method='sandbox_card'）
- **卡片文本解析进 performance_records**：新增 `repository.parse_sandbox_card_performance`（双模式正则：行格式 `2024\t称职` + 叙述式 `2024年：等次「称职」`）+ `repository.upsert_performance_record`（等次→分数：优秀=90 称职=75 基本称职=60 不称职=30）
- **contract_id 改用工号**（稳定，不随姓名变化）：`_gen_contract_id(emp_id, end_date)`
- **实测**（sandbox 3 合同）：

  | contract_id | 教师 | 解析 perf 条数 | AI 决策 |
  |---|---|---|---|
  | RPA-T20190033-20260415 | 钱实验 | 4 | observe |
  | RPA-T20200055-20260630 | 孙助理 | 6 | observe |
  | RPA-T20180021-20260831 | 王明远 | 6 | observe |

## 1.1.1

- **AI 续聘建议升级**：本地规则版 → LLM 优先 + 规则降级
  - 新增 `scripts/service/llm_decision.py`：调宿主 `jiangchang_skill_core.llm_manager.call_llm_json`（prompt 含教师信息 + 业绩 + 材料文本摘要），输出 `decision_source ∈ {llm, rules, rules_no_materials}`
  - `scripts/service/task_generator.py`：AI 决策统一改为调 `llm_decision.decide_suggestion`；降级版 reason 文案加「已结合材料包（含 X 个文件，Y 字内容）」前缀
- **SmartCampus HR 平台 RPA 采集（新增）**
  - 新增 `scripts/service/platform_collector.py`：Playwright 持久化 browser profile 复用登录态 → 抓合同表（姓名/单位/到期日/剩余天数/预警/建议） → 点"续聘材料包"按钮下载 PDF/Word → 落库
  - 平台：`https://sandbox.jc2009.com/industries/campus/smartcampus/app/hr/contracts`
  - 新增 CLI `collect-from-platform [--limit N] [--show-browser]`
  - **当前 sandbox mock 未部署「续聘材料包」按钮**，RPA 仅采集 6 列台账；材料下载代码已就绪，sandbox 补按钮后自动生效
  - 实测：headless 模式 + profile cookie 复用，抓 3 行合同（钱实验/孙助理/王明远）→ 落 `contracts` 表
- **材料包 PDF/Word 文本提取（新增）**
  - 新增 `scripts/service/material_parser.py`：pypdf → pdf2image + pytesseract OCR（扫描件兜底）；python-docx 抽 docx；antiword 兜底 .doc
  - 新增 CLI `parse-materials [--contract-id C001]`
- **数据模型扩展**
  - 新增表 `materials_content`（contract_id / file_name / file_path / extracted_text / parse_method / parsed_at）
  - `renewal_tasks` 加列：`decision_source` / `materials_summary`
  - 新增 `scripts/db/migrations.py`：idempotent ALTER/CREATE，`init-db` 自动应用
- **HTML 任务书升级**
  - `scripts/templates/task.html.j2` footer 加 "AI 建议来源：{{DECISION_SOURCE}} · 已审阅材料 {{MATERIALS_COUNT}} 份"
  - `scripts/service/html_renderer.py` 模板 ctx 加 `DECISION_SOURCE` / `MATERIALS_COUNT`
- **CLI 列表**：v1.1.0 的 9 个 + 2 个新增 = **11 个**
  - 新增：`collect-from-platform` / `parse-materials`
- **依赖新增**（`requirements.txt`）：playwright / pypdf / python-docx / pdf2image / pytesseract / Pillow
- **`.env.example` 新增项**：SMARTCAMPUS_BASE_URL / SMARTCAMPUS_PROFILE_DIR / MATERIALS_DOWNLOAD_DIR / OCR_LANG / LLM_MODEL_NAME
- **SKILL.md**：version 1.1.0 → 1.1.1；用户意图路由表加 2 行；加「数据来源」段说明三层来源 + AI 决策来源透明化

## 1.1.0

- 实现核心业务逻辑（9 个 CLI 命令全部可运行）
- 新增 `scripts/cli/app.py`：argparse 子命令分发
- 新增 `scripts/util/{constants,date_util,runtime_paths,logging_setup}.py`
- 新增 `scripts/db/{connection,seed_data,repository}.py`：SQLite + 5 张表 + 50 份样例合同 + 150 条业绩记录
- 新增 `scripts/service/scanner.py`：扫描核心（90/60/30 三级预警 + 写 alerts + 生成任务）
- 新增 `scripts/service/task_generator.py`：规则版 AI 续聘建议（师德/考核/趋势三规则）
- 新增 `scripts/service/dispatcher.py`：按单位/月份派发 payload（dry-run 模式）
- 新增 `scripts/service/html_renderer.py`：Jinja2 任务书 HTML 渲染（无 jinja2 时降级到 str.replace）
- 新增 `scripts/templates/task.html.j2`：任务书模板（基于 assets/html/example-report.html）
- 新增 `examples/{contracts_sample,performance_sample}.csv`：本地样例数据
- `scripts/main.py`：重写为降级模式（jiangchang_skill_core 可选）
- `.env.example`：新增 `DB_PATH` / `HTML_OUTPUT_DIR` / `JIANGCHANG_DATA_DIR`
- 验收：本地 `python scripts/main.py <cmd>` 9 个命令全部 exit code = 0

## 1.0.1

- 初版：基于匠厂 skill-template 主仓 v1.0.108 派生
- 实现核心业务：合同到期智能预警与续聘辅助（每日定时扫描 + 三级预警 + 个人版任务书 + 单位版清单 + 自动抄送）
- 输出形态：合同台账表状态更新 + 预警记录表 + 个人版 HTML 任务书 + 单位版 PDF 清单 + 派发日志
- 预期提效：因合同逾期未续签导致的劳动纠纷降为 0；人事处年终集中突击签合同的工作量减少 60%
- 业务行生命周期：可预警 → 预警中 → 已续签 / 已驳回 / 已过期
- 占位说明：本版仅完成骨架与文档，业务实现细节（`scripts/` 下 Python 模块、人事系统 API 对接、定时调度）由开发者后续按 `development/REQUIREMENTS.md` 补全