Files
moyi-model-intelligence-hub/docs/14-lifecycle-usage-credit-adjustments.md

66 lines
6.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 目录删除、使用记录与额度调整
- 状态:实现完成,本地验收;待部署到服务器并验收。
- 负责人: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;历史详情和输入恢复;删除渠道时关联检查;删除分组、模型后成功删除渠道,历史仍保留。
真实供应商计费、流式转发与公网升级不属于本次本地验收。页面中的费用样例仅在隔离测试库生成。