track-fund-progress-default/development/REQUIREMENTS.md

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 章节对齐