Version: 0.6.6.dev.260317

✨ feat(task,agent): 新增任务完成接口，并打通聊天全链路 Token 记账 - ✅ 新增“标记任务为完成”接口，并补充幂等保护，避免重复完成导致状态污染 - 📊 为聊天链路补充 Token 统计能力： - 流式主对话链路直接读取模型 `usage` - Agent 链路通过 `Eino callback + ctx` 聚合 `Generate usage` - 在流式场景下补齐缺失的 `usage` 数据 - 🧾 按口径 B 完成 Token 落库： - 用户消息 `token` 记为 `0` - 助手消息记录本轮总 `token` - 持久化时同步更新 `chat_histories.tokens_consumed`、`agent_chats.tokens_total`、`users.token_usage` - 🔄 异步标题生成产生的 Token 通过 Outbox 事件完成账本增量调整，保证统计口径一致 - 📝 同步更新 `AGENTS.md` 与 `.gitignore` - 📚 小幅更新 README 说明文档
2026-03-17 18:23:07 +08:00
parent 09dca9f772
commit 96be3e2a02
19 changed files with 660 additions and 36 deletions
--- a/backend/dao/agent.go
+++ b/backend/dao/agent.go
@@ -33,22 +33,32 @@ func (r *AgentDAO) WithTx(tx *gorm.DB) *AgentDAO {
 // 失败处理：
 // 1. 任一步骤失败都返回 error；
 // 2. 若调用方处于事务中，返回 error 会触发事务回滚。
-func (a *AgentDAO) saveChatHistoryCore(ctx context.Context, userID int, conversationID string, role, message string) error {
+func (a *AgentDAO) saveChatHistoryCore(ctx context.Context, userID int, conversationID string, role, message string, tokensConsumed int) error {
+	// 0. token 入库前兜底：负数统一归零，避免异常值污染累计统计。
+	if tokensConsumed < 0 {
+		tokensConsumed = 0
+	}
+
 	// 1. 先写 chat_histories 原始消息。
 	userChat := model.ChatHistory{
 		UserID:         userID,
 		MessageContent: &message,
 		Role:           &role,
 		ChatID:         conversationID,
+		TokensConsumed: tokensConsumed,
 	}
 	if err := a.db.WithContext(ctx).Create(&userChat).Error; err != nil {
 		return err
 	}

-	// 2. 再更新会话统计（message_count +1, last_message_at=now）。
+	// 2. 再更新会话统计：
+	// 2.1 message_count +1，保持和 chat_histories 行数口径一致；
+	// 2.2 tokens_total 累加本条消息 token；
+	// 2.3 last_message_at 刷新为当前时间，供会话排序使用。
 	now := time.Now()
 	updates := map[string]interface{}{
 		"message_count":   gorm.Expr("message_count + ?", 1),
+		"tokens_total":    gorm.Expr("tokens_total + ?", tokensConsumed),
 		"last_message_at": &now,
 	}
 	result := a.db.WithContext(ctx).Model(&model.AgentChat{}).
@@ -61,6 +71,23 @@ func (a *AgentDAO) saveChatHistoryCore(ctx context.Context, userID int, conversa
 		// 会话不存在时直接失败，避免出现“孤儿历史消息”。
 		return fmt.Errorf("conversation not found when updating stats: user_id=%d chat_id=%s", userID, conversationID)
 	}
+
+	// 3. 最后更新 users.token_usage（同一事务内）：
+	// 3.1 只在 tokensConsumed>0 时执行，避免无意义写入；
+	// 3.2 和 chat_histories/agent_chats 放在同一事务里，保证统计口径原子一致；
+	// 3.3 若用户行不存在则返回错误，触发事务回滚，防止出现“会话统计成功但用户统计丢失”。
+	if tokensConsumed > 0 {
+		userUpdate := a.db.WithContext(ctx).
+			Model(&model.User{}).
+			Where("id = ?", userID).
+			Update("token_usage", gorm.Expr("token_usage + ?", tokensConsumed))
+		if userUpdate.Error != nil {
+			return userUpdate.Error
+		}
+		if userUpdate.RowsAffected == 0 {
+			return fmt.Errorf("user not found when updating token usage: user_id=%d", userID)
+		}
+	}
 	return nil
 }

@@ -69,8 +96,8 @@ func (a *AgentDAO) saveChatHistoryCore(ctx context.Context, userID int, conversa
 // 设计目的：
 // 1. 给服务层组合多个 DAO 操作时复用，避免嵌套事务；
 // 2. 让 outbox 消费处理器可以和业务写入共享同一个 tx。
-func (a *AgentDAO) SaveChatHistoryInTx(ctx context.Context, userID int, conversationID string, role, message string) error {
-	return a.saveChatHistoryCore(ctx, userID, conversationID, role, message)
+func (a *AgentDAO) SaveChatHistoryInTx(ctx context.Context, userID int, conversationID string, role, message string, tokensConsumed int) error {
+	return a.saveChatHistoryCore(ctx, userID, conversationID, role, message, tokensConsumed)
 }

 // SaveChatHistory 在同步直写路径下写入聊天历史。
@@ -78,9 +105,58 @@ func (a *AgentDAO) SaveChatHistoryInTx(ctx context.Context, userID int, conversa
 // 说明：
 // 1. 该方法会自行开启事务；
 // 2. 内部复用 saveChatHistoryCore，确保和 SaveChatHistoryInTx 的业务口径完全一致。
-func (a *AgentDAO) SaveChatHistory(ctx context.Context, userID int, conversationID string, role, message string) error {
+func (a *AgentDAO) SaveChatHistory(ctx context.Context, userID int, conversationID string, role, message string, tokensConsumed int) error {
 	return a.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
-		return a.WithTx(tx).saveChatHistoryCore(ctx, userID, conversationID, role, message)
+		return a.WithTx(tx).saveChatHistoryCore(ctx, userID, conversationID, role, message, tokensConsumed)
+	})
+}
+
+// adjustTokenUsageCore 在同一事务语义下做“会话+用户”token 账本增量调整。
+//
+// 职责边界：
+// 1. 只更新 agent_chats.tokens_total 与 users.token_usage；
+// 2. 不写 chat_histories（消息落库由 SaveChatHistory* 路径负责）；
+// 3. deltaTokens<=0 时视为无操作，直接返回。
+func (a *AgentDAO) adjustTokenUsageCore(ctx context.Context, userID int, conversationID string, deltaTokens int) error {
+	if deltaTokens <= 0 {
+		return nil
+	}
+
+	// 1. 先更新会话累计 token。
+	chatUpdate := a.db.WithContext(ctx).
+		Model(&model.AgentChat{}).
+		Where("user_id = ? AND chat_id = ?", userID, conversationID).
+		Update("tokens_total", gorm.Expr("tokens_total + ?", deltaTokens))
+	if chatUpdate.Error != nil {
+		return chatUpdate.Error
+	}
+	if chatUpdate.RowsAffected == 0 {
+		return fmt.Errorf("conversation not found when adjusting tokens: user_id=%d chat_id=%s", userID, conversationID)
+	}
+
+	// 2. 再更新用户累计 token。
+	userUpdate := a.db.WithContext(ctx).
+		Model(&model.User{}).
+		Where("id = ?", userID).
+		Update("token_usage", gorm.Expr("token_usage + ?", deltaTokens))
+	if userUpdate.Error != nil {
+		return userUpdate.Error
+	}
+	if userUpdate.RowsAffected == 0 {
+		return fmt.Errorf("user not found when adjusting token usage: user_id=%d", userID)
+	}
+	return nil
+}
+
+// AdjustTokenUsageInTx 在调用方已开启事务时执行 token 账本增量调整。
+func (a *AgentDAO) AdjustTokenUsageInTx(ctx context.Context, userID int, conversationID string, deltaTokens int) error {
+	return a.adjustTokenUsageCore(ctx, userID, conversationID, deltaTokens)
+}
+
+// AdjustTokenUsage 在同步路径下执行 token 账本增量调整（内部自带事务）。
+func (a *AgentDAO) AdjustTokenUsage(ctx context.Context, userID int, conversationID string, deltaTokens int) error {
+	return a.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		return a.WithTx(tx).adjustTokenUsageCore(ctx, userID, conversationID, deltaTokens)
 	})
 }

--- a/backend/dao/task.go
+++ b/backend/dao/task.go
@@ -2,6 +2,7 @@ package dao

 import (
 	"context"
+	"errors"
 	"time"

 	"github.com/LoveLosita/smartflow/backend/model"
@@ -45,6 +46,76 @@ func (dao *TaskDAO) GetTasksByUserID(userID int) ([]model.Task, error) {
 	return tasks, nil
 }

+// CompleteTaskByID 将指定任务标记为“已完成”。
+//
+// 职责边界：
+// 1. 只负责“当前用户 + 指定 task_id”的完成状态更新；
+// 2. 不负责幂等中间件（由路由层统一挂载）；
+// 3. 不负责业务层响应包装（由 Service 层处理）。
+//
+// 返回语义：
+//  1. 第一个返回值 *model.Task：返回更新后的任务快照（至少含 ID/UserID/IsCompleted）；
+//  2. 第二个返回值 bool：
+//     2.1 true：任务原本就已完成，本次属于幂等命中；
+//     2.2 false：本次从未完成成功更新为已完成；
+//  3. error：
+//     3.1 gorm.ErrRecordNotFound：任务不存在或不属于当前用户；
+//     3.2 其他 error：数据库异常。
+func (dao *TaskDAO) CompleteTaskByID(ctx context.Context, userID int, taskID int) (*model.Task, bool, error) {
+	// 1. 基础兜底：非法参数直接返回“记录不存在”语义，避免下游误写。
+	if userID <= 0 || taskID <= 0 {
+		return nil, false, gorm.ErrRecordNotFound
+	}
+
+	// 2. 先查询目标任务，明确区分“已完成”与“不存在”。
+	var target model.Task
+	findErr := dao.db.WithContext(ctx).
+		Where("id = ? AND user_id = ?", taskID, userID).
+		First(&target).Error
+	if findErr != nil {
+		return nil, false, findErr
+	}
+
+	// 3. 若任务已完成，直接按幂等成功返回，不再写库。
+	if target.IsCompleted {
+		return &target, true, nil
+	}
+
+	// 4. 若任务未完成，执行状态更新。
+	//
+	// 4.1 使用 Model(&model.Task{UserID:userID}) 的目的：
+	//     让 cache_deleter 在 GORM Update 回调里拿到 user_id，从而正确删除任务缓存。
+	// 4.2 更新条件继续限定 user_id + id，避免误更新其他用户数据。
+	updateResult := dao.db.WithContext(ctx).
+		Model(&model.Task{UserID: userID}).
+		Where("id = ? AND user_id = ?", taskID, userID).
+		Update("is_completed", true)
+	if updateResult.Error != nil {
+		return nil, false, updateResult.Error
+	}
+
+	// 5. 极端并发兜底：
+	// 5.1 若 RowsAffected=0，可能是并发请求已先一步更新；
+	// 5.2 此时二次读取任务状态，若已完成则按幂等成功返回，否则视为不存在/异常。
+	if updateResult.RowsAffected == 0 {
+		var check model.Task
+		checkErr := dao.db.WithContext(ctx).
+			Where("id = ? AND user_id = ?", taskID, userID).
+			First(&check).Error
+		if checkErr != nil {
+			return nil, false, checkErr
+		}
+		if check.IsCompleted {
+			return &check, true, nil
+		}
+		return nil, false, errors.New("任务状态更新失败")
+	}
+
+	// 6. 返回更新后的快照给 Service 层组装响应。
+	target.IsCompleted = true
+	return &target, false, nil
+}
+
 // PromoteTaskUrgencyByIDs 批量执行“任务紧急性平移”。
 //
 // 职责边界：