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/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,