Version: 0.9.66.dev.260504

后端：
1. 阶段 2 user/auth 服务边界落地，新增 `cmd/userauth` go-zero zrpc 服务、`services/userauth` 核心实现、gateway user API/zrpc client 与 shared contracts/ports，迁移注册、登录、刷新 token、登出、JWT、黑名单和 token 额度治理
2. gateway 与启动装配切流，`cmd/all` 只保留边缘路由、鉴权和轻量组合，通过 userauth zrpc 访问核心用户能力；拆分 MySQL/Redis 初始化与 AutoMigrate 边界，`userauth` 自迁 `users` 和 token 记账幂等表，`all` 不再迁用户表
3. 清退 Gin 单体旧 user/auth DAO、model、service、router、middleware 和 JWT handler，并同步调整 agent/schedule/cache/outbox 相关调用依赖
4. 补齐 refresh token 防并发重放、MySQL 幂等 token 记账、额度 `>=` 拦截和 RPC 错误映射，避免重复记账与内部错误透出

文档：
1. 新增《学习计划论坛与Token商店PRD》

backend/service/agentsvc/agent.go

@@ -150,6 +150,7 @@ func (s *AgentService) PersistChatHistory(ctx context.Context, payload model.Cha
 			payload.ReasoningContent,
 			payload.ReasoningDurationSeconds,
 			payload.TokensConsumed,
+			"",
 		)
 	}
 	// 2. 已启用异步总线时，只发布“持久化请求事件”，不在请求路径阻塞 Kafka。

backend/service/agentsvc/agent_meta.go

@@ -218,7 +218,7 @@ func (s *AgentService) ensureConversationTitleAsync(userID int, chatID string) {
 					log.Printf("异步标题 token 记账事件发布失败 chat=%s tokens=%d err=%v", chatID, titleTokens, publishErr)
 				}
 			} else {
-				if adjustErr := s.repo.AdjustTokenUsage(ctx, userID, chatID, titleTokens); adjustErr != nil {
+				if adjustErr := s.repo.AdjustTokenUsage(ctx, userID, chatID, titleTokens, ""); adjustErr != nil {
 					log.Printf("异步标题 token 同步记账失败 chat=%s tokens=%d err=%v", chatID, titleTokens, adjustErr)
 				}
 			}

backend/service/agentsvc/agent_newagent.go

@@ -570,7 +570,7 @@ func (s *AgentService) adjustNewAgentRequestTokenUsage(ctx context.Context, user
 		return
 	}
 
-	if err := s.repo.AdjustTokenUsage(ctx, userID, chatID, deltaTokens); err != nil {
+	if err := s.repo.AdjustTokenUsage(ctx, userID, chatID, deltaTokens, ""); err != nil {
 		log.Printf("同步写入 newAgent 请求级 token 调整失败 chat=%s tokens=%d err=%v", chatID, deltaTokens, err)
 	}
 }

backend/service/events/chat_history_persist.go

@@ -4,37 +4,35 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"strconv"
+	"strings"
 
 	"github.com/LoveLosita/smartflow/backend/dao"
 	kafkabus "github.com/LoveLosita/smartflow/backend/infra/kafka"
 	outboxinfra "github.com/LoveLosita/smartflow/backend/infra/outbox"
 	"github.com/LoveLosita/smartflow/backend/model"
+	contracts "github.com/LoveLosita/smartflow/backend/shared/contracts/userauth"
+	"github.com/LoveLosita/smartflow/backend/shared/ports"
 	"gorm.io/gorm"
 )
 
 const (
-	// EventTypeChatHistoryPersistRequested 是"聊天消息持久化请求"的业务事件类型。
-	//
-	// 命名策略：
-	// 1. 只描述业务语义，不包含 outbox/kafka 等实现词；
-	// 2. 作为新路由键长期保留，后续协议变化优先走 event_version；
-	// 3. 旧路由键仅作兼容，不再作为新发布默认值。
+	// EventTypeChatHistoryPersistRequested 是聊天消息持久化请求的业务事件类型。
 	EventTypeChatHistoryPersistRequested = "chat.history.persist.requested"
 )
 
-// RegisterChatHistoryPersistHandler 注册"聊天消息持久化"消费者处理器。
-//
+// RegisterChatHistoryPersistHandler 注册“聊天消息持久化”消费者。
 // 职责边界：
-// 1. 只负责聊天事件，不处理其他业务事件；
-// 2. 只负责注册，不负责总线启停；
-// 3. 通过 outbox 通用事务入口把"业务写入 + consumed 推进"合并为一个事务；
-// 4. 当前版本仅注册新路由键（chat.history.persist.requested），不再注册旧兼容键。
+// 1. 只处理聊天历史事件，不处理其它业务事件；
+// 2. 只负责注册，不负责总线启动；
+// 3. 先写本地 chat 相关表，再调用 userauth 调整 token 额度；
+// 4. 当前版本仅注册新路由键，不再注册旧兼容键。
 func RegisterChatHistoryPersistHandler(
 	bus OutboxBus,
 	outboxRepo *outboxinfra.Repository,
 	repoManager *dao.RepoManager,
+	adjuster ports.TokenUsageAdjuster,
 ) error {
-	// 1. 依赖校验：任何一个关键依赖为空都无法安全处理消息。
 	if bus == nil {
 		return errors.New("event bus is nil")
 	}
@@ -44,28 +42,26 @@ func RegisterChatHistoryPersistHandler(
 	if repoManager == nil {
 		return errors.New("repo manager is nil")
 	}
+
 	eventOutboxRepo, err := scopedOutboxRepoForEvent(outboxRepo, EventTypeChatHistoryPersistRequested)
 	if err != nil {
 		return err
 	}
 
-	// 2. 定义统一处理器：
-	// 2.1 解析 payload；
-	// 2.2 调用 outbox 通用消费事务；
-	// 2.3 在事务回调中复用 RepoManager.WithTx 执行业务 DAO 写入。
 	handler := func(ctx context.Context, envelope kafkabus.Envelope) error {
 		var payload model.ChatHistoryPersistPayload
 		if unmarshalErr := json.Unmarshal(envelope.Payload, &payload); unmarshalErr != nil {
-			// 2.1 payload 非法属于不可恢复错误，直接标 dead，避免无意义重试。
 			_ = eventOutboxRepo.MarkDead(ctx, envelope.OutboxID, "解析聊天持久化载荷失败: "+unmarshalErr.Error())
 			return nil
 		}
 
-		// 2.2 使用 outbox 通用消费事务，保证"业务写入 + consumed 状态推进"原子一致。
-		return eventOutboxRepo.ConsumeAndMarkConsumed(ctx, envelope.OutboxID, func(tx *gorm.DB) error {
-			// 2.2.1 基于同一个 tx 构造 RepoManager，复用你现有跨包事务模型。
+		eventID := strings.TrimSpace(envelope.EventID)
+		if eventID == "" {
+			eventID = strconv.FormatInt(envelope.OutboxID, 10)
+		}
+
+		if err := eventOutboxRepo.ConsumeInTx(ctx, envelope.OutboxID, func(tx *gorm.DB) error {
 			txM := repoManager.WithTx(tx)
-			// 2.2.2 在同事务内写入聊天历史与会话计数。
 			return txM.Agent.SaveChatHistoryInTx(
 				ctx,
 				payload.UserID,
@@ -75,24 +71,32 @@ func RegisterChatHistoryPersistHandler(
 				payload.ReasoningContent,
 				payload.ReasoningDurationSeconds,
 				payload.TokensConsumed,
+				eventID,
 			)
-		})
+		}); err != nil {
+			return err
+		}
+
+		if payload.TokensConsumed > 0 {
+			if adjuster == nil {
+				return errors.New("userauth token adjuster is nil")
+			}
+			if _, err := adjuster.AdjustTokenUsage(ctx, contracts.AdjustTokenUsageRequest{
+				EventID:    eventID,
+				UserID:     payload.UserID,
+				TokenDelta: payload.TokensConsumed,
+			}); err != nil {
+				return err
+			}
+		}
+
+		return eventOutboxRepo.MarkConsumed(ctx, envelope.OutboxID)
 	}
 
-	// 3. 注册新路由键（主路由）。
-	if err := bus.RegisterEventHandler(EventTypeChatHistoryPersistRequested, handler); err != nil {
-		return err
-	}
-
-	return nil
+	return bus.RegisterEventHandler(EventTypeChatHistoryPersistRequested, handler)
 }
 
-// PublishChatHistoryPersistRequested 发布"聊天消息持久化请求"事件。
-//
-// 设计目的：
-// 1. 让业务层只传 DTO，不重复拼事件元数据；
-// 2. 统一消息键策略（conversation_id 作为 MessageKey/AggregateID）；
-// 3. 发布失败时显式返回 error，由调用方决定是否降级到同步写库。
+// PublishChatHistoryPersistRequested 发布“聊天消息持久化请求”事件。
 func PublishChatHistoryPersistRequested(
 	ctx context.Context,
 	publisher outboxinfra.EventPublisher,

backend/service/events/chat_token_usage_adjust.go

@@ -5,34 +5,36 @@ import (
 	"encoding/json"
 	"errors"
 	"strconv"
+	"strings"
 	"time"
 
 	"github.com/LoveLosita/smartflow/backend/dao"
 	kafkabus "github.com/LoveLosita/smartflow/backend/infra/kafka"
 	outboxinfra "github.com/LoveLosita/smartflow/backend/infra/outbox"
 	"github.com/LoveLosita/smartflow/backend/model"
+	contracts "github.com/LoveLosita/smartflow/backend/shared/contracts/userauth"
+	"github.com/LoveLosita/smartflow/backend/shared/ports"
 	"gorm.io/gorm"
 )
 
 const (
-	// EventTypeChatTokenUsageAdjustRequested 是“会话 token 账本增量调整”事件类型。
-	//
+	// EventTypeChatTokenUsageAdjustRequested 是“会话 token 额度调整”事件类型。
 	// 命名约束：
-	// 1. 仅表达业务语义，不泄露 outbox/kafka 实现细节；
+	// 1. 只表达业务语义，不泄露 outbox/kafka 实现细节；
 	// 2. 作为稳定路由键长期保留，后续演进优先通过 event_version。
 	EventTypeChatTokenUsageAdjustRequested = "chat.token.usage.adjust.requested"
 )
 
-// RegisterChatTokenUsageAdjustHandler 注册“会话 token 账本增量调整”消费者。
-//
+// RegisterChatTokenUsageAdjustHandler 注册“会话 token 额度调整”消费者。
 // 职责边界：
 // 1. 只处理 token 调整事件，不处理聊天正文落库；
-// 2. 通过 outbox 统一消费事务入口，保证“业务成功 + consumed 推进”原子一致；
+// 2. 先写本地账本，再调用 userauth 侧做额度同步；
 // 3. 非法载荷直接标记 dead，避免无意义重试。
 func RegisterChatTokenUsageAdjustHandler(
 	bus OutboxBus,
 	outboxRepo *outboxinfra.Repository,
 	repoManager *dao.RepoManager,
+	adjuster ports.TokenUsageAdjuster,
 ) error {
 	if bus == nil {
 		return errors.New("event bus is nil")
@@ -43,6 +45,7 @@ func RegisterChatTokenUsageAdjustHandler(
 	if repoManager == nil {
 		return errors.New("repo manager is nil")
 	}
+
 	eventOutboxRepo, err := scopedOutboxRepoForEvent(outboxRepo, EventTypeChatTokenUsageAdjustRequested)
 	if err != nil {
 		return err
@@ -60,20 +63,38 @@ func RegisterChatTokenUsageAdjustHandler(
 			return nil
 		}
 
-		return eventOutboxRepo.ConsumeAndMarkConsumed(ctx, envelope.OutboxID, func(tx *gorm.DB) error {
+		eventID := strings.TrimSpace(envelope.EventID)
+		if eventID == "" {
+			eventID = strconv.FormatInt(envelope.OutboxID, 10)
+		}
+
+		if err := eventOutboxRepo.ConsumeInTx(ctx, envelope.OutboxID, func(tx *gorm.DB) error {
 			txM := repoManager.WithTx(tx)
-			return txM.Agent.AdjustTokenUsageInTx(ctx, payload.UserID, payload.ConversationID, payload.TokensDelta)
-		})
+			return txM.Agent.AdjustTokenUsageInTx(ctx, payload.UserID, payload.ConversationID, payload.TokensDelta, eventID)
+		}); err != nil {
+			return err
+		}
+
+		if adjuster == nil {
+			return errors.New("userauth token adjuster is nil")
+		}
+		if _, err := adjuster.AdjustTokenUsage(ctx, contracts.AdjustTokenUsageRequest{
+			EventID:    eventID,
+			UserID:     payload.UserID,
+			TokenDelta: payload.TokensDelta,
+		}); err != nil {
+			return err
+		}
+
+		return eventOutboxRepo.MarkConsumed(ctx, envelope.OutboxID)
 	}
 
 	return bus.RegisterEventHandler(EventTypeChatTokenUsageAdjustRequested, handler)
 }
 
-// PublishChatTokenUsageAdjustRequested 发布“会话 token 账本增量调整”事件。
-//
-// 说明：
-// 1. 只保证“写入 outbox 成功”，不等待消费完成；
-// 2. 业务层只传 DTO，不关心 outbox/kafka 协议细节。
+// PublishChatTokenUsageAdjustRequested 发布“会话 token 额度调整”事件。
+// 1. 这里只保证 outbox 写入成功，不等待消费结果；
+// 2. 业务层只关心 DTO，不关心 outbox/Kafka 细节。
 func PublishChatTokenUsageAdjustRequested(
 	ctx context.Context,
 	publisher outboxinfra.EventPublisher,

backend/service/events/core_outbox_handlers.go

@@ -8,6 +8,7 @@ import (
 	"github.com/LoveLosita/smartflow/backend/memory"
 	"github.com/LoveLosita/smartflow/backend/notification"
 	sharedevents "github.com/LoveLosita/smartflow/backend/shared/events"
+	"github.com/LoveLosita/smartflow/backend/shared/ports"
 )
 
 // RegisterCoreOutboxHandlers 注册核心业务 outbox handler。
@@ -24,12 +25,13 @@ func RegisterCoreOutboxHandlers(
 	agentRepo *dao.AgentDAO,
 	cacheRepo *dao.CacheDAO,
 	memoryModule *memory.Module,
+	adjuster ports.TokenUsageAdjuster,
 ) error {
 	if err := validateCoreOutboxHandlerDeps(eventBus, outboxRepo, repoManager, agentRepo, cacheRepo, memoryModule); err != nil {
 		return err
 	}
 
-	return registerOutboxHandlerRoutes(coreOutboxHandlerRoutes(eventBus, outboxRepo, repoManager, agentRepo, cacheRepo, memoryModule))
+	return registerOutboxHandlerRoutes(coreOutboxHandlerRoutes(eventBus, outboxRepo, repoManager, agentRepo, cacheRepo, memoryModule, adjuster))
 }
 
 // RegisterAllOutboxHandlers 注册当前阶段所有 outbox handler。
@@ -47,6 +49,7 @@ func RegisterAllOutboxHandlers(
 	memoryModule *memory.Module,
 	activeTriggerWorkflow ActiveScheduleTriggeredProcessor,
 	notificationService *notification.NotificationService,
+	adjuster ports.TokenUsageAdjuster,
 ) error {
 	if err := validateAllOutboxHandlerDeps(eventBus, outboxRepo, repoManager, agentRepo, cacheRepo, memoryModule, activeTriggerWorkflow, notificationService); err != nil {
 		return err
@@ -61,6 +64,7 @@ func RegisterAllOutboxHandlers(
 		memoryModule,
 		activeTriggerWorkflow,
 		notificationService,
+		adjuster,
 	))
 }
 
@@ -129,13 +133,14 @@ func coreOutboxHandlerRoutes(
 	agentRepo *dao.AgentDAO,
 	cacheRepo *dao.CacheDAO,
 	memoryModule *memory.Module,
+	adjuster ports.TokenUsageAdjuster,
 ) []outboxHandlerRoute {
 	return []outboxHandlerRoute{
 		{
 			EventType: EventTypeChatHistoryPersistRequested,
 			Service:   outboxHandlerServiceAgent,
 			Register: func() error {
-				return RegisterChatHistoryPersistHandler(eventBus, outboxRepo, repoManager)
+				return RegisterChatHistoryPersistHandler(eventBus, outboxRepo, repoManager, adjuster)
 			},
 		},
 		{
@@ -149,7 +154,7 @@ func coreOutboxHandlerRoutes(
 			EventType: EventTypeChatTokenUsageAdjustRequested,
 			Service:   outboxHandlerServiceAgent,
 			Register: func() error {
-				return RegisterChatTokenUsageAdjustHandler(eventBus, outboxRepo, repoManager)
+				return RegisterChatTokenUsageAdjustHandler(eventBus, outboxRepo, repoManager, adjuster)
 			},
 		},
 		{
@@ -186,8 +191,9 @@ func allOutboxHandlerRoutes(
 	memoryModule *memory.Module,
 	activeTriggerWorkflow ActiveScheduleTriggeredProcessor,
 	notificationService *notification.NotificationService,
+	adjuster ports.TokenUsageAdjuster,
 ) []outboxHandlerRoute {
-	routes := coreOutboxHandlerRoutes(eventBus, outboxRepo, repoManager, agentRepo, cacheRepo, memoryModule)
+	routes := coreOutboxHandlerRoutes(eventBus, outboxRepo, repoManager, agentRepo, cacheRepo, memoryModule, adjuster)
 	routes = append(routes,
 		outboxHandlerRoute{
 			EventType: sharedevents.ActiveScheduleTriggeredEventType,

backend/service/schedule.go

@@ -18,16 +18,14 @@ import (
 
 type ScheduleService struct {
 	scheduleDAO  *dao.ScheduleDAO
-	userDAO      *dao.UserDAO
 	taskClassDAO *dao.TaskClassDAO
 	repoManager  *dao.RepoManager // 统一管理多个 DAO 的事务
 	cacheDAO     *dao.CacheDAO    // 需要在 ScheduleService 中使用缓存
 }
 
-func NewScheduleService(scheduleDAO *dao.ScheduleDAO, userDAO *dao.UserDAO, taskClassDAO *dao.TaskClassDAO, repoManager *dao.RepoManager, cacheDAO *dao.CacheDAO) *ScheduleService {
+func NewScheduleService(scheduleDAO *dao.ScheduleDAO, taskClassDAO *dao.TaskClassDAO, repoManager *dao.RepoManager, cacheDAO *dao.CacheDAO) *ScheduleService {
 	return &ScheduleService{
 		scheduleDAO:  scheduleDAO,
-		userDAO:      userDAO,
 		taskClassDAO: taskClassDAO,
 		repoManager:  repoManager,
 		cacheDAO:     cacheDAO,
@@ -35,14 +33,6 @@ func NewScheduleService(scheduleDAO *dao.ScheduleDAO, userDAO *dao.UserDAO, task
 }
 
 func (ss *ScheduleService) GetUserTodaySchedule(ctx context.Context, userID int) ([]model.UserTodaySchedule, error) {
-	//1.先检查用户id是否存在(考虑移除)
-	/*_, err := ss.userDAO.GetUserByID(userID)
-	if err != nil {
-		if errors.Is(err, gorm.ErrRecordNotFound) {
-			return nil, respond.WrongUserID
-		}
-		return nil, err
-	}*/
 	//1.先尝试从缓存获取数据
 	cachedResp, err := ss.cacheDAO.GetUserTodayScheduleFromCache(ctx, userID)
 	if err == nil {

backend/service/user.go

@@ -1,123 +0,0 @@
-// Package service 业务逻辑层
-// 包含所有核心业务逻辑
-package service
-
-import (
-	"errors"
-	"time"
-
-	"context"
-
-	"github.com/LoveLosita/smartflow/backend/auth"
-	"github.com/LoveLosita/smartflow/backend/dao"
-	"github.com/LoveLosita/smartflow/backend/model"
-	"github.com/LoveLosita/smartflow/backend/respond"
-	"github.com/LoveLosita/smartflow/backend/utils"
-	"gorm.io/gorm"
-)
-
-type UserService struct {
-	userRepo  *dao.UserDAO
-	cacheRepo *dao.CacheDAO
-}
-
-func NewUserService(userRepo *dao.UserDAO, cacheRepo *dao.CacheDAO) *UserService {
-	return &UserService{
-		userRepo:  userRepo, // 把传进来的 DAO 揣进口袋里
-		cacheRepo: cacheRepo,
-	}
-}
-
-func (sv *UserService) UserRegister(ctx context.Context, user model.UserRegisterRequest) (*model.UserRegisterResponse, error) {
-	//检查是否有空字段
-	if user.Username == "" || user.Password == "" ||
-		user.PhoneNumber == "" {
-		return nil, respond.MissingParam
-	}
-	// 检查字段长度是否超过90%
-	if len(user.Username) > 45 || len(user.Password) > 229 || len(user.PhoneNumber) > 18 {
-		return nil, respond.ParamTooLong
-	}
-	//检查用户名是否已存在
-	result, err := sv.userRepo.IfUsernameExists(user.Username)
-	if err != nil {
-		return nil, err
-	}
-	if result {
-		return nil, respond.InvalidName
-	}
-	hashedPwd, err := utils.HashPassword(user.Password) //调用utils层的方法
-	if err != nil {
-		return nil, err
-	}
-	user.Password = hashedPwd //将user的密码字段改为加密后的密码
-	newUser, err := sv.userRepo.Create(user.Username, user.PhoneNumber, user.Password)
-	if err != nil {
-		return nil, err
-	}
-	//返回注册成功的用户ID
-	return &model.UserRegisterResponse{ID: newUser.ID}, nil
-}
-
-func (sv *UserService) UserLogin(ctx context.Context, req *model.UserLoginRequest) (*model.Tokens, error) {
-	var tokens model.Tokens
-	hashedPwd, err := sv.userRepo.GetUserHashedPasswordByName(req.Username) //调用dao层的方法
-	if err != nil {
-		if errors.Is(err, gorm.ErrRecordNotFound) {
-			return nil, respond.WrongName
-		}
-		return nil, err
-	}
-	result, err := utils.CompareHashPwdAndPwd(hashedPwd, req.Password) //比较密码是否匹配
-	if err != nil {                                                    //其他错误
-		return &tokens, err
-	} else if !result { //密码不匹配
-		return nil, respond.WrongPwd
-	}
-	id, err := sv.userRepo.GetUserIDByName(req.Username)
-	if err != nil {
-		if errors.Is(err, gorm.ErrRecordNotFound) {
-			return nil, respond.WrongName
-		}
-		return nil, err
-	}
-	tokens.AccessToken, tokens.RefreshToken, err = auth.GenerateTokens(id) //生成jwt key
-	if err != nil {                                                        //其他错误
-		return nil, err
-	}
-	return &tokens, nil
-}
-
-func (sv *UserService) RefreshTokenHandler(ctx context.Context, refreshToken string) (*model.Tokens, error) {
-	// 1. 验证刷新令牌 (这里已经包含了 Redis 黑名单检查)
-	token, err := auth.ValidateRefreshToken(refreshToken, sv.cacheRepo)
-	if err != nil {
-		return nil, err
-	}
-
-	// 2. 改动点：直接断言为你定义的结构体 model.MyCustomClaims
-	if claims, ok := token.Claims.(*model.MyCustomClaims); ok {
-		// 3. 这里的 userID 已经是 int 了，不再需要 (float64) 转换
-		newAccessToken, newRefreshToken, err := auth.GenerateTokens(claims.UserID)
-		if err != nil {
-			return nil, err
-		}
-		// 返回新的双 Token
-		return &model.Tokens{
-			AccessToken:  newAccessToken,
-			RefreshToken: newRefreshToken,
-		}, nil
-	}
-
-	return nil, respond.InvalidClaims
-}
-
-func (sv *UserService) UserLogout(ctx context.Context, jti string, expireTime time.Time) error {
-	//1.直接把 jti 扔进黑名单
-	expiration := time.Until(expireTime)
-	err := sv.cacheRepo.SetBlacklist(jti, expiration)
-	if err != nil {
-		return err
-	}
-	return nil
-}