# REQUIREMENTS —— 项目经费进度播报助手（track-fund-progress-default）

> 需求来源：《核心建设内容：各部门"Skill"深度需求规格书》§4.1 财务处 Skill 002（项目经费"智能进度播报"）。
> 详细设计见工作区《财务处Skill002-项目经费智能进度播报-开发文档.md》；本文是该技能仓内的需求与验收主文档。
> 定位原则：辅助非决策、审慎非激进 —— 数字全部来自本地确定性计算，播报文本由规则模板生成；进度诊断仅作提醒。

## 0. 技能标识

- 拟定 slug：`track-fund-progress-default`
- 中文 name：项目经费进度播报助手
- 中文 description：高校项目经费执行监测与播报：按项目台账自动计算实际支出率与序时进度，识别严重滞后/支出异常偏快，生成三段式播报摘要、暂付款冲销与结题报销提醒，支持月度定时播报并输出《经费执行简报》。
- account-manager platform_key：不适用（无网页 RPA，无账号下发）
- 命名形态：标准型+scope（track ∈ 动词白名单；default ∈ scope 白名单；4 段 27 字符）
- 网页 RPA 登录策略：`not_needed`（无浏览器自动化）

## 0.1 宿主入口定位

| 主能力（Action id / CLI） | 对话 | 数据管理 | 定时 | 教程章节 | 不挂理由 |
|---------------------------|------|----------|------|----------|----------|
| `broadcast-progress`（broadcast，sync） | 挂 | toolbar（bind fund_projects，表单） | 不挂 | 入口一/入口二 | 即时播报由人发起；无人值守走月度播报 |
| `broadcast-monthly`（broadcast-monthly，**async**） | 挂 | 不挂 | **挂 cron** | 入口二/入口三 | 月度批量播报，任务中心可见进度 |
| `import-projects` | 挂 | 不挂 | 不挂 | 入口二 | 批量 JSON 导入走对话更直观 |
| `add-project` | 不挂 | toolbar（fund_projects，表单） | 不挂 | 入口一 | 结构化录入，表单更稳 |
| `list-projects` | 挂 | 仅展示表 | 不挂 | 入口二 | 台账日常在数据管理看 |
| `list-reports` / `stats` | 挂 | 不挂 | 不挂 | 入口二 | 查询类，对话即达 |
| `render-html` | 挂 | toolbar（bind progress_reports）+ skill-detail | 不挂 | 入口一/入口二 | 报告重建 |
| `view-rules` | 挂 | 仅展示表 | 不挂 | 入口二 | 阈值日常只读 |
| `set-rule` | 不挂 | row（alert_rules，预填 rule_key） | 不挂 | 入口一 | 管理员在表上改值更直接 |
| `health` / `version` / `config-path` | 不挂 | 不挂 | 不挂 | N/A | 运维诊断，仅 skill-detail |

定时挂载说明：`broadcast-monthly` 为 async + agent + cron，缺省参数（全部在研项目）可安全无人值守，无不可逆副作用；对应规格书"每月 5 号 9:00 自动执行"场景，具体时刻由宿主定时任务配置。
表外挂载说明：`stats`、`view-rules` 另挂 skill-detail（技能详情页运维查看），对话/数据管理挂载以本表为准；`broadcast` 支持可选 `--all-status`（缺省仅处理"在研"）。

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

- 本技能**无 RPA**：不启动浏览器、不操作桌面/手机、不调用外部 HTTP。
- 台账数据由用户录入/导入；Agent 不得编造金额与日期。
- 目标系统：无外部系统；全部计算在本地 SQLite。
- 财务系统直连、企业微信推送、PDF 导出、大模型润色均为后续扩展。

## 0.3 业务行生命周期

不适用：播报为只读计算 + 本地记录写入，无"处理队列"状态机。

## 1. 文档目标

明确 `track-fund-progress-default` 的研发范围、交付标准与验收要求。

## 2. 业务背景

横向/纵向项目经费"重立项、轻执行"，PI 不知道执行率，年底突击花钱或结题沉淀；财务处靠电话催报。需要开发 `track-fund-progress-default`：按台账自动计算执行率与序时进度、诊断偏差、生成三段式播报与简报，月度定时播报，减少人工催报。

## 3. 开发目标

- 台账维护（upsert/批量导入/表格编辑）与预警阈值配置
- 三步计算内核：执行率（C1-C3）、偏差诊断（D1-D3）、提醒与三段式播报（N1-N3）
- 播报结果 JSON + `progress_reports` 落库 + 《经费执行简报》HTML + 月度汇总简报
- 月度播报 async Action（cron 挂载，任务中心进度）
- 失败可诊断（稳定错误码 `ERROR:<CODE> <message>` + 统一日志）

## 4. 功能范围

### 必须实现

- `health` / `version` / `init-db` / `config-path`（模板基座；`run` 为模板演示占位）
- `add-project` / `import-projects` / `list-projects`
- `broadcast`（主命令，sync）/ `broadcast-monthly`（async + cron）
- `list-reports` / `show-report` / `render-html` / `view-rules` / `set-rule` / `stats`
- 业务表 3 张 + `_jiangchang_*` 中文展示元数据 + 预警规则种子（4 条）
- `assets/actions.json` 按 §0.1 定位表声明

### 可后续扩展

- 财务系统直连自动刷新台账、企业微信图文卡片推送、PDF 建议函、大模型润色、科目级分析、多人项目聚合

## 5. 非功能要求

- 目录结构符合 `skill-template` 规范；入口统一 `scripts/main.py`
- 单文件 < 900 行；UTF-8 without BOM；Windows UTF-8 输出兼容
- 机读输出 JSON；错误前缀 `ERROR:`；主命令 `task_start`/`task_failed` 日志齐全，无敏感明文
- 月度播报逐项目 `emit` 进度；金额 round(x,4)；不存证件号/银行卡号
- 测试离线可过（无网络、无浏览器）

## 6. 输入输出要求

### 输入

- 台账字段（camelCase/snake_case/中文键兼容）：projectNo、projectName、projectType、piName、department、totalApproved、totalReceived、totalSpent、frozenAmount、frozenSince、startDate、endDate、status
- 播报参数：`--project-no`、`--pi`、`--as-of`（缺省今天）

### 输出

- 成功：stdout JSON（`ok/batch_no/as_of/count/status_counts/brief_file/reports_brief`）
- 失败：`ERROR:<CODE> <中文 message>`（`CODE ∈ NO_PROJECTS|PROJECT_INVALID|REPORT_NOT_FOUND|RULE_INVALID|ENTITLEMENT_DENIED|QUERY_FAILED`）
- 落库：`progress_reports`（含 `project_id` 关联与 `items_json` 规则明细）；文件：`html/report-{id}.html`、`html/brief-{batch}.html`

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

- 无兄弟技能依赖；无外部系统
- `requirements.txt`：无特有依赖

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

- 不修改财务系统数据、不做报销代操作
- 不直连财务/科研系统、不推送企业微信、不导出 PDF
- 不存证件号、银行卡号等个人敏感信息
- 不兼容旧模板历史结构

## 9. 验收标准

- 目录名 = `SKILL.md` slug = `constants.SKILL_SLUG`；三处版本号一致（1.0.1；三处 = `scripts/util/constants.py` / `SKILL.md` / `CHANGELOG.md`）
- `health` / `version` / `init-db` 正常；`python tests/run_tests.py -v` 全绿
- 金标准测试覆盖 C1-C3/D1-D3/N1-N2 正反例与阈值边界；三种代表场景真实跑通（正常/严重滞后+暂付款超期/异常偏快+临近结题）
- `set-rule` 修改阈值后诊断随之变化；`stats` 与记录一致；月度播报生成汇总简报
- `init_db()` 写入展示元数据，中文 display_name 完整，`test_display_metadata` 通过
- `assets/actions.json` 与定位表、TUTORIAL 三入口一致；`test_tutorial_surfaces` 通过
- `developer_ids` 已配置（79017）；发布后 Gitea 工作流成功、市场可见可装
- 宿主多入口验收：对话播报、数据管理按钮/行级、HTML 简报预览、定时任务创建并手动触发月度播报

## 10. 开发注意事项

- `cli` 只做参数解析；核心逻辑在 `service`（fund_service 唯一内核，多入口复用）
- 业务表间禁止 SQLite 外键；时间字段 Unix 秒；金额 round(x,4)
- 保留模板演示 `cmd_run`（POLICY-RPA-003 录屏集成守护）；业务命令不使用录屏
- 修改开发规范时同步 `POLICY_MATRIX.md` 与对应守护测试
- 旧库迁移在 `init_db()` 幂等完成（`ALTER TABLE` 补列：`items_json`、`updated_at`）

## 11. 变更记录

| 日期 | 版本 | 变更人 | 变更内容 |
|------|------|--------|----------|
| 2026-09-13 | v1.0 | 开发组 | 初版：三步计算内核 + 台账/阈值维护 + 简报与月度播报 |
| 2026-09-24 | v1.1 | 开发组 | 对照验收修订：错误码格式 `ERROR:<CODE> <message>`、状态标签优先级（C3→待补录）、`project_id`/`items_json` 落库、月度增量 emit、简报 TITLE 转义与 §10 章节对齐 |