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

6.1 KiB
Raw Blame History

目录删除、使用记录与额度调整

  • 状态:实现完成,本地验收;待部署到服务器并验收。
  • 负责人: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;历史详情和输入恢复;删除渠道时关联检查;删除分组、模型后成功删除渠道,历史仍保留。

真实供应商计费、流式转发与公网升级不属于本次本地验收。页面中的费用样例仅在隔离测试库生成。