From 9ea0fbea5ff0bce00625d8f8acde9f7b349655a1 Mon Sep 17 00:00:00 2001
From: lxm <1274844347@qq.com>
Date: Mon, 17 Nov 2025 16:13:22 +0800
Subject: [PATCH] =?UTF-8?q?refactor(goods):=20=E5=B0=86Trade=E4=BD=BF?=
 =?UTF-8?q?=E7=94=A8=E7=B1=BB=E5=9E=8B=E9=87=8D=E5=91=BD=E5=90=8D=E4=B8=BA?=
 =?UTF-8?q?Translation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

更新商品相关枚举和控制器，将Trade使用类型统一更名为Translation以更准确描述其用途
---
 lib/data/models/goods.dart                    | 14 ++++----
 lib/data/services/network/api.dart            | 32 ++++++++++++++++++-
 .../controllers/goodstrade_controller.dart    |  4 +--
 3 files changed, 40 insertions(+), 10 deletions(-)

diff --git a/lib/data/models/goods.dart b/lib/data/models/goods.dart
index 99485eafe..bda3a6c37 100644
--- a/lib/data/models/goods.dart
+++ b/lib/data/models/goods.dart
@@ -6,7 +6,7 @@ enum UsageType {
   /// 未知使用量类型
   UsageNull, // 0
   /// 翻译
-  Trade, // 1
+  Translation, // 1
   /// 会议
   Meet, // 2
   /// 智能体
@@ -19,7 +19,7 @@ enum UsageType {
         case 0:
           return UsageType.UsageNull;
         case 1:
-          return UsageType.Trade;
+          return UsageType.Translation;
         case 2:
           return UsageType.Meet;
         case 3:
@@ -36,8 +36,8 @@ enum UsageType {
         case 'null':
         case 'unknown':
           return UsageType.UsageNull;
-        case 'trade':
-          return UsageType.Trade;
+        case 'translation':
+          return UsageType.Translation;
         case 'meet':
         case 'meeting':
           return UsageType.Meet;
@@ -54,7 +54,7 @@ enum UsageType {
     switch (this) {
       case UsageType.UsageNull:
         return 0;
-      case UsageType.Trade:
+      case UsageType.Translation:
         return 1;
       case UsageType.Meet:
         return 2;
@@ -67,8 +67,8 @@ enum UsageType {
     switch (this) {
       case UsageType.UsageNull:
         return 'UsageNull';
-      case UsageType.Trade:
-        return 'Trade';
+      case UsageType.Translation:
+        return 'Translation';
       case UsageType.Meet:
         return 'Meet';
       case UsageType.AI:
diff --git a/lib/data/services/network/api.dart b/lib/data/services/network/api.dart
index e405bd87f..ca56fc8a5 100644
--- a/lib/data/services/network/api.dart
+++ b/lib/data/services/network/api.dart
@@ -244,7 +244,37 @@ class Api {
     );
   }
 
-  //资源使用请求
+  /// 资源使用上报（`/api/home/user_usages`）
+  ///
+  /// 用途：在 AI 聊天等场景中，上报本次会话的消耗与功能调用次数，服务端据此统计并更新积分。
+  ///
+  /// 请求方式：`POST /api/home/user_usages`
+  ///
+  /// 认证：已通过全局拦截器自动携带 `Authorization`（见 `AuthInterceptor`）。
+  ///
+  /// 参数（`params`）结构：
+  /// - `usagetype`：`int` 类型，使用场景类型；Android 端 Agent 使用 `3` 表示 AICHAT。
+  /// - `usages`：`Map<String, int>`，各项指标的键值对，例如：
+  ///   - `AICHAT_PROMPT_TOKENS`：本次对话的提示词 Token 数
+  ///   - `AICHAT_COMPLETION_TOKENS`：本次对话的生成 Token 数
+  ///   - `AICHAT_FUNCTION_{函数名}`：被调用的函数次数（按函数名累加）
+  ///
+  /// 返回：标准封装后 `code == 0` 时返回 `data`。其中 `data.usages` 可能包含键 `"3"`，表示最新的 AI 积分值。
+  ///
+  /// 使用示例：
+  /// ```dart
+  /// final params = {
+  ///   'usagetype': 3, // AICHAT
+  ///   'usages': {
+  ///     'AICHAT_PROMPT_TOKENS': 120,
+  ///     'AICHAT_COMPLETION_TOKENS': 256,
+  ///     'AICHAT_FUNCTION_toolX': 1,
+  ///   }
+  /// };
+  /// final data = await Api.usagesResPoints(params);
+  /// final usages = (data['usages'] as Map?)?.cast<String, dynamic>();
+  /// final aiIntegral = usages?['3']; // 服务端返回的最新 AI 积分（如有）
+  /// ```
   static usagesResPoints([params]) {
     return DioManager().request(
       NWMethod.post,
diff --git a/lib/modules/goods/controllers/goodstrade_controller.dart b/lib/modules/goods/controllers/goodstrade_controller.dart
index 871241f9c..d0a218c5b 100644
--- a/lib/modules/goods/controllers/goodstrade_controller.dart
+++ b/lib/modules/goods/controllers/goodstrade_controller.dart
@@ -7,7 +7,7 @@ import 'goods_base_controller.dart';
 class GoodstradeController extends GoodsBaseController {
   @override
   Future<List<DBGoods>> fetchProducts() async {
-    final resp = await Api.getGoods({'usagetype': UsageType.Trade.toInt});
+    final resp = await Api.getGoods({'usagetype': UsageType.Translation.toInt});
     if (resp == null || resp is! Map) return [];
     if (resp.containsKey('error') || resp.containsKey('msg')) {
       final msg = resp['error'] ?? resp['msg'] ?? '服务器错误';
@@ -21,7 +21,7 @@ class GoodstradeController extends GoodsBaseController {
     if (data is List) {
       final list =
           data.whereType<Map<String, dynamic>>().map(DBGoods.fromJson).toList();
-      return list.where((g) => g.usagetype == UsageType.Trade).toList();
+      return list.where((g) => g.usagetype == UsageType.Translation).toList();
     }
     return [];
   }