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