feat(console): add deletion lifecycle, usage history and balance adjustments

This commit is contained in:
wlx committed 2026-09-19 21:08:45 +08:00
1 parent 32e977df5c
commit 7360cf3ebe
18 files changed
+832 -68

No files matched your search

@@ -0,0 +1,65 @@
# 目录删除、使用记录与额度调整
- 状态:实现完成,本地验收;待部署到服务器并验收。
- 负责人:Codex;产品验收:项目负责人。
- 更新时间:2026-09-19。
- 评审结论:在原有渠道、模型、分组与人民币账本上补齐生命周期操作;历史引用继续保留。
## 功能与验收标准
| 编号 | 入口 | 行为 |
| --- | --- | --- |
| LC-01 | 管理端 → 渠道管理 | 增加删除及确认弹窗;有未删除分组时阻止删除,提示先转移或删除分组。 |
| LC-02 | 管理端 → 模型与分组 | 模型和分组均可删除;删除模型会一并移除其全部分组。 |
| LC-03 | 用户端 → API Keys | 停用后可重新启用或删除;启用中的 Key 必须先停用。删除后不能从页面恢复。 |
| UH-01 | 用户端 → 任务中心 | 按使用记录显示同步调用及异步任务;统计筛选范围内的请求数、输入输出 Token、缓存、已记录人民币费用及平均耗时。 |
| UH-02 | 使用记录筛选 | 按 Key、模型、分组、状态、调用类型、请求类别、来源、费用记录状态、User-Agent、时间筛选;分页、排序、自定义列、刷新及 CSV 导出。 |
| UH-03 | 用户端 → 在线调试 → 调用历史 | 服务端持久保存的记录在刷新、重新登录后仍可查看;详情展示请求与响应,支持将文本输入和原分组载入调试。 |
| WC-01 | 管理端 → 用户与额度 → 调整额度 | 支持增加、减少、设置指定余额;人民币元,最多两位小数,目标余额可以为零,不得扣为负数。 |
| WC-02 | 用户与额度 → 额度流水 | 保留每笔增减差额、操作方式、调整原因、操作人、时间、调整前后余额。 |
删除采用数据库标记,列表和新调用入口会立即排除已删除项。已有调用、任务和额度流水保留。已删除模型/分组不能通过旧编辑接口重新启用;删除后新建同名渠道或分组取得新 ID,不继承旧 Key 授权。单纯“停用”仍可恢复。
用户只能查询、导出自己的使用记录和操作自己的 Key;管理员备注、来源 IP、凭据字段不出现在用户记录接口中。CSV 对公式前缀进行转义;最多导出 10000 条,超限要求缩小筛选范围,不静默截断。列表统计针对整个筛选结果,而非当前页。
调整额度的请求 ID 保证网络重试不会重复记账;数据库行锁串行化余额修改。页面提交时携带已看到的余额,余额被其他操作改变时要求刷新后重试。旧增加额度接口保留兼容。
## 数据边界
- 历史记录只展示服务端已经保存的数据,不能恢复升级前从未保存或已被管理员删除的记录。
- 旧调用没有端点、来源、缓存等字段时显示空缺;在线调试默认展示本账号全部历史,也可筛选“在线调试”来源。
- 本次不新增计价、实际扣费或汇率换算。费用显示已有 `cost_amount`,未记录显示“—”,不把未计费伪装成免费。金额展示以平台人民币账本为准。
- 当前 Java 网关未实现流式转发,首 Token 时延和推理强度没有数据时显示“—”,不会伪造或回填。类型筛选保留流式选项供已记录数据使用。
- 输入、输出 Token 采用现有网关记录;缓存计数仅在上游提供相应字段时采集。异步耗时包含排队,统计至任务进入终态。
- 在线调试“载入调试”仅恢复可识别的文本提示和仍存在的分组,不自动执行请求,不恢复明文 Key,也不承诺还原多轮上下文或附件。
## 接口
| 方法 | 路径 | 用途 |
| --- | --- | --- |
| DELETE | `/api/admin/providers/{id}` | 删除无关联分组的渠道 |
| DELETE | `/api/admin/model-definitions/{id}` | 删除模型及其分组 |
| DELETE | `/api/admin/models/{id}` | 删除分组 |
| PATCH | `/api/keys/{id}/status` | `status` 为 `active` 或 `disabled` |
| DELETE | `/api/keys/{id}` | 删除本人的已停用 Key |
| GET | `/api/usage` | 分页记录及同条件统计 |
| GET | `/api/usage/options` | 当前用户可筛选的 Key、模型和分组 |
| GET | `/api/usage/{id}` | 本人的调用详情 |
| GET | `/api/usage/export` | 使用相同筛选和排序导出 CSV |
| POST | `/api/admin/users/{id}/wallet/adjustments` | `requestId`、`operation`(increase/decrease/set)、`amount`、`reason`、`expectedBalance` |
## 迁移与部署
Flyway V12 增加目录/Key 删除时间、使用记录元数据、额度调整类型和前后余额;旧发放流水保留,自动标记为 increase 并计算 balance_before。运行迁移前先备份专用 `moyi_control` 数据库及原配置/证书。无需新增环境变量,继续保留 SMTP/SMS、数据库和加密配置。
新版前后端必须配套更新。V12 之后不要仅切换旧应用镜像:旧程序不了解删除标记,并且旧额度写入不满足新版账本字段约束。需要回退时使用升级前数据库备份和配套旧应用/配置,事先确认恢复备份会丢失备份后的写入。部署步骤见 `11-server-test-deployment.md`。
## 本地验证
隔离 PostgreSQL 位于 `127.0.0.1:55439`,测试按随机 schema 隔离。页面验收使用本机 `127.0.0.1:8788` / `5178` 与专用 schema,所有账号、Key 和使用记录均为本地验收数据,未连接云数据库或发送真实邮件/短信。
- Java:Maven clean verify;生命周期权限、删除后认证拒绝、历史引用保留、负余额拒绝、余额并发及幂等、使用记录分页/过滤/CSV、跨用户隔离、元数据采集、异步终态耗时。
- 前端:vue-tsc 类型检查与 Vite 构建。
- 浏览器:设置余额 100 元后扣减 25.50 元得到 74.50 元,流水前后余额正确;Key 停用/重新启用/删除;23 条使用记录分页及失败筛选;自定义列和 CSV;历史详情和输入恢复;删除渠道时关联检查;删除分组、模型后成功删除渠道,历史仍保留。
真实供应商计费、流式转发与公网升级不属于本次本地验收。页面中的费用样例仅在隔离测试库生成。