verify-scholarship-fraud-sas/development/REQUIREMENTS.md

# 奖助学金评定逻辑防伪校验 — 技能需求文档

> 派生自匠厂 skill-template 主仓 `development/REQUIREMENTS.md`，对应规格书第 4.3 节「🟠 学生处 Skill 001 —— 奖助学金评定"逻辑防伪校验"」。

---

## 0. 技能标识

- **拟定 slug（英文）**：`verify-scholarship-fraud-sas`
- **中文 name**：奖助学金评定逻辑防伪校验
- **中文 description（一句话）**：辅导员在汇总表中批量勾选候选人后，自动比对自报家庭年收入与一卡通消费、综测排名与成绩排名、本学年累计资助金额，生成《奖助评定复核建议清单》
- **account-manager platform_key（如有）**：N/A
- **命名形态**：标准型
- **目标 OEM 市场 `brands`（可选）**：未写则仅挂匠厂
- **网页 RPA（如有）— 登录策略**：**不适用**

## 0.1 宿主入口定位（必填）

| 主能力（Action id / CLI） | 对话 | 数据管理 | 定时 | 教程章节 | 不挂理由 |
|---------------------------|------|----------|------|----------|----------|
| `health` / `version` / `config-path` | 挂 | 不挂 | 不挂 | 入口二 | 默认必备 |
| `verify-candidate` | 挂 | row（候选人汇总表） | 不挂 | 入口一/入口二 | sync |
| `batch-verify-class` | 挂 | batch（候选人汇总表） | 不挂 | 入口一/入口二 | async |
| `mark-needs-review` | 不挂 | row（候选人汇总表） | 不挂 | 入口一 | 写状态 |
| `submit-review-result` | 不挂 | row（复核建议清单） | 不挂 | 入口一 | 写状态 |
| `render-html` | 挂 | row（复核建议清单） | 不挂 | 入口一/入口二 | sync |
| `sync-card-data` | 挂 | toolbar（一卡通消费） | 挂（占位） | 入口一/入口三 | cron 占位 |
| `sync-gdp-data` | 挂 | 不挂 | 挂（占位） | 入口三 | cron 占位 |

### 0.1.1 用户市场文档

- `README.md`：能力 / 场景 / 边界
- `TUTORIAL.md`：覆盖两入口，入口三写「占位」

## 0.2 AI + RPA 协作与授权边界

### Agent 设计

- 用户意图：校验候选人 / 批量校验 / 标记待复核 / 提交复核 / 查看清单 / 同步数据
- 意图 → Action 映射：
  - 单个校验 → `verify-candidate`
  - 批量校验 → `batch-verify-class`
  - 标记待复核 → `mark-needs-review`
  - 提交复核结果 → `submit-review-result`
  - 查看清单 → `render-html`
  - 同步一卡通 / GDP → `sync-card-data` / `sync-gdp-data`
- 缺参数追问：学生姓名 / 学号 / 班级
- 必须确认的动作：
  - `mark-needs-review` 标记前提示复核原因
  - `submit-review-result` 提交前提示最终结论
- 结果解释：成功（异常标签 + 详情）、部分成功（一卡通缺失但其他维度校验完成）、失败（数据源全部不可用 → 仅记录到日志）

### 授权与平台边界

- 学生工作部 / 一卡通中心 / 教务系统 API 凭证由学生处统一开通
- 学生家庭隐私数据（年收入 / 致贫原因）受严格保密
- 严禁逆向任何系统、破解私有协议
- 学生数据严禁写入日志

### RPA 风控设计

- 执行端：**N/A**

## 0.3 业务行生命周期

本技能对「候选人汇总表」中的每一行，遵守 `references/WORK_ITEM_STATUS.md` 角色约束：

| 角色 | 本技能状态值 | 说明 |
|------|--------------|------|
| 可操作（operable） | 待审 | 默认唯一可被 `verify-candidate` 捞起 |
| 进行中（in_progress） | 已标注 | AI 已发现异常，等待辅导员复核 |
| 成功类终态 | 已复核（保留） | 辅导员填写核查说明并通过 |
| 失败类终态 | 已复核（取消 / 调减） / 已驳回 | 默认不可再处理；失败原因字段：核查说明 |
| 跳过类终态 | 已撤回 | 学生主动撤回申请 |

> 重做靠人工将"已复核 / 已驳回"改回"待审"，不靠 AI 自动覆盖。

---

## 1. 文档目标

本文档用于明确 `verify-scholarship-fraud-sas` 的研发范围、交付标准、依赖关系和验收要求。

## 2. 业务背景

- **现状**：辅导员在奖助学金评审期人工翻查每位候选人的家庭资料与历史资助，效率低且容易遗漏
- **痛点**：
  - **效率低**：每位候选人需 15~20 分钟人工核查
  - **容易遗漏**：跨年度累计资助、生源地差异等难以全面比对
  - **认定争议**：抽查不到位引发学生投诉
- **目标**：自动完成「多源数据交叉比对 + 横向排名可疑 + 历史重复资助排查」，输出《复核建议清单》

## 3. 开发目标

- 拉取学生《家庭经济困难认定表》数据
- 拉取一卡通月均消费额（食堂 / 超市）
- 拉取综测成绩排名
- 拉取本学年已获资助记录
- 比对生源地人均 GDP（公开统计）
- 四类异常检测：
  - 多源数据一致性（年收入 vs 消费 vs GDP）
  - 横向排名可疑（成绩 vs 综测）
  - 历史重复资助（累计金额超限）
  - 致贫原因逻辑合理性（住址 vs GDP）
- 输出《复核建议清单》HTML 报告 + 高风险个案推送
- 写入业务表（候选人汇总表 / 复核建议清单 / 困难认定 / 一卡通消费 / 历史资助）

## 4. 功能范围

### 必须实现

- 支持 `python scripts/main.py health` / `version` / `config-path` / `init-db`
- 支持 `python scripts/main.py verify-candidate --candidate-id <id>`
- 支持 `python scripts/main.py batch-verify-class --class-id <id>`（async）
- 支持 `python scripts/main.py mark-needs-review --candidate-id <id> --reason <text>`
- 支持 `python scripts/main.py submit-review-result --candidate-id <id> --conclusion <保留/取消/调减> --review-note <text>`
- 支持 `python scripts/main.py render-html --list-id <id>`
- 支持 `python scripts/main.py sync-card-data` / `sync-gdp-data`（async，cron 占位）
- 完成 §0.1 入口定位表

### 可后续扩展

- AI 智能撰写核查说明草稿
- 校级 / 院级差异化学位资助规则
- 历史投诉数据联动（如某生此前有认定争议）

## 5. 非功能要求

- 目录结构符合 skill-template 规范
- 入口统一为 `scripts/main.py`
- 用户市场四 Tab
- 输出机读友好；错误前缀 `ERROR:`
- Windows UTF-8 兼容
- 学生家庭隐私数据严禁写入日志
- 单候选人校验耗时 ≤ 5 秒；批量校验 500 人 ≤ 30 秒

## 6. 输入输出要求

### 输入

- `candidate_id`：候选人主键（必填）
- `class_id`：班级主键（仅 batch 必填）
- `reason`：复核原因（mark-needs-review 必填）
- `conclusion`：最终结论（submit-review-result 必填，枚举：保留 / 取消 / 调减）
- `review_note`：核查说明（submit-review-result 必填）
- `list_id`：复核清单主键（仅 render 必填）
- 依赖系统：学生工作部 API / 一卡通中心 API / 教务系统 API
- 环境变量（`.env`）：
  - `SAS_API_BASE_URL` / `SAS_API_TOKEN`：学生工作部
  - `CARD_API_BASE_URL` / `CARD_API_TOKEN`：一卡通中心
  - `AA_API_BASE_URL` / `AA_API_TOKEN`：教务系统
  - `ANNUAL_AID_LIMIT`：年度累计资助上限（元）
  - `SCORE_GAP_THRESHOLD`：成绩排名与综测排名差值阈值（默认 10）
  - `CONSUMPTION_INCOME_RATIO`：消费 / 年收入比值阈值（默认 0.5）

### 输出

- 成功结果：`verify-candidate` 返回 `{risk_level, anomaly_types, anomaly_details}`
- 错误输出：`ERROR:` 稳定码 + 中文 message
- 数据库记录：写入 `复核建议清单` 表
- HTML 报告：落到 `html/`

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

### 兄弟技能依赖

- 无强制依赖

### 外部系统依赖

- **学生工作部 API**（困难认定 + 候选人）：必须
- **一卡通中心 API**（消费数据）：必须
- **教务系统 API**（成绩 + 综测排名）：必须
- **公开统计来源**（生源地 GDP）：必须

### Python 包依赖（requirements.txt）

- HTTP 请求：`requests>=2.31.0,<3`
- 数据处理：`pandas>=2.0.0,<3`
- 行政区划映射：`cpca>=0.5.0`
- `jiangchang-platform-kit` 由宿主提供

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

- 本次不实现 AI 智能撰写核查说明草稿
- 本次不集成历史投诉数据
- 本次不做 cron 启用（占位 Action 已就位）
- 本次不兼容旧模板历史结构

## 9. 验收标准

- 代码结构符合模板规范
- `health` / `version` / `config-path` / `init-db` 命令执行正常
- `verify-candidate` 在 100 人样例库中完成一次校验，平均耗时 ≤ 5 秒
- 业务表写入和查询符合 `references/SCHEMA.md`
- 异常识别准确率 ≥ 90%（基于样例库）
- 学生隐私数据 0 写入日志（`test_logging_contract.py` 守护）
- `SKILL.md` 的 `developer_ids` 已配置
- 安装后按 §0.1 完成宿主多入口验收

## 10. 开发注意事项

- 只修改当前 skill 仓库
- 学生家庭隐私数据严禁写入日志；导出报告脱敏
- 严禁逆向任何系统或绕过数据访问权限
- 异常检测阈值可在 `runtime/config` 调参
- `cli` 只做参数解析；核心逻辑在 `service`

## 11. 变更记录

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