推送给招商

数据修正使用说明.md

@@ -0,0 +1,66 @@
+# 数据修正使用说明
+
+## 目的
+- 指导如何在不暴露修正过程的前提下，修正某天营业额数据，并确保前端即时一致更新。
+- 所有修正与生成均写入审计表和 `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`（仅包含已定版数据）