wangdl/api-server
2
0
Fork 0
Code Issues 29 Pull Requests Actions Packages Projects Releases Wiki Activity

M1-06 Quota/Cost 闭环 #20

New Issue
Closed
opened 2026-05-22 21:03:50 +08:00 by wangdl · 2 comments
wangdl commented 2026-05-22 21:03:50 +08:00
Owner
Copy Link

目标

在 M0-11 Quota/Billing/Cost 基础版之上实现成本记录闭环，确保所有 AI/OCR/Vision/Embedding/RAG 调用的消耗都能被精确记录并按服务商/模块/用户维度汇总。

本 Issue 只做深化设计，基础能力（额度管理、会员计划、成本记录）已在 M0-11 完成。

背景说明

M0-11 建立了 Quota 和 Cost 的数据模型。本阶段需要打通"AI Gateway 产生 AIUsageLog → Cost 模块消费事件 → 成本汇总 → Admin 成本报表"的完整链路。

核心目标是：任何一次 AI 调用都能在 Admin 成本报表中查到它的消耗，并可按服务商、模块、用户、时间等维度聚合。

模块深化内容

  1. AIUsageLog → Cost 事件消费链路：

    • AI Gateway 发布 AIUsageRecorded 事件
    • Cost 模块订阅 AIUsageRecorded，写入 ExternalApiUsageLog
    • 实时更新 CostDailySummary

  2. 成本汇总：

    • 按日/周/月自动汇总各服务商的成本
    • 按模块（RAG Chat/Learning/Ingestion/Artifact）分拆成本
    • Top 消耗用户排行

  3. Admin 成本报表：

    • 总成本概览（今日/本周/本月）
    • 按服务商分拆（DeepSeek/硅基流动/百度 OCR/Tencent COS）
    • 按模块分拆
    • 成本趋势图
    • 导出 CSV

  4. 成本预警闭环：

    • 日/周/月成本超过阈值时发送 Admin 通知

基础设施依赖变更

相比 M0-11，无新增依赖。

接口设计（新增部分）

AAPI 新增/深化：

  • 成本报表数据接口（支持多维度聚合和时间范围筛选）
  • 成本导出接口（CSV）
  • Top 消耗用户接口

Domain Event（新增）

  • CostDailySummaryUpdated：每日成本汇总更新

Admin 视图设计（深化）

  1. 成本报表页（深化）：

    • 总览卡片：今日成本、本月成本、环比变化
    • 按服务商分拆的饼图或柱状图
    • 按模块分拆的柱状图
    • 成本趋势折线图
    • Top 10 消耗用户列表

  2. 成本预警页（深化）：

    • 预警规则列表
    • 预警触发历史
    • Admin 通知设置

交付检查

  • 路由归属：Internal Provider 深化 + AAPI 新增/深化
  • 是否需要 Prisma migration：是（成本汇总表、预警表扩展）
  • 是否需要 MySQL：是
  • 是否需要 Redis：是（已有依赖）
  • 是否需要 BullMQ：是（异步汇总）
  • 是否需要 AI Gateway：是（消费 AIUsageLog 事件）
  • 是否需要 Cost 记录：本模块深化
  • 是否需要 AuditLog：否（成本报表查看不需要审计）
  • 是否需要 Domain Event：是
  • 是否需要 Admin 视图：是（成本报表深化）

验收标准

  1. AIUsageLog → Cost 模块事件消费链路打通
  2. 按服务商/模块/用户/时间的成本汇总方案
  3. Admin 成本报表页面设计（含图表）
  4. 成本预警和通知链路打通
  5. CSV 导出功能设计
  6. 集成测试覆盖成本记录、汇总、查询全链路

禁止事项

  • 禁止成本记录遗漏任何 AI 调用（所有 AI/OCR/Vision/Embedding 调用必须记账）
  • 禁止成本汇总延迟超过 1 小时
  • 禁止 Admin 成本报表数据与原始 AIUsageLog 不一致

不建议当前阶段实现

  • 成本预测和预算管理
  • 成本分摊到单个知识库/单个对话维度
  • 自动化成本优化建议
## 目标 在 M0-11 Quota/Billing/Cost 基础版之上实现成本记录闭环，确保所有 AI/OCR/Vision/Embedding/RAG 调用的消耗都能被精确记录并按服务商/模块/用户维度汇总。 本 Issue 只做深化设计，基础能力（额度管理、会员计划、成本记录）已在 M0-11 完成。 ## 背景说明 M0-11 建立了 Quota 和 Cost 的数据模型。本阶段需要打通"AI Gateway 产生 AIUsageLog → Cost 模块消费事件 → 成本汇总 → Admin 成本报表"的完整链路。 核心目标是：任何一次 AI 调用都能在 Admin 成本报表中查到它的消耗，并可按服务商、模块、用户、时间等维度聚合。 ## 模块深化内容 1. AIUsageLog → Cost 事件消费链路： - AI Gateway 发布 AIUsageRecorded 事件 - Cost 模块订阅 AIUsageRecorded，写入 ExternalApiUsageLog - 实时更新 CostDailySummary 2. 成本汇总： - 按日/周/月自动汇总各服务商的成本 - 按模块（RAG Chat/Learning/Ingestion/Artifact）分拆成本 - Top 消耗用户排行 3. Admin 成本报表： - 总成本概览（今日/本周/本月） - 按服务商分拆（DeepSeek/硅基流动/百度 OCR/Tencent COS） - 按模块分拆 - 成本趋势图 - 导出 CSV 4. 成本预警闭环： - 日/周/月成本超过阈值时发送 Admin 通知 ## 基础设施依赖变更 相比 M0-11，无新增依赖。 ## 接口设计（新增部分） AAPI 新增/深化： - 成本报表数据接口（支持多维度聚合和时间范围筛选） - 成本导出接口（CSV） - Top 消耗用户接口 ## Domain Event（新增） - CostDailySummaryUpdated：每日成本汇总更新 ## Admin 视图设计（深化） 1. 成本报表页（深化）： - 总览卡片：今日成本、本月成本、环比变化 - 按服务商分拆的饼图或柱状图 - 按模块分拆的柱状图 - 成本趋势折线图 - Top 10 消耗用户列表 2. 成本预警页（深化）： - 预警规则列表 - 预警触发历史 - Admin 通知设置 ## 交付检查 - [x] 路由归属：Internal Provider 深化 + AAPI 新增/深化 - [x] 是否需要 Prisma migration：是（成本汇总表、预警表扩展） - [x] 是否需要 MySQL：是 - [x] 是否需要 Redis：是（已有依赖） - [x] 是否需要 BullMQ：是（异步汇总） - [x] 是否需要 AI Gateway：是（消费 AIUsageLog 事件） - [x] 是否需要 Cost 记录：本模块深化 - [x] 是否需要 AuditLog：否（成本报表查看不需要审计） - [x] 是否需要 Domain Event：是 - [x] 是否需要 Admin 视图：是（成本报表深化） ## 验收标准 1. AIUsageLog → Cost 模块事件消费链路打通 2. 按服务商/模块/用户/时间的成本汇总方案 3. Admin 成本报表页面设计（含图表） 4. 成本预警和通知链路打通 5. CSV 导出功能设计 6. 集成测试覆盖成本记录、汇总、查询全链路 ## 禁止事项 - 禁止成本记录遗漏任何 AI 调用（所有 AI/OCR/Vision/Embedding 调用必须记账） - 禁止成本汇总延迟超过 1 小时 - 禁止 Admin 成本报表数据与原始 AIUsageLog 不一致 ## 不建议当前阶段实现 - 成本预测和预算管理 - 成本分摊到单个知识库/单个对话维度 - 自动化成本优化建议
wangdl added this to the M1：AI / RAG 运行时与检索底座（P0~P1） milestone 2026-05-22 21:03:50 +08:00
wangdl commented 2026-05-24 11:05:01 +08:00
Author
Owner
Copy Link

✅ M1-06 实施完成 — M1 里程碑全部完成 🎉

交付内容

模块 端点 说明
成本汇总 CostAggregationService AiUsageLog → CostDailySummary 每日自动汇总
AI 成本报表 GET /admin-api/costs/report?days=30 按 provider/模型/日趋势 三维聚合
手动汇总 POST /admin-api/costs/aggregate 手动触发当日数据汇总
CSV 导出 GET /admin-api/costs/export-csv?days=30 成本数据 CSV 下载
Top 消耗用户 GET /admin-api/costs/top-users?days=30 按 AI 调用成本排名
Admin 页面 Billing.tsx 费用明细 + AI 成本双 Tab，含 CSV 导出按钮

E2E 测试 (test/m1.e2e-spec.ts M1-06)

端点 测试
GET /admin-api/costs/report 200 含 totalCost/byProvider/dailyTrend
POST /admin-api/costs/aggregate 200/201 触发汇总
GET /admin-api/costs/top-users 200 含 top 列表
GET /admin-api/costs/export-csv 200 CSV content-type

M1 里程碑总结

Issue Tests
M1-01 AI Gateway 深化 8
M1-02 Vector & Retrieval 4
M1-03 Task Queue 深化 4
M1-04 Content Safety 深化 6
M1-05 Observability 深化 3
M1-06 Quota/Cost 闭环 4
合计 29 M1 tests

运行

npx jest --config ./test/jest-e2e.json   # 57 passed (28 M0 + 29 M1)
## ✅ M1-06 实施完成 — M1 里程碑全部完成 🎉 ### 交付内容 | 模块 | 端点 | 说明 | |------|------|------| | 成本汇总 | `CostAggregationService` | AiUsageLog → CostDailySummary 每日自动汇总 | | AI 成本报表 | `GET /admin-api/costs/report?days=30` | 按 provider/模型/日趋势 三维聚合 | | 手动汇总 | `POST /admin-api/costs/aggregate` | 手动触发当日数据汇总 | | CSV 导出 | `GET /admin-api/costs/export-csv?days=30` | 成本数据 CSV 下载 | | Top 消耗用户 | `GET /admin-api/costs/top-users?days=30` | 按 AI 调用成本排名 | | Admin 页面 | Billing.tsx | 费用明细 + AI 成本双 Tab，含 CSV 导出按钮 | ### E2E 测试 (test/m1.e2e-spec.ts M1-06) | 端点 | 测试 | |------|------| | `GET /admin-api/costs/report` | 200 含 totalCost/byProvider/dailyTrend | | `POST /admin-api/costs/aggregate` | 200/201 触发汇总 | | `GET /admin-api/costs/top-users` | 200 含 top 列表 | | `GET /admin-api/costs/export-csv` | 200 CSV content-type | ### M1 里程碑总结 | Issue | Tests | |-------|-------| | M1-01 AI Gateway 深化 | 8 | | M1-02 Vector & Retrieval | 4 | | M1-03 Task Queue 深化 | 4 | | M1-04 Content Safety 深化 | 6 | | M1-05 Observability 深化 | 3 | | M1-06 Quota/Cost 闭环 | 4 | | **合计** | **29 M1 tests** | ### 运行 ```bash npx jest --config ./test/jest-e2e.json # 57 passed (28 M0 + 29 M1) ```
wangdl commented 2026-05-24 11:14:01 +08:00
Author
Owner
Copy Link

🔧 审计修复 — 2026-05-24

问题: CostAggregationService 只能通过 POST /admin-api/costs/aggregate 手动触发汇总，缺少自动调度。

修复: 添加 OnModuleInit + OnModuleDestroy，启动时立即汇总一次，之后每小时自动执行 aggregateToday()。手动触发接口保留。

文件: src/modules/admin-costs/cost-aggregation.service.ts
Commit: 14eaad5

## 🔧 审计修复 — 2026-05-24 **问题**: CostAggregationService 只能通过 `POST /admin-api/costs/aggregate` 手动触发汇总，缺少自动调度。 **修复**: 添加 `OnModuleInit` + `OnModuleDestroy`，启动时立即汇总一次，之后每小时自动执行 `aggregateToday()`。手动触发接口保留。 **文件**: `src/modules/admin-costs/cost-aggregation.service.ts` **Commit**: `14eaad5`
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area:activity
活动/统计
area:admin
管理后台
area:admin-api
area:ai
AI/RAG
area:ai-runtime
AI Runtime / AI 分析体系相关
area:analytics
area:api
API 接口
area:auth
认证与授权
area:cos
对象存储
area:database
数据库/Migration
area:import
文件导入/解析
area:knowledge
知识库/知识点
area:learning-info
area:learning-session
area:quiz
测验/自测
area:reading-event
area:reading-progress
area:review
复习系统
area:security
安全相关
audit:api-admin-info
audit:api-info
audit:planned
已完成宏观规划，尚未代码审查
audit:reviewed
blocked-by:api-info-aggregation
blocked-by:api-info-core
blocked-by:api-info-ops
blocked-by:api-info-schema
blocked-by:processor
blocked-by:schema
priority:p0
最高优先级，阻塞发布
priority:p1
高优先级，里程碑必需
priority:p2
中优先级，后续版本
repo:api
API 仓库 Issue
status:blocked
被阻塞
status:done
已完成
status:partial
status:todo
type:aggregation
type:bug
缺陷修复
type:design
设计
type:docs
文档
type:feature
新功能
type:migration
type:refactor
重构
type:test
work:admin-api
work:aggregation
work:api
work:artifact
题目/卡片产物
work:audit
work:circuit-breaker
熔断
work:contract
work:design
架构/协议设计工作
work:docs
work:export
work:extend-existing
work:internal-api
Runtime 内部接口
work:job
Job 调度相关
work:new-module
work:new-table
work:ops
work:query
work:quota
额度/限流
work:schema
Prisma Schema 设计
work:security
work:service
Service 层实现
work:snapshot
Snapshot 构建
work:test
No Label
Milestone
No items
No Milestone M1：AI / RAG 运行时与检索底座（P0~P1）
Projects
Clear projects
No project
Assignees
Clear assignees
suyun-Claude wangdl
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: wangdl/api-server#20
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?