Version: 0.9.78.dev.260506

2026-05-06 00:30:08 +08:00
parent 3b6fca44a6
commit 33227e48a7
71 changed files with 13137 additions and 62 deletions
--- a/backend/services/tokenstore/dao/connect.go
+++ b/backend/services/tokenstore/dao/connect.go
@@ -0,0 +1,184 @@
+package dao
+
+import (
+	"fmt"
+
+	outboxinfra "github.com/LoveLosita/smartflow/backend/shared/infra/outbox"
+	tokenmodel "github.com/LoveLosita/smartflow/backend/services/tokenstore/model"
+	"github.com/spf13/viper"
+	"gorm.io/driver/mysql"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+// OpenDBFromConfig 创建 token-store 服务自己的数据库句柄，并迁移本服务私有表。
+//
+// 职责边界：
+// 1. 只迁移 token_* 表和 token-store outbox 表，不迁移 users，避免和 user/auth 服务边界冲突；
+// 2. 自动迁移后执行 P0 seed，确保前端商品页有可展示商品；
+// 3. 返回 *gorm.DB 供本服务 DAO 复用，调用方负责进程生命周期。
+func OpenDBFromConfig() (*gorm.DB, error) {
+	host := viper.GetString("database.host")
+	port := viper.GetString("database.port")
+	user := viper.GetString("database.user")
+	password := viper.GetString("database.password")
+	dbname := viper.GetString("database.dbname")
+
+	dsn := fmt.Sprintf(
+		"%s:%s@tcp(%s:%s)/%s?charset=utf8mb4&parseTime=True&loc=Local",
+		user, password, host, port, dbname,
+	)
+
+	db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
+	if err != nil {
+		return nil, err
+	}
+	if err = AutoMigrate(db); err != nil {
+		return nil, err
+	}
+	if err = SeedDefaults(db); err != nil {
+		return nil, err
+	}
+	return db, nil
+}
+
+// AutoMigrate 只迁移 token-store 服务拥有的表。
+//
+// 步骤说明：
+// 1. 先创建商品、订单、获取账本和奖励规则表；
+// 2. 再按 service catalog 创建 token-store outbox 表，保证论坛奖励事件有稳定落表目录；
+// 3. 通过唯一约束保证 order_no、event_id 和幂等键不会重复写入；
+// 4. 失败时直接返回错误，避免服务在 schema 不完整时继续启动。
+func AutoMigrate(db *gorm.DB) error {
+	if db == nil {
+		return fmt.Errorf("tokenstore auto migrate failed: db is nil")
+	}
+	if err := db.AutoMigrate(
+		&tokenmodel.TokenProduct{},
+		&tokenmodel.TokenOrder{},
+		&tokenmodel.TokenGrant{},
+		&tokenmodel.TokenRewardRule{},
+	); err != nil {
+		return fmt.Errorf("auto migrate tokenstore tables failed: %w", err)
+	}
+	if err := outboxinfra.AutoMigrateServiceTable(db, outboxinfra.ServiceTokenStore); err != nil {
+		return err
+	}
+	return nil
+}
+
+// SeedDefaults 写入 P0 默认商品和奖励规则。
+//
+// 步骤说明：
+// 1. 商品和奖励规则都用稳定业务键做 upsert，允许重复启动服务；
+// 2. seed 只提供 P0 默认数据，不代表有管理后台能力；
+// 3. 后续若商品或规则由运营后台维护，可替换本函数或仅保留初始化兜底。
+func SeedDefaults(db *gorm.DB) error {
+	if db == nil {
+		return fmt.Errorf("tokenstore seed failed: db is nil")
+	}
+	if err := seedDefaultProducts(db); err != nil {
+		return err
+	}
+	if err := seedDefaultRewardRules(db); err != nil {
+		return err
+	}
+	return nil
+}
+
+func seedDefaultProducts(db *gorm.DB) error {
+	products := defaultTokenProducts()
+	for _, product := range products {
+		if err := db.Clauses(clause.OnConflict{
+			Columns: []clause.Column{{Name: "sku"}},
+			DoUpdates: clause.AssignmentColumns([]string{
+				"name",
+				"description",
+				"token_amount",
+				"price_cent",
+				"currency",
+				"badge",
+				"status",
+				"sort_order",
+				"updated_at",
+			}),
+		}).Create(&product).Error; err != nil {
+			return fmt.Errorf("seed token product %s failed: %w", product.SKU, err)
+		}
+	}
+	return nil
+}
+
+func defaultTokenProducts() []tokenmodel.TokenProduct {
+	return []tokenmodel.TokenProduct{
+		{
+			SKU:         "token_basic_100",
+			Name:        "基础 Token 包",
+			Description: "适合轻量使用 Agent。",
+			TokenAmount: 100,
+			PriceCent:   990,
+			Currency:    "CNY",
+			Badge:       "入门",
+			Status:      tokenmodel.TokenProductStatusActive,
+			SortOrder:   10,
+		},
+		{
+			SKU:         "token_plus_300",
+			Name:        "进阶 Token 包",
+			Description: "适合高频规划和复盘。",
+			TokenAmount: 300,
+			PriceCent:   1990,
+			Currency:    "CNY",
+			Badge:       "推荐",
+			Status:      tokenmodel.TokenProductStatusActive,
+			SortOrder:   20,
+		},
+		{
+			SKU:         "token_pro_800",
+			Name:        "专业 Token 包",
+			Description: "适合长周期学习计划和高频 Agent 使用。",
+			TokenAmount: 800,
+			PriceCent:   3990,
+			Currency:    "CNY",
+			Badge:       "高频",
+			Status:      tokenmodel.TokenProductStatusActive,
+			SortOrder:   30,
+		},
+	}
+}
+
+func seedDefaultRewardRules(db *gorm.DB) error {
+	rules := defaultTokenRewardRules()
+	for _, rule := range rules {
+		if err := db.Clauses(clause.OnConflict{
+			Columns: []clause.Column{{Name: "source"}},
+			DoUpdates: clause.AssignmentColumns([]string{
+				"name",
+				"amount",
+				"status",
+				"config_json",
+				"updated_at",
+			}),
+		}).Create(&rule).Error; err != nil {
+			return fmt.Errorf("seed token reward rule %s failed: %w", rule.Source, err)
+		}
+	}
+	return nil
+}
+
+func defaultTokenRewardRules() []tokenmodel.TokenRewardRule {
+	return []tokenmodel.TokenRewardRule{
+		{
+			Source: tokenmodel.TokenGrantSourceForumLike,
+			Name:   "计划被点赞奖励",
+			Amount: 1,
+			Status: tokenmodel.TokenRewardRuleStatusActive,
+		},
+		{
+			Source: tokenmodel.TokenGrantSourceForumImport,
+			Name:   "计划被导入奖励",
+			Amount: 5,
+			Status: tokenmodel.TokenRewardRuleStatusActive,
+		},
+	}
+}
--- a/backend/services/tokenstore/dao/tokenstore.go
+++ b/backend/services/tokenstore/dao/tokenstore.go
@@ -0,0 +1,285 @@
+package dao
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	tokenmodel "github.com/LoveLosita/smartflow/backend/services/tokenstore/model"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+// TokenStoreDAO 承载 token-store 私有表的持久化访问。
+//
+// 职责边界：
+// 1. 只访问 token_products、token_orders、token_grants、token_reward_rules。
+// 2. 只提供查询、事务和原子状态更新，不组装 RPC/HTTP 视图。
+// 3. 业务状态机、幂等回退和提示文案由 sv 层负责。
+type TokenStoreDAO struct {
+	db *gorm.DB
+}
+
+func NewTokenStoreDAO(db *gorm.DB) *TokenStoreDAO {
+	return &TokenStoreDAO{db: db}
+}
+
+func (dao *TokenStoreDAO) WithTx(tx *gorm.DB) *TokenStoreDAO {
+	return &TokenStoreDAO{db: tx}
+}
+
+// Transaction 在一个数据库事务内执行 token-store 写操作。
+func (dao *TokenStoreDAO) Transaction(ctx context.Context, fn func(txDAO *TokenStoreDAO) error) error {
+	return dao.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		return fn(dao.WithTx(tx))
+	})
+}
+
+type ListTokenOrdersQuery struct {
+	UserID   uint64
+	Page     int
+	PageSize int
+	Status   string
+}
+
+type ListTokenGrantsQuery struct {
+	UserID   uint64
+	Page     int
+	PageSize int
+	Source   string
+}
+
+type TokenGrantSummary struct {
+	RecordedTokenTotal int64
+	AppliedTokenTotal  int64
+}
+
+func (dao *TokenStoreDAO) ListActiveProducts(ctx context.Context) ([]tokenmodel.TokenProduct, error) {
+	var products []tokenmodel.TokenProduct
+	err := dao.db.WithContext(ctx).
+		Where("status = ?", tokenmodel.TokenProductStatusActive).
+		Order("sort_order ASC, id ASC").
+		Find(&products).Error
+	return products, err
+}
+
+// FindRewardRuleBySource 按来源读取社区奖励规则。
+//
+// 职责边界：
+// 1. 只读取 token_reward_rules，不计算最终发放金额，也不判断停用语义；
+// 2. 未找到规则时返回 nil，由服务层决定配置或默认值兜底；
+// 3. source 在 DAO 层做一次规范化，避免大小写和空格造成规则漏命中。
+func (dao *TokenStoreDAO) FindRewardRuleBySource(ctx context.Context, source string) (*tokenmodel.TokenRewardRule, error) {
+	source = strings.ToLower(strings.TrimSpace(source))
+	if source == "" {
+		return nil, nil
+	}
+
+	var rule tokenmodel.TokenRewardRule
+	err := dao.db.WithContext(ctx).
+		Where("source = ?", source).
+		First(&rule).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &rule, nil
+}
+
+func (dao *TokenStoreDAO) FindActiveProductByID(ctx context.Context, productID uint64) (*tokenmodel.TokenProduct, error) {
+	var product tokenmodel.TokenProduct
+	err := dao.db.WithContext(ctx).
+		Where("id = ? AND status = ?", productID, tokenmodel.TokenProductStatusActive).
+		First(&product).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &product, nil
+}
+
+func (dao *TokenStoreDAO) FindOrderByUserIdempotencyKey(ctx context.Context, userID uint64, key string) (*tokenmodel.TokenOrder, error) {
+	var order tokenmodel.TokenOrder
+	err := dao.db.WithContext(ctx).
+		Where("user_id = ? AND idempotency_key = ?", userID, key).
+		First(&order).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &order, nil
+}
+
+func (dao *TokenStoreDAO) CreateOrder(ctx context.Context, order *tokenmodel.TokenOrder) error {
+	return dao.db.WithContext(ctx).Create(order).Error
+}
+
+func (dao *TokenStoreDAO) CountOrders(ctx context.Context, query ListTokenOrdersQuery) (int64, error) {
+	db := dao.db.WithContext(ctx).
+		Model(&tokenmodel.TokenOrder{}).
+		Where("user_id = ?", query.UserID)
+	if status := strings.TrimSpace(query.Status); status != "" {
+		db = db.Where("status = ?", status)
+	}
+
+	var total int64
+	err := db.Count(&total).Error
+	return total, err
+}
+
+func (dao *TokenStoreDAO) ListOrders(ctx context.Context, query ListTokenOrdersQuery) ([]tokenmodel.TokenOrder, error) {
+	db := dao.db.WithContext(ctx).
+		Where("user_id = ?", query.UserID)
+	if status := strings.TrimSpace(query.Status); status != "" {
+		db = db.Where("status = ?", status)
+	}
+
+	var orders []tokenmodel.TokenOrder
+	err := db.Order("created_at DESC, id DESC").
+		Offset((query.Page - 1) * query.PageSize).
+		Limit(query.PageSize).
+		Find(&orders).Error
+	return orders, err
+}
+
+func (dao *TokenStoreDAO) FindOrderByID(ctx context.Context, orderID uint64) (*tokenmodel.TokenOrder, error) {
+	var order tokenmodel.TokenOrder
+	err := dao.db.WithContext(ctx).Where("id = ?", orderID).First(&order).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &order, nil
+}
+
+func (dao *TokenStoreDAO) LockOrderByID(ctx context.Context, orderID uint64) (*tokenmodel.TokenOrder, error) {
+	var order tokenmodel.TokenOrder
+	err := dao.db.WithContext(ctx).
+		Clauses(clause.Locking{Strength: "UPDATE"}).
+		Where("id = ?", orderID).
+		First(&order).Error
+	if err != nil {
+		return nil, err
+	}
+	return &order, nil
+}
+
+// UpdateOrderState 只负责把订单持久化到最新状态。
+//
+// 职责边界：
+// 1. 调用方必须先完成状态机判断，并决定最终 status/paid_at/granted_at。
+// 2. 这里不做“是否允许从 A -> B”校验，避免 DAO 层承载业务规则。
+// 3. payment_mode 允许调用方显式回填，保证 mock paid 后订单快照完整。
+func (dao *TokenStoreDAO) UpdateOrderState(ctx context.Context, orderID uint64, status string, paidAt *time.Time, grantedAt *time.Time, paymentMode string) error {
+	updates := map[string]any{
+		"status":       status,
+		"paid_at":      paidAt,
+		"granted_at":   grantedAt,
+		"payment_mode": paymentMode,
+		"updated_at":   time.Now(),
+	}
+	return dao.db.WithContext(ctx).
+		Model(&tokenmodel.TokenOrder{}).
+		Where("id = ?", orderID).
+		Updates(updates).Error
+}
+
+func (dao *TokenStoreDAO) FindGrantByEventID(ctx context.Context, eventID string) (*tokenmodel.TokenGrant, error) {
+	var grant tokenmodel.TokenGrant
+	err := dao.db.WithContext(ctx).
+		Where("event_id = ?", eventID).
+		First(&grant).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &grant, nil
+}
+
+func (dao *TokenStoreDAO) FindGrantByOrderID(ctx context.Context, orderID uint64) (*tokenmodel.TokenGrant, error) {
+	var grant tokenmodel.TokenGrant
+	err := dao.db.WithContext(ctx).
+		Where("order_id = ?", orderID).
+		Order("created_at DESC, id DESC").
+		First(&grant).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &grant, nil
+}
+
+func (dao *TokenStoreDAO) ListGrantsByOrderIDs(ctx context.Context, orderIDs []uint64) ([]tokenmodel.TokenGrant, error) {
+	if len(orderIDs) == 0 {
+		return []tokenmodel.TokenGrant{}, nil
+	}
+
+	var grants []tokenmodel.TokenGrant
+	err := dao.db.WithContext(ctx).
+		Where("order_id IN ?", orderIDs).
+		Order("created_at DESC, id DESC").
+		Find(&grants).Error
+	return grants, err
+}
+
+func (dao *TokenStoreDAO) CreateGrant(ctx context.Context, grant *tokenmodel.TokenGrant) error {
+	return dao.db.WithContext(ctx).Create(grant).Error
+}
+
+func (dao *TokenStoreDAO) CountGrants(ctx context.Context, query ListTokenGrantsQuery) (int64, error) {
+	db := dao.db.WithContext(ctx).
+		Model(&tokenmodel.TokenGrant{}).
+		Where("user_id = ?", query.UserID)
+	if source := strings.TrimSpace(query.Source); source != "" {
+		db = db.Where("source = ?", source)
+	}
+
+	var total int64
+	err := db.Count(&total).Error
+	return total, err
+}
+
+func (dao *TokenStoreDAO) ListGrants(ctx context.Context, query ListTokenGrantsQuery) ([]tokenmodel.TokenGrant, error) {
+	db := dao.db.WithContext(ctx).
+		Where("user_id = ?", query.UserID)
+	if source := strings.TrimSpace(query.Source); source != "" {
+		db = db.Where("source = ?", source)
+	}
+
+	var grants []tokenmodel.TokenGrant
+	err := db.Order("created_at DESC, id DESC").
+		Offset((query.Page - 1) * query.PageSize).
+		Limit(query.PageSize).
+		Find(&grants).Error
+	return grants, err
+}
+
+func (dao *TokenStoreDAO) SummarizePositiveGrants(ctx context.Context, userID uint64) (TokenGrantSummary, error) {
+	var summary TokenGrantSummary
+	err := dao.db.WithContext(ctx).
+		Model(&tokenmodel.TokenGrant{}).
+		Select(
+			`COALESCE(SUM(CASE WHEN amount > 0 AND status IN (?, ?) THEN amount ELSE 0 END), 0) AS recorded_token_total,
+			 COALESCE(SUM(CASE WHEN amount > 0 AND (quota_applied = ? OR status = ?) THEN amount ELSE 0 END), 0) AS applied_token_total`,
+			tokenmodel.TokenGrantStatusRecorded,
+			tokenmodel.TokenGrantStatusApplied,
+			true,
+			tokenmodel.TokenGrantStatusApplied,
+		).
+		Where("user_id = ?", userID).
+		Scan(&summary).Error
+	return summary, err
+}
--- a/backend/services/tokenstore/model/token.go
+++ b/backend/services/tokenstore/model/token.go
@@ -0,0 +1,155 @@
+package model
+
+import "time"
+
+const (
+	// TokenProductStatusActive 表示商品可在 Token 商店展示和购买。
+	TokenProductStatusActive = "active"
+	// TokenProductStatusInactive 表示商品已下架，不再对前端展示。
+	TokenProductStatusInactive = "inactive"
+)
+
+const (
+	// TokenOrderStatusPending 表示订单已创建，等待支付确认。
+	TokenOrderStatusPending = "pending"
+	// TokenOrderStatusPaid 表示订单已确认支付，等待写入获取账本。
+	TokenOrderStatusPaid = "paid"
+	// TokenOrderStatusGranted 表示订单已经写入 token_grants 获取账本。
+	TokenOrderStatusGranted = "granted"
+	// TokenOrderStatusClosed 表示订单关闭，P0 暂不实现复杂关闭流程。
+	TokenOrderStatusClosed = "closed"
+)
+
+const (
+	// TokenGrantStatusRecorded 表示 Token 获取事实已记录在 token-store 内。
+	TokenGrantStatusRecorded = "recorded"
+	// TokenGrantStatusApplied 表示后续已同步到 user/auth 权威额度。
+	TokenGrantStatusApplied = "applied"
+	// TokenGrantStatusSkipped 表示命中奖励规则或幂等条件后跳过发放。
+	TokenGrantStatusSkipped = "skipped"
+	// TokenGrantStatusFailed 表示记录或后续同步失败，可按 event_id 重试。
+	TokenGrantStatusFailed = "failed"
+)
+
+const (
+	// TokenGrantSourcePurchase 表示购买 Token 商品产生的获取记录。
+	TokenGrantSourcePurchase = "purchase"
+	// TokenGrantSourceForumLike 表示计划被点赞产生的作者奖励。
+	TokenGrantSourceForumLike = "forum_like"
+	// TokenGrantSourceForumImport 表示计划被导入产生的作者奖励。
+	TokenGrantSourceForumImport = "forum_import"
+	// TokenGrantSourceManual 预留人工补偿来源，P0 不做管理后台。
+	TokenGrantSourceManual = "manual"
+)
+
+const (
+	// TokenRewardRuleStatusActive 表示奖励规则启用。
+	TokenRewardRuleStatusActive = "active"
+	// TokenRewardRuleStatusInactive 表示奖励规则停用。
+	TokenRewardRuleStatusInactive = "inactive"
+)
+
+// TokenProduct 是 Token 商店商品表。
+//
+// 职责边界：
+// 1. P0 从表读取商品，由 seed 初始化 2-3 个固定商品；
+// 2. 不承载真实支付渠道配置，也不做商品管理后台；
+// 3. 下单时会复制商品快照到订单，避免后续改价影响历史订单。
+type TokenProduct struct {
+	ID          uint64    `gorm:"column:id;primaryKey;autoIncrement"`
+	SKU         string    `gorm:"column:sku;type:varchar(64);not null;uniqueIndex:uk_token_products_sku;comment:商品稳定编码"`
+	Name        string    `gorm:"column:name;type:varchar(80);not null;comment:商品名称"`
+	Description string    `gorm:"column:description;type:varchar(255);comment:商品描述"`
+	TokenAmount int64     `gorm:"column:token_amount;not null;comment:商品包含Token数量"`
+	PriceCent   int64     `gorm:"column:price_cent;not null;comment:价格，单位分"`
+	Currency    string    `gorm:"column:currency;type:varchar(16);not null;default:'CNY';comment:币种"`
+	Badge       string    `gorm:"column:badge;type:varchar(32);comment:前端角标"`
+	Status      string    `gorm:"column:status;type:varchar(32);not null;default:'active';index:idx_token_products_status_sort,priority:1;comment:active/inactive"`
+	SortOrder   int       `gorm:"column:sort_order;not null;default:0;index:idx_token_products_status_sort,priority:2;comment:展示排序"`
+	CreatedAt   time.Time `gorm:"column:created_at;autoCreateTime;comment:创建时间"`
+	UpdatedAt   time.Time `gorm:"column:updated_at;autoUpdateTime;comment:更新时间"`
+}
+
+func (TokenProduct) TableName() string {
+	return "token_products"
+}
+
+// TokenOrder 是 Token 商品订单表。
+//
+// 职责边界：
+// 1. 记录用户购买商品的订单状态机；
+// 2. P0 只支持 mock paid，不接真实支付网关；
+// 3. granted 只表示已写入 token-store 获取账本，不代表已同步到 user/auth 权威额度。
+type TokenOrder struct {
+	ID                  uint64     `gorm:"column:id;primaryKey;autoIncrement"`
+	OrderNo             string     `gorm:"column:order_no;type:varchar(64);not null;uniqueIndex:uk_token_orders_order_no;comment:订单号"`
+	UserID              uint64     `gorm:"column:user_id;not null;uniqueIndex:uk_token_orders_user_idem,priority:1;index:idx_token_orders_user_status_created,priority:1;comment:下单用户ID"`
+	ProductID           uint64     `gorm:"column:product_id;not null;index:idx_token_orders_product;comment:商品ID"`
+	ProductSKU          string     `gorm:"column:product_sku;type:varchar(64);not null;comment:商品SKU快照"`
+	ProductName         string     `gorm:"column:product_name;type:varchar(80);not null;comment:商品名称快照"`
+	ProductSnapshotJSON string     `gorm:"column:product_snapshot_json;type:json;not null;comment:商品完整快照JSON"`
+	Quantity            int        `gorm:"column:quantity;not null;default:1;comment:购买数量"`
+	TokenAmount         int64      `gorm:"column:token_amount;not null;comment:订单总Token数量"`
+	AmountCent          int64      `gorm:"column:amount_cent;not null;comment:订单总金额，单位分"`
+	Currency            string     `gorm:"column:currency;type:varchar(16);not null;default:'CNY';comment:币种"`
+	Status              string     `gorm:"column:status;type:varchar(32);not null;default:'pending';index:idx_token_orders_user_status_created,priority:2;comment:pending/paid/granted/closed"`
+	PaymentMode         string     `gorm:"column:payment_mode;type:varchar(32);not null;default:'mock';comment:支付模式，P0为mock"`
+	IdempotencyKey      *string    `gorm:"column:idempotency_key;type:varchar(128);uniqueIndex:uk_token_orders_user_idem,priority:2;comment:创建订单幂等键"`
+	PaidAt              *time.Time `gorm:"column:paid_at;comment:支付确认时间"`
+	GrantedAt           *time.Time `gorm:"column:granted_at;comment:写入获取账本时间"`
+	CreatedAt           time.Time  `gorm:"column:created_at;autoCreateTime;index:idx_token_orders_user_status_created,priority:3;comment:创建时间"`
+	UpdatedAt           time.Time  `gorm:"column:updated_at;autoUpdateTime;comment:更新时间"`
+}
+
+func (TokenOrder) TableName() string {
+	return "token_orders"
+}
+
+// TokenGrant 是 Token 获取账本表。
+//
+// 职责边界：
+// 1. 记录购买、论坛点赞奖励、论坛导入奖励等 Token 获取事实；
+// 2. event_id 是最终幂等边界，避免订单或 outbox 重试重复发放；
+// 3. P0 不直接修改 users 表，quota_applied 默认为 false。
+type TokenGrant struct {
+	ID           uint64     `gorm:"column:id;primaryKey;autoIncrement"`
+	EventID      string     `gorm:"column:event_id;type:varchar(128);not null;uniqueIndex:uk_token_grants_event;comment:幂等事件ID"`
+	UserID       uint64     `gorm:"column:user_id;not null;index:idx_token_grants_user_source_created,priority:1;comment:获得Token的用户ID"`
+	Source       string     `gorm:"column:source;type:varchar(32);not null;index:idx_token_grants_user_source_created,priority:2;comment:purchase/forum_like/forum_import/manual"`
+	SourceLabel  string     `gorm:"column:source_label;type:varchar(64);comment:前端展示来源"`
+	SourceRefID  *uint64    `gorm:"column:source_ref_id;index:idx_token_grants_source_ref;comment:来源业务ID，如order_id/post_id/import_id"`
+	OrderID      *uint64    `gorm:"column:order_id;index:idx_token_grants_order;comment:购买订单ID，非购买来源为空"`
+	Amount       int64      `gorm:"column:amount;not null;comment:获取Token数量"`
+	Status       string     `gorm:"column:status;type:varchar(32);not null;default:'recorded';index:idx_token_grants_status;comment:recorded/applied/skipped/failed"`
+	QuotaApplied bool       `gorm:"column:quota_applied;not null;default:false;comment:是否已同步到user/auth权威额度"`
+	Description  string     `gorm:"column:description;type:varchar(255);comment:前端展示描述"`
+	AppliedAt    *time.Time `gorm:"column:applied_at;comment:同步到权威额度时间"`
+	LastError    *string    `gorm:"column:last_error;type:text;comment:后续同步失败原因"`
+	CreatedAt    time.Time  `gorm:"column:created_at;autoCreateTime;index:idx_token_grants_user_source_created,priority:3;comment:创建时间"`
+	UpdatedAt    time.Time  `gorm:"column:updated_at;autoUpdateTime;comment:更新时间"`
+}
+
+func (TokenGrant) TableName() string {
+	return "token_grants"
+}
+
+// TokenRewardRule 是社区奖励规则表。
+//
+// 职责边界：
+// 1. P0 可用 seed 初始化点赞、导入奖励额度；
+// 2. 不提供管理后台，规则调整先通过配置或 seed 变更；
+// 3. 规则命中后的最终发放仍以 token_grants.event_id 幂等为准。
+type TokenRewardRule struct {
+	ID         uint64    `gorm:"column:id;primaryKey;autoIncrement"`
+	Source     string    `gorm:"column:source;type:varchar(32);not null;uniqueIndex:uk_token_reward_rules_source;comment:forum_like/forum_import"`
+	Name       string    `gorm:"column:name;type:varchar(80);not null;comment:规则名称"`
+	Amount     int64     `gorm:"column:amount;not null;comment:奖励Token数量"`
+	Status     string    `gorm:"column:status;type:varchar(32);not null;default:'active';index:idx_token_reward_rules_status;comment:active/inactive"`
+	ConfigJSON *string   `gorm:"column:config_json;type:json;comment:预留扩展配置"`
+	CreatedAt  time.Time `gorm:"column:created_at;autoCreateTime;comment:创建时间"`
+	UpdatedAt  time.Time `gorm:"column:updated_at;autoUpdateTime;comment:更新时间"`
+}
+
+func (TokenRewardRule) TableName() string {
+	return "token_reward_rules"
+}
--- a/backend/services/tokenstore/rpc/errors.go
+++ b/backend/services/tokenstore/rpc/errors.go
@@ -0,0 +1,72 @@
+package rpc
+
+import (
+	"errors"
+	"log"
+	"strings"
+
+	"github.com/LoveLosita/smartflow/backend/shared/respond"
+	tokenstoresv "github.com/LoveLosita/smartflow/backend/services/tokenstore/sv"
+	"google.golang.org/genproto/googleapis/rpc/errdetails"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+)
+
+const tokenStoreErrorDomain = "smartflow.tokenstore"
+
+// grpcErrorFromServiceError 负责把 token-store 内部错误收口成 gRPC status。
+//
+// 职责边界：
+// 1. 只处理服务内部错误到跨进程错误的转换；
+// 2. 不决定 HTTP 状态码，也不直接写前端响应；
+// 3. 未识别错误统一按 Internal 处理，避免泄露数据库或支付细节。
+func grpcErrorFromServiceError(err error) error {
+	if err == nil {
+		return nil
+	}
+
+	var resp respond.Response
+	if errors.As(err, &resp) {
+		return grpcErrorFromResponse(resp)
+	}
+	if errors.Is(err, tokenstoresv.ErrNotImplemented) {
+		return status.Error(codes.Unimplemented, err.Error())
+	}
+	log.Printf("tokenstore rpc internal error: %v", err)
+	return status.Error(codes.Internal, "tokenstore service internal error")
+}
+
+func grpcErrorFromResponse(resp respond.Response) error {
+	code := grpcCodeFromRespondStatus(resp.Status)
+	message := strings.TrimSpace(resp.Info)
+	if message == "" {
+		message = strings.TrimSpace(resp.Status)
+	}
+
+	st := status.New(code, message)
+	detail := &errdetails.ErrorInfo{
+		Domain: tokenStoreErrorDomain,
+		Reason: resp.Status,
+		Metadata: map[string]string{
+			"info": resp.Info,
+		},
+	}
+	withDetails, err := st.WithDetails(detail)
+	if err != nil {
+		return st.Err()
+	}
+	return withDetails.Err()
+}
+
+func grpcCodeFromRespondStatus(statusValue string) codes.Code {
+	switch strings.TrimSpace(statusValue) {
+	case respond.MissingToken.Status, respond.InvalidToken.Status, respond.InvalidClaims.Status, respond.ErrUnauthorized.Status:
+		return codes.Unauthenticated
+	case respond.MissingParam.Status, respond.WrongParamType.Status, respond.ParamTooLong.Status, respond.WrongUserID.Status:
+		return codes.InvalidArgument
+	}
+	if strings.HasPrefix(strings.TrimSpace(statusValue), "5") {
+		return codes.Internal
+	}
+	return codes.InvalidArgument
+}
--- a/backend/services/tokenstore/rpc/handler.go
+++ b/backend/services/tokenstore/rpc/handler.go
@@ -0,0 +1,313 @@
+package rpc
+
+import (
+	"context"
+	"errors"
+
+	"github.com/LoveLosita/smartflow/backend/shared/respond"
+	"github.com/LoveLosita/smartflow/backend/services/tokenstore/rpc/pb"
+	tokenstoresv "github.com/LoveLosita/smartflow/backend/services/tokenstore/sv"
+	tokencontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/tokenstore"
+)
+
+type Handler struct {
+	pb.UnimplementedTokenStoreServiceServer
+	svc *tokenstoresv.Service
+}
+
+func NewHandler(svc *tokenstoresv.Service) *Handler {
+	return &Handler{svc: svc}
+}
+
+// service 负责统一校验 RPC 层依赖是否已经注入。
+//
+// 职责边界：
+// 1. 只判断 handler 自身和业务 service 是否可用；
+// 2. 不负责支付状态流转、订单幂等和 grant 账本写入；
+// 3. 失败时返回可直接转成 gRPC status 的业务错误。
+func (h *Handler) service() (*tokenstoresv.Service, error) {
+	if h == nil || h.svc == nil {
+		return nil, errors.New("tokenstore service dependency not initialized")
+	}
+	return h.svc, nil
+}
+
+// GetSummary 负责把 Token 概览请求从 gRPC 协议转成内部服务调用。
+func (h *Handler) GetSummary(ctx context.Context, req *pb.GetTokenSummaryRequest) (*pb.GetTokenSummaryResponse, error) {
+	svc, err := h.service()
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	if req == nil {
+		return nil, grpcErrorFromServiceError(respond.MissingParam)
+	}
+
+	summary, err := svc.GetSummary(ctx, req.ActorUserId)
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.GetTokenSummaryResponse{Summary: tokenSummaryToPB(summary)}, nil
+}
+
+func (h *Handler) ListProducts(ctx context.Context, req *pb.ListTokenProductsRequest) (*pb.ListTokenProductsResponse, error) {
+	svc, err := h.service()
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	if req == nil {
+		return nil, grpcErrorFromServiceError(respond.MissingParam)
+	}
+
+	items, err := svc.ListProducts(ctx, req.ActorUserId)
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.ListTokenProductsResponse{Items: tokenProductsToPB(items)}, nil
+}
+
+func (h *Handler) CreateOrder(ctx context.Context, req *pb.CreateTokenOrderRequest) (*pb.CreateTokenOrderResponse, error) {
+	svc, err := h.service()
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	if req == nil {
+		return nil, grpcErrorFromServiceError(respond.MissingParam)
+	}
+
+	order, err := svc.CreateOrder(ctx, tokencontracts.CreateTokenOrderRequest{
+		ActorUserID:    req.ActorUserId,
+		ProductID:      req.ProductId,
+		Quantity:       int(req.Quantity),
+		IdempotencyKey: req.IdempotencyKey,
+	})
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.CreateTokenOrderResponse{Order: tokenOrderToPB(order)}, nil
+}
+
+func (h *Handler) ListOrders(ctx context.Context, req *pb.ListTokenOrdersRequest) (*pb.ListTokenOrdersResponse, error) {
+	svc, err := h.service()
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	if req == nil {
+		return nil, grpcErrorFromServiceError(respond.MissingParam)
+	}
+
+	items, page, err := svc.ListOrders(ctx, tokencontracts.ListTokenOrdersRequest{
+		ActorUserID: req.ActorUserId,
+		Page:        int(req.Page),
+		PageSize:    int(req.PageSize),
+		Status:      req.Status,
+	})
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.ListTokenOrdersResponse{
+		Items: tokenOrdersToPB(items),
+		Page:  tokenPageToPB(page),
+	}, nil
+}
+
+func (h *Handler) GetOrder(ctx context.Context, req *pb.GetTokenOrderRequest) (*pb.GetTokenOrderResponse, error) {
+	svc, err := h.service()
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	if req == nil {
+		return nil, grpcErrorFromServiceError(respond.MissingParam)
+	}
+
+	order, err := svc.GetOrder(ctx, req.ActorUserId, req.OrderId)
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.GetTokenOrderResponse{Order: tokenOrderToPB(order)}, nil
+}
+
+func (h *Handler) MockPaidOrder(ctx context.Context, req *pb.MockPaidOrderRequest) (*pb.MockPaidOrderResponse, error) {
+	svc, err := h.service()
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	if req == nil {
+		return nil, grpcErrorFromServiceError(respond.MissingParam)
+	}
+
+	order, err := svc.MockPaidOrder(ctx, tokencontracts.MockPaidOrderRequest{
+		ActorUserID:    req.ActorUserId,
+		OrderID:        req.OrderId,
+		MockChannel:    req.MockChannel,
+		IdempotencyKey: req.IdempotencyKey,
+	})
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.MockPaidOrderResponse{Order: tokenOrderToPB(order)}, nil
+}
+
+func (h *Handler) ListGrants(ctx context.Context, req *pb.ListTokenGrantsRequest) (*pb.ListTokenGrantsResponse, error) {
+	svc, err := h.service()
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	if req == nil {
+		return nil, grpcErrorFromServiceError(respond.MissingParam)
+	}
+
+	items, page, err := svc.ListGrants(ctx, tokencontracts.ListTokenGrantsRequest{
+		ActorUserID: req.ActorUserId,
+		Page:        int(req.Page),
+		PageSize:    int(req.PageSize),
+		Source:      req.Source,
+	})
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.ListTokenGrantsResponse{
+		Items: tokenGrantsToPB(items),
+		Page:  tokenPageToPB(page),
+	}, nil
+}
+
+// RecordForumRewardGrant 负责把论坛 outbox 奖励事件转成 token-store 内部账本写入调用。
+func (h *Handler) RecordForumRewardGrant(ctx context.Context, req *pb.RecordForumRewardGrantRequest) (*pb.RecordForumRewardGrantResponse, error) {
+	svc, err := h.service()
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	if req == nil {
+		return nil, grpcErrorFromServiceError(respond.MissingParam)
+	}
+
+	grant, err := svc.RecordForumRewardGrant(ctx, tokencontracts.RecordForumRewardGrantRequest{
+		EventID:        req.EventId,
+		ReceiverUserID: req.ReceiverUserId,
+		Source:         req.Source,
+		SourceRefID:    req.SourceRefId,
+	})
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.RecordForumRewardGrantResponse{Grant: tokenGrantToPB(grant)}, nil
+}
+
+func tokenPageToPB(page tokencontracts.PageResult) *pb.PageResponse {
+	return &pb.PageResponse{
+		Page:     int32(page.Page),
+		PageSize: int32(page.PageSize),
+		Total:    int32(page.Total),
+		HasMore:  page.HasMore,
+	}
+}
+
+func tokenSummaryToPB(summary *tokencontracts.TokenSummary) *pb.TokenSummary {
+	if summary == nil {
+		return nil
+	}
+	return &pb.TokenSummary{
+		RecordedTokenTotal:     summary.RecordedTokenTotal,
+		AppliedTokenTotal:      summary.AppliedTokenTotal,
+		PendingApplyTokenTotal: summary.PendingApplyTokenTotal,
+		QuotaSyncStatus:        summary.QuotaSyncStatus,
+		Tip:                    summary.Tip,
+	}
+}
+
+func tokenProductToPB(product tokencontracts.TokenProductView) *pb.TokenProductView {
+	return &pb.TokenProductView{
+		ProductId:   product.ProductID,
+		Name:        product.Name,
+		Description: product.Description,
+		TokenAmount: product.TokenAmount,
+		PriceCent:   product.PriceCent,
+		PriceText:   product.PriceText,
+		Currency:    product.Currency,
+		Badge:       product.Badge,
+		Status:      product.Status,
+		SortOrder:   int32(product.SortOrder),
+	}
+}
+
+func tokenProductsToPB(items []tokencontracts.TokenProductView) []*pb.TokenProductView {
+	if len(items) == 0 {
+		return nil
+	}
+	result := make([]*pb.TokenProductView, 0, len(items))
+	for i := range items {
+		result = append(result, tokenProductToPB(items[i]))
+	}
+	return result
+}
+
+func tokenGrantToPB(grant *tokencontracts.TokenGrantView) *pb.TokenGrantView {
+	if grant == nil {
+		return nil
+	}
+	return &pb.TokenGrantView{
+		GrantId:      grant.GrantID,
+		EventId:      grant.EventID,
+		Source:       grant.Source,
+		SourceLabel:  grant.SourceLabel,
+		Amount:       grant.Amount,
+		Status:       grant.Status,
+		QuotaApplied: grant.QuotaApplied,
+		Description:  grant.Description,
+		CreatedAt:    grant.CreatedAt,
+	}
+}
+
+func tokenGrantsToPB(items []tokencontracts.TokenGrantView) []*pb.TokenGrantView {
+	if len(items) == 0 {
+		return nil
+	}
+	result := make([]*pb.TokenGrantView, 0, len(items))
+	for i := range items {
+		item := items[i]
+		result = append(result, tokenGrantToPB(&item))
+	}
+	return result
+}
+
+func tokenOrderToPB(order *tokencontracts.TokenOrderView) *pb.TokenOrderView {
+	if order == nil {
+		return nil
+	}
+	return &pb.TokenOrderView{
+		OrderId:         order.OrderID,
+		OrderNo:         order.OrderNo,
+		Status:          order.Status,
+		TokenAmount:     order.TokenAmount,
+		AmountCent:      order.AmountCent,
+		PriceText:       order.PriceText,
+		Currency:        order.Currency,
+		PaymentMode:     order.PaymentMode,
+		Grant:           tokenGrantToPB(order.Grant),
+		CreatedAt:       order.CreatedAt,
+		PaidAt:          tokenStringFromPtr(order.PaidAt),
+		GrantedAt:       tokenStringFromPtr(order.GrantedAt),
+		ProductSnapshot: order.ProductSnapshot,
+		ProductName:     order.ProductName,
+		Quantity:        int32(order.Quantity),
+	}
+}
+
+func tokenOrdersToPB(items []tokencontracts.TokenOrderView) []*pb.TokenOrderView {
+	if len(items) == 0 {
+		return nil
+	}
+	result := make([]*pb.TokenOrderView, 0, len(items))
+	for i := range items {
+		item := items[i]
+		result = append(result, tokenOrderToPB(&item))
+	}
+	return result
+}
+
+func tokenStringFromPtr(value *string) string {
+	if value == nil {
+		return ""
+	}
+	return *value
+}
--- a/backend/services/tokenstore/rpc/pb/tokenstore.pb.go
+++ b/backend/services/tokenstore/rpc/pb/tokenstore.pb.go
@@ -0,0 +1,231 @@
+package pb
+
+import proto "github.com/golang/protobuf/proto"
+
+var _ = proto.Marshal
+
+const _ = proto.ProtoPackageIsVersion3
+
+type PageResponse struct {
+	Page     int32 `protobuf:"varint,1,opt,name=page,proto3" json:"page,omitempty"`
+	PageSize int32 `protobuf:"varint,2,opt,name=page_size,json=pageSize,proto3" json:"page_size,omitempty"`
+	Total    int32 `protobuf:"varint,3,opt,name=total,proto3" json:"total,omitempty"`
+	HasMore  bool  `protobuf:"varint,4,opt,name=has_more,json=hasMore,proto3" json:"has_more,omitempty"`
+}
+
+func (m *PageResponse) Reset()         { *m = PageResponse{} }
+func (m *PageResponse) String() string { return proto.CompactTextString(m) }
+func (*PageResponse) ProtoMessage()    {}
+
+type TokenSummary struct {
+	RecordedTokenTotal     int64  `protobuf:"varint,1,opt,name=recorded_token_total,json=recordedTokenTotal,proto3" json:"recorded_token_total,omitempty"`
+	AppliedTokenTotal      int64  `protobuf:"varint,2,opt,name=applied_token_total,json=appliedTokenTotal,proto3" json:"applied_token_total,omitempty"`
+	PendingApplyTokenTotal int64  `protobuf:"varint,3,opt,name=pending_apply_token_total,json=pendingApplyTokenTotal,proto3" json:"pending_apply_token_total,omitempty"`
+	QuotaSyncStatus        string `protobuf:"bytes,4,opt,name=quota_sync_status,json=quotaSyncStatus,proto3" json:"quota_sync_status,omitempty"`
+	Tip                    string `protobuf:"bytes,5,opt,name=tip,proto3" json:"tip,omitempty"`
+}
+
+func (m *TokenSummary) Reset()         { *m = TokenSummary{} }
+func (m *TokenSummary) String() string { return proto.CompactTextString(m) }
+func (*TokenSummary) ProtoMessage()    {}
+
+type TokenProductView struct {
+	ProductId   uint64 `protobuf:"varint,1,opt,name=product_id,json=productId,proto3" json:"product_id,omitempty"`
+	Name        string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
+	Description string `protobuf:"bytes,3,opt,name=description,proto3" json:"description,omitempty"`
+	TokenAmount int64  `protobuf:"varint,4,opt,name=token_amount,json=tokenAmount,proto3" json:"token_amount,omitempty"`
+	PriceCent   int64  `protobuf:"varint,5,opt,name=price_cent,json=priceCent,proto3" json:"price_cent,omitempty"`
+	PriceText   string `protobuf:"bytes,6,opt,name=price_text,json=priceText,proto3" json:"price_text,omitempty"`
+	Currency    string `protobuf:"bytes,7,opt,name=currency,proto3" json:"currency,omitempty"`
+	Badge       string `protobuf:"bytes,8,opt,name=badge,proto3" json:"badge,omitempty"`
+	Status      string `protobuf:"bytes,9,opt,name=status,proto3" json:"status,omitempty"`
+	SortOrder   int32  `protobuf:"varint,10,opt,name=sort_order,json=sortOrder,proto3" json:"sort_order,omitempty"`
+}
+
+func (m *TokenProductView) Reset()         { *m = TokenProductView{} }
+func (m *TokenProductView) String() string { return proto.CompactTextString(m) }
+func (*TokenProductView) ProtoMessage()    {}
+
+type TokenGrantView struct {
+	GrantId      uint64 `protobuf:"varint,1,opt,name=grant_id,json=grantId,proto3" json:"grant_id,omitempty"`
+	EventId      string `protobuf:"bytes,2,opt,name=event_id,json=eventId,proto3" json:"event_id,omitempty"`
+	Source       string `protobuf:"bytes,3,opt,name=source,proto3" json:"source,omitempty"`
+	SourceLabel  string `protobuf:"bytes,4,opt,name=source_label,json=sourceLabel,proto3" json:"source_label,omitempty"`
+	Amount       int64  `protobuf:"varint,5,opt,name=amount,proto3" json:"amount,omitempty"`
+	Status       string `protobuf:"bytes,6,opt,name=status,proto3" json:"status,omitempty"`
+	QuotaApplied bool   `protobuf:"varint,7,opt,name=quota_applied,json=quotaApplied,proto3" json:"quota_applied,omitempty"`
+	Description  string `protobuf:"bytes,8,opt,name=description,proto3" json:"description,omitempty"`
+	CreatedAt    string `protobuf:"bytes,9,opt,name=created_at,json=createdAt,proto3" json:"created_at,omitempty"`
+}
+
+func (m *TokenGrantView) Reset()         { *m = TokenGrantView{} }
+func (m *TokenGrantView) String() string { return proto.CompactTextString(m) }
+func (*TokenGrantView) ProtoMessage()    {}
+
+type TokenOrderView struct {
+	OrderId         uint64          `protobuf:"varint,1,opt,name=order_id,json=orderId,proto3" json:"order_id,omitempty"`
+	OrderNo         string          `protobuf:"bytes,2,opt,name=order_no,json=orderNo,proto3" json:"order_no,omitempty"`
+	Status          string          `protobuf:"bytes,3,opt,name=status,proto3" json:"status,omitempty"`
+	TokenAmount     int64           `protobuf:"varint,4,opt,name=token_amount,json=tokenAmount,proto3" json:"token_amount,omitempty"`
+	AmountCent      int64           `protobuf:"varint,5,opt,name=amount_cent,json=amountCent,proto3" json:"amount_cent,omitempty"`
+	PriceText       string          `protobuf:"bytes,6,opt,name=price_text,json=priceText,proto3" json:"price_text,omitempty"`
+	Currency        string          `protobuf:"bytes,7,opt,name=currency,proto3" json:"currency,omitempty"`
+	PaymentMode     string          `protobuf:"bytes,8,opt,name=payment_mode,json=paymentMode,proto3" json:"payment_mode,omitempty"`
+	Grant           *TokenGrantView `protobuf:"bytes,9,opt,name=grant,proto3" json:"grant,omitempty"`
+	CreatedAt       string          `protobuf:"bytes,10,opt,name=created_at,json=createdAt,proto3" json:"created_at,omitempty"`
+	PaidAt          string          `protobuf:"bytes,11,opt,name=paid_at,json=paidAt,proto3" json:"paid_at,omitempty"`
+	GrantedAt       string          `protobuf:"bytes,12,opt,name=granted_at,json=grantedAt,proto3" json:"granted_at,omitempty"`
+	ProductSnapshot string          `protobuf:"bytes,13,opt,name=product_snapshot,json=productSnapshot,proto3" json:"product_snapshot,omitempty"`
+	ProductName     string          `protobuf:"bytes,14,opt,name=product_name,json=productName,proto3" json:"product_name,omitempty"`
+	Quantity        int32           `protobuf:"varint,15,opt,name=quantity,proto3" json:"quantity,omitempty"`
+}
+
+func (m *TokenOrderView) Reset()         { *m = TokenOrderView{} }
+func (m *TokenOrderView) String() string { return proto.CompactTextString(m) }
+func (*TokenOrderView) ProtoMessage()    {}
+
+type GetTokenSummaryRequest struct {
+	ActorUserId uint64 `protobuf:"varint,1,opt,name=actor_user_id,json=actorUserId,proto3" json:"actor_user_id,omitempty"`
+}
+
+func (m *GetTokenSummaryRequest) Reset()         { *m = GetTokenSummaryRequest{} }
+func (m *GetTokenSummaryRequest) String() string { return proto.CompactTextString(m) }
+func (*GetTokenSummaryRequest) ProtoMessage()    {}
+
+type GetTokenSummaryResponse struct {
+	Summary *TokenSummary `protobuf:"bytes,1,opt,name=summary,proto3" json:"summary,omitempty"`
+}
+
+func (m *GetTokenSummaryResponse) Reset()         { *m = GetTokenSummaryResponse{} }
+func (m *GetTokenSummaryResponse) String() string { return proto.CompactTextString(m) }
+func (*GetTokenSummaryResponse) ProtoMessage()    {}
+
+type ListTokenProductsRequest struct {
+	ActorUserId uint64 `protobuf:"varint,1,opt,name=actor_user_id,json=actorUserId,proto3" json:"actor_user_id,omitempty"`
+}
+
+func (m *ListTokenProductsRequest) Reset()         { *m = ListTokenProductsRequest{} }
+func (m *ListTokenProductsRequest) String() string { return proto.CompactTextString(m) }
+func (*ListTokenProductsRequest) ProtoMessage()    {}
+
+type ListTokenProductsResponse struct {
+	Items []*TokenProductView `protobuf:"bytes,1,rep,name=items,proto3" json:"items,omitempty"`
+}
+
+func (m *ListTokenProductsResponse) Reset()         { *m = ListTokenProductsResponse{} }
+func (m *ListTokenProductsResponse) String() string { return proto.CompactTextString(m) }
+func (*ListTokenProductsResponse) ProtoMessage()    {}
+
+type CreateTokenOrderRequest struct {
+	ActorUserId    uint64 `protobuf:"varint,1,opt,name=actor_user_id,json=actorUserId,proto3" json:"actor_user_id,omitempty"`
+	ProductId      uint64 `protobuf:"varint,2,opt,name=product_id,json=productId,proto3" json:"product_id,omitempty"`
+	Quantity       int32  `protobuf:"varint,3,opt,name=quantity,proto3" json:"quantity,omitempty"`
+	IdempotencyKey string `protobuf:"bytes,4,opt,name=idempotency_key,json=idempotencyKey,proto3" json:"idempotency_key,omitempty"`
+}
+
+func (m *CreateTokenOrderRequest) Reset()         { *m = CreateTokenOrderRequest{} }
+func (m *CreateTokenOrderRequest) String() string { return proto.CompactTextString(m) }
+func (*CreateTokenOrderRequest) ProtoMessage()    {}
+
+type CreateTokenOrderResponse struct {
+	Order *TokenOrderView `protobuf:"bytes,1,opt,name=order,proto3" json:"order,omitempty"`
+}
+
+func (m *CreateTokenOrderResponse) Reset()         { *m = CreateTokenOrderResponse{} }
+func (m *CreateTokenOrderResponse) String() string { return proto.CompactTextString(m) }
+func (*CreateTokenOrderResponse) ProtoMessage()    {}
+
+type ListTokenOrdersRequest struct {
+	ActorUserId uint64 `protobuf:"varint,1,opt,name=actor_user_id,json=actorUserId,proto3" json:"actor_user_id,omitempty"`
+	Page        int32  `protobuf:"varint,2,opt,name=page,proto3" json:"page,omitempty"`
+	PageSize    int32  `protobuf:"varint,3,opt,name=page_size,json=pageSize,proto3" json:"page_size,omitempty"`
+	Status      string `protobuf:"bytes,4,opt,name=status,proto3" json:"status,omitempty"`
+}
+
+func (m *ListTokenOrdersRequest) Reset()         { *m = ListTokenOrdersRequest{} }
+func (m *ListTokenOrdersRequest) String() string { return proto.CompactTextString(m) }
+func (*ListTokenOrdersRequest) ProtoMessage()    {}
+
+type ListTokenOrdersResponse struct {
+	Items []*TokenOrderView `protobuf:"bytes,1,rep,name=items,proto3" json:"items,omitempty"`
+	Page  *PageResponse     `protobuf:"bytes,2,opt,name=page,proto3" json:"page,omitempty"`
+}
+
+func (m *ListTokenOrdersResponse) Reset()         { *m = ListTokenOrdersResponse{} }
+func (m *ListTokenOrdersResponse) String() string { return proto.CompactTextString(m) }
+func (*ListTokenOrdersResponse) ProtoMessage()    {}
+
+type GetTokenOrderRequest struct {
+	ActorUserId uint64 `protobuf:"varint,1,opt,name=actor_user_id,json=actorUserId,proto3" json:"actor_user_id,omitempty"`
+	OrderId     uint64 `protobuf:"varint,2,opt,name=order_id,json=orderId,proto3" json:"order_id,omitempty"`
+}
+
+func (m *GetTokenOrderRequest) Reset()         { *m = GetTokenOrderRequest{} }
+func (m *GetTokenOrderRequest) String() string { return proto.CompactTextString(m) }
+func (*GetTokenOrderRequest) ProtoMessage()    {}
+
+type GetTokenOrderResponse struct {
+	Order *TokenOrderView `protobuf:"bytes,1,opt,name=order,proto3" json:"order,omitempty"`
+}
+
+func (m *GetTokenOrderResponse) Reset()         { *m = GetTokenOrderResponse{} }
+func (m *GetTokenOrderResponse) String() string { return proto.CompactTextString(m) }
+func (*GetTokenOrderResponse) ProtoMessage()    {}
+
+type MockPaidOrderRequest struct {
+	ActorUserId    uint64 `protobuf:"varint,1,opt,name=actor_user_id,json=actorUserId,proto3" json:"actor_user_id,omitempty"`
+	OrderId        uint64 `protobuf:"varint,2,opt,name=order_id,json=orderId,proto3" json:"order_id,omitempty"`
+	MockChannel    string `protobuf:"bytes,3,opt,name=mock_channel,json=mockChannel,proto3" json:"mock_channel,omitempty"`
+	IdempotencyKey string `protobuf:"bytes,4,opt,name=idempotency_key,json=idempotencyKey,proto3" json:"idempotency_key,omitempty"`
+}
+
+func (m *MockPaidOrderRequest) Reset()         { *m = MockPaidOrderRequest{} }
+func (m *MockPaidOrderRequest) String() string { return proto.CompactTextString(m) }
+func (*MockPaidOrderRequest) ProtoMessage()    {}
+
+type MockPaidOrderResponse struct {
+	Order *TokenOrderView `protobuf:"bytes,1,opt,name=order,proto3" json:"order,omitempty"`
+}
+
+func (m *MockPaidOrderResponse) Reset()         { *m = MockPaidOrderResponse{} }
+func (m *MockPaidOrderResponse) String() string { return proto.CompactTextString(m) }
+func (*MockPaidOrderResponse) ProtoMessage()    {}
+
+type ListTokenGrantsRequest struct {
+	ActorUserId uint64 `protobuf:"varint,1,opt,name=actor_user_id,json=actorUserId,proto3" json:"actor_user_id,omitempty"`
+	Page        int32  `protobuf:"varint,2,opt,name=page,proto3" json:"page,omitempty"`
+	PageSize    int32  `protobuf:"varint,3,opt,name=page_size,json=pageSize,proto3" json:"page_size,omitempty"`
+	Source      string `protobuf:"bytes,4,opt,name=source,proto3" json:"source,omitempty"`
+}
+
+func (m *ListTokenGrantsRequest) Reset()         { *m = ListTokenGrantsRequest{} }
+func (m *ListTokenGrantsRequest) String() string { return proto.CompactTextString(m) }
+func (*ListTokenGrantsRequest) ProtoMessage()    {}
+
+type ListTokenGrantsResponse struct {
+	Items []*TokenGrantView `protobuf:"bytes,1,rep,name=items,proto3" json:"items,omitempty"`
+	Page  *PageResponse     `protobuf:"bytes,2,opt,name=page,proto3" json:"page,omitempty"`
+}
+
+func (m *ListTokenGrantsResponse) Reset()         { *m = ListTokenGrantsResponse{} }
+func (m *ListTokenGrantsResponse) String() string { return proto.CompactTextString(m) }
+func (*ListTokenGrantsResponse) ProtoMessage()    {}
+
+type RecordForumRewardGrantRequest struct {
+	EventId        string `protobuf:"bytes,1,opt,name=event_id,json=eventId,proto3" json:"event_id,omitempty"`
+	ReceiverUserId uint64 `protobuf:"varint,2,opt,name=receiver_user_id,json=receiverUserId,proto3" json:"receiver_user_id,omitempty"`
+	Source         string `protobuf:"bytes,3,opt,name=source,proto3" json:"source,omitempty"`
+	SourceRefId    string `protobuf:"bytes,4,opt,name=source_ref_id,json=sourceRefId,proto3" json:"source_ref_id,omitempty"`
+}
+
+func (m *RecordForumRewardGrantRequest) Reset()         { *m = RecordForumRewardGrantRequest{} }
+func (m *RecordForumRewardGrantRequest) String() string { return proto.CompactTextString(m) }
+func (*RecordForumRewardGrantRequest) ProtoMessage()    {}
+
+type RecordForumRewardGrantResponse struct {
+	Grant *TokenGrantView `protobuf:"bytes,1,opt,name=grant,proto3" json:"grant,omitempty"`
+}
+
+func (m *RecordForumRewardGrantResponse) Reset()         { *m = RecordForumRewardGrantResponse{} }
+func (m *RecordForumRewardGrantResponse) String() string { return proto.CompactTextString(m) }
+func (*RecordForumRewardGrantResponse) ProtoMessage()    {}
--- a/backend/services/tokenstore/rpc/pb/tokenstore_grpc.pb.go
+++ b/backend/services/tokenstore/rpc/pb/tokenstore_grpc.pb.go
@@ -0,0 +1,185 @@
+package pb
+
+import (
+	context "context"
+
+	grpc "google.golang.org/grpc"
+	codes "google.golang.org/grpc/codes"
+	status "google.golang.org/grpc/status"
+)
+
+const (
+	TokenStoreService_GetSummary_FullMethodName             = "/smartflow.tokenstore.TokenStoreService/GetSummary"
+	TokenStoreService_ListProducts_FullMethodName           = "/smartflow.tokenstore.TokenStoreService/ListProducts"
+	TokenStoreService_CreateOrder_FullMethodName            = "/smartflow.tokenstore.TokenStoreService/CreateOrder"
+	TokenStoreService_ListOrders_FullMethodName             = "/smartflow.tokenstore.TokenStoreService/ListOrders"
+	TokenStoreService_GetOrder_FullMethodName               = "/smartflow.tokenstore.TokenStoreService/GetOrder"
+	TokenStoreService_MockPaidOrder_FullMethodName          = "/smartflow.tokenstore.TokenStoreService/MockPaidOrder"
+	TokenStoreService_ListGrants_FullMethodName             = "/smartflow.tokenstore.TokenStoreService/ListGrants"
+	TokenStoreService_RecordForumRewardGrant_FullMethodName = "/smartflow.tokenstore.TokenStoreService/RecordForumRewardGrant"
+)
+
+type TokenStoreServiceClient interface {
+	GetSummary(ctx context.Context, in *GetTokenSummaryRequest, opts ...grpc.CallOption) (*GetTokenSummaryResponse, error)
+	ListProducts(ctx context.Context, in *ListTokenProductsRequest, opts ...grpc.CallOption) (*ListTokenProductsResponse, error)
+	CreateOrder(ctx context.Context, in *CreateTokenOrderRequest, opts ...grpc.CallOption) (*CreateTokenOrderResponse, error)
+	ListOrders(ctx context.Context, in *ListTokenOrdersRequest, opts ...grpc.CallOption) (*ListTokenOrdersResponse, error)
+	GetOrder(ctx context.Context, in *GetTokenOrderRequest, opts ...grpc.CallOption) (*GetTokenOrderResponse, error)
+	MockPaidOrder(ctx context.Context, in *MockPaidOrderRequest, opts ...grpc.CallOption) (*MockPaidOrderResponse, error)
+	ListGrants(ctx context.Context, in *ListTokenGrantsRequest, opts ...grpc.CallOption) (*ListTokenGrantsResponse, error)
+	RecordForumRewardGrant(ctx context.Context, in *RecordForumRewardGrantRequest, opts ...grpc.CallOption) (*RecordForumRewardGrantResponse, error)
+}
+
+type tokenStoreServiceClient struct {
+	cc grpc.ClientConnInterface
+}
+
+func NewTokenStoreServiceClient(cc grpc.ClientConnInterface) TokenStoreServiceClient {
+	return &tokenStoreServiceClient{cc}
+}
+
+func (c *tokenStoreServiceClient) GetSummary(ctx context.Context, in *GetTokenSummaryRequest, opts ...grpc.CallOption) (*GetTokenSummaryResponse, error) {
+	return invokeTokenStore[GetTokenSummaryResponse](ctx, c.cc, TokenStoreService_GetSummary_FullMethodName, in, opts...)
+}
+
+func (c *tokenStoreServiceClient) ListProducts(ctx context.Context, in *ListTokenProductsRequest, opts ...grpc.CallOption) (*ListTokenProductsResponse, error) {
+	return invokeTokenStore[ListTokenProductsResponse](ctx, c.cc, TokenStoreService_ListProducts_FullMethodName, in, opts...)
+}
+
+func (c *tokenStoreServiceClient) CreateOrder(ctx context.Context, in *CreateTokenOrderRequest, opts ...grpc.CallOption) (*CreateTokenOrderResponse, error) {
+	return invokeTokenStore[CreateTokenOrderResponse](ctx, c.cc, TokenStoreService_CreateOrder_FullMethodName, in, opts...)
+}
+
+func (c *tokenStoreServiceClient) ListOrders(ctx context.Context, in *ListTokenOrdersRequest, opts ...grpc.CallOption) (*ListTokenOrdersResponse, error) {
+	return invokeTokenStore[ListTokenOrdersResponse](ctx, c.cc, TokenStoreService_ListOrders_FullMethodName, in, opts...)
+}
+
+func (c *tokenStoreServiceClient) GetOrder(ctx context.Context, in *GetTokenOrderRequest, opts ...grpc.CallOption) (*GetTokenOrderResponse, error) {
+	return invokeTokenStore[GetTokenOrderResponse](ctx, c.cc, TokenStoreService_GetOrder_FullMethodName, in, opts...)
+}
+
+func (c *tokenStoreServiceClient) MockPaidOrder(ctx context.Context, in *MockPaidOrderRequest, opts ...grpc.CallOption) (*MockPaidOrderResponse, error) {
+	return invokeTokenStore[MockPaidOrderResponse](ctx, c.cc, TokenStoreService_MockPaidOrder_FullMethodName, in, opts...)
+}
+
+func (c *tokenStoreServiceClient) ListGrants(ctx context.Context, in *ListTokenGrantsRequest, opts ...grpc.CallOption) (*ListTokenGrantsResponse, error) {
+	return invokeTokenStore[ListTokenGrantsResponse](ctx, c.cc, TokenStoreService_ListGrants_FullMethodName, in, opts...)
+}
+
+func (c *tokenStoreServiceClient) RecordForumRewardGrant(ctx context.Context, in *RecordForumRewardGrantRequest, opts ...grpc.CallOption) (*RecordForumRewardGrantResponse, error) {
+	return invokeTokenStore[RecordForumRewardGrantResponse](ctx, c.cc, TokenStoreService_RecordForumRewardGrant_FullMethodName, in, opts...)
+}
+
+func invokeTokenStore[Resp any](ctx context.Context, cc grpc.ClientConnInterface, fullMethod string, in interface{}, opts ...grpc.CallOption) (*Resp, error) {
+	out := new(Resp)
+	err := cc.Invoke(ctx, fullMethod, in, out, opts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+type TokenStoreServiceServer interface {
+	GetSummary(context.Context, *GetTokenSummaryRequest) (*GetTokenSummaryResponse, error)
+	ListProducts(context.Context, *ListTokenProductsRequest) (*ListTokenProductsResponse, error)
+	CreateOrder(context.Context, *CreateTokenOrderRequest) (*CreateTokenOrderResponse, error)
+	ListOrders(context.Context, *ListTokenOrdersRequest) (*ListTokenOrdersResponse, error)
+	GetOrder(context.Context, *GetTokenOrderRequest) (*GetTokenOrderResponse, error)
+	MockPaidOrder(context.Context, *MockPaidOrderRequest) (*MockPaidOrderResponse, error)
+	ListGrants(context.Context, *ListTokenGrantsRequest) (*ListTokenGrantsResponse, error)
+	RecordForumRewardGrant(context.Context, *RecordForumRewardGrantRequest) (*RecordForumRewardGrantResponse, error)
+}
+
+type UnimplementedTokenStoreServiceServer struct{}
+
+func (UnimplementedTokenStoreServiceServer) GetSummary(context.Context, *GetTokenSummaryRequest) (*GetTokenSummaryResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method GetSummary not implemented")
+}
+
+func (UnimplementedTokenStoreServiceServer) ListProducts(context.Context, *ListTokenProductsRequest) (*ListTokenProductsResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method ListProducts not implemented")
+}
+
+func (UnimplementedTokenStoreServiceServer) CreateOrder(context.Context, *CreateTokenOrderRequest) (*CreateTokenOrderResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method CreateOrder not implemented")
+}
+
+func (UnimplementedTokenStoreServiceServer) ListOrders(context.Context, *ListTokenOrdersRequest) (*ListTokenOrdersResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method ListOrders not implemented")
+}
+
+func (UnimplementedTokenStoreServiceServer) GetOrder(context.Context, *GetTokenOrderRequest) (*GetTokenOrderResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method GetOrder not implemented")
+}
+
+func (UnimplementedTokenStoreServiceServer) MockPaidOrder(context.Context, *MockPaidOrderRequest) (*MockPaidOrderResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method MockPaidOrder not implemented")
+}
+
+func (UnimplementedTokenStoreServiceServer) ListGrants(context.Context, *ListTokenGrantsRequest) (*ListTokenGrantsResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method ListGrants not implemented")
+}
+
+func (UnimplementedTokenStoreServiceServer) RecordForumRewardGrant(context.Context, *RecordForumRewardGrantRequest) (*RecordForumRewardGrantResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method RecordForumRewardGrant not implemented")
+}
+
+func RegisterTokenStoreServiceServer(s grpc.ServiceRegistrar, srv TokenStoreServiceServer) {
+	s.RegisterService(&TokenStoreService_ServiceDesc, srv)
+}
+
+func tokenStoreUnaryHandler[Req any](methodName string, fullMethod string, invoke func(TokenStoreServiceServer, context.Context, *Req) (interface{}, error)) grpc.MethodDesc {
+	return grpc.MethodDesc{
+		MethodName: methodName,
+		Handler: func(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+			in := new(Req)
+			if err := dec(in); err != nil {
+				return nil, err
+			}
+			if interceptor == nil {
+				return invoke(srv.(TokenStoreServiceServer), ctx, in)
+			}
+			info := &grpc.UnaryServerInfo{
+				Server:     srv,
+				FullMethod: fullMethod,
+			}
+			handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+				return invoke(srv.(TokenStoreServiceServer), ctx, req.(*Req))
+			}
+			return interceptor(ctx, in, info, handler)
+		},
+	}
+}
+
+var TokenStoreService_ServiceDesc = grpc.ServiceDesc{
+	ServiceName: "smartflow.tokenstore.TokenStoreService",
+	HandlerType: (*TokenStoreServiceServer)(nil),
+	Methods: []grpc.MethodDesc{
+		tokenStoreUnaryHandler[GetTokenSummaryRequest]("GetSummary", TokenStoreService_GetSummary_FullMethodName, func(s TokenStoreServiceServer, ctx context.Context, req *GetTokenSummaryRequest) (interface{}, error) {
+			return s.GetSummary(ctx, req)
+		}),
+		tokenStoreUnaryHandler[ListTokenProductsRequest]("ListProducts", TokenStoreService_ListProducts_FullMethodName, func(s TokenStoreServiceServer, ctx context.Context, req *ListTokenProductsRequest) (interface{}, error) {
+			return s.ListProducts(ctx, req)
+		}),
+		tokenStoreUnaryHandler[CreateTokenOrderRequest]("CreateOrder", TokenStoreService_CreateOrder_FullMethodName, func(s TokenStoreServiceServer, ctx context.Context, req *CreateTokenOrderRequest) (interface{}, error) {
+			return s.CreateOrder(ctx, req)
+		}),
+		tokenStoreUnaryHandler[ListTokenOrdersRequest]("ListOrders", TokenStoreService_ListOrders_FullMethodName, func(s TokenStoreServiceServer, ctx context.Context, req *ListTokenOrdersRequest) (interface{}, error) {
+			return s.ListOrders(ctx, req)
+		}),
+		tokenStoreUnaryHandler[GetTokenOrderRequest]("GetOrder", TokenStoreService_GetOrder_FullMethodName, func(s TokenStoreServiceServer, ctx context.Context, req *GetTokenOrderRequest) (interface{}, error) {
+			return s.GetOrder(ctx, req)
+		}),
+		tokenStoreUnaryHandler[MockPaidOrderRequest]("MockPaidOrder", TokenStoreService_MockPaidOrder_FullMethodName, func(s TokenStoreServiceServer, ctx context.Context, req *MockPaidOrderRequest) (interface{}, error) {
+			return s.MockPaidOrder(ctx, req)
+		}),
+		tokenStoreUnaryHandler[ListTokenGrantsRequest]("ListGrants", TokenStoreService_ListGrants_FullMethodName, func(s TokenStoreServiceServer, ctx context.Context, req *ListTokenGrantsRequest) (interface{}, error) {
+			return s.ListGrants(ctx, req)
+		}),
+		tokenStoreUnaryHandler[RecordForumRewardGrantRequest]("RecordForumRewardGrant", TokenStoreService_RecordForumRewardGrant_FullMethodName, func(s TokenStoreServiceServer, ctx context.Context, req *RecordForumRewardGrantRequest) (interface{}, error) {
+			return s.RecordForumRewardGrant(ctx, req)
+		}),
+	},
+	Streams:  []grpc.StreamDesc{},
+	Metadata: "tokenstore.proto",
+}
--- a/backend/services/tokenstore/rpc/server.go
+++ b/backend/services/tokenstore/rpc/server.go
@@ -0,0 +1,73 @@
+package rpc
+
+import (
+	"errors"
+	"log"
+	"strings"
+	"time"
+
+	"github.com/LoveLosita/smartflow/backend/services/tokenstore/rpc/pb"
+	tokenstoresv "github.com/LoveLosita/smartflow/backend/services/tokenstore/sv"
+	"github.com/zeromicro/go-zero/core/service"
+	"github.com/zeromicro/go-zero/zrpc"
+	"google.golang.org/grpc"
+)
+
+const (
+	defaultListenOn = "0.0.0.0:9095"
+	defaultTimeout  = 2 * time.Second
+)
+
+type ServerOptions struct {
+	ListenOn string
+	Timeout  time.Duration
+	Service  *tokenstoresv.Service
+}
+
+// Start 启动 token-store zrpc 服务。
+//
+// 职责边界：
+// 1. 只负责装配 go-zero zrpc server 和注册 protobuf service；
+// 2. 不创建 DB 连接，也不接入 user/auth 授额出口，这些依赖由 cmd 入口注入；
+// 3. 启动后阻塞当前进程，保持后续“一服务一进程”的迁移方向。
+func Start(opts ServerOptions) {
+	server, listenOn, err := NewServer(opts)
+	if err != nil {
+		log.Fatalf("failed to build tokenstore zrpc server: %v", err)
+	}
+	defer server.Stop()
+
+	log.Printf("tokenstore zrpc service starting on %s", listenOn)
+	server.Start()
+}
+
+// NewServer 负责创建 token-store RPC server，供 cmd 启动和测试复用。
+func NewServer(opts ServerOptions) (*zrpc.RpcServer, string, error) {
+	if opts.Service == nil {
+		return nil, "", errors.New("tokenstore service dependency not initialized")
+	}
+
+	listenOn := strings.TrimSpace(opts.ListenOn)
+	if listenOn == "" {
+		listenOn = defaultListenOn
+	}
+	timeout := opts.Timeout
+	if timeout <= 0 {
+		timeout = defaultTimeout
+	}
+
+	server, err := zrpc.NewServer(zrpc.RpcServerConf{
+		ServiceConf: service.ServiceConf{
+			Name: "tokenstore.rpc",
+			Mode: service.DevMode,
+		},
+		ListenOn: listenOn,
+		Timeout:  int64(timeout / time.Millisecond),
+	}, func(grpcServer *grpc.Server) {
+		pb.RegisterTokenStoreServiceServer(grpcServer, NewHandler(opts.Service))
+	})
+	if err != nil {
+		return nil, "", err
+	}
+	return server, listenOn, nil
+}
--- a/backend/services/tokenstore/rpc/tokenstore.proto
+++ b/backend/services/tokenstore/rpc/tokenstore.proto
@@ -0,0 +1,156 @@
+syntax = "proto3";
+
+package smartflow.tokenstore;
+
+option go_package = "github.com/LoveLosita/smartflow/backend/services/tokenstore/rpc/pb";
+
+service TokenStoreService {
+  rpc GetSummary(GetTokenSummaryRequest) returns (GetTokenSummaryResponse);
+  rpc ListProducts(ListTokenProductsRequest) returns (ListTokenProductsResponse);
+  rpc CreateOrder(CreateTokenOrderRequest) returns (CreateTokenOrderResponse);
+  rpc ListOrders(ListTokenOrdersRequest) returns (ListTokenOrdersResponse);
+  rpc GetOrder(GetTokenOrderRequest) returns (GetTokenOrderResponse);
+  rpc MockPaidOrder(MockPaidOrderRequest) returns (MockPaidOrderResponse);
+  rpc ListGrants(ListTokenGrantsRequest) returns (ListTokenGrantsResponse);
+  rpc RecordForumRewardGrant(RecordForumRewardGrantRequest) returns (RecordForumRewardGrantResponse);
+}
+
+message PageResponse {
+  int32 page = 1;
+  int32 page_size = 2;
+  int32 total = 3;
+  bool has_more = 4;
+}
+
+message TokenSummary {
+  int64 recorded_token_total = 1;
+  int64 applied_token_total = 2;
+  int64 pending_apply_token_total = 3;
+  string quota_sync_status = 4;
+  string tip = 5;
+}
+
+message TokenProductView {
+  uint64 product_id = 1;
+  string name = 2;
+  string description = 3;
+  int64 token_amount = 4;
+  int64 price_cent = 5;
+  string price_text = 6;
+  string currency = 7;
+  string badge = 8;
+  string status = 9;
+  int32 sort_order = 10;
+}
+
+message TokenGrantView {
+  uint64 grant_id = 1;
+  string event_id = 2;
+  string source = 3;
+  string source_label = 4;
+  int64 amount = 5;
+  string status = 6;
+  bool quota_applied = 7;
+  string description = 8;
+  string created_at = 9;
+}
+
+message TokenOrderView {
+  uint64 order_id = 1;
+  string order_no = 2;
+  string status = 3;
+  int64 token_amount = 4;
+  int64 amount_cent = 5;
+  string price_text = 6;
+  string currency = 7;
+  string payment_mode = 8;
+  TokenGrantView grant = 9;
+  string created_at = 10;
+  string paid_at = 11;
+  string granted_at = 12;
+  string product_snapshot = 13;
+  string product_name = 14;
+  int32 quantity = 15;
+}
+
+message GetTokenSummaryRequest {
+  uint64 actor_user_id = 1;
+}
+
+message GetTokenSummaryResponse {
+  TokenSummary summary = 1;
+}
+
+message ListTokenProductsRequest {
+  uint64 actor_user_id = 1;
+}
+
+message ListTokenProductsResponse {
+  repeated TokenProductView items = 1;
+}
+
+message CreateTokenOrderRequest {
+  uint64 actor_user_id = 1;
+  uint64 product_id = 2;
+  int32 quantity = 3;
+  string idempotency_key = 4;
+}
+
+message CreateTokenOrderResponse {
+  TokenOrderView order = 1;
+}
+
+message ListTokenOrdersRequest {
+  uint64 actor_user_id = 1;
+  int32 page = 2;
+  int32 page_size = 3;
+  string status = 4;
+}
+
+message ListTokenOrdersResponse {
+  repeated TokenOrderView items = 1;
+  PageResponse page = 2;
+}
+
+message GetTokenOrderRequest {
+  uint64 actor_user_id = 1;
+  uint64 order_id = 2;
+}
+
+message GetTokenOrderResponse {
+  TokenOrderView order = 1;
+}
+
+message MockPaidOrderRequest {
+  uint64 actor_user_id = 1;
+  uint64 order_id = 2;
+  string mock_channel = 3;
+  string idempotency_key = 4;
+}
+
+message MockPaidOrderResponse {
+  TokenOrderView order = 1;
+}
+
+message ListTokenGrantsRequest {
+  uint64 actor_user_id = 1;
+  int32 page = 2;
+  int32 page_size = 3;
+  string source = 4;
+}
+
+message ListTokenGrantsResponse {
+  repeated TokenGrantView items = 1;
+  PageResponse page = 2;
+}
+
+message RecordForumRewardGrantRequest {
+  string event_id = 1;
+  uint64 receiver_user_id = 2;
+  string source = 3;
+  string source_ref_id = 4;
+}
+
+message RecordForumRewardGrantResponse {
+  TokenGrantView grant = 1;
+}
--- a/backend/services/tokenstore/sv/grant.go
+++ b/backend/services/tokenstore/sv/grant.go
@@ -0,0 +1,84 @@
+package sv
+
+import (
+	"context"
+	"strings"
+
+	"github.com/LoveLosita/smartflow/backend/shared/respond"
+	tokenstoredao "github.com/LoveLosita/smartflow/backend/services/tokenstore/dao"
+	tokencontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/tokenstore"
+)
+
+// GetSummary 聚合当前用户在 token-store 账本中的获得记录。
+//
+// 职责边界：
+// 1. 只统计 token_grants，不读取 user/auth 的权威额度。
+// 2. 只汇总正向获取额度，避免把未来的冲正或补偿误算进 P0 展示口径。
+// 3. quota_sync_status 在 P0 固定为 not_connected，明确告知尚未打通权威额度。
+func (s *Service) GetSummary(ctx context.Context, actorUserID uint64) (*tokencontracts.TokenSummary, error) {
+	if err := s.Ready(); err != nil {
+		return nil, err
+	}
+	if actorUserID == 0 {
+		return nil, respond.MissingParam
+	}
+
+	summary, err := s.tokenDAO.SummarizePositiveGrants(ctx, actorUserID)
+	if err != nil {
+		return nil, err
+	}
+
+	pending := summary.RecordedTokenTotal - summary.AppliedTokenTotal
+	if pending < 0 {
+		pending = 0
+	}
+
+	return &tokencontracts.TokenSummary{
+		RecordedTokenTotal:     summary.RecordedTokenTotal,
+		AppliedTokenTotal:      summary.AppliedTokenTotal,
+		PendingApplyTokenTotal: pending,
+		QuotaSyncStatus:        tokenSummaryQuotaStatusNotConnected,
+		Tip:                    tokenSummaryTipP0,
+	}, nil
+}
+
+// ListGrants 按用户分页查询 Token 获得记录。
+//
+// 职责边界：
+// 1. 只支持 user_id 维度分页和 source 过滤，不做跨用户检索。
+// 2. 负责把空 source 归一化为“不筛选”，避免 DAO 层重复处理入口噪音。
+// 3. 结果只来自账本事实，不推导 user/auth 可用额度。
+func (s *Service) ListGrants(ctx context.Context, req tokencontracts.ListTokenGrantsRequest) ([]tokencontracts.TokenGrantView, tokencontracts.PageResult, error) {
+	if err := s.Ready(); err != nil {
+		return nil, tokencontracts.PageResult{}, err
+	}
+	if req.ActorUserID == 0 {
+		return nil, tokencontracts.PageResult{}, respond.MissingParam
+	}
+
+	page, pageSize := normalizePage(req.Page, req.PageSize)
+	query := tokenstoredao.ListTokenGrantsQuery{
+		UserID:   req.ActorUserID,
+		Page:     page,
+		PageSize: pageSize,
+		Source:   strings.TrimSpace(req.Source),
+	}
+
+	total, err := s.tokenDAO.CountGrants(ctx, query)
+	if err != nil {
+		return nil, tokencontracts.PageResult{}, err
+	}
+	grants, err := s.tokenDAO.ListGrants(ctx, query)
+	if err != nil {
+		return nil, tokencontracts.PageResult{}, err
+	}
+	if len(grants) == 0 {
+		return []tokencontracts.TokenGrantView{}, pageResult(page, pageSize, total), nil
+	}
+
+	result := make([]tokencontracts.TokenGrantView, 0, len(grants))
+	for _, grant := range grants {
+		result = append(result, grantViewFromModel(grant))
+	}
+	return result, pageResult(page, pageSize, total), nil
+}
--- a/backend/services/tokenstore/sv/helpers.go
+++ b/backend/services/tokenstore/sv/helpers.go
@@ -0,0 +1,238 @@
+package sv
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/LoveLosita/smartflow/backend/shared/respond"
+	tokenmodel "github.com/LoveLosita/smartflow/backend/services/tokenstore/model"
+	tokencontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/tokenstore"
+	"github.com/google/uuid"
+	"gorm.io/gorm"
+)
+
+const (
+	defaultPage     = 1
+	defaultPageSize = 20
+	maxPageSize     = 50
+
+	tokenSummaryQuotaStatusNotConnected = "not_connected"
+	tokenSummaryTipP0                   = "当前仅统计 Token 商店已记录的获得记录，尚未同步到 user/auth 可用额度。"
+)
+
+type productSnapshot struct {
+	ProductID   uint64 `json:"product_id"`
+	SKU         string `json:"sku"`
+	Name        string `json:"name"`
+	Description string `json:"description"`
+	TokenAmount int64  `json:"token_amount"`
+	PriceCent   int64  `json:"price_cent"`
+	PriceText   string `json:"price_text"`
+	Currency    string `json:"currency"`
+	Badge       string `json:"badge"`
+	Status      string `json:"status"`
+	SortOrder   int    `json:"sort_order"`
+}
+
+func normalizePage(page int, pageSize int) (int, int) {
+	if page <= 0 {
+		page = defaultPage
+	}
+	if pageSize <= 0 {
+		pageSize = defaultPageSize
+	}
+	if pageSize > maxPageSize {
+		pageSize = maxPageSize
+	}
+	return page, pageSize
+}
+
+func pageResult(page int, pageSize int, total int64) tokencontracts.PageResult {
+	return tokencontracts.PageResult{
+		Page:     page,
+		PageSize: pageSize,
+		Total:    int(total),
+		HasMore:  int64(page*pageSize) < total,
+	}
+}
+
+func formatTime(value time.Time) string {
+	if value.IsZero() {
+		return ""
+	}
+	return value.Format(time.RFC3339)
+}
+
+func formatTimePtr(value *time.Time) *string {
+	if value == nil || value.IsZero() {
+		return nil
+	}
+	formatted := value.Format(time.RFC3339)
+	return &formatted
+}
+
+func formatPriceText(currency string, amountCent int64) string {
+	if strings.EqualFold(strings.TrimSpace(currency), "CNY") {
+		return fmt.Sprintf("¥%.2f", float64(amountCent)/100)
+	}
+	return fmt.Sprintf("%s %.2f", strings.ToUpper(strings.TrimSpace(currency)), float64(amountCent)/100)
+}
+
+func stringPtrFromNonEmpty(value string) *string {
+	trimmed := strings.TrimSpace(value)
+	if trimmed == "" {
+		return nil
+	}
+	return &trimmed
+}
+
+func productViewFromModel(product tokenmodel.TokenProduct) tokencontracts.TokenProductView {
+	return tokencontracts.TokenProductView{
+		ProductID:   product.ID,
+		Name:        product.Name,
+		Description: product.Description,
+		TokenAmount: product.TokenAmount,
+		PriceCent:   product.PriceCent,
+		PriceText:   formatPriceText(product.Currency, product.PriceCent),
+		Currency:    product.Currency,
+		Badge:       product.Badge,
+		Status:      product.Status,
+		SortOrder:   product.SortOrder,
+	}
+}
+
+func grantViewFromModel(grant tokenmodel.TokenGrant) tokencontracts.TokenGrantView {
+	return tokencontracts.TokenGrantView{
+		GrantID:      grant.ID,
+		EventID:      grant.EventID,
+		Source:       grant.Source,
+		SourceLabel:  grantSourceLabel(grant.Source, grant.SourceLabel),
+		Amount:       grant.Amount,
+		Status:       grant.Status,
+		QuotaApplied: grant.QuotaApplied,
+		Description:  grant.Description,
+		CreatedAt:    formatTime(grant.CreatedAt),
+	}
+}
+
+func orderViewFromModel(order tokenmodel.TokenOrder, grant *tokenmodel.TokenGrant) tokencontracts.TokenOrderView {
+	var grantView *tokencontracts.TokenGrantView
+	if grant != nil {
+		view := grantViewFromModel(*grant)
+		grantView = &view
+	}
+
+	return tokencontracts.TokenOrderView{
+		OrderID:         order.ID,
+		OrderNo:         order.OrderNo,
+		Status:          order.Status,
+		ProductSnapshot: order.ProductSnapshotJSON,
+		ProductName:     order.ProductName,
+		Quantity:        order.Quantity,
+		TokenAmount:     order.TokenAmount,
+		AmountCent:      order.AmountCent,
+		PriceText:       formatPriceText(order.Currency, order.AmountCent),
+		Currency:        order.Currency,
+		PaymentMode:     order.PaymentMode,
+		Grant:           grantView,
+		CreatedAt:       formatTime(order.CreatedAt),
+		PaidAt:          formatTimePtr(order.PaidAt),
+		GrantedAt:       formatTimePtr(order.GrantedAt),
+	}
+}
+
+func grantSourceLabel(source string, fallback string) string {
+	if strings.TrimSpace(fallback) != "" {
+		return fallback
+	}
+	switch strings.TrimSpace(source) {
+	case tokenmodel.TokenGrantSourcePurchase:
+		return "购买充值"
+	case tokenmodel.TokenGrantSourceForumLike:
+		return "计划被点赞"
+	case tokenmodel.TokenGrantSourceForumImport:
+		return "计划被导入"
+	case tokenmodel.TokenGrantSourceManual:
+		return "人工补发"
+	default:
+		return "Token 获得记录"
+	}
+}
+
+func buildProductSnapshot(product tokenmodel.TokenProduct) (string, error) {
+	snapshot := productSnapshot{
+		ProductID:   product.ID,
+		SKU:         product.SKU,
+		Name:        product.Name,
+		Description: product.Description,
+		TokenAmount: product.TokenAmount,
+		PriceCent:   product.PriceCent,
+		PriceText:   formatPriceText(product.Currency, product.PriceCent),
+		Currency:    product.Currency,
+		Badge:       product.Badge,
+		Status:      product.Status,
+		SortOrder:   product.SortOrder,
+	}
+	raw, err := json.Marshal(snapshot)
+	if err != nil {
+		return "", err
+	}
+	return string(raw), nil
+}
+
+func newOrderNo() string {
+	return fmt.Sprintf(
+		"TS%s%s",
+		time.Now().Format("20060102150405"),
+		strings.ReplaceAll(uuid.NewString(), "-", ""),
+	)
+}
+
+func purchaseGrantEventID(orderID uint64) string {
+	return fmt.Sprintf("order:%d:paid", orderID)
+}
+
+func purchaseGrantDescription(productName string) string {
+	trimmed := strings.TrimSpace(productName)
+	if trimmed == "" {
+		return "购买 Token 商品"
+	}
+	return fmt.Sprintf("购买%s", trimmed)
+}
+
+func isDuplicateKeyError(err error) bool {
+	if err == nil {
+		return false
+	}
+	lower := strings.ToLower(err.Error())
+	return strings.Contains(lower, "duplicate entry") ||
+		strings.Contains(lower, "duplicate key") ||
+		strings.Contains(lower, "unique constraint") ||
+		strings.Contains(lower, "unique violation") ||
+		strings.Contains(lower, "error 1062")
+}
+
+func normalizeRecordNotFound(err error, fallback error) error {
+	if errorsIsRecordNotFound(err) {
+		return fallback
+	}
+	return err
+}
+
+func errorsIsRecordNotFound(err error) bool {
+	return errors.Is(err, gorm.ErrRecordNotFound)
+}
+
+// tokenStoreBadRequestStatus 是 token-store P0 统一业务校验错误码。
+// 具体错误原因仍放在 Info，避免为每个商品/订单校验分支提前扩散大量细分码。
+const tokenStoreBadRequestStatus = "40067"
+
+func tokenStoreBadRequest(message string) respond.Response {
+	return respond.Response{
+		Status: tokenStoreBadRequestStatus,
+		Info:   strings.TrimSpace(message),
+	}
+}
--- a/backend/services/tokenstore/sv/order.go
+++ b/backend/services/tokenstore/sv/order.go
@@ -0,0 +1,312 @@
+package sv
+
+import (
+	"context"
+	"strings"
+	"time"
+
+	"github.com/LoveLosita/smartflow/backend/shared/respond"
+	tokenstoredao "github.com/LoveLosita/smartflow/backend/services/tokenstore/dao"
+	tokenmodel "github.com/LoveLosita/smartflow/backend/services/tokenstore/model"
+	tokencontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/tokenstore"
+)
+
+// CreateOrder 创建 Token 商品订单。
+//
+// 职责边界：
+// 1. 校验 actor_user_id、product_id、quantity 与幂等键。
+// 2. 只生成 pending 订单和商品快照，不触发真实支付或 user/auth 同步。
+// 3. 并发冲突时优先按 user_id + idempotency_key 回查旧单，保证 P0 幂等语义。
+func (s *Service) CreateOrder(ctx context.Context, req tokencontracts.CreateTokenOrderRequest) (*tokencontracts.TokenOrderView, error) {
+	if err := s.Ready(); err != nil {
+		return nil, err
+	}
+	if req.ActorUserID == 0 || req.ProductID == 0 {
+		return nil, respond.MissingParam
+	}
+	if req.Quantity < 1 || req.Quantity > 99 {
+		return nil, tokenStoreBadRequest("quantity 仅支持 1 到 99")
+	}
+
+	idempotencyKey := strings.TrimSpace(req.IdempotencyKey)
+	if idempotencyKey != "" {
+		existing, err := s.tokenDAO.FindOrderByUserIdempotencyKey(ctx, req.ActorUserID, idempotencyKey)
+		if err != nil {
+			return nil, err
+		}
+		if existing != nil {
+			return s.orderViewByID(ctx, req.ActorUserID, existing.ID)
+		}
+	}
+
+	product, err := s.tokenDAO.FindActiveProductByID(ctx, req.ProductID)
+	if err != nil {
+		return nil, err
+	}
+	if product == nil {
+		return nil, tokenStoreBadRequest("商品不存在或已下架")
+	}
+
+	productSnapshot, err := buildProductSnapshot(*product)
+	if err != nil {
+		return nil, err
+	}
+
+	order := tokenmodel.TokenOrder{
+		OrderNo:             newOrderNo(),
+		UserID:              req.ActorUserID,
+		ProductID:           product.ID,
+		ProductSKU:          product.SKU,
+		ProductName:         product.Name,
+		ProductSnapshotJSON: productSnapshot,
+		Quantity:            req.Quantity,
+		TokenAmount:         product.TokenAmount * int64(req.Quantity),
+		AmountCent:          product.PriceCent * int64(req.Quantity),
+		Currency:            product.Currency,
+		Status:              tokenmodel.TokenOrderStatusPending,
+		PaymentMode:         "mock",
+		IdempotencyKey:      stringPtrFromNonEmpty(idempotencyKey),
+	}
+	if err := s.tokenDAO.CreateOrder(ctx, &order); err != nil {
+		if idempotencyKey != "" && isDuplicateKeyError(err) {
+			existing, findErr := s.tokenDAO.FindOrderByUserIdempotencyKey(ctx, req.ActorUserID, idempotencyKey)
+			if findErr != nil {
+				return nil, findErr
+			}
+			if existing != nil {
+				return s.orderViewByID(ctx, req.ActorUserID, existing.ID)
+			}
+		}
+		return nil, err
+	}
+
+	return s.orderViewByID(ctx, req.ActorUserID, order.ID)
+}
+
+// ListOrders 按用户分页查询订单列表。
+//
+// 职责边界：
+// 1. 只支持当前用户维度分页，不做跨用户检索。
+// 2. status 为空时不过滤，非空时按精确值过滤。
+// 3. 负责把订单与 grant 账本拼装成统一视图。
+func (s *Service) ListOrders(ctx context.Context, req tokencontracts.ListTokenOrdersRequest) ([]tokencontracts.TokenOrderView, tokencontracts.PageResult, error) {
+	if err := s.Ready(); err != nil {
+		return nil, tokencontracts.PageResult{}, err
+	}
+	if req.ActorUserID == 0 {
+		return nil, tokencontracts.PageResult{}, respond.MissingParam
+	}
+
+	page, pageSize := normalizePage(req.Page, req.PageSize)
+	query := tokenstoredao.ListTokenOrdersQuery{
+		UserID:   req.ActorUserID,
+		Page:     page,
+		PageSize: pageSize,
+		Status:   strings.TrimSpace(req.Status),
+	}
+
+	total, err := s.tokenDAO.CountOrders(ctx, query)
+	if err != nil {
+		return nil, tokencontracts.PageResult{}, err
+	}
+	orders, err := s.tokenDAO.ListOrders(ctx, query)
+	if err != nil {
+		return nil, tokencontracts.PageResult{}, err
+	}
+	if len(orders) == 0 {
+		return []tokencontracts.TokenOrderView{}, pageResult(page, pageSize, total), nil
+	}
+
+	grantMap, err := s.orderGrantMap(ctx, collectOrderIDs(orders))
+	if err != nil {
+		return nil, tokencontracts.PageResult{}, err
+	}
+
+	result := make([]tokencontracts.TokenOrderView, 0, len(orders))
+	for _, order := range orders {
+		result = append(result, orderViewFromModel(order, grantMap[order.ID]))
+	}
+	return result, pageResult(page, pageSize, total), nil
+}
+
+// GetOrder 查询单个订单详情，并校验归属用户。
+func (s *Service) GetOrder(ctx context.Context, actorUserID uint64, orderID uint64) (*tokencontracts.TokenOrderView, error) {
+	if err := s.Ready(); err != nil {
+		return nil, err
+	}
+	if actorUserID == 0 || orderID == 0 {
+		return nil, respond.MissingParam
+	}
+	return s.orderViewByID(ctx, actorUserID, orderID)
+}
+
+// MockPaidOrder 在同步事务里完成 mock paid 和 grant 入账。
+//
+// 职责边界：
+// 1. 只处理订单状态流转与 token_grants 幂等写入，不调用 user/auth。
+// 2. event_id 固定为 order:{order_id}:paid，作为最终 grant 幂等边界。
+// 3. 重复调用优先复用既有 grant，再把订单补齐到 granted，避免重复写账本。
+func (s *Service) MockPaidOrder(ctx context.Context, req tokencontracts.MockPaidOrderRequest) (*tokencontracts.TokenOrderView, error) {
+	if err := s.Ready(); err != nil {
+		return nil, err
+	}
+	if req.ActorUserID == 0 || req.OrderID == 0 {
+		return nil, respond.MissingParam
+	}
+
+	var resultOrder tokenmodel.TokenOrder
+	var resultGrant *tokenmodel.TokenGrant
+	err := s.tokenDAO.Transaction(ctx, func(txDAO *tokenstoredao.TokenStoreDAO) error {
+		now := time.Now()
+
+		// 1. 先锁订单并校验归属，避免并发 mock paid 重复写 grant。
+		// 2. 订单不存在直接返回；订单不属于当前用户时明确拒绝。
+		// 3. closed 状态不允许继续支付，避免把关闭单重新拉回可用态。
+		order, err := txDAO.LockOrderByID(ctx, req.OrderID)
+		if err != nil {
+			return normalizeRecordNotFound(err, tokenStoreBadRequest("订单不存在"))
+		}
+		if order.UserID != req.ActorUserID {
+			return tokenStoreBadRequest("订单不属于当前用户")
+		}
+		switch order.Status {
+		case tokenmodel.TokenOrderStatusPending, tokenmodel.TokenOrderStatusPaid, tokenmodel.TokenOrderStatusGranted:
+		case tokenmodel.TokenOrderStatusClosed:
+			return tokenStoreBadRequest("订单已关闭，不能执行 mock paid")
+		default:
+			return tokenStoreBadRequest("订单状态不支持执行 mock paid")
+		}
+
+		eventID := purchaseGrantEventID(order.ID)
+		grant, err := txDAO.FindGrantByEventID(ctx, eventID)
+		if err != nil {
+			return err
+		}
+
+		// 1. grant 不存在时才尝试创建，保证账本幂等写入边界只在 event_id。
+		// 2. 即使因为历史脏数据或极端并发触发唯一冲突，也要立刻按 event_id 反查旧 grant。
+		// 3. 这里不写 user/auth，只把 token-store 自己的账本事实补齐。
+		if grant == nil {
+			sourceRefID := order.ID
+			orderID := order.ID
+			newGrant := &tokenmodel.TokenGrant{
+				EventID:      eventID,
+				UserID:       order.UserID,
+				Source:       tokenmodel.TokenGrantSourcePurchase,
+				SourceLabel:  grantSourceLabel(tokenmodel.TokenGrantSourcePurchase, ""),
+				SourceRefID:  &sourceRefID,
+				OrderID:      &orderID,
+				Amount:       order.TokenAmount,
+				Status:       tokenmodel.TokenGrantStatusRecorded,
+				QuotaApplied: false,
+				Description:  purchaseGrantDescription(order.ProductName),
+			}
+			if err := txDAO.CreateGrant(ctx, newGrant); err != nil {
+				if !isDuplicateKeyError(err) {
+					return err
+				}
+				newGrant, err = txDAO.FindGrantByEventID(ctx, eventID)
+				if err != nil {
+					return err
+				}
+				if newGrant == nil {
+					return tokenStoreBadRequest("Token 发放记录创建后未找到")
+				}
+			}
+			grant = newGrant
+		}
+
+		// 1. 无论订单原来是 pending、paid 还是 granted，只要 grant 已确定，就把订单补齐到 granted。
+		// 2. paid_at 缺失时使用本次确认时间；granted_at 缺失时优先复用 grant.created_at，保证链路时间可追溯。
+		// 3. 这样即便出现“grant 已有、订单未完成切流”的历史半状态，也能在重复调用时自愈。
+		paidAt := order.PaidAt
+		if paidAt == nil || paidAt.IsZero() {
+			paidAt = &now
+		}
+		grantedAt := order.GrantedAt
+		if grantedAt == nil || grantedAt.IsZero() {
+			if grant != nil && !grant.CreatedAt.IsZero() {
+				grantCreatedAt := grant.CreatedAt
+				grantedAt = &grantCreatedAt
+			} else {
+				grantedAt = &now
+			}
+		}
+		paymentMode := strings.TrimSpace(order.PaymentMode)
+		if paymentMode == "" {
+			paymentMode = strings.TrimSpace(req.MockChannel)
+		}
+		if paymentMode == "" {
+			paymentMode = "mock"
+		}
+		if err := txDAO.UpdateOrderState(ctx, order.ID, tokenmodel.TokenOrderStatusGranted, paidAt, grantedAt, paymentMode); err != nil {
+			return err
+		}
+
+		order.Status = tokenmodel.TokenOrderStatusGranted
+		order.PaidAt = paidAt
+		order.GrantedAt = grantedAt
+		order.PaymentMode = paymentMode
+		resultOrder = *order
+		resultGrant = grant
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	view := orderViewFromModel(resultOrder, resultGrant)
+	return &view, nil
+}
+
+func (s *Service) orderViewByID(ctx context.Context, actorUserID uint64, orderID uint64) (*tokencontracts.TokenOrderView, error) {
+	order, err := s.tokenDAO.FindOrderByID(ctx, orderID)
+	if err != nil {
+		return nil, err
+	}
+	if order == nil {
+		return nil, tokenStoreBadRequest("订单不存在")
+	}
+	if order.UserID != actorUserID {
+		return nil, tokenStoreBadRequest("订单不属于当前用户")
+	}
+
+	grant, err := s.tokenDAO.FindGrantByOrderID(ctx, order.ID)
+	if err != nil {
+		return nil, err
+	}
+	view := orderViewFromModel(*order, grant)
+	return &view, nil
+}
+
+func (s *Service) orderGrantMap(ctx context.Context, orderIDs []uint64) (map[uint64]*tokenmodel.TokenGrant, error) {
+	result := make(map[uint64]*tokenmodel.TokenGrant, len(orderIDs))
+	if len(orderIDs) == 0 {
+		return result, nil
+	}
+
+	grants, err := s.tokenDAO.ListGrantsByOrderIDs(ctx, orderIDs)
+	if err != nil {
+		return nil, err
+	}
+	for i := range grants {
+		grant := grants[i]
+		if grant.OrderID == nil {
+			continue
+		}
+		if _, exists := result[*grant.OrderID]; exists {
+			continue
+		}
+		grantCopy := grant
+		result[*grant.OrderID] = &grantCopy
+	}
+	return result, nil
+}
+
+func collectOrderIDs(orders []tokenmodel.TokenOrder) []uint64 {
+	result := make([]uint64, 0, len(orders))
+	for _, order := range orders {
+		result = append(result, order.ID)
+	}
+	return result
+}
--- a/backend/services/tokenstore/sv/outbox.go
+++ b/backend/services/tokenstore/sv/outbox.go
@@ -0,0 +1,157 @@
+package sv
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log"
+	"strconv"
+	"strings"
+
+	tokencontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/tokenstore"
+	sharedevents "github.com/LoveLosita/smartflow/backend/shared/events"
+	kafkabus "github.com/LoveLosita/smartflow/backend/shared/infra/kafka"
+	outboxinfra "github.com/LoveLosita/smartflow/backend/shared/infra/outbox"
+)
+
+// OutboxBus 是 token-store 注册论坛奖励 handler 需要的最小总线接口。
+type OutboxBus interface {
+	RegisterEventHandler(eventType string, handler outboxinfra.MessageHandler) error
+}
+
+// RegisterForumRewardRoutes 只登记 token-store 负责消费的论坛奖励事件归属。
+//
+// 职责边界：
+// 1. 只负责把事件类型路由到 token-store 的服务级 outbox；
+// 2. 不注册 handler，也不启动 consumer；
+// 3. 供发布方和消费方在不同进程内共享同一份事件归属映射。
+func RegisterForumRewardRoutes() error {
+	if err := outboxinfra.RegisterEventService(sharedevents.ForumPostLikedEventType, outboxinfra.ServiceTokenStore); err != nil {
+		return err
+	}
+	return outboxinfra.RegisterEventService(sharedevents.ForumPostImportedEventType, outboxinfra.ServiceTokenStore)
+}
+
+// RegisterForumRewardHandlers 注册 token-store 对论坛奖励事件的消费处理器。
+//
+// 职责边界：
+// 1. 只消费 forum.post.liked / forum.post.imported 两类事件；
+// 2. 论坛奖励账本写入由 token-store Service 负责，handler 不自行计算金额；
+// 3. grant 写入成功后再标记 consumed；若标记失败，可依赖 event_id 幂等安全重试。
+func RegisterForumRewardHandlers(bus OutboxBus, outboxRepo *outboxinfra.Repository, svc *Service) error {
+	if bus == nil {
+		return errors.New("event bus is nil")
+	}
+	if outboxRepo == nil {
+		return errors.New("outbox repository is nil")
+	}
+	if svc == nil {
+		return errors.New("tokenstore service is nil")
+	}
+	if err := RegisterForumRewardRoutes(); err != nil {
+		return err
+	}
+	if err := registerForumRewardHandler(bus, outboxRepo, svc, sharedevents.ForumPostLikedEventType, sharedevents.ForumRewardSourceLike); err != nil {
+		return err
+	}
+	return registerForumRewardHandler(bus, outboxRepo, svc, sharedevents.ForumPostImportedEventType, sharedevents.ForumRewardSourceImport)
+}
+
+func registerForumRewardHandler(
+	bus OutboxBus,
+	outboxRepo *outboxinfra.Repository,
+	svc *Service,
+	eventType string,
+	source string,
+) error {
+	route, ok := outboxinfra.ResolveEventRoute(eventType)
+	if !ok {
+		return fmt.Errorf("forum reward outbox route is missing: eventType=%s", eventType)
+	}
+	eventOutboxRepo := outboxRepo.WithRoute(route)
+
+	handler := func(ctx context.Context, envelope kafkabus.Envelope) error {
+		if !isAllowedForumRewardEventVersion(envelope.EventVersion) {
+			if err := eventOutboxRepo.MarkDead(ctx, envelope.OutboxID, fmt.Sprintf("论坛奖励事件版本不受支持: %s", envelope.EventVersion)); err != nil {
+				return err
+			}
+			return nil
+		}
+
+		var payload sharedevents.ForumPostRewardPayload
+		if err := json.Unmarshal(envelope.Payload, &payload); err != nil {
+			if markErr := eventOutboxRepo.MarkDead(ctx, envelope.OutboxID, "解析论坛奖励载荷失败: "+err.Error()); markErr != nil {
+				return markErr
+			}
+			return nil
+		}
+		if err := payload.Validate(); err != nil {
+			if markErr := eventOutboxRepo.MarkDead(ctx, envelope.OutboxID, "论坛奖励载荷非法: "+err.Error()); markErr != nil {
+				return markErr
+			}
+			return nil
+		}
+		if payload.EventType() != eventType {
+			if markErr := eventOutboxRepo.MarkDead(ctx, envelope.OutboxID, fmt.Sprintf("论坛奖励事件类型不匹配: envelope=%s payload=%s", eventType, payload.EventType())); markErr != nil {
+				return markErr
+			}
+			return nil
+		}
+
+		eventID := strings.TrimSpace(envelope.EventID)
+		if eventID == "" {
+			eventID = strings.TrimSpace(payload.EventID)
+		}
+		if eventID == "" {
+			if markErr := eventOutboxRepo.MarkDead(ctx, envelope.OutboxID, "论坛奖励 event_id 为空"); markErr != nil {
+				return markErr
+			}
+			return nil
+		}
+
+		grant, err := svc.RecordForumRewardGrant(ctx, tokencontracts.RecordForumRewardGrantRequest{
+			EventID:        eventID,
+			ReceiverUserID: payload.RewardReceiverUserID,
+			Source:         forumRewardSource(payload, source),
+			SourceRefID:    forumRewardSourceRefID(payload, source),
+		})
+		if err != nil {
+			return err
+		}
+		if err := eventOutboxRepo.MarkConsumed(ctx, envelope.OutboxID); err != nil {
+			return err
+		}
+
+		log.Printf(
+			"forum reward event consumed by tokenstore: event_type=%s event_id=%s grant_id=%d outbox_id=%d",
+			eventType,
+			eventID,
+			grant.GrantID,
+			envelope.OutboxID,
+		)
+		return nil
+	}
+
+	return bus.RegisterEventHandler(eventType, handler)
+}
+
+func isAllowedForumRewardEventVersion(version string) bool {
+	version = strings.TrimSpace(version)
+	return version == "" || version == sharedevents.ForumRewardEventVersion
+}
+
+func forumRewardSource(payload sharedevents.ForumPostRewardPayload, fallback string) string {
+	source := strings.TrimSpace(payload.Source)
+	if source != "" {
+		return source
+	}
+	return fallback
+}
+
+func forumRewardSourceRefID(payload sharedevents.ForumPostRewardPayload, source string) string {
+	if source == sharedevents.ForumRewardSourceImport && payload.ImportID > 0 {
+		return strconv.FormatUint(payload.ImportID, 10)
+	}
+	return strconv.FormatUint(payload.PostID, 10)
+}
--- a/backend/services/tokenstore/sv/product.go
+++ b/backend/services/tokenstore/sv/product.go
@@ -0,0 +1,34 @@
+package sv
+
+import (
+	"context"
+
+	tokencontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/tokenstore"
+)
+
+// ListProducts 返回当前可售商品列表。
+//
+// 职责边界：
+// 1. 只返回 active 商品，不负责后台商品管理。
+// 2. 负责补齐 price_text，保持前端不必重复格式化价格。
+// 3. actorUserID 当前仅保留为统一接口形状，P0 不参与筛选。
+func (s *Service) ListProducts(ctx context.Context, actorUserID uint64) ([]tokencontracts.TokenProductView, error) {
+	_ = actorUserID
+	if err := s.Ready(); err != nil {
+		return nil, err
+	}
+
+	products, err := s.tokenDAO.ListActiveProducts(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if len(products) == 0 {
+		return []tokencontracts.TokenProductView{}, nil
+	}
+
+	result := make([]tokencontracts.TokenProductView, 0, len(products))
+	for _, product := range products {
+		result = append(result, productViewFromModel(product))
+	}
+	return result, nil
+}
--- a/backend/services/tokenstore/sv/reward.go
+++ b/backend/services/tokenstore/sv/reward.go
@@ -0,0 +1,234 @@
+package sv
+
+import (
+	"context"
+	"errors"
+	"strconv"
+	"strings"
+
+	tokenmodel "github.com/LoveLosita/smartflow/backend/services/tokenstore/model"
+	tokencontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/tokenstore"
+	"github.com/spf13/viper"
+)
+
+const (
+	forumLikeRewardConfigKey   = "tokenstore.reward.forumLikeAmount"
+	forumImportRewardConfigKey = "tokenstore.reward.forumImportAmount"
+
+	defaultForumLikeRewardAmount   int64 = 1
+	defaultForumImportRewardAmount int64 = 5
+)
+
+type forumRewardGrantRequest struct {
+	EventID        string
+	ReceiverUserID uint64
+	Source         string
+	SourceRefID    uint64
+}
+
+type forumRewardDecision struct {
+	Amount      int64
+	Status      string
+	Description string
+}
+
+// RecordForumRewardGrant 负责把论坛点赞/导入奖励写入 token_grants。
+//
+// 职责边界：
+// 1. 只处理 forum_like / forum_import 两类奖励账本写入，不修改 users，也不调用 user/auth；
+// 2. 以 event_id 作为最终幂等边界，重复请求校验一致后返回既有 grant；
+// 3. 奖励金额优先读取 token_reward_rules，配置和代码默认值只作为兜底。
+func (s *Service) RecordForumRewardGrant(ctx context.Context, req tokencontracts.RecordForumRewardGrantRequest) (*tokencontracts.TokenGrantView, error) {
+	if err := s.Ready(); err != nil {
+		return nil, err
+	}
+
+	normalized, err := normalizeForumRewardGrantRequest(req)
+	if err != nil {
+		return nil, err
+	}
+
+	// 1. 先按 event_id 回查，命中时直接视为成功，避免 outbox 重试重复写账本。
+	// 2. 命中后必须校验用户、来源和来源业务 ID，避免错误复用 event_id 时静默吞掉错账。
+	// 3. 校验通过才返回既有 grant，兼容“首次已成功、调用方超时后重试”的常见场景。
+	existing, err := s.tokenDAO.FindGrantByEventID(ctx, normalized.EventID)
+	if err != nil {
+		return nil, err
+	}
+	if existing != nil {
+		if err := validateExistingForumRewardGrant(*existing, normalized); err != nil {
+			return nil, err
+		}
+		view := grantViewFromModel(*existing)
+		return &view, nil
+	}
+
+	sourceRefID := normalized.SourceRefID
+	decision, err := s.forumRewardDecision(ctx, normalized.Source)
+	if err != nil {
+		return nil, err
+	}
+	grant := tokenmodel.TokenGrant{
+		EventID:      normalized.EventID,
+		UserID:       normalized.ReceiverUserID,
+		Source:       normalized.Source,
+		SourceLabel:  grantSourceLabel(normalized.Source, ""),
+		SourceRefID:  &sourceRefID,
+		Amount:       decision.Amount,
+		Status:       decision.Status,
+		QuotaApplied: false,
+		Description:  decision.Description,
+	}
+
+	// 1. 账本写入只依赖 token_grants.event_id 唯一约束兜底并发幂等。
+	// 2. 若并发下插入触发唯一键冲突，立刻回查 event_id，把已有 grant 当作成功结果返回。
+	// 3. 只有“冲突后仍查不到旧记录”这种异常态才上抛内部错误，避免吞掉真实一致性问题。
+	if err := s.tokenDAO.CreateGrant(ctx, &grant); err != nil {
+		if !isDuplicateKeyError(err) {
+			return nil, err
+		}
+
+		existing, err := s.tokenDAO.FindGrantByEventID(ctx, normalized.EventID)
+		if err != nil {
+			return nil, err
+		}
+		if existing == nil {
+			return nil, errors.New("forum reward grant duplicated but not found by event_id")
+		}
+		if err := validateExistingForumRewardGrant(*existing, normalized); err != nil {
+			return nil, err
+		}
+		view := grantViewFromModel(*existing)
+		return &view, nil
+	}
+
+	view := grantViewFromModel(grant)
+	return &view, nil
+}
+
+func normalizeForumRewardGrantRequest(req tokencontracts.RecordForumRewardGrantRequest) (forumRewardGrantRequest, error) {
+	normalized := forumRewardGrantRequest{
+		EventID:        strings.TrimSpace(req.EventID),
+		ReceiverUserID: req.ReceiverUserID,
+		Source:         strings.ToLower(strings.TrimSpace(req.Source)),
+	}
+
+	switch {
+	case normalized.EventID == "":
+		return forumRewardGrantRequest{}, tokenStoreBadRequest("event_id 不能为空")
+	case normalized.ReceiverUserID == 0:
+		return forumRewardGrantRequest{}, tokenStoreBadRequest("receiver_user_id 不能为空")
+	}
+
+	sourceRefID, err := parseForumRewardSourceRefID(req.SourceRefID)
+	if err != nil {
+		return forumRewardGrantRequest{}, err
+	}
+	normalized.SourceRefID = sourceRefID
+
+	switch normalized.Source {
+	case tokenmodel.TokenGrantSourceForumLike, tokenmodel.TokenGrantSourceForumImport:
+		return normalized, nil
+	default:
+		return forumRewardGrantRequest{}, tokenStoreBadRequest("source 仅支持 forum_like 或 forum_import")
+	}
+}
+
+func parseForumRewardSourceRefID(raw string) (uint64, error) {
+	trimmed := strings.TrimSpace(raw)
+	if trimmed == "" {
+		return 0, tokenStoreBadRequest("source_ref_id 不能为空")
+	}
+
+	parsed, err := strconv.ParseUint(trimmed, 10, 64)
+	if err != nil || parsed == 0 {
+		return 0, tokenStoreBadRequest("source_ref_id 必须是正整数")
+	}
+	return parsed, nil
+}
+
+// validateExistingForumRewardGrant 校验重复 event_id 是否真的是同一条论坛奖励。
+//
+// 职责边界：
+// 1. 只比较幂等所需的最小字段：接收人、来源和来源业务 ID；
+// 2. 不比较金额和状态，避免规则调整后重放旧事件被误判；
+// 3. 不一致时返回业务校验错误，让上游暴露这类错账风险。
+func validateExistingForumRewardGrant(existing tokenmodel.TokenGrant, req forumRewardGrantRequest) error {
+	sourceRefID := uint64(0)
+	if existing.SourceRefID != nil {
+		sourceRefID = *existing.SourceRefID
+	}
+	if existing.UserID != req.ReceiverUserID || existing.Source != req.Source || sourceRefID != req.SourceRefID {
+		return tokenStoreBadRequest("event_id 幂等冲突：已有奖励记录与本次论坛奖励请求不一致")
+	}
+	return nil
+}
+
+// forumRewardDecision 解析论坛奖励发放决策。
+//
+// 职责边界：
+// 1. 优先读取 token_reward_rules，保持“从表里读”的 P0 口径；
+// 2. 规则停用或金额非正时写 skipped 账本，消费 outbox 但不增加 Token；
+// 3. 表规则缺失时再读取配置和代码默认值，兼容旧环境尚未 seed 的情况。
+func (s *Service) forumRewardDecision(ctx context.Context, source string) (forumRewardDecision, error) {
+	rule, err := s.tokenDAO.FindRewardRuleBySource(ctx, source)
+	if err != nil {
+		return forumRewardDecision{}, err
+	}
+	if rule != nil {
+		if strings.TrimSpace(rule.Status) != tokenmodel.TokenRewardRuleStatusActive {
+			return skippedForumRewardDecision(source, "奖励规则已停用，未发放 Token"), nil
+		}
+		if rule.Amount <= 0 {
+			return skippedForumRewardDecision(source, "奖励规则金额非正，未发放 Token"), nil
+		}
+		return recordedForumRewardDecision(source, rule.Amount), nil
+	}
+
+	switch strings.TrimSpace(source) {
+	case tokenmodel.TokenGrantSourceForumLike:
+		return recordedForumRewardDecision(source, positiveConfigAmountOrDefault(forumLikeRewardConfigKey, defaultForumLikeRewardAmount)), nil
+	case tokenmodel.TokenGrantSourceForumImport:
+		return recordedForumRewardDecision(source, positiveConfigAmountOrDefault(forumImportRewardConfigKey, defaultForumImportRewardAmount)), nil
+	default:
+		return skippedForumRewardDecision(source, "未知论坛奖励来源，未发放 Token"), nil
+	}
+}
+
+func recordedForumRewardDecision(source string, amount int64) forumRewardDecision {
+	if amount <= 0 {
+		return skippedForumRewardDecision(source, "奖励金额非正，未发放 Token")
+	}
+	return forumRewardDecision{
+		Amount:      amount,
+		Status:      tokenmodel.TokenGrantStatusRecorded,
+		Description: forumRewardDescription(source),
+	}
+}
+
+func skippedForumRewardDecision(source string, description string) forumRewardDecision {
+	return forumRewardDecision{
+		Amount:      0,
+		Status:      tokenmodel.TokenGrantStatusSkipped,
+		Description: strings.TrimSpace(description),
+	}
+}
+
+func positiveConfigAmountOrDefault(configKey string, fallback int64) int64 {
+	amount := viper.GetInt64(configKey)
+	if amount <= 0 {
+		return fallback
+	}
+	return amount
+}
+
+func forumRewardDescription(source string) string {
+	switch strings.TrimSpace(source) {
+	case tokenmodel.TokenGrantSourceForumLike:
+		return "计划被点赞奖励"
+	case tokenmodel.TokenGrantSourceForumImport:
+		return "计划被导入奖励"
+	default:
+		return "论坛奖励入账"
+	}
+}
--- a/backend/services/tokenstore/sv/service.go
+++ b/backend/services/tokenstore/sv/service.go
@@ -0,0 +1,60 @@
+package sv
+
+import (
+	"context"
+	"errors"
+
+	tokenstoredao "github.com/LoveLosita/smartflow/backend/services/tokenstore/dao"
+	tokencontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/tokenstore"
+	"gorm.io/gorm"
+)
+
+// ErrNotImplemented 表示 RPC 骨架已接线，但对应业务用例还在后续步骤实现。
+var ErrNotImplemented = errors.New("tokenstore service method not implemented")
+
+// TokenGrantOutlet 是 token-store 后续切到 user/auth 权威额度的内部发放出口。
+//
+// 职责边界：
+// 1. P0 只记录 token-store 自己的获取事实和账本；
+// 2. 禁止直接修改 users 表；
+// 3. 后续切 user/auth 时新增 adapter，服务编排层不重写。
+type TokenGrantOutlet interface {
+	RecordAcquisition(ctx context.Context, grant tokencontracts.TokenGrantRecord) error
+}
+
+// Options 是 token-store 服务的依赖注入参数。
+type Options struct {
+	DB          *gorm.DB
+	GrantOutlet TokenGrantOutlet
+}
+
+// Service 承载 Token 商店服务内部业务编排。
+//
+// 职责边界：
+// 1. 负责商品、订单、mock paid、grant 账本和奖励规则；
+// 2. 不负责登录鉴权，也不直接修改 user/auth 权威额度；
+// 3. 不负责真实第三方支付回调，P0 只处理 mock paid。
+type Service struct {
+	db          *gorm.DB
+	tokenDAO    *tokenstoredao.TokenStoreDAO
+	grantOutlet TokenGrantOutlet
+}
+
+func New(opts Options) *Service {
+	return &Service{
+		db:          opts.DB,
+		tokenDAO:    tokenstoredao.NewTokenStoreDAO(opts.DB),
+		grantOutlet: opts.GrantOutlet,
+	}
+}
+
+// Ready 用于第二步骨架阶段的依赖检查。
+func (s *Service) Ready() error {
+	if s == nil {
+		return errors.New("tokenstore service is nil")
+	}
+	if s.db == nil {
+		return errors.New("tokenstore db is nil")
+	}
+	return nil
+}