# 验收记录：年度分解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，无未推送提交 ✓