PushToZhaoShang/数据修正使用说明.md

数据修正使用说明

目的

• 指导如何在不暴露修正过程的前提下，修正某天营业额数据，并确保前端即时一致更新。
• 所有修正与生成均写入审计表和 app.log，便于稽核与追踪。

前置准备

• 在项目根目录创建或编辑 .env，设置管理口令：
  • ADMIN_TOKEN=你的口令
• 后端运行于 http://localhost:5000（Docker 或本地均可）。

修正接口

• URL：PUT /api/admin/turnover
• 鉴权：请求头 X-Admin-Token: <你的口令>（来自 .env）
• Content-Type：application/json
• 请求体：
  • date：YYYY-MM-DD
  • amount：数值（营业额）
  • reason：字符串（修正原因）
  • actor：可选，执行者标识

请求示例

• curl（Windows PowerShell 请使用完整双引号并转义）：

curl -X PUT http://localhost:5000/api/admin/turnover ^
  -H "Content-Type: application/json" ^
  -H "X-Admin-Token: <你的口令>" ^
  -d "{\"date\":\"2025-12-06\",\"amount\":3123.45,\"reason\":\"调整入账\"}"

• PowerShell（推荐）：

$body = @{ date = "2025-12-06"; amount = 3123.45; reason = "调整入账" } | ConvertTo-Json
Invoke-RestMethod -Method Put -Uri "http://localhost:5000/api/admin/turnover" -Headers @{"X-Admin-Token"="<你的口令>"} -ContentType "application/json" -Body $body

• Postman：
  • Method: PUT；URL: http://localhost:5000/api/admin/turnover
  • Headers: X-Admin-Token: <你的口令>；Content-Type: application/json
  • Body(JSON)：{"date":"2025-12-06","amount":3123.45,"reason":"调整入账"}

成功结果与前端效果

• 接口返回：{"ok": true}
• 后端行为：
  • 写入/更新 daily_revenue 对应日期的记录，并置 is_final=true
  • 写入 audit_log 审计记录
  • 追加一行到 app.log（与历史格式一致）
• 前端：每 60 秒轮询 GET /api/metrics 与 GET /api/series7，修正后下一次轮询即可显示新值；修正过程不在前端展示。

生成与定版规则（一致性）

• 每天本地时间 23:00 自动生成并定版当日数据（is_final=true）。
• 已定版的数据不会被定时任务覆盖；如需变更，请使用修正接口。
• CSV 导出仅包含已定版数据。

审计与回滚

• 审计表：audit_log
  • 字段：date、old_amount、new_amount、reason、actor、type(generate/correct/import_log)、created_at
• 回滚方式：再次调用修正接口，将 amount 改回目标值，并注明 reason（例如：回滚）。

常见问题

• 401 未授权：检查 .env 中 ADMIN_TOKEN 与请求头 X-Admin-Token 是否一致。
• 前端未更新：等待轮询或手动刷新；确保后端正在运行并能访问 GET /api/metrics 与 GET /api/series7。
• 时间与周次显示不符：系统按本地时区与“周一为周起、周日为周止”的规则计算区间。

相关接口（只读）

• 指标：GET /api/metrics（含 today：日期与周几；未到 23:00 或未定版则 amount=null）
• 7 日序列：GET /api/series7（今日定版后纳入，否则截止到昨日）
• 导出：GET /api/export（仅包含已定版数据）