# 数据修正使用说明

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