track-fund-progress-default/acceptance-reports/20260924-105401-acceptance.md

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

- 相对路径：`acceptance-reports/20260924-105401-acceptance.md`
- 技能 slug：`track-fund-progress-default`
- git 提交短哈希：`a91ead3`（工作区含本轮未提交整改，见文末「本轮整改记录」）
- checklist_version：`1.0`
- 验收执行时间：2026-09-24 10:51–10:54（本地）
- 验收环境：Windows，Python `D:\jiangchang\huashang\.venv\Scripts\python.exe`（jiangchang-platform-kit 1.2.12），数据根 `D:\jiangchang-data`（用户 10032）
- 验收方式：CLI 端到端实测 + 默认测试套件 + 代码/文档静态核对；宿主 UI（数据管理页面、任务中心、市场）未接入，相关条目按 `NEED_MANUAL` 如实记录为**未做**

---

## 0. 技能画像（验收前填写，用于裁剪）

- [x] S0-1 交互形态：**纯本地**（本地 SQLite 计算，无外部 HTTP/RPA）
- [x] S0-2 目标站登录策略：**not_needed**
- [x] S0-3 是否依赖账号会话：**否**
- [x] S0-4 持久化：**另有业务表**（fund_projects / progress_reports / alert_rules）
- [x] S0-5 Skill Action：**含异步长任务**（broadcast-monthly = async）
- [x] S0-6 是否需要在任务中心查看进度或结果：**是**
- [x] S0-7 授权来源：无外部系统账号/数据权限；本地台账数据由宿主用户录入，执行走宿主 entitlement
- [x] S0-8 不可逆外部副作用：**否**（只读计算 + 本地记录/HTML 写入；无付款/删除/发送）
- [x] S0-9 入口定位表：**已填写**（`development/REQUIREMENTS.md` §0.1，与 `assets/actions.json`、开发文档 §9 三方一致）
- [x] S0-10 主用户路径：**对话 + 数据管理 + 定时**（与定位表一致）
- [x] S0-11 业务行生命周期：**不适用**（REQUIREMENTS §0.3 已声明：无处理队列状态机）
- [x] S0-12 HTML 页面报告：**有**（`{data}/html/*.html` + `render-html`，侧栏预览）

---

## 1. 安装与可运行

- [ ] A1-1 **P0** **NEED_MANUAL（未做）** 按平台方式加载后技能可被识别、打开详情或执行入口。已做：CLI 侧 `health`/`version`/全部子命令可执行。未做：宿主页打开技能详情（需人工真机）。
- [x] A1-2 **P0** **PASS** `python scripts/main.py health` 输出 `health: ok`、`platform_kit_version_ok: True`、env 路径可读，exit 0。
- [x] A1-3 **P0** **PASS** `version` 返回 `1.0.1`；与 `scripts/util/constants.py:4 SKILL_VERSION`、`SKILL.md:4 version`、`CHANGELOG.md ## 1.0.1`、git tag `v1.0.1` 一致。
- [x] A1-4 **P1** **PASS** 用户可见配置（4 条预警阈值）：`view-rules` 可读；`set-rule lag_threshold 0.70` 后同一项目判定由「严重滞后」翻转为「正常」，恢复 `0.10` 后回到「严重滞后」（实测 report_id 7/8），行为与说明一致。

## 2. 对外说明是否自洽

- [x] A2-1 **P0** **PASS** README 面向业务用户说明做什么/给谁用/准备什么（台账 5 类字段）。
- [x] A2-2 **P0** **PASS** 用户主路径为对话/数据管理操作，不以开发目录为入口。
- [x] A2-3 **P1** **PASS** TUTORIAL 按准备→入口一/二/三→常见卡住结构编排，`test_tutorial_surfaces` 通过。
- [x] A2-4 **P1** **PASS** DEMO.md 有演示信息位；`demo_video_url: ""` 并明示「无视频时的图文演示脚本」，不假装有视频。
- [x] A2-5 **P0** **PASS** CHANGELOG 首节 `## 1.0.1` 对应当前交付版本；`test_docs_standards` 通过。
- [x] A2-6 **P0** **PASS** SKILL.md 意图路由区分即时播报（sync）与月度播报（async 长任务），与真实能力一致。
- [x] A2-7 **P0** **PASS** README 无分步 1/2/3、无 Agent 话术块、无入口专章（`test_tutorial_surfaces` 反模式约束通过）。
- [x] A2-8 **P0** **PASS** 教程覆盖定位表全部「挂」入口（数据管理 toolbar/row、对话、定时入口三），`test_business_skill_tutorial_aligns_with_actions` 通过。
- [x] A2-9 **P0** **PASS** 有 cron：教程入口三写明宿主定时任务建「技能直调」选「月度经费播报」及每月 5 号 9:00 场景。
- [x] A2-10 **P1** **PASS** 教程主能力对照表与 `actions.json` label 一致（tutorial 对齐测试通过）。
- [x] A2-11 **P1** **PASS** 数据管理主路径入口在 toolbar（add-project 录入、broadcast-progress 播报、render-html 重建），教程不以 skill-detail 为唯一路径。
- [x] A2-12 **P0** **PASS** 说明/教程无 `# 技能名` 开篇（`test_market_docs_forbid_redundant_page_h1` 通过）。

## 3. 主能力行为

- [x] A3-1 **P0** **PASS** 主成功路径闭环实测（as_of=2026-08-15）：①NSFC2026001 → 正常/🟢（report-9）；②LAG2026001 → 严重滞后/🔴+冲销提醒（report-10）；③FAST2026001 → 支出异常偏快/🟠+结题提醒（report-11）；`broadcast-monthly` 3 项目 + 汇总页 `brief-006ab490ad2f5ddd.html`。
- [x] A3-2 **P0** **PASS** 缺参/非法输入稳定失败：`broadcast --project-no NOPE123` → `ERROR:NO_PROJECTS` exit 1；`add-project --start 2026/13/40` → `ERROR:PROJECT_INVALID` exit 1，不假成功。
- [x] A3-3 **P1** **PASS** 失败可诊断：`{data}/10032/logs/jiangchang.log` 有 `task_failed ... error_code=PROJECT_INVALID detail=...`，可定位到 stage（project/rules/broadcast/…）。
- [x] A3-4 **P0** **PASS** 多入口共用同一内核：CLI 与 Action 均落 `scripts/main.py` 同一子命令，`fund_service.run_broadcast` 唯一内核（代码结构 + `test_service` 类用例；宿主侧触发效果见 A9-3）。
- [x] A3-5 **P0** **PASS** 定位表已填写；「挂」的入口在 `actions.json` 有对应声明（13 个 Action，`test_actions_manifest` jsonschema/entrypoint/bind 校验通过）。
- [x] A3-6 **P1** **PASS** 「不挂」入口均有书面理由（定位表「不挂理由」列逐行填写）。

## 4. 调度与长任务

- [x] A4-1 **P0** **PASS** 秒级短操作：单项目 `broadcast` 实测 <1s 返回 JSON（三场景各约 0.3s）。
- [ ] A4-2 **P0** **NEED_MANUAL（未做）** 长任务经 Agent/动作触发后进入任务中心。已做：broadcast-monthly 为 async + `job_context`/`emit`/`finish` 代码路径完整、CLI 正常终态。未做：宿主任务中心真机确认（需人工）。
- [ ] A4-3 **P0** **NEED_MANUAL（未做）** 任务中心进行中/结束状态与成功失败结论。已做：增量 `emit` 回调（`[i/n] 项目：状态`）+ 单测 `test_on_progress_called_per_project`。未做：宿主任务中心真机观察（需人工）。
- [ ] A4-4 **P1** **NEED_MANUAL（未做）** 进度文案可理解性需在宿主任务中心真机查看；文案设计为 `[1/3] 钙钛矿…：正常` 形式（代码层已核）。
- [x] A4-5 **P1** **PASS** 动作参数覆盖主路径：broadcast-progress 暴露 projectNo/pi/asOf；broadcast-monthly 零参缺省=全部在研（安全无人值守）；`--all-status` 为可选扩展且已在 §8/定位表补记。
- [ ] A4-6 **P1** **N/A** 无「引用同库另一张业务表」的动作参数（set-rule 经 row 行绑定预填本表 rule_key，非手填内部编号）。
- [ ] A4-7 **P1** **N/A** 无互斥采集/操作模式。
- [ ] A4-8 **P1** **NEED_MANUAL（未做）** set-rule 行按钮打开的 form 参数区是否重复映射主键，须宿主真机打开确认（代码层：inputMapping 仅映射 rule_key，无 visibleWhen 藏字段）。

## 5. 账号与浏览器会话

- 本技能纯本地、无浏览器/账号会话（画像 S0-1/S0-2/S0-3），A5-1 ~ A5-12 全部 **N/A**（无网页 RPA 形态，等价项已在 §1–§4 覆盖）。

## 6. 结果落点

- [ ] A6-1 **P0** **NEED_MANUAL（未做）** 宿主任务中心/任务记录中可见对应条目。已做：CLI `{"type":"result",...}` 终态事件 + 日志 `task_start`/`broadcast_kernel_done`。未做：宿主任务列表真机核对（需人工）。
- [x] A6-2 **P0** **PASS** 成功跑完后新业务数据可查：`list-projects` 3 行、`stats` report_total 与库内一致、`list-reports` 含新记录；表 `_jiangchang_tables.visible=1` 且列元数据齐备（数据管理渲染由测试守护）。
- [x] A6-3 **P1** **PASS** 重复业务键幂等：同 project_no 再次 `add-project` 为 `action=updated` 且未提供字段不覆盖（`test_upsert_create_then_partial_update`）。
- [x] A6-4 **P1** **PASS** 零结果成功与失败可区分：无匹配项目为 `ERROR:NO_PROJECTS` 失败退出；正常空参全量播报成功返回。
- [x] A6-5 **P1** **PASS** 产出文件落在约定位置：`{data}/10032/track-fund-progress-default/html/report-*.html`、`brief-*.html`（实测可打开、grep 内容命中）。
- [x] A6-6 **P0** **PASS** 业务表 DDL 无 `FOREIGN KEY`/`REFERENCES`（`display_metadata_validator` 守护测试通过；跨表仅存 project_id 业务 id，关联在 `_record_to_result` 代码层完成）。
- [ ] A6-7 **P0** **N/A** 无「处理业务行」类 Action（REQUIREMENTS §0.3 声明无处理队列）。
- [ ] A6-8 **P0** **N/A** 同上（条目自带 N/A 条款）。
- [ ] A6-9 **P1** **N/A** 同上（状态→角色映射已声明不适用）。
- [ ] A6-10 **P1** **NEED_MANUAL（未做）** HTML 侧栏预览横向铺满/无横向滚动条/刷新时间，须宿主预览区真机确认；HTML 本体已验证（结构、转义、页脚、状态灯、提醒章节）。
- [x] A6-11 **P1** **PASS** 状态类列 `status`/`status_tag` 均 `searchable: 1` 且 `options_json` value 与存库枚举一致（`connection.py` 元数据定义 + `test_display_metadata` 通过）。
- [ ] A6-12 **P2** **N/A** 无 `display_type: boolean` 列。
- [x] A6-13 **P0** **PASS** 未创建 `task_logs`（`test_db_smoke` 断言 tables 仅 3 业务表 + 元数据表）。
- [ ] A6-14 **P0** **N/A** 无废弃表迁移场景。

## 7. 可观测与安全观感

- [x] A7-1 **P0** **PASS** 失败提示为业务中文（日期格式无效/无项目），无密码、Cookie、token 泄露；全仓无敏感字段存储（红线扫描通过）。
- [x] A7-2 **P0** **PASS** `jiangchang.log` 可见 `task_start` 与 `task_failed`/`broadcast_kernel_done`；失败含 `error_code=PROJECT_INVALID`，非仅 `cli_start`（2026-09-24 10:51:23 实录）。
- [x] A7-3 **P0** **PASS** 故意失败（非法日期）：日志先 `WARNING task_failed error_code=...`，随后 stdout `ERROR:PROJECT_INVALID ...`（顺序与实录一致）。
- [x] A7-4 **P1** **PASS** 关键步骤带 `stage=`（project/rules/broadcast/kernel/render/monthly），`broadcast_kernel_start/down` 记录批次与计数。
- [ ] A7-5 **P1** **N/A** 不宣称业务录屏（业务命令无录屏调用；`record_video` 缺省关闭；cmd_run 仅为模板演示）。
- [x] A7-6 **P2** **PASS** 用户可见文案为业务语言（严重滞后/暂付款冲销/结题决算）。
- [x] A7-7 **P2** **PASS** 数据管理按钮中文名（经费进度播报/录入项目台账/生成经费简报/更新预警阈值）不与宿主「查看/编辑/删除」重名（actions.json label 核对）。

## 8. AI + RPA 合规与工业级风控

- 本技能无外部系统、无 RPA、无不可逆业务动作（画像 S0-1/S0-8）；A8-1 ~ A8-16 全部 **N/A**。相关红线（不改财务数据、不存敏感信息、不逆向）由开发文档 §5.3 与 `test_development_policy_guard`/`test_no_rpa_helpers_import` 持续守护。

## 9. 质量门禁与交活底线

- [x] A9-1 **P0** **PASS** `python tests/run_tests.py -v`：**338 tests OK（3 skipped）**，2026-09-24 10:54 实测（基线 321 → 本轮新增 17 条金标准/守护用例）。
- [x] A9-2 **P0** **PASS** 本技能为纯本地确定性计算，本地即真实档；三代表性场景已真实跑通（A3-1），不以模拟档充数。
- [ ] A9-3 **P0** **NEED_MANUAL（未做）** 定位表「挂」的宿主入口按声明抽测（对话播报、数据管理 toolbar/row、HTML 侧栏预览与重建、定时任务创建并手动触发月度播报）。已做：各入口背后的 CLI 命令全部实测通过，`test_tutorial_surfaces`+`test_actions_manifest` 校验声明三方一致。未做：宿主 UI 真机点选（需人工，步骤见「给技术人员的修改清单」）。
- [x] A9-4 **P0** **PASS** 版本一致（POLICY-RELEASE-001）：`SKILL.md version` = `SKILL_VERSION` = git tag `v1.0.1`（无前缀）；CHANGELOG 有 `## 1.0.1` 小节。
- [ ] A9-5 **P1** **NEED_MANUAL（未做）** 开发者按平台规则安装并测到该技能（Gitea 工作流成功 + 市场可见可装截图/记录）。已有：tag `v1.0.1`、Gitea remote、`.github/workflows/release_skill.yaml` 就绪；市场安装验证记录仍缺（需人工/平台侧执行）。

---

## 10. 报告结尾必填

### 1. 结论

**不通过**（存在 5 项未完成的 P0 `NEED_MANUAL`：A1-1、A4-2、A4-3、A6-1、A9-3 —— 全部为宿主 UI 真机验证缺口，**无代码类 P0 FAIL**；0 项 FAIL）。

### 2. 统计

| 取值 | 数量 |
|------|------|
| PASS | 39 |
| FAIL | 0 |
| N/A | 36 |
| NEED_MANUAL（未做） | 9（P0 × 5，P1 × 4） |
| 合计 A 类条目 | 84 |

P0 FAIL 列表：无。
P0 NEED_MANUAL 未做列表：A1-1、A4-2、A4-3、A6-1、A9-3。

### 3. 给技术人员的修改清单

> 以下均为**人工验证缺口**，无代码缺陷。按 P0 → P1 排序；每项给出期望现象与建议步骤。

**P0**

1. **A1-1 宿主识别**：宿主技能详情页能打开本技能，名称「项目经费进度播报助手」、版本 1.0.1 可见；`health`/`version` 详情区可执行。
2. **A4-2 + A4-3 任务中心（月度播报）**：宿主定时任务建「技能直调」→ 选「月度经费播报」→ 手动触发；期望：任务中心出现进行中条目，进度按 `[i/n] 项目名：状态` 逐项滚动，结束后有成功结论与批次号；故意断库/无项目时为失败态且原因可读。
3. **A6-1 任务记录可追溯**：上述任务完成后，任务中心历史列表可查到该条目与终态摘要（成功/失败均有）。
4. **A9-3 多入口抽测**：①对话：「查一下我的经费执行怎么样」→ 播报文本；②数据管理：项目台账 toolbar「经费进度播报」、预警规则行按钮改阈值、播报记录 toolbar「生成经费简报」；③HTML 侧栏打开 `report-*.html` 预览后点重建；④定时入口同 A4-2。期望：各入口结果与 CLI 一致（同一内核），无入口分叉。

**P1**

5. **A4-4**：任务中心进行中条目的进度文案人工读一遍，确认 `[1/3] …：正常」可理解。
6. **A4-8**：数据管理「预警规则」行点开编辑 form，确认参数区仅阈值字段、无重复主键映射、提交正常。
7. **A6-10**：数据管理侧栏预览 HTML 简报：横向铺满、无横向滚动条；重新播报后刷新内容与页头时间。
8. **A9-5**：走 `release.ps1` 发版（或验证 v1.0.1 已在市场）：Gitea 工作流成功截图 + 技能市场对开发者可见、可安装、装后 `health` 通过；记录存入本目录。

**复验方式**：完成上述人工项后按 `acceptance-reports/README.md` 再生成一份新时间戳报告，勿覆盖本报告。

---

## 附：本轮整改记录（对照开发文档审核后已修复，测试守护）

1. 「待补录」状态标签触发条件修正（C3 触发且 D 未判 → 待补录），优先级与文档 §6.2 对齐。
2. `broadcast-monthly` 改为逐项目计算即 `emit` 增量进度（`run_broadcast(on_progress=…)`），任务中心可见进行中。
3. `progress_reports.project_id` 播报时回填（修复 render-html 重建丢金额）；新增 `items_json` 规则明细列（重建保留提醒章节）；补 `updated_at` + 触发器。
4. 旧库迁移改为重建表拷数（SQLite `ALTER ADD COLUMN` 不允许非常量默认值），含回归测试 `test_init_db_migrates_legacy_progress_reports`；真实旧库迁移实测通过（6 行历史保留）。
5. 简报 `{{TITLE}}` HTML 转义；章节顺序对齐 §10 并新增独立「暂付款 / 结题提醒」章节；页脚改为文档逐字文案。
6. 金标准补测：−10%/+20% 恰界与越界、C2 钳位、N2 反例、C3 逐字段、HTML 注入转义、三色状态灯+提醒断言、`on_progress`、project_id/items_json 落库、`broadcast-monthly` async+cron 定位表守护。
7. 文档口径统一：`ERROR:<CODE> <message>`、成功字段 `reports_brief`、`--all-status` 与 skill-detail 表外挂载补记、C1 level=warn、验收 1 明确三处版本号位置（开发文档 v1.1 + REQUIREMENTS v1.1 同步）。