chore(docs): 提交项目级 AGENTS.md 与既有验收记录 (cashflow-structure 部署前置)

docs/verification/budget-decompose-400-hint-20260831.md

@@ -0,0 +1,43 @@
+# 验收记录：年度分解400错误提示优化（budget-decompose-400-hint）
+
+- **任务**: budget-decompose-400-hint-20260831.md
+- **执行人**: wecom-fullstack（全栈Bot）
+- **完成时间**: 2026-08-31 20:0x CST（本会话补齐验收）
+- **Commit**: 9cccaa6cfc6ad309c11c4f7f68009b2a43c92800（fix(budget): 年度分解400提示优化——含可用年份+双路径引导）
+- **状态**: ✅ 通过（代码修改由 18:28 会话提交推送，本会话完成独立验收）
+
+## 输出物证据
+
+### 输出物1：budget.py 400提示优化（可用年份+双路径）
+grep 命中：
+- 行225: `avail_years = [r[0] for r in db.query(distinct(BudgetPlan.budget_year)).filter(...)`（entity_id + period LIKE %-00 + status active）
+- 行231-232: `if avail_years:` → `hint += f"；现有年度数据年份：{', '.join(...)}"`
+- 行233: `hint += "。请先在预算录入中填写该年度预算总额，或改用战略预算编制按地图录入；如需按已有月度数据反向生成请咨询管理员。"`
+
+### 输出物2：单KPI缺参400提示
+- 行307: `raise HTTPException(400, "缺少必要参数: annual_budget（单KPI分解需传年度预算值）")`
+
+### 输出物3：后端重启
+- systemd cma-backend ActiveState=active，ActiveEnterTimestamp=2026-08-31 18:28:25（commit 9cccaa6 提交 18:28:11 后由 CI deploy hook 自动重启）
+- `GET http://127.0.0.1:8010/health` → `{"status":"ok","version":"1.0.0"}` (200)
+
+### 输出物4：实测提示（API 真实调用）
+- entity_id=1 + year=2025 → 400：
+  `该年度(2025)没有年度预算总额（period=YYYY-00）；现有年度数据年份：2026。请先在预算录入中填写该年度预算总额，或改用战略预算编制按地图录入；如需按已有月度数据反向生成请咨询管理员。`
+  ✅ 含可用年份(2026) + 双路径引导
+- entity_id=2（陕西博海）+ year=2026 → 400：
+  `该年度(2026)没有年度预算总额（period=YYYY-00）。请先在预算录入中填写该年度预算总额，或改用战略预算编制按地图录入；如需按已有月度数据反向生成请咨询管理员。`
+  ✅ 含双路径引导（博海无年度行，avail_years 为空 → 无年份列表，符合预期）
+- entity_id=1 + year=2026 → 200：`批量分解完成：4个KPI`（成功路径未受影响）
+- 单KPI缺参（kpi_id=5 不传 annual_budget）→ 400：`缺少必要参数: annual_budget（单KPI分解需传年度预算值）` ✅
+
+### 输出物5：pytest 全量回归
+- `venv/bin/python3 -m pytest tests/ -q` → **711 passed, 1 xfailed**（基线 711 passed / 1 xfailed，全绿）
+
+### 输出物6（可选）：前端错误提示样式
+- 本期未做（任务建议本期只做后端提示，前端 doDecompose catch 已显示 e.detail 自动受益）
+
+## 风险点核对
+- 成功路径（200）未改动：entity_id=1 year=2026 实测 200 正常 ✓
+- git commit 只含本次文件：9cccaa6 仅改 backend/app/api/budget.py（13 insertions, 2 deletions）✓
+- HEAD == origin/main，无未推送提交 ✓