Version: 0.9.78.dev.260506

backend/services/taskclassforum/adapter/taskclass_rpc.go

@@ -0,0 +1,329 @@
+package adapter
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"sort"
+	"strings"
+	"time"
+
+	taskclassclient "github.com/LoveLosita/smartflow/backend/client/taskclass"
+	forumsv "github.com/LoveLosita/smartflow/backend/services/taskclassforum/sv"
+	taskclasscontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/taskclass"
+	"github.com/LoveLosita/smartflow/backend/shared/respond"
+)
+
+var errTaskClassRPCAdapterNotReady = errors.New("taskclassforum task-class rpc adapter is not initialized")
+
+// TaskClassRPCAdapter 负责把 task-class 独立服务适配成计划广场需要的快照端口。
+//
+// 职责边界：
+// 1. 只通过 task-class zrpc 读取/创建任务类，不直连 task_classes / task_items 物理表；
+// 2. 只暴露论坛导入/发布需要的白名单快照语义，不透传 schedule 写入能力；
+// 3. 论坛业务层只依赖快照端口，后续 task-class 契约继续演进时只改这一层。
+type TaskClassRPCAdapter struct {
+	client *taskclassclient.Client
+}
+
+var _ forumsv.TaskClassSnapshotPort = (*TaskClassRPCAdapter)(nil)
+
+// NewTaskClassRPCAdapter 创建基于 task-class zrpc 的论坛快照适配器。
+func NewTaskClassRPCAdapter(client *taskclassclient.Client) *TaskClassRPCAdapter {
+	return &TaskClassRPCAdapter{client: client}
+}
+
+// GetOwnedTaskClassSnapshot 读取当前用户自己的 TaskClass，并投影为论坛可分享快照。
+//
+// 职责边界：
+// 1. 只读取当前用户可见的单个 TaskClass；
+// 2. 只返回论坛白名单字段和条目 source id/order/content；
+// 3. 不透传 embedded_time、status 和任何 schedule 绑定细节。
+func (a *TaskClassRPCAdapter) GetOwnedTaskClassSnapshot(ctx context.Context, userID uint64, taskClassID uint64) (*forumsv.TaskClassSnapshot, error) {
+	if err := a.ensureReady(); err != nil {
+		return nil, err
+	}
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+
+	userIDInt, err := toUserID(userID)
+	if err != nil {
+		return nil, err
+	}
+	taskClassIDInt, err := toTaskClassID(taskClassID)
+	if err != nil {
+		return nil, err
+	}
+
+	raw, err := a.client.GetAgentTaskClasses(ctx, taskclasscontracts.AgentTaskClassesRequest{
+		UserID:       userIDInt,
+		TaskClassIDs: []int{taskClassIDInt},
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	var resp taskclasscontracts.AgentTaskClassesResponse
+	if err := json.Unmarshal(raw, &resp); err != nil {
+		return nil, err
+	}
+	if len(resp.TaskClasses) == 0 {
+		return nil, respond.UserTaskClassNotFound
+	}
+
+	snapshot, err := snapshotFromTaskClass(resp.TaskClasses[0])
+	if err != nil {
+		return nil, err
+	}
+	return &snapshot, nil
+}
+
+// CreateTaskClassFromSnapshot 基于论坛模板快照为当前用户创建 task-class 服务里的副本。
+//
+// 职责边界：
+// 1. 只创建 task-class 主体与 items，不写 forum_imports；
+// 2. 所有 item 都作为新记录创建，不沿用原任务条目的 ID；
+// 3. 不写 schedule，导入后仍保持“当前用户自己的未安排副本”语义。
+func (a *TaskClassRPCAdapter) CreateTaskClassFromSnapshot(ctx context.Context, userID uint64, snapshot forumsv.TaskClassSnapshot, targetTitle string) (*forumsv.CreatedTaskClass, error) {
+	if err := a.ensureReady(); err != nil {
+		return nil, err
+	}
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+
+	userIDInt, err := toUserID(userID)
+	if err != nil {
+		return nil, err
+	}
+
+	title := strings.TrimSpace(targetTitle)
+	if title == "" {
+		title = strings.TrimSpace(snapshot.Title)
+	}
+	if title == "" || strings.TrimSpace(snapshot.Mode) == "" {
+		return nil, respond.MissingParam
+	}
+
+	if _, _, err := parseSnapshotDateRange(snapshot.Mode, snapshot.StartDate, snapshot.EndDate); err != nil {
+		return nil, err
+	}
+
+	raw, err := a.client.AddTaskClass(ctx, buildUpsertTaskClassRequest(userIDInt, title, snapshot))
+	if err != nil {
+		return nil, err
+	}
+
+	var created taskclasscontracts.UpsertTaskClassResponse
+	if err := json.Unmarshal(raw, &created); err != nil {
+		return nil, err
+	}
+	if created.TaskClassID <= 0 {
+		return nil, respond.InternalError(errors.New("task-class rpc add response missing task_class_id"))
+	}
+	return &forumsv.CreatedTaskClass{
+		TaskClassID: uint64(created.TaskClassID),
+		Title:       title,
+	}, nil
+}
+
+func snapshotFromTaskClass(taskClass taskclasscontracts.AgentTaskClass) (forumsv.TaskClassSnapshot, error) {
+	items := snapshotItemsFromTaskClassItems(taskClass.Items)
+	snapshot := forumsv.TaskClassSnapshot{
+		TaskClassID:        uint64(taskClass.ID),
+		Title:              strings.TrimSpace(taskClass.Name),
+		Mode:               strings.TrimSpace(taskClass.Mode),
+		StartDate:          strings.TrimSpace(taskClass.StartDate),
+		EndDate:            strings.TrimSpace(taskClass.EndDate),
+		SubjectType:        strings.TrimSpace(taskClass.SubjectType),
+		DifficultyLevel:    strings.TrimSpace(taskClass.DifficultyLevel),
+		CognitiveIntensity: strings.TrimSpace(taskClass.CognitiveIntensity),
+		TotalSlots:         taskClass.TotalSlots,
+		AllowFillerCourse:  taskClass.AllowFillerCourse,
+		Strategy:           strings.TrimSpace(taskClass.Strategy),
+		ExcludedSlots:      cloneIntSlice(taskClass.ExcludedSlots),
+		ExcludedDaysOfWeek: cloneIntSlice(taskClass.ExcludedDaysOfWeek),
+		StrategyLabels:     strategyLabels(taskClass.Strategy),
+		Items:              items,
+	}
+
+	configJSON, err := buildConfigSnapshotJSON(snapshot)
+	if err != nil {
+		return forumsv.TaskClassSnapshot{}, err
+	}
+	snapshot.ConfigSnapshotJSON = configJSON
+	return snapshot, nil
+}
+
+func snapshotItemsFromTaskClassItems(items []taskclasscontracts.AgentTaskClassItem) []forumsv.TaskClassSnapshotItem {
+	if len(items) == 0 {
+		return []forumsv.TaskClassSnapshotItem{}
+	}
+
+	sorted := append([]taskclasscontracts.AgentTaskClassItem(nil), items...)
+	sort.SliceStable(sorted, func(i, j int) bool {
+		leftOrder := derefInt(sorted[i].Order)
+		rightOrder := derefInt(sorted[j].Order)
+		if leftOrder != rightOrder {
+			return leftOrder < rightOrder
+		}
+		return sorted[i].ID < sorted[j].ID
+	})
+
+	result := make([]forumsv.TaskClassSnapshotItem, 0, len(sorted))
+	for _, item := range sorted {
+		content := strings.TrimSpace(item.Content)
+		if content == "" {
+			continue
+		}
+		result = append(result, forumsv.TaskClassSnapshotItem{
+			TaskItemID: uint64(item.ID),
+			Order:      derefInt(item.Order),
+			Content:    content,
+		})
+	}
+	return result
+}
+
+func buildUpsertTaskClassRequest(userID int, title string, snapshot forumsv.TaskClassSnapshot) taskclasscontracts.UpsertTaskClassRequest {
+	items := make([]taskclasscontracts.UpsertTaskClassItemConfig, 0, len(snapshot.Items))
+	sortedItems := append([]forumsv.TaskClassSnapshotItem(nil), snapshot.Items...)
+	sort.SliceStable(sortedItems, func(i, j int) bool {
+		if sortedItems[i].Order != sortedItems[j].Order {
+			return sortedItems[i].Order < sortedItems[j].Order
+		}
+		return sortedItems[i].TaskItemID < sortedItems[j].TaskItemID
+	})
+	for _, item := range sortedItems {
+		content := strings.TrimSpace(item.Content)
+		if content == "" {
+			continue
+		}
+		items = append(items, taskclasscontracts.UpsertTaskClassItemConfig{
+			Order:   item.Order,
+			Content: content,
+		})
+	}
+
+	return taskclasscontracts.UpsertTaskClassRequest{
+		UserID:             userID,
+		Name:               title,
+		StartDate:          strings.TrimSpace(snapshot.StartDate),
+		EndDate:            strings.TrimSpace(snapshot.EndDate),
+		Mode:               strings.TrimSpace(snapshot.Mode),
+		SubjectType:        strings.TrimSpace(snapshot.SubjectType),
+		DifficultyLevel:    strings.TrimSpace(snapshot.DifficultyLevel),
+		CognitiveIntensity: strings.TrimSpace(snapshot.CognitiveIntensity),
+		Config: taskclasscontracts.UpsertTaskClassConfig{
+			TotalSlots:         snapshot.TotalSlots,
+			AllowFillerCourse:  snapshot.AllowFillerCourse,
+			Strategy:           strings.TrimSpace(snapshot.Strategy),
+			ExcludedSlots:      cloneIntSlice(snapshot.ExcludedSlots),
+			ExcludedDaysOfWeek: cloneIntSlice(snapshot.ExcludedDaysOfWeek),
+		},
+		Items: items,
+	}
+}
+
+func strategyLabels(strategy string) []string {
+	trimmed := strings.TrimSpace(strategy)
+	if trimmed == "" {
+		return []string{}
+	}
+	return []string{trimmed}
+}
+
+func (a *TaskClassRPCAdapter) ensureReady() error {
+	if a == nil || a.client == nil {
+		return errTaskClassRPCAdapterNotReady
+	}
+	return nil
+}
+
+func toUserID(value uint64) (int, error) {
+	if value == 0 || value > uint64(maxIntValue()) {
+		return 0, respond.WrongUserID
+	}
+	return int(value), nil
+}
+
+func toTaskClassID(value uint64) (int, error) {
+	if value == 0 || value > uint64(maxIntValue()) {
+		return 0, respond.WrongTaskClassID
+	}
+	return int(value), nil
+}
+
+func maxIntValue() int {
+	return int(^uint(0) >> 1)
+}
+
+func derefInt(value *int) int {
+	if value == nil {
+		return 0
+	}
+	return *value
+}
+
+func parseSnapshotDateRange(mode string, startDate string, endDate string) (*time.Time, *time.Time, error) {
+	parsedStart, err := parseDatePtr(startDate)
+	if err != nil {
+		return nil, nil, respond.WrongParamType
+	}
+	parsedEnd, err := parseDatePtr(endDate)
+	if err != nil {
+		return nil, nil, respond.WrongParamType
+	}
+
+	if strings.TrimSpace(mode) != "auto" {
+		return parsedStart, parsedEnd, nil
+	}
+	if parsedStart == nil || parsedEnd == nil {
+		return nil, nil, respond.MissingParamForAutoScheduling
+	}
+	if parsedStart.After(*parsedEnd) {
+		return nil, nil, respond.InvalidDateRange
+	}
+	return parsedStart, parsedEnd, nil
+}
+
+func buildConfigSnapshotJSON(snapshot forumsv.TaskClassSnapshot) (string, error) {
+	raw, err := json.Marshal(map[string]any{
+		"mode":                  snapshot.Mode,
+		"start_date":            snapshot.StartDate,
+		"end_date":              snapshot.EndDate,
+		"subject_type":          snapshot.SubjectType,
+		"difficulty_level":      snapshot.DifficultyLevel,
+		"cognitive_intensity":   snapshot.CognitiveIntensity,
+		"total_slots":           snapshot.TotalSlots,
+		"allow_filler_course":   snapshot.AllowFillerCourse,
+		"strategy":              snapshot.Strategy,
+		"excluded_slots":        cloneIntSlice(snapshot.ExcludedSlots),
+		"excluded_days_of_week": cloneIntSlice(snapshot.ExcludedDaysOfWeek),
+		"strategy_labels":       append([]string(nil), snapshot.StrategyLabels...),
+	})
+	if err != nil {
+		return "", err
+	}
+	return string(raw), nil
+}
+
+func parseDatePtr(value string) (*time.Time, error) {
+	trimmed := strings.TrimSpace(value)
+	if trimmed == "" {
+		return nil, nil
+	}
+	parsed, err := time.ParseInLocation("2006-01-02", trimmed, time.Local)
+	if err != nil {
+		return nil, err
+	}
+	return &parsed, nil
+}
+
+func cloneIntSlice(values []int) []int {
+	if len(values) == 0 {
+		return []int{}
+	}
+	return append([]int(nil), values...)
+}

backend/services/taskclassforum/commenttree/tree.go

@@ -0,0 +1,204 @@
+package commenttree
+
+import (
+	"fmt"
+	"sort"
+	"time"
+
+	forummodel "github.com/LoveLosita/smartflow/backend/services/taskclassforum/model"
+	forumcontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/taskclassforum"
+)
+
+const deletedCommentPlaceholder = "该评论已删除"
+
+type commentTreeNode struct {
+	comment  forummodel.ForumComment
+	parent   *commentTreeNode
+	children []*commentTreeNode
+}
+
+// BuildForumCommentTree 将扁平评论组装为多层评论树。
+//
+// 职责边界：
+// 1. 负责根据 parent_comment_id 组装无限层树结构，并按 CreatedAt 升序稳定排序；
+// 2. 负责把软删除评论转换成前端展示文案，同时保留 deleted 状态与 deleted_at；
+// 3. 不负责查询数据库、补充真实昵称头像，也不负责帖子级权限校验。
+func BuildForumCommentTree(comments []forummodel.ForumComment, actorUserID uint64) []forumcontracts.ForumCommentNode {
+	if len(comments) == 0 {
+		return nil
+	}
+
+	nodesByID := make(map[uint64]*commentTreeNode, len(comments))
+	orderedNodes := make([]*commentTreeNode, 0, len(comments))
+	for i := range comments {
+		node := &commentTreeNode{comment: comments[i]}
+		nodesByID[comments[i].ID] = node
+		orderedNodes = append(orderedNodes, node)
+	}
+
+	roots := attachCommentTreeNodes(orderedNodes, nodesByID)
+	sortCommentTreeChildren(roots)
+
+	result := make([]forumcontracts.ForumCommentNode, 0, len(roots))
+	for i := range roots {
+		result = append(result, buildForumCommentNode(roots[i], actorUserID))
+	}
+	return result
+}
+
+// attachCommentTreeNodes 按原始 parent_comment_id 把评论挂成树。
+//
+// 职责边界：
+// 1. 只处理节点挂载关系，不做字段格式化；
+// 2. 缺失父节点、自指向、环引用都回退到根层，避免整棵树丢失；
+// 3. 根层顺序先保留输入顺序，后续统一由排序函数做稳定排序。
+func attachCommentTreeNodes(
+	orderedNodes []*commentTreeNode,
+	nodesByID map[uint64]*commentTreeNode,
+) []*commentTreeNode {
+	roots := make([]*commentTreeNode, 0, len(orderedNodes))
+	for i := range orderedNodes {
+		node := orderedNodes[i]
+		parentID := node.comment.ParentCommentID
+		if parentID == nil {
+			roots = append(roots, node)
+			continue
+		}
+
+		parentNode, ok := nodesByID[*parentID]
+		if !ok || parentNode == nil || parentNode.comment.ID == node.comment.ID {
+			roots = append(roots, node)
+			continue
+		}
+
+		if wouldCreateCommentCycle(nodesByID, node.comment.ID, parentNode) {
+			roots = append(roots, node)
+			continue
+		}
+
+		node.parent = parentNode
+		parentNode.children = append(parentNode.children, node)
+	}
+	return roots
+}
+
+// wouldCreateCommentCycle 判断把 child 挂到 parent 下时是否会形成环。
+//
+// 职责边界：
+// 1. 只依赖原始 parent_comment_id 链路判断，不依赖当前挂载顺序；
+// 2. 一旦发现 child 会回到自己，或父链本身已成环，就返回 true；
+// 3. 父链中途断开时按“无环”处理，让节点继续挂到可用分支上。
+func wouldCreateCommentCycle(
+	nodesByID map[uint64]*commentTreeNode,
+	childCommentID uint64,
+	parentNode *commentTreeNode,
+) bool {
+	visited := make(map[uint64]struct{})
+	current := parentNode
+	for current != nil {
+		if current.comment.ID == childCommentID {
+			return true
+		}
+		if _, seen := visited[current.comment.ID]; seen {
+			return true
+		}
+		visited[current.comment.ID] = struct{}{}
+
+		if current.comment.ParentCommentID == nil {
+			return false
+		}
+
+		nextNode, ok := nodesByID[*current.comment.ParentCommentID]
+		if !ok {
+			return false
+		}
+		current = nextNode
+	}
+	return false
+}
+
+// sortCommentTreeChildren 对根层以下的兄弟节点做 CreatedAt 升序稳定排序。
+//
+// 职责边界：
+// 1. 根层顺序来自服务层根评论分页，必须保留 latest/oldest 的查询语义；
+// 2. 子回复统一按 CreatedAt 升序展示，符合常见对话阅读顺序；
+// 3. 相同 CreatedAt 依赖稳定排序保留原始输入顺序，避免同秒回复来回跳动。
+func sortCommentTreeChildren(nodes []*commentTreeNode) {
+	if len(nodes) == 0 {
+		return
+	}
+
+	for i := range nodes {
+		sort.SliceStable(nodes[i].children, func(left, right int) bool {
+			return nodes[i].children[left].comment.CreatedAt.Before(nodes[i].children[right].comment.CreatedAt)
+		})
+		sortCommentTreeChildren(nodes[i].children)
+	}
+}
+
+// buildForumCommentNode 把内部树节点转换成对外契约节点。
+//
+// 职责边界：
+// 1. 负责软删除展示文案、CanDelete、时间格式等输出字段整理；
+// 2. 根节点统一输出 nil parent_comment_id；孤儿兜底到根层后也遵循该规则；
+// 3. 这里沿用当前服务里的“用户{ID}”占位昵称语义。
+func buildForumCommentNode(node *commentTreeNode, actorUserID uint64) forumcontracts.ForumCommentNode {
+	children := make([]forumcontracts.ForumCommentNode, 0, len(node.children))
+	for i := range node.children {
+		children = append(children, buildForumCommentNode(node.children[i], actorUserID))
+	}
+
+	// 1. 先基于最终挂载结果回填 parent_comment_id，保证孤儿回退到根层后对外语义一致。
+	// 2. 再处理软删除评论文案：内容固定替换，但 status 仍保留 deleted，便于前端区分。
+	// 3. 最后按“当前用户且评论可见”计算 CanDelete，避免已删除评论被重复展示可删除按钮。
+	parentCommentID := actualParentCommentID(node.parent)
+	content := node.comment.Content
+	if node.comment.Status == forummodel.ForumCommentStatusDeleted {
+		content = deletedCommentPlaceholder
+	}
+
+	return forumcontracts.ForumCommentNode{
+		CommentID:       node.comment.ID,
+		PostID:          node.comment.PostID,
+		ParentCommentID: parentCommentID,
+		Content:         content,
+		Status:          node.comment.Status,
+		Author:          buildCommentAuthor(node.comment.UserID),
+		CanDelete:       node.comment.Status == forummodel.ForumCommentStatusVisible && node.comment.UserID == actorUserID,
+		CreatedAt:       formatCommentTime(node.comment.CreatedAt),
+		DeletedAt:       formatCommentTimePtr(node.comment.DeletedAt),
+		Children:        children,
+	}
+}
+
+func actualParentCommentID(parent *commentTreeNode) *uint64 {
+	if parent == nil {
+		return nil
+	}
+	parentID := parent.comment.ID
+	return &parentID
+}
+
+func formatCommentTime(value time.Time) string {
+	if value.IsZero() {
+		return ""
+	}
+	return value.Format(time.RFC3339)
+}
+
+func formatCommentTimePtr(value *time.Time) *string {
+	if value == nil || value.IsZero() {
+		return nil
+	}
+	formatted := value.Format(time.RFC3339)
+	return &formatted
+}
+
+func buildCommentAuthor(userID uint64) forumcontracts.UserBrief {
+	// 由于本轮写入范围被限制在 commenttree/tree.go，暂时无法把 UserBrief 生成逻辑下沉成公共能力；
+	// 这里先与现有服务层保持同一占位昵称语义，避免为了抽公共层去改动 sv/contract 等非授权文件。
+	return forumcontracts.UserBrief{
+		UserID:   userID,
+		Nickname: fmt.Sprintf("用户%d", userID),
+	}
+}

backend/services/taskclassforum/dao/cache.go

@@ -0,0 +1,146 @@
+package dao
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+
+	forumcontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/taskclassforum"
+	"github.com/go-redis/redis/v8"
+)
+
+const commentTreeCacheTTL = 2 * time.Minute
+
+type commentTreeCachePayload struct {
+	Items []forumcontracts.ForumCommentNode `json:"items"`
+	Page  forumcontracts.PageResult         `json:"page"`
+}
+
+// CommentTreeCache 承载计划广场评论树的 Redis 缓存能力。
+//
+// 职责边界：
+// 1. 只负责评论树读模型的 JSON 缓存和版本号失效，不读写 MySQL；
+// 2. 不计算当前用户是否可删除评论，避免把用户视角写进共享缓存；
+// 3. Redis 异常向上返回，由 service 层决定是否降级回源 DB。
+type CommentTreeCache struct {
+	client *redis.Client
+	ttl    time.Duration
+}
+
+func NewCommentTreeCache(client *redis.Client) *CommentTreeCache {
+	return &CommentTreeCache{
+		client: client,
+		ttl:    commentTreeCacheTTL,
+	}
+}
+
+func commentTreeVersionKey(postID uint64) string {
+	return fmt.Sprintf("forum:comments:%d:version", postID)
+}
+
+func commentTreeDataKey(postID uint64, version int64, sort string, page int, pageSize int) string {
+	return fmt.Sprintf(
+		"forum:comments:%d:v%d:sort:%s:page:%d:size:%d",
+		postID,
+		version,
+		strings.TrimSpace(sort),
+		page,
+		pageSize,
+	)
+}
+
+// GetCommentTree 读取指定帖子、排序和分页维度下的评论树缓存。
+//
+// 返回值语义：
+// 1. hit=true 表示命中缓存，items/page 可直接用于返回前的用户视角补全；
+// 2. hit=false 且 error=nil 表示未命中，调用方应回源 DB；
+// 3. error 非空表示 Redis 或 JSON 异常，调用方应记录日志并回源 DB。
+func (c *CommentTreeCache) GetCommentTree(ctx context.Context, postID uint64, page int, pageSize int, sort string) ([]forumcontracts.ForumCommentNode, forumcontracts.PageResult, bool, error) {
+	if c == nil || c.client == nil {
+		return nil, forumcontracts.PageResult{}, false, errors.New("评论树缓存未初始化")
+	}
+	version, err := c.currentCommentTreeVersion(ctx, postID)
+	if err != nil {
+		return nil, forumcontracts.PageResult{}, false, err
+	}
+
+	raw, err := c.client.Get(ctx, commentTreeDataKey(postID, version, sort, page, pageSize)).Result()
+	if errors.Is(err, redis.Nil) {
+		return nil, forumcontracts.PageResult{}, false, nil
+	}
+	if err != nil {
+		return nil, forumcontracts.PageResult{}, false, err
+	}
+
+	var payload commentTreeCachePayload
+	if err = json.Unmarshal([]byte(raw), &payload); err != nil {
+		return nil, forumcontracts.PageResult{}, false, err
+	}
+	if payload.Items == nil {
+		payload.Items = []forumcontracts.ForumCommentNode{}
+	}
+	return payload.Items, payload.Page, true, nil
+}
+
+// SetCommentTree 写入指定帖子、排序和分页维度下的评论树缓存。
+//
+// 步骤说明：
+// 1. 先读取当前版本号，保证写入 key 与后续读取 key 一致；
+// 2. 再序列化去个性化后的评论树，避免缓存里带入某个用户的 can_delete；
+// 3. 最后写入短 TTL，让版本失效失败时也能靠自然过期兜底。
+func (c *CommentTreeCache) SetCommentTree(ctx context.Context, postID uint64, page int, pageSize int, sort string, items []forumcontracts.ForumCommentNode, pageResult forumcontracts.PageResult) error {
+	if c == nil || c.client == nil {
+		return errors.New("评论树缓存未初始化")
+	}
+	version, err := c.currentCommentTreeVersion(ctx, postID)
+	if err != nil {
+		return err
+	}
+
+	if items == nil {
+		items = []forumcontracts.ForumCommentNode{}
+	}
+	data, err := json.Marshal(commentTreeCachePayload{
+		Items: items,
+		Page:  pageResult,
+	})
+	if err != nil {
+		return err
+	}
+	return c.client.Set(ctx, commentTreeDataKey(postID, version, sort, page, pageSize), data, c.ttl).Err()
+}
+
+// BumpCommentTreeVersion 递增帖子评论树版本号，让旧分页缓存自然失效。
+//
+// 职责边界：
+// 1. 只做版本递增，不扫描删除旧 data key，避免写评论时阻塞 Redis；
+// 2. 旧 data key 依赖短 TTL 自动回收；
+// 3. 当 version key 不存在时 INCR 会从 1 开始，能够让默认 v0 缓存失效。
+func (c *CommentTreeCache) BumpCommentTreeVersion(ctx context.Context, postID uint64) error {
+	if c == nil || c.client == nil {
+		return errors.New("评论树缓存未初始化")
+	}
+	return c.client.Incr(ctx, commentTreeVersionKey(postID)).Err()
+}
+
+func (c *CommentTreeCache) currentCommentTreeVersion(ctx context.Context, postID uint64) (int64, error) {
+	raw, err := c.client.Get(ctx, commentTreeVersionKey(postID)).Result()
+	if errors.Is(err, redis.Nil) {
+		return 0, nil
+	}
+	if err != nil {
+		return 0, err
+	}
+	version, err := strconv.ParseInt(strings.TrimSpace(raw), 10, 64)
+	if err != nil {
+		return 0, err
+	}
+	if version < 0 {
+		return 0, nil
+	}
+	return version, nil
+}

backend/services/taskclassforum/dao/connect.go

@@ -0,0 +1,70 @@
+package dao
+
+import (
+	"fmt"
+
+	outboxinfra "github.com/LoveLosita/smartflow/backend/shared/infra/outbox"
+	forummodel "github.com/LoveLosita/smartflow/backend/services/taskclassforum/model"
+	"github.com/spf13/viper"
+	"gorm.io/driver/mysql"
+	"gorm.io/gorm"
+)
+
+// OpenDBFromConfig 创建计划广场服务自己的数据库句柄，并迁移本服务私有表。
+//
+// 职责边界：
+// 1. 只迁移 forum_* 表和本服务 outbox 表，不迁移 task_classes / task_items，避免抢占 task-class 拆分线；
+// 2. 不负责装配 legacy TaskClass adapter，adapter 在服务实现阶段单独注入；
+// 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
+	}
+	return db, nil
+}
+
+// AutoMigrate 只迁移计划广场服务拥有的表。
+//
+// 步骤说明：
+// 1. 先创建帖子、模板、条目、点赞、评论、导入记录表；
+// 2. 再按 service catalog 创建 taskclass-forum outbox 表，为后续论坛自身异步事件预留稳定目录；
+// 3. 迁移期论坛奖励事件直接写 token-store outbox 表，发布端也兜底创建目标表，避免独立启动顺序导致奖励漏表；
+// 4. 唯一约束交给 GORM tag 生成，保证点赞和导入幂等有数据库兜底；
+// 5. 失败时直接返回错误，避免服务在 schema 不完整时继续启动。
+func AutoMigrate(db *gorm.DB) error {
+	if db == nil {
+		return fmt.Errorf("taskclassforum auto migrate failed: db is nil")
+	}
+	if err := db.AutoMigrate(
+		&forummodel.ForumPost{},
+		&forummodel.ForumPostTemplate{},
+		&forummodel.ForumPostTemplateItem{},
+		&forummodel.ForumLike{},
+		&forummodel.ForumComment{},
+		&forummodel.ForumImport{},
+	); err != nil {
+		return fmt.Errorf("auto migrate taskclassforum tables failed: %w", err)
+	}
+	if err := outboxinfra.AutoMigrateServiceTable(db, outboxinfra.ServiceTaskClassForum); err != nil {
+		return err
+	}
+	if err := outboxinfra.AutoMigrateServiceTable(db, outboxinfra.ServiceTokenStore); err != nil {
+		return err
+	}
+	return nil
+}

backend/services/taskclassforum/dao/forum.go

@@ -0,0 +1,466 @@
+package dao
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	forummodel "github.com/LoveLosita/smartflow/backend/services/taskclassforum/model"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+// ForumDAO 承载计划广场私有表的持久化访问。
+//
+// 职责边界：
+// 1. 只访问 forum_* 表，不直接读写旧 task_classes / task_items；
+// 2. 只做查询、事务和基础状态更新，不组装前端 DTO；
+// 3. 业务规则由 sv 层控制，DAO 仅提供必要的数据原子操作。
+type ForumDAO struct {
+	db *gorm.DB
+}
+
+func NewForumDAO(db *gorm.DB) *ForumDAO {
+	return &ForumDAO{db: db}
+}
+
+func (dao *ForumDAO) WithTx(tx *gorm.DB) *ForumDAO {
+	return &ForumDAO{db: tx}
+}
+
+// GormDB 返回当前 DAO 绑定的 GORM 句柄。
+//
+// 职责边界：
+// 1. 只提供给需要和 forum 业务事务同提交的基础设施使用，例如 outbox 入队；
+// 2. 不鼓励业务层绕过 DAO 任意读写 forum_* 表；
+// 3. 若当前 DAO 来自 WithTx，返回值就是同一个事务句柄。
+func (dao *ForumDAO) GormDB() *gorm.DB {
+	if dao == nil {
+		return nil
+	}
+	return dao.db
+}
+
+// Transaction 在一个数据库事务内执行计划广场写操作。
+func (dao *ForumDAO) Transaction(ctx context.Context, fn func(txDAO *ForumDAO) error) error {
+	return dao.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		return fn(dao.WithTx(tx))
+	})
+}
+
+type ListPostsQuery struct {
+	Page     int
+	PageSize int
+	Sort     string
+	Keyword  string
+	Tag      string
+}
+
+// CreatePostSnapshot 在同一事务中写帖子、模板和模板条目。
+func (dao *ForumDAO) CreatePostSnapshot(ctx context.Context, post *forummodel.ForumPost, template *forummodel.ForumPostTemplate, items []forummodel.ForumPostTemplateItem) error {
+	return dao.Transaction(ctx, func(txDAO *ForumDAO) error {
+		if err := txDAO.db.Create(post).Error; err != nil {
+			return err
+		}
+		template.PostID = post.ID
+		if err := txDAO.db.Create(template).Error; err != nil {
+			return err
+		}
+		for i := range items {
+			items[i].PostID = post.ID
+			items[i].TemplateID = template.ID
+		}
+		if len(items) > 0 {
+			if err := txDAO.db.Create(&items).Error; err != nil {
+				return err
+			}
+		}
+		return nil
+	})
+}
+
+func (dao *ForumDAO) FindPostByIdempotencyKey(ctx context.Context, userID uint64, key string) (*forummodel.ForumPost, error) {
+	var post forummodel.ForumPost
+	err := dao.db.WithContext(ctx).
+		Where("author_user_id = ? AND idempotency_key = ?", userID, key).
+		First(&post).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &post, nil
+}
+
+func (dao *ForumDAO) ListPosts(ctx context.Context, query ListPostsQuery) ([]forummodel.ForumPost, int64, error) {
+	db := dao.db.WithContext(ctx).
+		Model(&forummodel.ForumPost{}).
+		Where("status = ? AND deleted_at IS NULL", forummodel.ForumPostStatusPublished)
+	if keyword := strings.TrimSpace(query.Keyword); keyword != "" {
+		like := "%" + keyword + "%"
+		db = db.Where("title LIKE ? OR summary LIKE ?", like, like)
+	}
+	if tag := strings.TrimSpace(query.Tag); tag != "" {
+		db = db.Where("JSON_CONTAINS(tags_json, JSON_QUOTE(?))", tag)
+	}
+
+	var total int64
+	if err := db.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+
+	orderBy := "created_at DESC"
+	switch strings.TrimSpace(query.Sort) {
+	case "likes":
+		orderBy = "like_count DESC, created_at DESC"
+	case "imports":
+		orderBy = "import_count DESC, created_at DESC"
+	}
+
+	var posts []forummodel.ForumPost
+	err := db.Order(orderBy).
+		Offset((query.Page - 1) * query.PageSize).
+		Limit(query.PageSize).
+		Find(&posts).Error
+	if err != nil {
+		return nil, 0, err
+	}
+	return posts, total, nil
+}
+
+func (dao *ForumDAO) ListPublishedTagJSONs(ctx context.Context) ([]string, error) {
+	var rows []struct {
+		TagsJSON string
+	}
+	err := dao.db.WithContext(ctx).
+		Model(&forummodel.ForumPost{}).
+		Select("tags_json").
+		Where("status = ? AND deleted_at IS NULL", forummodel.ForumPostStatusPublished).
+		Find(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+	result := make([]string, 0, len(rows))
+	for _, row := range rows {
+		result = append(result, row.TagsJSON)
+	}
+	return result, nil
+}
+
+func (dao *ForumDAO) FindPublishedPost(ctx context.Context, postID uint64) (*forummodel.ForumPost, error) {
+	var post forummodel.ForumPost
+	err := dao.db.WithContext(ctx).
+		Where("id = ? AND status = ? AND deleted_at IS NULL", postID, forummodel.ForumPostStatusPublished).
+		First(&post).Error
+	if err != nil {
+		return nil, err
+	}
+	return &post, nil
+}
+
+func (dao *ForumDAO) LockPublishedPost(ctx context.Context, postID uint64) (*forummodel.ForumPost, error) {
+	var post forummodel.ForumPost
+	err := dao.db.WithContext(ctx).
+		Clauses(clause.Locking{Strength: "UPDATE"}).
+		Where("id = ? AND status = ? AND deleted_at IS NULL", postID, forummodel.ForumPostStatusPublished).
+		First(&post).Error
+	if err != nil {
+		return nil, err
+	}
+	return &post, nil
+}
+
+func (dao *ForumDAO) FindTemplateByPostID(ctx context.Context, postID uint64) (*forummodel.ForumPostTemplate, error) {
+	var template forummodel.ForumPostTemplate
+	err := dao.db.WithContext(ctx).Where("post_id = ?", postID).First(&template).Error
+	if err != nil {
+		return nil, err
+	}
+	return &template, nil
+}
+
+func (dao *ForumDAO) ListTemplateItemsByPostID(ctx context.Context, postID uint64) ([]forummodel.ForumPostTemplateItem, error) {
+	var items []forummodel.ForumPostTemplateItem
+	err := dao.db.WithContext(ctx).
+		Where("post_id = ?", postID).
+		Order("item_order ASC").
+		Find(&items).Error
+	return items, err
+}
+
+func (dao *ForumDAO) FindTemplatesByPostIDs(ctx context.Context, postIDs []uint64) (map[uint64]forummodel.ForumPostTemplate, error) {
+	var templates []forummodel.ForumPostTemplate
+	err := dao.db.WithContext(ctx).Where("post_id IN ?", postIDs).Find(&templates).Error
+	if err != nil {
+		return nil, err
+	}
+	result := make(map[uint64]forummodel.ForumPostTemplate, len(templates))
+	for _, template := range templates {
+		result[template.PostID] = template
+	}
+	return result, nil
+}
+
+func (dao *ForumDAO) CountTemplateItemsByPostIDs(ctx context.Context, postIDs []uint64) (map[uint64]int, error) {
+	var rows []struct {
+		PostID uint64
+		Count  int
+	}
+	err := dao.db.WithContext(ctx).
+		Model(&forummodel.ForumPostTemplateItem{}).
+		Select("post_id, COUNT(*) AS count").
+		Where("post_id IN ?", postIDs).
+		Group("post_id").
+		Find(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+	result := make(map[uint64]int, len(rows))
+	for _, row := range rows {
+		result[row.PostID] = row.Count
+	}
+	return result, nil
+}
+
+func (dao *ForumDAO) LikedPostIDSet(ctx context.Context, userID uint64, postIDs []uint64) (map[uint64]bool, error) {
+	var likes []forummodel.ForumLike
+	err := dao.db.WithContext(ctx).
+		Select("post_id").
+		Where("user_id = ? AND post_id IN ? AND status = ?", userID, postIDs, forummodel.ForumLikeStatusActive).
+		Find(&likes).Error
+	if err != nil {
+		return nil, err
+	}
+	result := make(map[uint64]bool, len(likes))
+	for _, like := range likes {
+		result[like.PostID] = true
+	}
+	return result, nil
+}
+
+func (dao *ForumDAO) ImportedPostIDSet(ctx context.Context, userID uint64, postIDs []uint64) (map[uint64]bool, error) {
+	var imports []forummodel.ForumImport
+	err := dao.db.WithContext(ctx).
+		Select("post_id").
+		Where("user_id = ? AND post_id IN ? AND status = ?", userID, postIDs, forummodel.ForumImportStatusImported).
+		Find(&imports).Error
+	if err != nil {
+		return nil, err
+	}
+	result := make(map[uint64]bool, len(imports))
+	for _, item := range imports {
+		result[item.PostID] = true
+	}
+	return result, nil
+}
+
+func (dao *ForumDAO) FindLike(ctx context.Context, postID uint64, userID uint64) (*forummodel.ForumLike, error) {
+	var like forummodel.ForumLike
+	err := dao.db.WithContext(ctx).Where("post_id = ? AND user_id = ?", postID, userID).First(&like).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &like, nil
+}
+
+func (dao *ForumDAO) CreateLike(ctx context.Context, like *forummodel.ForumLike) error {
+	return dao.db.WithContext(ctx).Create(like).Error
+}
+
+func (dao *ForumDAO) ActivateLike(ctx context.Context, likeID uint64) error {
+	return dao.db.WithContext(ctx).
+		Model(&forummodel.ForumLike{}).
+		Where("id = ?", likeID).
+		Updates(map[string]any{
+			"status":      forummodel.ForumLikeStatusActive,
+			"canceled_at": nil,
+			"updated_at":  time.Now(),
+		}).Error
+}
+
+func (dao *ForumDAO) CancelLike(ctx context.Context, likeID uint64, now time.Time) error {
+	return dao.db.WithContext(ctx).
+		Model(&forummodel.ForumLike{}).
+		Where("id = ?", likeID).
+		Updates(map[string]any{
+			"status":      forummodel.ForumLikeStatusCanceled,
+			"canceled_at": &now,
+			"updated_at":  now,
+		}).Error
+}
+
+func (dao *ForumDAO) AddPostCounter(ctx context.Context, postID uint64, column string, delta int64) error {
+	expr := "CASE WHEN " + column + " + ? < 0 THEN 0 ELSE " + column + " + ? END"
+	return dao.db.WithContext(ctx).
+		Model(&forummodel.ForumPost{}).
+		Where("id = ?", postID).
+		UpdateColumn(column, gorm.Expr(expr, delta, delta)).Error
+}
+
+func (dao *ForumDAO) FindCommentByID(ctx context.Context, commentID uint64) (*forummodel.ForumComment, error) {
+	var comment forummodel.ForumComment
+	err := dao.db.WithContext(ctx).Where("id = ?", commentID).First(&comment).Error
+	if err != nil {
+		return nil, err
+	}
+	return &comment, nil
+}
+
+func (dao *ForumDAO) LockCommentByID(ctx context.Context, commentID uint64) (*forummodel.ForumComment, error) {
+	var comment forummodel.ForumComment
+	err := dao.db.WithContext(ctx).
+		Clauses(clause.Locking{Strength: "UPDATE"}).
+		Where("id = ?", commentID).
+		First(&comment).Error
+	if err != nil {
+		return nil, err
+	}
+	return &comment, nil
+}
+
+func (dao *ForumDAO) FindCommentByIdempotencyKey(ctx context.Context, userID uint64, key string) (*forummodel.ForumComment, error) {
+	var comment forummodel.ForumComment
+	err := dao.db.WithContext(ctx).
+		Where("user_id = ? AND idempotency_key = ?", userID, key).
+		First(&comment).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &comment, nil
+}
+
+func (dao *ForumDAO) CreateComment(ctx context.Context, comment *forummodel.ForumComment) error {
+	return dao.db.WithContext(ctx).Create(comment).Error
+}
+
+func (dao *ForumDAO) CountRootComments(ctx context.Context, postID uint64) (int64, error) {
+	var total int64
+	err := dao.db.WithContext(ctx).
+		Model(&forummodel.ForumComment{}).
+		Where("post_id = ? AND parent_comment_id IS NULL", postID).
+		Count(&total).Error
+	return total, err
+}
+
+func (dao *ForumDAO) ListRootComments(ctx context.Context, postID uint64, page int, pageSize int, sort string) ([]forummodel.ForumComment, error) {
+	orderBy := "created_at ASC"
+	if strings.TrimSpace(sort) == "latest" {
+		orderBy = "created_at DESC"
+	}
+	var comments []forummodel.ForumComment
+	err := dao.db.WithContext(ctx).
+		Where("post_id = ? AND parent_comment_id IS NULL", postID).
+		Order(orderBy).
+		Offset((page - 1) * pageSize).
+		Limit(pageSize).
+		Find(&comments).Error
+	return comments, err
+}
+
+func (dao *ForumDAO) ListCommentsByPostID(ctx context.Context, postID uint64) ([]forummodel.ForumComment, error) {
+	var comments []forummodel.ForumComment
+	err := dao.db.WithContext(ctx).
+		Where("post_id = ?", postID).
+		Order("created_at ASC").
+		Find(&comments).Error
+	return comments, err
+}
+
+func (dao *ForumDAO) SoftDeleteComment(ctx context.Context, commentID uint64, now time.Time) error {
+	tx := dao.db.WithContext(ctx).
+		Model(&forummodel.ForumComment{}).
+		Where("id = ? AND status = ?", commentID, forummodel.ForumCommentStatusVisible).
+		Updates(map[string]any{
+			"status":     forummodel.ForumCommentStatusDeleted,
+			"deleted_at": &now,
+			"updated_at": now,
+		})
+	return tx.Error
+}
+
+func (dao *ForumDAO) FindImport(ctx context.Context, postID uint64, userID uint64) (*forummodel.ForumImport, error) {
+	var item forummodel.ForumImport
+	err := dao.db.WithContext(ctx).Where("post_id = ? AND user_id = ?", postID, userID).First(&item).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &item, nil
+}
+
+func (dao *ForumDAO) FindImportByIdempotencyKey(ctx context.Context, userID uint64, key string) (*forummodel.ForumImport, error) {
+	var item forummodel.ForumImport
+	err := dao.db.WithContext(ctx).
+		Where("user_id = ? AND idempotency_key = ?", userID, key).
+		First(&item).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &item, nil
+}
+
+func (dao *ForumDAO) CreateImport(ctx context.Context, item *forummodel.ForumImport) error {
+	return dao.db.WithContext(ctx).Create(item).Error
+}
+
+func (dao *ForumDAO) UpdateImportProcessing(ctx context.Context, importID uint64, title string, now time.Time) error {
+	return dao.db.WithContext(ctx).
+		Model(&forummodel.ForumImport{}).
+		Where("id = ?", importID).
+		Updates(map[string]any{
+			"target_title": title,
+			"status":       forummodel.ForumImportStatusPending,
+			"last_error":   nil,
+			"updated_at":   now,
+		}).Error
+}
+
+func (dao *ForumDAO) FinalizeImport(ctx context.Context, importID uint64, newTaskClassID uint64, targetTitle string, now time.Time) error {
+	return dao.db.WithContext(ctx).
+		Model(&forummodel.ForumImport{}).
+		Where("id = ?", importID).
+		Updates(map[string]any{
+			"new_task_class_id": &newTaskClassID,
+			"target_title":      targetTitle,
+			"status":            forummodel.ForumImportStatusImported,
+			"last_error":        nil,
+			"updated_at":        now,
+		}).Error
+}
+
+func (dao *ForumDAO) MarkImportFailed(ctx context.Context, importID uint64, message string, now time.Time) error {
+	return dao.db.WithContext(ctx).
+		Model(&forummodel.ForumImport{}).
+		Where("id = ?", importID).
+		Updates(map[string]any{
+			"status":     forummodel.ForumImportStatusFailed,
+			"last_error": &message,
+			"updated_at": now,
+		}).Error
+}
+
+func (dao *ForumDAO) MarkImportFailedAfterTaskClassCreated(ctx context.Context, importID uint64, newTaskClassID uint64, targetTitle string, message string, now time.Time) error {
+	return dao.db.WithContext(ctx).
+		Model(&forummodel.ForumImport{}).
+		Where("id = ?", importID).
+		Updates(map[string]any{
+			"new_task_class_id": &newTaskClassID,
+			"target_title":      targetTitle,
+			"status":            forummodel.ForumImportStatusFailed,
+			"last_error":        &message,
+			"updated_at":        now,
+		}).Error
+}

backend/services/taskclassforum/model/forum.go

@@ -0,0 +1,186 @@
+package model
+
+import "time"
+
+const (
+	// ForumPostStatusPublished 表示帖子已公开展示在计划广场。
+	ForumPostStatusPublished = "published"
+	// ForumPostStatusHidden 表示帖子被作者隐藏或后续治理流程下架。
+	ForumPostStatusHidden = "hidden"
+	// ForumPostStatusDeleted 表示帖子已软删除，P0 暂不对前端展示。
+	ForumPostStatusDeleted = "deleted"
+	// ForumPostStatusPendingReview 预留审核态，P0 不启用审核后台。
+	ForumPostStatusPendingReview = "pending_review"
+)
+
+const (
+	// ForumLikeStatusActive 表示当前用户仍保持点赞。
+	ForumLikeStatusActive = "active"
+	// ForumLikeStatusCanceled 表示用户取消点赞，保留记录用于奖励幂等。
+	ForumLikeStatusCanceled = "canceled"
+)
+
+const (
+	// ForumCommentStatusVisible 表示评论正常展示。
+	ForumCommentStatusVisible = "visible"
+	// ForumCommentStatusDeleted 表示评论已由本人删除，服务层仍保留子回复结构。
+	ForumCommentStatusDeleted = "deleted"
+)
+
+const (
+	// ForumImportStatusPending 表示导入记录已占位，正在创建 TaskClass 副本。
+	ForumImportStatusPending = "pending"
+	// ForumImportStatusImported 表示导入已成功创建当前用户自己的 TaskClass 副本。
+	ForumImportStatusImported = "imported"
+	// ForumImportStatusFailed 表示导入副本创建或最终确认失败，可由后续重试覆盖。
+	ForumImportStatusFailed = "failed"
+)
+
+// ForumPost 是计划广场帖子主体表。
+//
+// 职责边界：
+// 1. 只保存社区帖子可展示信息、作者和计数字段；
+// 2. 不保存完整 TaskClass 模板，模板快照归 ForumPostTemplate / ForumPostTemplateItem；
+// 3. 计数字段由服务事务内维护，避免列表页每次做聚合统计。
+type ForumPost struct {
+	ID                uint64     `gorm:"column:id;primaryKey;autoIncrement"`
+	AuthorUserID      uint64     `gorm:"column:author_user_id;not null;index:idx_forum_posts_author_status,priority:1;uniqueIndex:uk_forum_posts_author_idem,priority:1;comment:作者用户ID"`
+	SourceTaskClassID uint64     `gorm:"column:source_task_class_id;not null;index:idx_forum_posts_source_task_class;comment:发布时选择的原始TaskClass ID，仅用于审计"`
+	Title             string     `gorm:"column:title;type:varchar(80);not null;comment:帖子标题"`
+	Summary           string     `gorm:"column:summary;type:text;comment:帖子简介"`
+	TagsJSON          string     `gorm:"column:tags_json;type:json;not null;comment:标签JSON数组"`
+	IdempotencyKey    *string    `gorm:"column:idempotency_key;type:varchar(128);uniqueIndex:uk_forum_posts_author_idem,priority:2;comment:发布请求幂等键"`
+	Status            string     `gorm:"column:status;type:varchar(32);not null;default:'published';index:idx_forum_posts_status_created,priority:1;index:idx_forum_posts_author_status,priority:2;comment:published/hidden/deleted/pending_review"`
+	LikeCount         int64      `gorm:"column:like_count;not null;default:0;index:idx_forum_posts_like_count;comment:点赞数冗余计数"`
+	CommentCount      int64      `gorm:"column:comment_count;not null;default:0;comment:评论数冗余计数"`
+	ImportCount       int64      `gorm:"column:import_count;not null;default:0;index:idx_forum_posts_import_count;comment:导入数冗余计数"`
+	CreatedAt         time.Time  `gorm:"column:created_at;autoCreateTime;index:idx_forum_posts_status_created,priority:2;comment:创建时间"`
+	UpdatedAt         time.Time  `gorm:"column:updated_at;autoUpdateTime;comment:更新时间"`
+	DeletedAt         *time.Time `gorm:"column:deleted_at;index;comment:软删除时间"`
+}
+
+func (ForumPost) TableName() string {
+	return "forum_posts"
+}
+
+// ForumPostTemplate 是发布瞬间复制出的 TaskClass 配置快照。
+//
+// 职责边界：
+// 1. 只保存可分享的 TaskClass 配置白名单；
+// 2. 不保存 embedded_time、schedule 绑定和用户私有排程状态；
+// 3. 后续原作者修改原 TaskClass 时，本快照不跟随变化。
+type ForumPostTemplate struct {
+	ID                     uint64     `gorm:"column:id;primaryKey;autoIncrement"`
+	PostID                 uint64     `gorm:"column:post_id;not null;uniqueIndex:uk_forum_templates_post;comment:所属帖子ID"`
+	SourceTaskClassID      uint64     `gorm:"column:source_task_class_id;not null;comment:原始TaskClass ID"`
+	Mode                   string     `gorm:"column:mode;type:varchar(32);comment:TaskClass 模式"`
+	StartDate              *time.Time `gorm:"column:start_date;comment:计划开始日期"`
+	EndDate                *time.Time `gorm:"column:end_date;comment:计划结束日期"`
+	SubjectType            string     `gorm:"column:subject_type;type:varchar(32);comment:学科类型"`
+	DifficultyLevel        string     `gorm:"column:difficulty_level;type:varchar(16);comment:难度等级"`
+	CognitiveIntensity     string     `gorm:"column:cognitive_intensity;type:varchar(16);comment:认知强度"`
+	TotalSlots             int        `gorm:"column:total_slots;comment:分配的总节数"`
+	AllowFillerCourse      bool       `gorm:"column:allow_filler_course;not null;default:true;comment:是否允许填充课程空隙"`
+	Strategy               string     `gorm:"column:strategy;type:varchar(32);comment:规划策略"`
+	ExcludedSlotsJSON      *string    `gorm:"column:excluded_slots_json;type:json;comment:排除节次JSON数组"`
+	ExcludedDaysOfWeekJSON *string    `gorm:"column:excluded_days_of_week_json;type:json;comment:排除星期JSON数组"`
+	StrategyLabelsJSON     *string    `gorm:"column:strategy_labels_json;type:json;comment:前端展示用策略标签JSON数组"`
+	ConfigSnapshotJSON     *string    `gorm:"column:config_snapshot_json;type:json;comment:过滤后的配置快照，便于后续兼容扩展"`
+	CreatedAt              time.Time  `gorm:"column:created_at;autoCreateTime;comment:创建时间"`
+	UpdatedAt              time.Time  `gorm:"column:updated_at;autoUpdateTime;comment:更新时间"`
+}
+
+func (ForumPostTemplate) TableName() string {
+	return "forum_post_templates"
+}
+
+// ForumPostTemplateItem 是 TaskClassItem 的可分享快照。
+//
+// 职责边界：
+// 1. 只保存任务条目的顺序和内容；
+// 2. 不保存 embedded_time，避免把原作者私有排程状态带给导入用户；
+// 3. 导入时服务层按这些快照重新创建当前用户自己的 TaskClassItem。
+type ForumPostTemplateItem struct {
+	ID               uint64    `gorm:"column:id;primaryKey;autoIncrement"`
+	TemplateID       uint64    `gorm:"column:template_id;not null;uniqueIndex:uk_forum_template_items_order,priority:1;index:idx_forum_template_items_template;comment:模板ID"`
+	PostID           uint64    `gorm:"column:post_id;not null;index:idx_forum_template_items_post;comment:帖子ID，便于按帖子直接读取预览"`
+	SourceTaskItemID uint64    `gorm:"column:source_task_item_id;not null;comment:原始TaskClassItem ID，仅用于审计"`
+	Order            int       `gorm:"column:item_order;not null;uniqueIndex:uk_forum_template_items_order,priority:2;comment:条目顺序"`
+	Content          string    `gorm:"column:content;type:text;not null;comment:任务条目内容"`
+	CreatedAt        time.Time `gorm:"column:created_at;autoCreateTime;comment:创建时间"`
+}
+
+func (ForumPostTemplateItem) TableName() string {
+	return "forum_post_template_items"
+}
+
+// ForumLike 是点赞幂等表。
+//
+// 职责边界：
+// 1. 通过 post_id + user_id 唯一约束保证同一用户同一帖子只有一条点赞状态；
+// 2. 取消点赞只把状态改为 canceled，不删除记录，避免作者奖励被反复触发；
+// 3. event_id 对应首次点赞奖励事件，供 token-store 账本幂等使用。
+type ForumLike struct {
+	ID           uint64     `gorm:"column:id;primaryKey;autoIncrement"`
+	PostID       uint64     `gorm:"column:post_id;not null;uniqueIndex:uk_forum_likes_post_user,priority:1;index:idx_forum_likes_post_status,priority:1;comment:帖子ID"`
+	UserID       uint64     `gorm:"column:user_id;not null;uniqueIndex:uk_forum_likes_post_user,priority:2;comment:点赞用户ID"`
+	AuthorUserID uint64     `gorm:"column:author_user_id;not null;index:idx_forum_likes_author;comment:帖子作者ID，便于奖励和审计"`
+	Status       string     `gorm:"column:status;type:varchar(32);not null;default:'active';index:idx_forum_likes_post_status,priority:2;comment:active/canceled"`
+	EventID      string     `gorm:"column:event_id;type:varchar(128);not null;uniqueIndex:uk_forum_likes_event;comment:首次点赞事件ID"`
+	LikedAt      time.Time  `gorm:"column:liked_at;autoCreateTime;comment:首次点赞时间"`
+	CanceledAt   *time.Time `gorm:"column:canceled_at;comment:最近一次取消点赞时间"`
+	CreatedAt    time.Time  `gorm:"column:created_at;autoCreateTime;comment:创建时间"`
+	UpdatedAt    time.Time  `gorm:"column:updated_at;autoUpdateTime;comment:更新时间"`
+}
+
+func (ForumLike) TableName() string {
+	return "forum_likes"
+}
+
+// ForumComment 是评论和多层回复的扁平存储表。
+//
+// 职责边界：
+// 1. 数据库只保存 parent_comment_id，不保存树结构；
+// 2. 服务层按帖子读取扁平评论后组装评论树；
+// 3. 删除评论使用 status + deleted_at 软删除，保留子回复链路。
+type ForumComment struct {
+	ID              uint64     `gorm:"column:id;primaryKey;autoIncrement"`
+	PostID          uint64     `gorm:"column:post_id;not null;index:idx_forum_comments_post_parent_created,priority:1;comment:帖子ID"`
+	ParentCommentID *uint64    `gorm:"column:parent_comment_id;index:idx_forum_comments_post_parent_created,priority:2;comment:父评论ID，根评论为空"`
+	UserID          uint64     `gorm:"column:user_id;not null;uniqueIndex:uk_forum_comments_user_idem,priority:1;index:idx_forum_comments_user;comment:评论用户ID"`
+	Content         string     `gorm:"column:content;type:text;not null;comment:评论内容"`
+	Status          string     `gorm:"column:status;type:varchar(32);not null;default:'visible';index:idx_forum_comments_status;comment:visible/deleted"`
+	IdempotencyKey  *string    `gorm:"column:idempotency_key;type:varchar(128);uniqueIndex:uk_forum_comments_user_idem,priority:2;comment:评论创建幂等键"`
+	CreatedAt       time.Time  `gorm:"column:created_at;autoCreateTime;index:idx_forum_comments_post_parent_created,priority:3;comment:创建时间"`
+	UpdatedAt       time.Time  `gorm:"column:updated_at;autoUpdateTime;comment:更新时间"`
+	DeletedAt       *time.Time `gorm:"column:deleted_at;comment:用户删除时间"`
+}
+
+func (ForumComment) TableName() string {
+	return "forum_comments"
+}
+
+// ForumImport 是一键导入记录表。
+//
+// 职责边界：
+// 1. 通过 post_id + user_id 唯一约束保证同一用户同一计划只导入一次；
+// 2. 只记录导入到 TaskClass 的结果，不写 schedule；
+// 3. event_id 对应导入奖励事件，供 token-store 账本幂等使用。
+type ForumImport struct {
+	ID             uint64    `gorm:"column:id;primaryKey;autoIncrement"`
+	PostID         uint64    `gorm:"column:post_id;not null;uniqueIndex:uk_forum_imports_post_user,priority:1;index:idx_forum_imports_post;comment:帖子ID"`
+	UserID         uint64    `gorm:"column:user_id;not null;uniqueIndex:uk_forum_imports_post_user,priority:2;uniqueIndex:uk_forum_imports_user_idem,priority:1;index:idx_forum_imports_user;comment:导入用户ID"`
+	AuthorUserID   uint64    `gorm:"column:author_user_id;not null;index:idx_forum_imports_author;comment:帖子作者ID，便于奖励和审计"`
+	NewTaskClassID *uint64   `gorm:"column:new_task_class_id;comment:导入后创建的当前用户TaskClass ID，pending/failed 时为空"`
+	TargetTitle    string    `gorm:"column:target_title;type:varchar(80);comment:导入后的TaskClass标题"`
+	Status         string    `gorm:"column:status;type:varchar(32);not null;default:'pending';comment:pending/imported/failed"`
+	EventID        string    `gorm:"column:event_id;type:varchar(128);not null;uniqueIndex:uk_forum_imports_event;comment:导入事件ID"`
+	IdempotencyKey *string   `gorm:"column:idempotency_key;type:varchar(128);uniqueIndex:uk_forum_imports_user_idem,priority:2;comment:导入请求幂等键"`
+	LastError      *string   `gorm:"column:last_error;type:text;comment:最近一次导入失败原因"`
+	CreatedAt      time.Time `gorm:"column:created_at;autoCreateTime;comment:创建时间"`
+	UpdatedAt      time.Time `gorm:"column:updated_at;autoUpdateTime;comment:更新时间"`
+}
+
+func (ForumImport) TableName() string {
+	return "forum_imports"
+}

backend/services/taskclassforum/rpc/errors.go

@@ -0,0 +1,72 @@
+package rpc
+
+import (
+	"errors"
+	"log"
+	"strings"
+
+	"github.com/LoveLosita/smartflow/backend/shared/respond"
+	"google.golang.org/genproto/googleapis/rpc/errdetails"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+)
+
+const taskClassForumErrorDomain = "smartflow.taskclassforum"
+
+// grpcErrorFromServiceError 负责把计划广场内部错误收口成 gRPC status。
+//
+// 职责边界：
+// 1. 只做 service error -> gRPC error 的传输适配；
+// 2. 不负责 HTTP 响应，gateway client 后续会把 gRPC error 反解成 respond.Response；
+// 3. 普通内部错误只暴露统一文案，避免把 DAO / SQL 细节透给前端。
+func grpcErrorFromServiceError(err error) error {
+	if err == nil {
+		return nil
+	}
+
+	var resp respond.Response
+	if errors.As(err, &resp) {
+		return grpcErrorFromResponse(resp)
+	}
+	log.Printf("taskclassforum rpc internal error: %v", err)
+	return status.Error(codes.Internal, "taskclassforum 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: taskClassForumErrorDomain,
+		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
+	case respond.UserTaskClassNotFound.Status:
+		return codes.NotFound
+	case respond.UserTaskClassForbidden.Status, respond.TaskClassItemNotBelongToUser.Status:
+		return codes.PermissionDenied
+	}
+	if strings.HasPrefix(strings.TrimSpace(statusValue), "5") {
+		return codes.Internal
+	}
+	return codes.InvalidArgument
+}

backend/services/taskclassforum/rpc/handler.go

@@ -0,0 +1,412 @@
+package rpc
+
+import (
+	"context"
+	"errors"
+
+	"github.com/LoveLosita/smartflow/backend/shared/respond"
+	"github.com/LoveLosita/smartflow/backend/services/taskclassforum/rpc/pb"
+	forumsv "github.com/LoveLosita/smartflow/backend/services/taskclassforum/sv"
+	forumcontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/taskclassforum"
+)
+
+type Handler struct {
+	pb.UnimplementedTaskClassForumServiceServer
+	svc *forumsv.Service
+}
+
+func NewHandler(svc *forumsv.Service) *Handler {
+	return &Handler{svc: svc}
+}
+
+// service 负责统一校验 RPC 层依赖是否已经注入。
+//
+// 职责边界：
+// 1. 只判断 handler 自身和业务 service 是否可用；
+// 2. 不负责校验请求参数，也不处理具体业务规则；
+// 3. 失败时返回可直接转成 gRPC status 的业务错误。
+func (h *Handler) service() (*forumsv.Service, error) {
+	if h == nil || h.svc == nil {
+		return nil, errors.New("taskclassforum service dependency not initialized")
+	}
+	return h.svc, nil
+}
+
+// ListPosts 负责把计划广场列表请求从 gRPC 协议转成内部服务调用。
+func (h *Handler) ListPosts(ctx context.Context, req *pb.ListForumPostsRequest) (*pb.ListForumPostsResponse, error) {
+	svc, err := h.service()
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	if req == nil {
+		return nil, grpcErrorFromServiceError(respond.MissingParam)
+	}
+
+	items, page, err := svc.ListPosts(ctx, req.ActorUserId, int(req.Page), int(req.PageSize), req.Sort, req.Keyword, req.Tag)
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.ListForumPostsResponse{
+		Items: forumPostBriefsToPB(items),
+		Page:  forumPageToPB(page),
+	}, nil
+}
+
+func (h *Handler) ListTags(ctx context.Context, req *pb.ListForumTagsRequest) (*pb.ListForumTagsResponse, error) {
+	svc, err := h.service()
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	if req == nil {
+		return nil, grpcErrorFromServiceError(respond.MissingParam)
+	}
+
+	items, err := svc.ListTags(ctx, req.ActorUserId, int(req.Limit))
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.ListForumTagsResponse{Items: forumTagItemsToPB(items)}, nil
+}
+
+func (h *Handler) CreatePost(ctx context.Context, req *pb.CreateForumPostRequest) (*pb.CreateForumPostResponse, error) {
+	svc, err := h.service()
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	if req == nil {
+		return nil, grpcErrorFromServiceError(respond.MissingParam)
+	}
+
+	post, err := svc.CreatePost(ctx, forumcontracts.CreateForumPostRequest{
+		ActorUserID:    req.ActorUserId,
+		TaskClassID:    req.TaskClassId,
+		Title:          req.Title,
+		Summary:        req.Summary,
+		Tags:           append([]string(nil), req.Tags...),
+		IdempotencyKey: req.IdempotencyKey,
+	})
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.CreateForumPostResponse{Post: forumPostBriefToPB(post)}, nil
+}
+
+func (h *Handler) GetPost(ctx context.Context, req *pb.GetForumPostRequest) (*pb.GetForumPostResponse, error) {
+	svc, err := h.service()
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	if req == nil {
+		return nil, grpcErrorFromServiceError(respond.MissingParam)
+	}
+
+	data, err := svc.GetPost(ctx, req.ActorUserId, req.PostId)
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.GetForumPostResponse{Data: forumPostDetailToPB(data)}, nil
+}
+
+func (h *Handler) LikePost(ctx context.Context, req *pb.LikeForumPostRequest) (*pb.LikeForumPostResponse, error) {
+	svc, err := h.service()
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	if req == nil {
+		return nil, grpcErrorFromServiceError(respond.MissingParam)
+	}
+
+	counters, viewerState, err := svc.LikePost(ctx, req.ActorUserId, req.PostId)
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.LikeForumPostResponse{
+		Counters:    forumPostCountersToPB(counters),
+		ViewerState: forumPostViewerStateToPB(viewerState),
+	}, nil
+}
+
+func (h *Handler) UnlikePost(ctx context.Context, req *pb.UnlikeForumPostRequest) (*pb.UnlikeForumPostResponse, error) {
+	svc, err := h.service()
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	if req == nil {
+		return nil, grpcErrorFromServiceError(respond.MissingParam)
+	}
+
+	counters, viewerState, err := svc.UnlikePost(ctx, req.ActorUserId, req.PostId)
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.UnlikeForumPostResponse{
+		Counters:    forumPostCountersToPB(counters),
+		ViewerState: forumPostViewerStateToPB(viewerState),
+	}, nil
+}
+
+func (h *Handler) ListComments(ctx context.Context, req *pb.ListForumCommentsRequest) (*pb.ListForumCommentsResponse, error) {
+	svc, err := h.service()
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	if req == nil {
+		return nil, grpcErrorFromServiceError(respond.MissingParam)
+	}
+
+	items, page, err := svc.ListComments(ctx, req.ActorUserId, req.PostId, int(req.Page), int(req.PageSize), req.Sort)
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.ListForumCommentsResponse{
+		Items: forumCommentNodesToPB(items),
+		Page:  forumPageToPB(page),
+	}, nil
+}
+
+func (h *Handler) CreateComment(ctx context.Context, req *pb.CreateForumCommentRequest) (*pb.CreateForumCommentResponse, error) {
+	svc, err := h.service()
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	if req == nil {
+		return nil, grpcErrorFromServiceError(respond.MissingParam)
+	}
+
+	comment, err := svc.CreateComment(ctx, forumcontracts.CreateForumCommentRequest{
+		ActorUserID:     req.ActorUserId,
+		PostID:          req.PostId,
+		Content:         req.Content,
+		ParentCommentID: forumUint64PtrFromPositive(req.ParentCommentId),
+		IdempotencyKey:  req.IdempotencyKey,
+	})
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.CreateForumCommentResponse{Comment: forumCommentNodeToPB(comment)}, nil
+}
+
+func (h *Handler) DeleteComment(ctx context.Context, req *pb.DeleteForumCommentRequest) (*pb.DeleteForumCommentResponse, error) {
+	svc, err := h.service()
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	if req == nil {
+		return nil, grpcErrorFromServiceError(respond.MissingParam)
+	}
+
+	result, err := svc.DeleteComment(ctx, req.ActorUserId, req.CommentId)
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.DeleteForumCommentResponse{
+		CommentId: result.CommentID,
+		Status:    result.Status,
+	}, nil
+}
+
+func (h *Handler) ImportPost(ctx context.Context, req *pb.ImportForumPostRequest) (*pb.ImportForumPostResponse, error) {
+	svc, err := h.service()
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	if req == nil {
+		return nil, grpcErrorFromServiceError(respond.MissingParam)
+	}
+
+	result, err := svc.ImportPost(ctx, forumcontracts.ImportForumPostRequest{
+		ActorUserID:    req.ActorUserId,
+		PostID:         req.PostId,
+		TargetTitle:    req.TargetTitle,
+		IdempotencyKey: req.IdempotencyKey,
+	})
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.ImportForumPostResponse{
+		ImportId:       result.ImportID,
+		PostId:         result.PostID,
+		NewTaskClassId: result.NewTaskClassID,
+		TaskClassTitle: result.TaskClassTitle,
+		ImportCount:    result.ImportCount,
+		CreatedAt:      result.CreatedAt,
+	}, nil
+}
+
+func forumPageToPB(page forumcontracts.PageResult) *pb.PageResponse {
+	return &pb.PageResponse{
+		Page:     int32(page.Page),
+		PageSize: int32(page.PageSize),
+		Total:    int32(page.Total),
+		HasMore:  page.HasMore,
+	}
+}
+
+func forumUserToPB(user forumcontracts.UserBrief) *pb.UserBrief {
+	return &pb.UserBrief{
+		UserId:    user.UserID,
+		Nickname:  user.Nickname,
+		AvatarUrl: user.AvatarURL,
+	}
+}
+
+func forumTemplateSummaryToPB(summary forumcontracts.TemplateSummary) *pb.TemplateSummary {
+	return &pb.TemplateSummary{
+		TaskCount:      int32(summary.TaskCount),
+		Mode:           summary.Mode,
+		StartDate:      summary.StartDate,
+		EndDate:        summary.EndDate,
+		StrategyLabels: append([]string(nil), summary.StrategyLabels...),
+	}
+}
+
+func forumPostCountersToPB(counters forumcontracts.ForumPostCounters) *pb.ForumPostCounters {
+	return &pb.ForumPostCounters{
+		LikeCount:    counters.LikeCount,
+		CommentCount: counters.CommentCount,
+		ImportCount:  counters.ImportCount,
+	}
+}
+
+func forumPostViewerStateToPB(viewerState forumcontracts.ForumPostViewerState) *pb.ForumPostViewerState {
+	return &pb.ForumPostViewerState{
+		Liked:        viewerState.Liked,
+		ImportedOnce: viewerState.ImportedOnce,
+	}
+}
+
+func forumPostBriefToPB(post *forumcontracts.ForumPostBrief) *pb.ForumPostBrief {
+	if post == nil {
+		return nil
+	}
+	return &pb.ForumPostBrief{
+		PostId:          post.PostID,
+		Title:           post.Title,
+		Summary:         post.Summary,
+		Tags:            append([]string(nil), post.Tags...),
+		Author:          forumUserToPB(post.Author),
+		TemplateSummary: forumTemplateSummaryToPB(post.TemplateSummary),
+		Counters:        forumPostCountersToPB(post.Counters),
+		ViewerState:     forumPostViewerStateToPB(post.ViewerState),
+		Status:          post.Status,
+		CreatedAt:       post.CreatedAt,
+	}
+}
+
+func forumPostBriefsToPB(items []forumcontracts.ForumPostBrief) []*pb.ForumPostBrief {
+	if len(items) == 0 {
+		return nil
+	}
+	result := make([]*pb.ForumPostBrief, 0, len(items))
+	for i := range items {
+		item := items[i]
+		result = append(result, forumPostBriefToPB(&item))
+	}
+	return result
+}
+
+func forumTemplateItemPreviewToPB(item forumcontracts.TemplateItemPreview) *pb.TemplateItemPreview {
+	return &pb.TemplateItemPreview{
+		ItemId:  item.ItemID,
+		Order:   int32(item.Order),
+		Content: item.Content,
+	}
+}
+
+func forumTemplateDetailToPB(detail forumcontracts.TemplateDetail) *pb.TemplateDetail {
+	preview := make([]*pb.TemplateItemPreview, 0, len(detail.ItemsPreview))
+	for i := range detail.ItemsPreview {
+		item := detail.ItemsPreview[i]
+		preview = append(preview, forumTemplateItemPreviewToPB(item))
+	}
+	return &pb.TemplateDetail{
+		Mode:           detail.Mode,
+		StartDate:      detail.StartDate,
+		EndDate:        detail.EndDate,
+		StrategyLabels: append([]string(nil), detail.StrategyLabels...),
+		TaskCount:      int32(detail.TaskCount),
+		ItemsPreview:   preview,
+	}
+}
+
+func forumPostDetailToPB(detail *forumcontracts.ForumPostDetail) *pb.ForumPostDetail {
+	if detail == nil {
+		return nil
+	}
+	return &pb.ForumPostDetail{
+		Post:     forumPostBriefToPB(&detail.Post),
+		Template: forumTemplateDetailToPB(detail.Template),
+	}
+}
+
+func forumTagItemsToPB(items []forumcontracts.ForumTagItem) []*pb.ForumTagItem {
+	if len(items) == 0 {
+		return nil
+	}
+	result := make([]*pb.ForumTagItem, 0, len(items))
+	for i := range items {
+		item := items[i]
+		result = append(result, &pb.ForumTagItem{
+			Tag:       item.Tag,
+			PostCount: int32(item.PostCount),
+		})
+	}
+	return result
+}
+
+func forumCommentNodeToPB(node *forumcontracts.ForumCommentNode) *pb.ForumCommentNode {
+	if node == nil {
+		return nil
+	}
+	children := make([]*pb.ForumCommentNode, 0, len(node.Children))
+	for i := range node.Children {
+		child := node.Children[i]
+		children = append(children, forumCommentNodeToPB(&child))
+	}
+	return &pb.ForumCommentNode{
+		CommentId:       node.CommentID,
+		PostId:          node.PostID,
+		ParentCommentId: forumUint64FromPtr(node.ParentCommentID),
+		Content:         node.Content,
+		Status:          node.Status,
+		Author:          forumUserToPB(node.Author),
+		CanDelete:       node.CanDelete,
+		CreatedAt:       node.CreatedAt,
+		DeletedAt:       forumStringFromPtr(node.DeletedAt),
+		Children:        children,
+	}
+}
+
+func forumCommentNodesToPB(items []forumcontracts.ForumCommentNode) []*pb.ForumCommentNode {
+	if len(items) == 0 {
+		return nil
+	}
+	result := make([]*pb.ForumCommentNode, 0, len(items))
+	for i := range items {
+		item := items[i]
+		result = append(result, forumCommentNodeToPB(&item))
+	}
+	return result
+}
+
+func forumUint64FromPtr(value *uint64) uint64 {
+	if value == nil {
+		return 0
+	}
+	return *value
+}
+
+func forumUint64PtrFromPositive(value uint64) *uint64 {
+	if value == 0 {
+		return nil
+	}
+	result := value
+	return &result
+}
+
+func forumStringFromPtr(value *string) string {
+	if value == nil {
+		return ""
+	}
+	return *value
+}

backend/services/taskclassforum/rpc/pb/taskclassforum.pb.go

@@ -0,0 +1,339 @@
+package pb
+
+import proto "github.com/golang/protobuf/proto"
+
+var _ = proto.Marshal
+
+const _ = proto.ProtoPackageIsVersion3
+
+type PageRequest 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"`
+}
+
+func (m *PageRequest) Reset()         { *m = PageRequest{} }
+func (m *PageRequest) String() string { return proto.CompactTextString(m) }
+func (*PageRequest) ProtoMessage()    {}
+
+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 UserBrief struct {
+	UserId    uint64 `protobuf:"varint,1,opt,name=user_id,json=userId,proto3" json:"user_id,omitempty"`
+	Nickname  string `protobuf:"bytes,2,opt,name=nickname,proto3" json:"nickname,omitempty"`
+	AvatarUrl string `protobuf:"bytes,3,opt,name=avatar_url,json=avatarUrl,proto3" json:"avatar_url,omitempty"`
+}
+
+func (m *UserBrief) Reset()         { *m = UserBrief{} }
+func (m *UserBrief) String() string { return proto.CompactTextString(m) }
+func (*UserBrief) ProtoMessage()    {}
+
+type TemplateSummary struct {
+	TaskCount      int32    `protobuf:"varint,1,opt,name=task_count,json=taskCount,proto3" json:"task_count,omitempty"`
+	Mode           string   `protobuf:"bytes,2,opt,name=mode,proto3" json:"mode,omitempty"`
+	StartDate      string   `protobuf:"bytes,3,opt,name=start_date,json=startDate,proto3" json:"start_date,omitempty"`
+	EndDate        string   `protobuf:"bytes,4,opt,name=end_date,json=endDate,proto3" json:"end_date,omitempty"`
+	StrategyLabels []string `protobuf:"bytes,5,rep,name=strategy_labels,json=strategyLabels,proto3" json:"strategy_labels,omitempty"`
+}
+
+func (m *TemplateSummary) Reset()         { *m = TemplateSummary{} }
+func (m *TemplateSummary) String() string { return proto.CompactTextString(m) }
+func (*TemplateSummary) ProtoMessage()    {}
+
+type ForumPostCounters struct {
+	LikeCount    int64 `protobuf:"varint,1,opt,name=like_count,json=likeCount,proto3" json:"like_count,omitempty"`
+	CommentCount int64 `protobuf:"varint,2,opt,name=comment_count,json=commentCount,proto3" json:"comment_count,omitempty"`
+	ImportCount  int64 `protobuf:"varint,3,opt,name=import_count,json=importCount,proto3" json:"import_count,omitempty"`
+}
+
+func (m *ForumPostCounters) Reset()         { *m = ForumPostCounters{} }
+func (m *ForumPostCounters) String() string { return proto.CompactTextString(m) }
+func (*ForumPostCounters) ProtoMessage()    {}
+
+type ForumPostViewerState struct {
+	Liked        bool `protobuf:"varint,1,opt,name=liked,proto3" json:"liked,omitempty"`
+	ImportedOnce bool `protobuf:"varint,2,opt,name=imported_once,json=importedOnce,proto3" json:"imported_once,omitempty"`
+}
+
+func (m *ForumPostViewerState) Reset()         { *m = ForumPostViewerState{} }
+func (m *ForumPostViewerState) String() string { return proto.CompactTextString(m) }
+func (*ForumPostViewerState) ProtoMessage()    {}
+
+type ForumPostBrief struct {
+	PostId          uint64                `protobuf:"varint,1,opt,name=post_id,json=postId,proto3" json:"post_id,omitempty"`
+	Title           string                `protobuf:"bytes,2,opt,name=title,proto3" json:"title,omitempty"`
+	Summary         string                `protobuf:"bytes,3,opt,name=summary,proto3" json:"summary,omitempty"`
+	Tags            []string              `protobuf:"bytes,4,rep,name=tags,proto3" json:"tags,omitempty"`
+	Author          *UserBrief            `protobuf:"bytes,5,opt,name=author,proto3" json:"author,omitempty"`
+	TemplateSummary *TemplateSummary      `protobuf:"bytes,6,opt,name=template_summary,json=templateSummary,proto3" json:"template_summary,omitempty"`
+	Counters        *ForumPostCounters    `protobuf:"bytes,7,opt,name=counters,proto3" json:"counters,omitempty"`
+	ViewerState     *ForumPostViewerState `protobuf:"bytes,8,opt,name=viewer_state,json=viewerState,proto3" json:"viewer_state,omitempty"`
+	Status          string                `protobuf:"bytes,9,opt,name=status,proto3" json:"status,omitempty"`
+	CreatedAt       string                `protobuf:"bytes,10,opt,name=created_at,json=createdAt,proto3" json:"created_at,omitempty"`
+}
+
+func (m *ForumPostBrief) Reset()         { *m = ForumPostBrief{} }
+func (m *ForumPostBrief) String() string { return proto.CompactTextString(m) }
+func (*ForumPostBrief) ProtoMessage()    {}
+
+type TemplateItemPreview struct {
+	ItemId  uint64 `protobuf:"varint,1,opt,name=item_id,json=itemId,proto3" json:"item_id,omitempty"`
+	Order   int32  `protobuf:"varint,2,opt,name=order,proto3" json:"order,omitempty"`
+	Content string `protobuf:"bytes,3,opt,name=content,proto3" json:"content,omitempty"`
+}
+
+func (m *TemplateItemPreview) Reset()         { *m = TemplateItemPreview{} }
+func (m *TemplateItemPreview) String() string { return proto.CompactTextString(m) }
+func (*TemplateItemPreview) ProtoMessage()    {}
+
+type TemplateDetail struct {
+	Mode           string                 `protobuf:"bytes,1,opt,name=mode,proto3" json:"mode,omitempty"`
+	StartDate      string                 `protobuf:"bytes,2,opt,name=start_date,json=startDate,proto3" json:"start_date,omitempty"`
+	EndDate        string                 `protobuf:"bytes,3,opt,name=end_date,json=endDate,proto3" json:"end_date,omitempty"`
+	StrategyLabels []string               `protobuf:"bytes,4,rep,name=strategy_labels,json=strategyLabels,proto3" json:"strategy_labels,omitempty"`
+	TaskCount      int32                  `protobuf:"varint,5,opt,name=task_count,json=taskCount,proto3" json:"task_count,omitempty"`
+	ItemsPreview   []*TemplateItemPreview `protobuf:"bytes,6,rep,name=items_preview,json=itemsPreview,proto3" json:"items_preview,omitempty"`
+}
+
+func (m *TemplateDetail) Reset()         { *m = TemplateDetail{} }
+func (m *TemplateDetail) String() string { return proto.CompactTextString(m) }
+func (*TemplateDetail) ProtoMessage()    {}
+
+type ForumPostDetail struct {
+	Post     *ForumPostBrief `protobuf:"bytes,1,opt,name=post,proto3" json:"post,omitempty"`
+	Template *TemplateDetail `protobuf:"bytes,2,opt,name=template,proto3" json:"template,omitempty"`
+}
+
+func (m *ForumPostDetail) Reset()         { *m = ForumPostDetail{} }
+func (m *ForumPostDetail) String() string { return proto.CompactTextString(m) }
+func (*ForumPostDetail) ProtoMessage()    {}
+
+type ForumCommentNode struct {
+	CommentId       uint64              `protobuf:"varint,1,opt,name=comment_id,json=commentId,proto3" json:"comment_id,omitempty"`
+	PostId          uint64              `protobuf:"varint,2,opt,name=post_id,json=postId,proto3" json:"post_id,omitempty"`
+	ParentCommentId uint64              `protobuf:"varint,3,opt,name=parent_comment_id,json=parentCommentId,proto3" json:"parent_comment_id,omitempty"`
+	Content         string              `protobuf:"bytes,4,opt,name=content,proto3" json:"content,omitempty"`
+	Status          string              `protobuf:"bytes,5,opt,name=status,proto3" json:"status,omitempty"`
+	Author          *UserBrief          `protobuf:"bytes,6,opt,name=author,proto3" json:"author,omitempty"`
+	CanDelete       bool                `protobuf:"varint,7,opt,name=can_delete,json=canDelete,proto3" json:"can_delete,omitempty"`
+	CreatedAt       string              `protobuf:"bytes,8,opt,name=created_at,json=createdAt,proto3" json:"created_at,omitempty"`
+	DeletedAt       string              `protobuf:"bytes,9,opt,name=deleted_at,json=deletedAt,proto3" json:"deleted_at,omitempty"`
+	Children        []*ForumCommentNode `protobuf:"bytes,10,rep,name=children,proto3" json:"children,omitempty"`
+}
+
+func (m *ForumCommentNode) Reset()         { *m = ForumCommentNode{} }
+func (m *ForumCommentNode) String() string { return proto.CompactTextString(m) }
+func (*ForumCommentNode) ProtoMessage()    {}
+
+type ListForumPostsRequest 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"`
+	Sort        string `protobuf:"bytes,4,opt,name=sort,proto3" json:"sort,omitempty"`
+	Keyword     string `protobuf:"bytes,5,opt,name=keyword,proto3" json:"keyword,omitempty"`
+	Tag         string `protobuf:"bytes,6,opt,name=tag,proto3" json:"tag,omitempty"`
+}
+
+func (m *ListForumPostsRequest) Reset()         { *m = ListForumPostsRequest{} }
+func (m *ListForumPostsRequest) String() string { return proto.CompactTextString(m) }
+func (*ListForumPostsRequest) ProtoMessage()    {}
+
+type ListForumPostsResponse struct {
+	Items []*ForumPostBrief `protobuf:"bytes,1,rep,name=items,proto3" json:"items,omitempty"`
+	Page  *PageResponse     `protobuf:"bytes,2,opt,name=page,proto3" json:"page,omitempty"`
+}
+
+func (m *ListForumPostsResponse) Reset()         { *m = ListForumPostsResponse{} }
+func (m *ListForumPostsResponse) String() string { return proto.CompactTextString(m) }
+func (*ListForumPostsResponse) ProtoMessage()    {}
+
+type ListForumTagsRequest struct {
+	ActorUserId uint64 `protobuf:"varint,1,opt,name=actor_user_id,json=actorUserId,proto3" json:"actor_user_id,omitempty"`
+	Limit       int32  `protobuf:"varint,2,opt,name=limit,proto3" json:"limit,omitempty"`
+}
+
+func (m *ListForumTagsRequest) Reset()         { *m = ListForumTagsRequest{} }
+func (m *ListForumTagsRequest) String() string { return proto.CompactTextString(m) }
+func (*ListForumTagsRequest) ProtoMessage()    {}
+
+type ForumTagItem struct {
+	Tag       string `protobuf:"bytes,1,opt,name=tag,proto3" json:"tag,omitempty"`
+	PostCount int32  `protobuf:"varint,2,opt,name=post_count,json=postCount,proto3" json:"post_count,omitempty"`
+}
+
+func (m *ForumTagItem) Reset()         { *m = ForumTagItem{} }
+func (m *ForumTagItem) String() string { return proto.CompactTextString(m) }
+func (*ForumTagItem) ProtoMessage()    {}
+
+type ListForumTagsResponse struct {
+	Items []*ForumTagItem `protobuf:"bytes,1,rep,name=items,proto3" json:"items,omitempty"`
+}
+
+func (m *ListForumTagsResponse) Reset()         { *m = ListForumTagsResponse{} }
+func (m *ListForumTagsResponse) String() string { return proto.CompactTextString(m) }
+func (*ListForumTagsResponse) ProtoMessage()    {}
+
+type CreateForumPostRequest struct {
+	ActorUserId    uint64   `protobuf:"varint,1,opt,name=actor_user_id,json=actorUserId,proto3" json:"actor_user_id,omitempty"`
+	TaskClassId    uint64   `protobuf:"varint,2,opt,name=task_class_id,json=taskClassId,proto3" json:"task_class_id,omitempty"`
+	Title          string   `protobuf:"bytes,3,opt,name=title,proto3" json:"title,omitempty"`
+	Summary        string   `protobuf:"bytes,4,opt,name=summary,proto3" json:"summary,omitempty"`
+	Tags           []string `protobuf:"bytes,5,rep,name=tags,proto3" json:"tags,omitempty"`
+	IdempotencyKey string   `protobuf:"bytes,6,opt,name=idempotency_key,json=idempotencyKey,proto3" json:"idempotency_key,omitempty"`
+}
+
+func (m *CreateForumPostRequest) Reset()         { *m = CreateForumPostRequest{} }
+func (m *CreateForumPostRequest) String() string { return proto.CompactTextString(m) }
+func (*CreateForumPostRequest) ProtoMessage()    {}
+
+type CreateForumPostResponse struct {
+	Post *ForumPostBrief `protobuf:"bytes,1,opt,name=post,proto3" json:"post,omitempty"`
+}
+
+func (m *CreateForumPostResponse) Reset()         { *m = CreateForumPostResponse{} }
+func (m *CreateForumPostResponse) String() string { return proto.CompactTextString(m) }
+func (*CreateForumPostResponse) ProtoMessage()    {}
+
+type GetForumPostRequest struct {
+	ActorUserId uint64 `protobuf:"varint,1,opt,name=actor_user_id,json=actorUserId,proto3" json:"actor_user_id,omitempty"`
+	PostId      uint64 `protobuf:"varint,2,opt,name=post_id,json=postId,proto3" json:"post_id,omitempty"`
+}
+
+func (m *GetForumPostRequest) Reset()         { *m = GetForumPostRequest{} }
+func (m *GetForumPostRequest) String() string { return proto.CompactTextString(m) }
+func (*GetForumPostRequest) ProtoMessage()    {}
+
+type GetForumPostResponse struct {
+	Data *ForumPostDetail `protobuf:"bytes,1,opt,name=data,proto3" json:"data,omitempty"`
+}
+
+func (m *GetForumPostResponse) Reset()         { *m = GetForumPostResponse{} }
+func (m *GetForumPostResponse) String() string { return proto.CompactTextString(m) }
+func (*GetForumPostResponse) ProtoMessage()    {}
+
+type LikeForumPostRequest struct {
+	ActorUserId uint64 `protobuf:"varint,1,opt,name=actor_user_id,json=actorUserId,proto3" json:"actor_user_id,omitempty"`
+	PostId      uint64 `protobuf:"varint,2,opt,name=post_id,json=postId,proto3" json:"post_id,omitempty"`
+}
+
+func (m *LikeForumPostRequest) Reset()         { *m = LikeForumPostRequest{} }
+func (m *LikeForumPostRequest) String() string { return proto.CompactTextString(m) }
+func (*LikeForumPostRequest) ProtoMessage()    {}
+
+type LikeForumPostResponse struct {
+	Counters    *ForumPostCounters    `protobuf:"bytes,1,opt,name=counters,proto3" json:"counters,omitempty"`
+	ViewerState *ForumPostViewerState `protobuf:"bytes,2,opt,name=viewer_state,json=viewerState,proto3" json:"viewer_state,omitempty"`
+}
+
+func (m *LikeForumPostResponse) Reset()         { *m = LikeForumPostResponse{} }
+func (m *LikeForumPostResponse) String() string { return proto.CompactTextString(m) }
+func (*LikeForumPostResponse) ProtoMessage()    {}
+
+type UnlikeForumPostRequest struct {
+	ActorUserId uint64 `protobuf:"varint,1,opt,name=actor_user_id,json=actorUserId,proto3" json:"actor_user_id,omitempty"`
+	PostId      uint64 `protobuf:"varint,2,opt,name=post_id,json=postId,proto3" json:"post_id,omitempty"`
+}
+
+func (m *UnlikeForumPostRequest) Reset()         { *m = UnlikeForumPostRequest{} }
+func (m *UnlikeForumPostRequest) String() string { return proto.CompactTextString(m) }
+func (*UnlikeForumPostRequest) ProtoMessage()    {}
+
+type UnlikeForumPostResponse struct {
+	Counters    *ForumPostCounters    `protobuf:"bytes,1,opt,name=counters,proto3" json:"counters,omitempty"`
+	ViewerState *ForumPostViewerState `protobuf:"bytes,2,opt,name=viewer_state,json=viewerState,proto3" json:"viewer_state,omitempty"`
+}
+
+func (m *UnlikeForumPostResponse) Reset()         { *m = UnlikeForumPostResponse{} }
+func (m *UnlikeForumPostResponse) String() string { return proto.CompactTextString(m) }
+func (*UnlikeForumPostResponse) ProtoMessage()    {}
+
+type ListForumCommentsRequest struct {
+	ActorUserId uint64 `protobuf:"varint,1,opt,name=actor_user_id,json=actorUserId,proto3" json:"actor_user_id,omitempty"`
+	PostId      uint64 `protobuf:"varint,2,opt,name=post_id,json=postId,proto3" json:"post_id,omitempty"`
+	Page        int32  `protobuf:"varint,3,opt,name=page,proto3" json:"page,omitempty"`
+	PageSize    int32  `protobuf:"varint,4,opt,name=page_size,json=pageSize,proto3" json:"page_size,omitempty"`
+	Sort        string `protobuf:"bytes,5,opt,name=sort,proto3" json:"sort,omitempty"`
+}
+
+func (m *ListForumCommentsRequest) Reset()         { *m = ListForumCommentsRequest{} }
+func (m *ListForumCommentsRequest) String() string { return proto.CompactTextString(m) }
+func (*ListForumCommentsRequest) ProtoMessage()    {}
+
+type ListForumCommentsResponse struct {
+	Items []*ForumCommentNode `protobuf:"bytes,1,rep,name=items,proto3" json:"items,omitempty"`
+	Page  *PageResponse       `protobuf:"bytes,2,opt,name=page,proto3" json:"page,omitempty"`
+}
+
+func (m *ListForumCommentsResponse) Reset()         { *m = ListForumCommentsResponse{} }
+func (m *ListForumCommentsResponse) String() string { return proto.CompactTextString(m) }
+func (*ListForumCommentsResponse) ProtoMessage()    {}
+
+type CreateForumCommentRequest struct {
+	ActorUserId     uint64 `protobuf:"varint,1,opt,name=actor_user_id,json=actorUserId,proto3" json:"actor_user_id,omitempty"`
+	PostId          uint64 `protobuf:"varint,2,opt,name=post_id,json=postId,proto3" json:"post_id,omitempty"`
+	Content         string `protobuf:"bytes,3,opt,name=content,proto3" json:"content,omitempty"`
+	ParentCommentId uint64 `protobuf:"varint,4,opt,name=parent_comment_id,json=parentCommentId,proto3" json:"parent_comment_id,omitempty"`
+	IdempotencyKey  string `protobuf:"bytes,5,opt,name=idempotency_key,json=idempotencyKey,proto3" json:"idempotency_key,omitempty"`
+}
+
+func (m *CreateForumCommentRequest) Reset()         { *m = CreateForumCommentRequest{} }
+func (m *CreateForumCommentRequest) String() string { return proto.CompactTextString(m) }
+func (*CreateForumCommentRequest) ProtoMessage()    {}
+
+type CreateForumCommentResponse struct {
+	Comment *ForumCommentNode `protobuf:"bytes,1,opt,name=comment,proto3" json:"comment,omitempty"`
+}
+
+func (m *CreateForumCommentResponse) Reset()         { *m = CreateForumCommentResponse{} }
+func (m *CreateForumCommentResponse) String() string { return proto.CompactTextString(m) }
+func (*CreateForumCommentResponse) ProtoMessage()    {}
+
+type DeleteForumCommentRequest struct {
+	ActorUserId uint64 `protobuf:"varint,1,opt,name=actor_user_id,json=actorUserId,proto3" json:"actor_user_id,omitempty"`
+	CommentId   uint64 `protobuf:"varint,2,opt,name=comment_id,json=commentId,proto3" json:"comment_id,omitempty"`
+}
+
+func (m *DeleteForumCommentRequest) Reset()         { *m = DeleteForumCommentRequest{} }
+func (m *DeleteForumCommentRequest) String() string { return proto.CompactTextString(m) }
+func (*DeleteForumCommentRequest) ProtoMessage()    {}
+
+type DeleteForumCommentResponse struct {
+	CommentId uint64 `protobuf:"varint,1,opt,name=comment_id,json=commentId,proto3" json:"comment_id,omitempty"`
+	Status    string `protobuf:"bytes,2,opt,name=status,proto3" json:"status,omitempty"`
+}
+
+func (m *DeleteForumCommentResponse) Reset()         { *m = DeleteForumCommentResponse{} }
+func (m *DeleteForumCommentResponse) String() string { return proto.CompactTextString(m) }
+func (*DeleteForumCommentResponse) ProtoMessage()    {}
+
+type ImportForumPostRequest struct {
+	ActorUserId    uint64 `protobuf:"varint,1,opt,name=actor_user_id,json=actorUserId,proto3" json:"actor_user_id,omitempty"`
+	PostId         uint64 `protobuf:"varint,2,opt,name=post_id,json=postId,proto3" json:"post_id,omitempty"`
+	TargetTitle    string `protobuf:"bytes,3,opt,name=target_title,json=targetTitle,proto3" json:"target_title,omitempty"`
+	IdempotencyKey string `protobuf:"bytes,4,opt,name=idempotency_key,json=idempotencyKey,proto3" json:"idempotency_key,omitempty"`
+}
+
+func (m *ImportForumPostRequest) Reset()         { *m = ImportForumPostRequest{} }
+func (m *ImportForumPostRequest) String() string { return proto.CompactTextString(m) }
+func (*ImportForumPostRequest) ProtoMessage()    {}
+
+type ImportForumPostResponse struct {
+	ImportId       uint64 `protobuf:"varint,1,opt,name=import_id,json=importId,proto3" json:"import_id,omitempty"`
+	PostId         uint64 `protobuf:"varint,2,opt,name=post_id,json=postId,proto3" json:"post_id,omitempty"`
+	NewTaskClassId uint64 `protobuf:"varint,3,opt,name=new_task_class_id,json=newTaskClassId,proto3" json:"new_task_class_id,omitempty"`
+	TaskClassTitle string `protobuf:"bytes,4,opt,name=task_class_title,json=taskClassTitle,proto3" json:"task_class_title,omitempty"`
+	ImportCount    int64  `protobuf:"varint,5,opt,name=import_count,json=importCount,proto3" json:"import_count,omitempty"`
+	CreatedAt      string `protobuf:"bytes,6,opt,name=created_at,json=createdAt,proto3" json:"created_at,omitempty"`
+}
+
+func (m *ImportForumPostResponse) Reset()         { *m = ImportForumPostResponse{} }
+func (m *ImportForumPostResponse) String() string { return proto.CompactTextString(m) }
+func (*ImportForumPostResponse) ProtoMessage()    {}

backend/services/taskclassforum/rpc/pb/taskclassforum_grpc.pb.go

@@ -0,0 +1,213 @@
+package pb
+
+import (
+	context "context"
+
+	grpc "google.golang.org/grpc"
+	codes "google.golang.org/grpc/codes"
+	status "google.golang.org/grpc/status"
+)
+
+const (
+	TaskClassForumService_ListPosts_FullMethodName     = "/smartflow.taskclassforum.TaskClassForumService/ListPosts"
+	TaskClassForumService_ListTags_FullMethodName      = "/smartflow.taskclassforum.TaskClassForumService/ListTags"
+	TaskClassForumService_CreatePost_FullMethodName    = "/smartflow.taskclassforum.TaskClassForumService/CreatePost"
+	TaskClassForumService_GetPost_FullMethodName       = "/smartflow.taskclassforum.TaskClassForumService/GetPost"
+	TaskClassForumService_LikePost_FullMethodName      = "/smartflow.taskclassforum.TaskClassForumService/LikePost"
+	TaskClassForumService_UnlikePost_FullMethodName    = "/smartflow.taskclassforum.TaskClassForumService/UnlikePost"
+	TaskClassForumService_ListComments_FullMethodName  = "/smartflow.taskclassforum.TaskClassForumService/ListComments"
+	TaskClassForumService_CreateComment_FullMethodName = "/smartflow.taskclassforum.TaskClassForumService/CreateComment"
+	TaskClassForumService_DeleteComment_FullMethodName = "/smartflow.taskclassforum.TaskClassForumService/DeleteComment"
+	TaskClassForumService_ImportPost_FullMethodName    = "/smartflow.taskclassforum.TaskClassForumService/ImportPost"
+)
+
+type TaskClassForumServiceClient interface {
+	ListPosts(ctx context.Context, in *ListForumPostsRequest, opts ...grpc.CallOption) (*ListForumPostsResponse, error)
+	ListTags(ctx context.Context, in *ListForumTagsRequest, opts ...grpc.CallOption) (*ListForumTagsResponse, error)
+	CreatePost(ctx context.Context, in *CreateForumPostRequest, opts ...grpc.CallOption) (*CreateForumPostResponse, error)
+	GetPost(ctx context.Context, in *GetForumPostRequest, opts ...grpc.CallOption) (*GetForumPostResponse, error)
+	LikePost(ctx context.Context, in *LikeForumPostRequest, opts ...grpc.CallOption) (*LikeForumPostResponse, error)
+	UnlikePost(ctx context.Context, in *UnlikeForumPostRequest, opts ...grpc.CallOption) (*UnlikeForumPostResponse, error)
+	ListComments(ctx context.Context, in *ListForumCommentsRequest, opts ...grpc.CallOption) (*ListForumCommentsResponse, error)
+	CreateComment(ctx context.Context, in *CreateForumCommentRequest, opts ...grpc.CallOption) (*CreateForumCommentResponse, error)
+	DeleteComment(ctx context.Context, in *DeleteForumCommentRequest, opts ...grpc.CallOption) (*DeleteForumCommentResponse, error)
+	ImportPost(ctx context.Context, in *ImportForumPostRequest, opts ...grpc.CallOption) (*ImportForumPostResponse, error)
+}
+
+type taskClassForumServiceClient struct {
+	cc grpc.ClientConnInterface
+}
+
+func NewTaskClassForumServiceClient(cc grpc.ClientConnInterface) TaskClassForumServiceClient {
+	return &taskClassForumServiceClient{cc}
+}
+
+func (c *taskClassForumServiceClient) ListPosts(ctx context.Context, in *ListForumPostsRequest, opts ...grpc.CallOption) (*ListForumPostsResponse, error) {
+	return invokeTaskClassForum[ListForumPostsResponse](ctx, c.cc, TaskClassForumService_ListPosts_FullMethodName, in, opts...)
+}
+
+func (c *taskClassForumServiceClient) ListTags(ctx context.Context, in *ListForumTagsRequest, opts ...grpc.CallOption) (*ListForumTagsResponse, error) {
+	return invokeTaskClassForum[ListForumTagsResponse](ctx, c.cc, TaskClassForumService_ListTags_FullMethodName, in, opts...)
+}
+
+func (c *taskClassForumServiceClient) CreatePost(ctx context.Context, in *CreateForumPostRequest, opts ...grpc.CallOption) (*CreateForumPostResponse, error) {
+	return invokeTaskClassForum[CreateForumPostResponse](ctx, c.cc, TaskClassForumService_CreatePost_FullMethodName, in, opts...)
+}
+
+func (c *taskClassForumServiceClient) GetPost(ctx context.Context, in *GetForumPostRequest, opts ...grpc.CallOption) (*GetForumPostResponse, error) {
+	return invokeTaskClassForum[GetForumPostResponse](ctx, c.cc, TaskClassForumService_GetPost_FullMethodName, in, opts...)
+}
+
+func (c *taskClassForumServiceClient) LikePost(ctx context.Context, in *LikeForumPostRequest, opts ...grpc.CallOption) (*LikeForumPostResponse, error) {
+	return invokeTaskClassForum[LikeForumPostResponse](ctx, c.cc, TaskClassForumService_LikePost_FullMethodName, in, opts...)
+}
+
+func (c *taskClassForumServiceClient) UnlikePost(ctx context.Context, in *UnlikeForumPostRequest, opts ...grpc.CallOption) (*UnlikeForumPostResponse, error) {
+	return invokeTaskClassForum[UnlikeForumPostResponse](ctx, c.cc, TaskClassForumService_UnlikePost_FullMethodName, in, opts...)
+}
+
+func (c *taskClassForumServiceClient) ListComments(ctx context.Context, in *ListForumCommentsRequest, opts ...grpc.CallOption) (*ListForumCommentsResponse, error) {
+	return invokeTaskClassForum[ListForumCommentsResponse](ctx, c.cc, TaskClassForumService_ListComments_FullMethodName, in, opts...)
+}
+
+func (c *taskClassForumServiceClient) CreateComment(ctx context.Context, in *CreateForumCommentRequest, opts ...grpc.CallOption) (*CreateForumCommentResponse, error) {
+	return invokeTaskClassForum[CreateForumCommentResponse](ctx, c.cc, TaskClassForumService_CreateComment_FullMethodName, in, opts...)
+}
+
+func (c *taskClassForumServiceClient) DeleteComment(ctx context.Context, in *DeleteForumCommentRequest, opts ...grpc.CallOption) (*DeleteForumCommentResponse, error) {
+	return invokeTaskClassForum[DeleteForumCommentResponse](ctx, c.cc, TaskClassForumService_DeleteComment_FullMethodName, in, opts...)
+}
+
+func (c *taskClassForumServiceClient) ImportPost(ctx context.Context, in *ImportForumPostRequest, opts ...grpc.CallOption) (*ImportForumPostResponse, error) {
+	return invokeTaskClassForum[ImportForumPostResponse](ctx, c.cc, TaskClassForumService_ImportPost_FullMethodName, in, opts...)
+}
+
+func invokeTaskClassForum[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 TaskClassForumServiceServer interface {
+	ListPosts(context.Context, *ListForumPostsRequest) (*ListForumPostsResponse, error)
+	ListTags(context.Context, *ListForumTagsRequest) (*ListForumTagsResponse, error)
+	CreatePost(context.Context, *CreateForumPostRequest) (*CreateForumPostResponse, error)
+	GetPost(context.Context, *GetForumPostRequest) (*GetForumPostResponse, error)
+	LikePost(context.Context, *LikeForumPostRequest) (*LikeForumPostResponse, error)
+	UnlikePost(context.Context, *UnlikeForumPostRequest) (*UnlikeForumPostResponse, error)
+	ListComments(context.Context, *ListForumCommentsRequest) (*ListForumCommentsResponse, error)
+	CreateComment(context.Context, *CreateForumCommentRequest) (*CreateForumCommentResponse, error)
+	DeleteComment(context.Context, *DeleteForumCommentRequest) (*DeleteForumCommentResponse, error)
+	ImportPost(context.Context, *ImportForumPostRequest) (*ImportForumPostResponse, error)
+}
+
+type UnimplementedTaskClassForumServiceServer struct{}
+
+func (UnimplementedTaskClassForumServiceServer) ListPosts(context.Context, *ListForumPostsRequest) (*ListForumPostsResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method ListPosts not implemented")
+}
+
+func (UnimplementedTaskClassForumServiceServer) ListTags(context.Context, *ListForumTagsRequest) (*ListForumTagsResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method ListTags not implemented")
+}
+
+func (UnimplementedTaskClassForumServiceServer) CreatePost(context.Context, *CreateForumPostRequest) (*CreateForumPostResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method CreatePost not implemented")
+}
+
+func (UnimplementedTaskClassForumServiceServer) GetPost(context.Context, *GetForumPostRequest) (*GetForumPostResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method GetPost not implemented")
+}
+
+func (UnimplementedTaskClassForumServiceServer) LikePost(context.Context, *LikeForumPostRequest) (*LikeForumPostResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method LikePost not implemented")
+}
+
+func (UnimplementedTaskClassForumServiceServer) UnlikePost(context.Context, *UnlikeForumPostRequest) (*UnlikeForumPostResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method UnlikePost not implemented")
+}
+
+func (UnimplementedTaskClassForumServiceServer) ListComments(context.Context, *ListForumCommentsRequest) (*ListForumCommentsResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method ListComments not implemented")
+}
+
+func (UnimplementedTaskClassForumServiceServer) CreateComment(context.Context, *CreateForumCommentRequest) (*CreateForumCommentResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method CreateComment not implemented")
+}
+
+func (UnimplementedTaskClassForumServiceServer) DeleteComment(context.Context, *DeleteForumCommentRequest) (*DeleteForumCommentResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method DeleteComment not implemented")
+}
+
+func (UnimplementedTaskClassForumServiceServer) ImportPost(context.Context, *ImportForumPostRequest) (*ImportForumPostResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method ImportPost not implemented")
+}
+
+func RegisterTaskClassForumServiceServer(s grpc.ServiceRegistrar, srv TaskClassForumServiceServer) {
+	s.RegisterService(&TaskClassForumService_ServiceDesc, srv)
+}
+
+func taskClassForumUnaryHandler[Req any](methodName string, fullMethod string, invoke func(TaskClassForumServiceServer, 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.(TaskClassForumServiceServer), ctx, in)
+			}
+			info := &grpc.UnaryServerInfo{
+				Server:     srv,
+				FullMethod: fullMethod,
+			}
+			handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+				return invoke(srv.(TaskClassForumServiceServer), ctx, req.(*Req))
+			}
+			return interceptor(ctx, in, info, handler)
+		},
+	}
+}
+
+var TaskClassForumService_ServiceDesc = grpc.ServiceDesc{
+	ServiceName: "smartflow.taskclassforum.TaskClassForumService",
+	HandlerType: (*TaskClassForumServiceServer)(nil),
+	Methods: []grpc.MethodDesc{
+		taskClassForumUnaryHandler[ListForumPostsRequest]("ListPosts", TaskClassForumService_ListPosts_FullMethodName, func(s TaskClassForumServiceServer, ctx context.Context, req *ListForumPostsRequest) (interface{}, error) {
+			return s.ListPosts(ctx, req)
+		}),
+		taskClassForumUnaryHandler[ListForumTagsRequest]("ListTags", TaskClassForumService_ListTags_FullMethodName, func(s TaskClassForumServiceServer, ctx context.Context, req *ListForumTagsRequest) (interface{}, error) {
+			return s.ListTags(ctx, req)
+		}),
+		taskClassForumUnaryHandler[CreateForumPostRequest]("CreatePost", TaskClassForumService_CreatePost_FullMethodName, func(s TaskClassForumServiceServer, ctx context.Context, req *CreateForumPostRequest) (interface{}, error) {
+			return s.CreatePost(ctx, req)
+		}),
+		taskClassForumUnaryHandler[GetForumPostRequest]("GetPost", TaskClassForumService_GetPost_FullMethodName, func(s TaskClassForumServiceServer, ctx context.Context, req *GetForumPostRequest) (interface{}, error) {
+			return s.GetPost(ctx, req)
+		}),
+		taskClassForumUnaryHandler[LikeForumPostRequest]("LikePost", TaskClassForumService_LikePost_FullMethodName, func(s TaskClassForumServiceServer, ctx context.Context, req *LikeForumPostRequest) (interface{}, error) {
+			return s.LikePost(ctx, req)
+		}),
+		taskClassForumUnaryHandler[UnlikeForumPostRequest]("UnlikePost", TaskClassForumService_UnlikePost_FullMethodName, func(s TaskClassForumServiceServer, ctx context.Context, req *UnlikeForumPostRequest) (interface{}, error) {
+			return s.UnlikePost(ctx, req)
+		}),
+		taskClassForumUnaryHandler[ListForumCommentsRequest]("ListComments", TaskClassForumService_ListComments_FullMethodName, func(s TaskClassForumServiceServer, ctx context.Context, req *ListForumCommentsRequest) (interface{}, error) {
+			return s.ListComments(ctx, req)
+		}),
+		taskClassForumUnaryHandler[CreateForumCommentRequest]("CreateComment", TaskClassForumService_CreateComment_FullMethodName, func(s TaskClassForumServiceServer, ctx context.Context, req *CreateForumCommentRequest) (interface{}, error) {
+			return s.CreateComment(ctx, req)
+		}),
+		taskClassForumUnaryHandler[DeleteForumCommentRequest]("DeleteComment", TaskClassForumService_DeleteComment_FullMethodName, func(s TaskClassForumServiceServer, ctx context.Context, req *DeleteForumCommentRequest) (interface{}, error) {
+			return s.DeleteComment(ctx, req)
+		}),
+		taskClassForumUnaryHandler[ImportForumPostRequest]("ImportPost", TaskClassForumService_ImportPost_FullMethodName, func(s TaskClassForumServiceServer, ctx context.Context, req *ImportForumPostRequest) (interface{}, error) {
+			return s.ImportPost(ctx, req)
+		}),
+	},
+	Streams:  []grpc.StreamDesc{},
+	Metadata: "taskclassforum.proto",
+}

backend/services/taskclassforum/rpc/server.go

@@ -0,0 +1,73 @@
+package rpc
+
+import (
+	"errors"
+	"log"
+	"strings"
+	"time"
+
+	"github.com/LoveLosita/smartflow/backend/services/taskclassforum/rpc/pb"
+	forumsv "github.com/LoveLosita/smartflow/backend/services/taskclassforum/sv"
+	"github.com/zeromicro/go-zero/core/service"
+	"github.com/zeromicro/go-zero/zrpc"
+	"google.golang.org/grpc"
+)
+
+const (
+	defaultListenOn = "0.0.0.0:9090"
+	defaultTimeout  = 2 * time.Second
+)
+
+type ServerOptions struct {
+	ListenOn string
+	Timeout  time.Duration
+	Service  *forumsv.Service
+}
+
+// Start 启动计划广场 zrpc 服务。
+//
+// 职责边界：
+// 1. 只负责装配 go-zero zrpc server 和注册 protobuf service；
+// 2. 不创建 DB 连接，也不装配 TaskClass legacy adapter，这些依赖由 cmd 入口注入；
+// 3. 启动后阻塞当前进程，保持后续“一服务一进程”的迁移方向。
+func Start(opts ServerOptions) {
+	server, listenOn, err := NewServer(opts)
+	if err != nil {
+		log.Fatalf("failed to build taskclassforum zrpc server: %v", err)
+	}
+	defer server.Stop()
+
+	log.Printf("taskclassforum zrpc service starting on %s", listenOn)
+	server.Start()
+}
+
+// NewServer 负责创建计划广场 RPC server，供 cmd 启动和测试复用。
+func NewServer(opts ServerOptions) (*zrpc.RpcServer, string, error) {
+	if opts.Service == nil {
+		return nil, "", errors.New("taskclassforum 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: "taskclassforum.rpc",
+			Mode: service.DevMode,
+		},
+		ListenOn: listenOn,
+		Timeout:  int64(timeout / time.Millisecond),
+	}, func(grpcServer *grpc.Server) {
+		pb.RegisterTaskClassForumServiceServer(grpcServer, NewHandler(opts.Service))
+	})
+	if err != nil {
+		return nil, "", err
+	}
+	return server, listenOn, nil
+}

backend/services/taskclassforum/rpc/taskclassforum.proto

@@ -0,0 +1,222 @@
+syntax = "proto3";
+
+package smartflow.taskclassforum;
+
+option go_package = "github.com/LoveLosita/smartflow/backend/services/taskclassforum/rpc/pb";
+
+service TaskClassForumService {
+  rpc ListPosts(ListForumPostsRequest) returns (ListForumPostsResponse);
+  rpc ListTags(ListForumTagsRequest) returns (ListForumTagsResponse);
+  rpc CreatePost(CreateForumPostRequest) returns (CreateForumPostResponse);
+  rpc GetPost(GetForumPostRequest) returns (GetForumPostResponse);
+  rpc LikePost(LikeForumPostRequest) returns (LikeForumPostResponse);
+  rpc UnlikePost(UnlikeForumPostRequest) returns (UnlikeForumPostResponse);
+  rpc ListComments(ListForumCommentsRequest) returns (ListForumCommentsResponse);
+  rpc CreateComment(CreateForumCommentRequest) returns (CreateForumCommentResponse);
+  rpc DeleteComment(DeleteForumCommentRequest) returns (DeleteForumCommentResponse);
+  rpc ImportPost(ImportForumPostRequest) returns (ImportForumPostResponse);
+}
+
+message PageRequest {
+  int32 page = 1;
+  int32 page_size = 2;
+}
+
+message PageResponse {
+  int32 page = 1;
+  int32 page_size = 2;
+  int32 total = 3;
+  bool has_more = 4;
+}
+
+message UserBrief {
+  uint64 user_id = 1;
+  string nickname = 2;
+  string avatar_url = 3;
+}
+
+message TemplateSummary {
+  int32 task_count = 1;
+  string mode = 2;
+  string start_date = 3;
+  string end_date = 4;
+  repeated string strategy_labels = 5;
+}
+
+message ForumPostCounters {
+  int64 like_count = 1;
+  int64 comment_count = 2;
+  int64 import_count = 3;
+}
+
+message ForumPostViewerState {
+  bool liked = 1;
+  bool imported_once = 2;
+}
+
+message ForumPostBrief {
+  uint64 post_id = 1;
+  string title = 2;
+  string summary = 3;
+  repeated string tags = 4;
+  UserBrief author = 5;
+  TemplateSummary template_summary = 6;
+  ForumPostCounters counters = 7;
+  ForumPostViewerState viewer_state = 8;
+  string status = 9;
+  string created_at = 10;
+}
+
+message TemplateItemPreview {
+  uint64 item_id = 1;
+  int32 order = 2;
+  string content = 3;
+}
+
+message TemplateDetail {
+  string mode = 1;
+  string start_date = 2;
+  string end_date = 3;
+  repeated string strategy_labels = 4;
+  int32 task_count = 5;
+  repeated TemplateItemPreview items_preview = 6;
+}
+
+message ForumPostDetail {
+  ForumPostBrief post = 1;
+  TemplateDetail template = 2;
+}
+
+message ForumCommentNode {
+  uint64 comment_id = 1;
+  uint64 post_id = 2;
+  uint64 parent_comment_id = 3;
+  string content = 4;
+  string status = 5;
+  UserBrief author = 6;
+  bool can_delete = 7;
+  string created_at = 8;
+  string deleted_at = 9;
+  repeated ForumCommentNode children = 10;
+}
+
+message ListForumPostsRequest {
+  uint64 actor_user_id = 1;
+  int32 page = 2;
+  int32 page_size = 3;
+  string sort = 4;
+  string keyword = 5;
+  string tag = 6;
+}
+
+message ListForumPostsResponse {
+  repeated ForumPostBrief items = 1;
+  PageResponse page = 2;
+}
+
+message ListForumTagsRequest {
+  uint64 actor_user_id = 1;
+  int32 limit = 2;
+}
+
+message ForumTagItem {
+  string tag = 1;
+  int32 post_count = 2;
+}
+
+message ListForumTagsResponse {
+  repeated ForumTagItem items = 1;
+}
+
+message CreateForumPostRequest {
+  uint64 actor_user_id = 1;
+  uint64 task_class_id = 2;
+  string title = 3;
+  string summary = 4;
+  repeated string tags = 5;
+  string idempotency_key = 6;
+}
+
+message CreateForumPostResponse {
+  ForumPostBrief post = 1;
+}
+
+message GetForumPostRequest {
+  uint64 actor_user_id = 1;
+  uint64 post_id = 2;
+}
+
+message GetForumPostResponse {
+  ForumPostDetail data = 1;
+}
+
+message LikeForumPostRequest {
+  uint64 actor_user_id = 1;
+  uint64 post_id = 2;
+}
+
+message LikeForumPostResponse {
+  ForumPostCounters counters = 1;
+  ForumPostViewerState viewer_state = 2;
+}
+
+message UnlikeForumPostRequest {
+  uint64 actor_user_id = 1;
+  uint64 post_id = 2;
+}
+
+message UnlikeForumPostResponse {
+  ForumPostCounters counters = 1;
+  ForumPostViewerState viewer_state = 2;
+}
+
+message ListForumCommentsRequest {
+  uint64 actor_user_id = 1;
+  uint64 post_id = 2;
+  int32 page = 3;
+  int32 page_size = 4;
+  string sort = 5;
+}
+
+message ListForumCommentsResponse {
+  repeated ForumCommentNode items = 1;
+  PageResponse page = 2;
+}
+
+message CreateForumCommentRequest {
+  uint64 actor_user_id = 1;
+  uint64 post_id = 2;
+  string content = 3;
+  uint64 parent_comment_id = 4;
+  string idempotency_key = 5;
+}
+
+message CreateForumCommentResponse {
+  ForumCommentNode comment = 1;
+}
+
+message DeleteForumCommentRequest {
+  uint64 actor_user_id = 1;
+  uint64 comment_id = 2;
+}
+
+message DeleteForumCommentResponse {
+  uint64 comment_id = 1;
+  string status = 2;
+}
+
+message ImportForumPostRequest {
+  uint64 actor_user_id = 1;
+  uint64 post_id = 2;
+  string target_title = 3;
+  string idempotency_key = 4;
+}
+
+message ImportForumPostResponse {
+  uint64 import_id = 1;
+  uint64 post_id = 2;
+  uint64 new_task_class_id = 3;
+  string task_class_title = 4;
+  int64 import_count = 5;
+  string created_at = 6;
+}

backend/services/taskclassforum/sv/comment.go

@@ -0,0 +1,284 @@
+package sv
+
+import (
+	"context"
+	"log"
+	"strings"
+	"time"
+
+	"github.com/LoveLosita/smartflow/backend/shared/respond"
+	"github.com/LoveLosita/smartflow/backend/services/taskclassforum/commenttree"
+	forumdao "github.com/LoveLosita/smartflow/backend/services/taskclassforum/dao"
+	forummodel "github.com/LoveLosita/smartflow/backend/services/taskclassforum/model"
+	forumcontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/taskclassforum"
+)
+
+// ListComments 查询评论树。
+//
+// 职责边界：
+// 1. P0 按根评论分页，避免一次把超大评论区全部暴露给前端；
+// 2. 数据库存储仍是扁平 parent_comment_id，树结构由 commenttree 包组装；
+// 3. 采用 cache-aside 缓存去个性化评论树，返回前再补当前用户的删除权限。
+func (s *Service) ListComments(ctx context.Context, actorUserID uint64, postID uint64, page int, pageSize int, sortBy string) ([]forumcontracts.ForumCommentNode, forumcontracts.PageResult, error) {
+	if err := s.Ready(); err != nil {
+		return nil, forumcontracts.PageResult{}, err
+	}
+	if postID == 0 {
+		return nil, forumcontracts.PageResult{}, respond.MissingParam
+	}
+	page, pageSize = normalizePage(page, pageSize)
+	sortBy = normalizeCommentSort(sortBy)
+	if _, err := s.forumDAO.FindPublishedPost(ctx, postID); err != nil {
+		return nil, forumcontracts.PageResult{}, normalizeRecordNotFound(err, respond.UserTaskClassNotFound)
+	}
+
+	if cachedItems, cachedPage, hit := s.getCommentTreeCacheBestEffort(ctx, postID, page, pageSize, sortBy); hit {
+		return personalizeCommentNodesForActor(cachedItems, actorUserID), cachedPage, nil
+	}
+
+	total, err := s.forumDAO.CountRootComments(ctx, postID)
+	if err != nil {
+		return nil, forumcontracts.PageResult{}, err
+	}
+	roots, err := s.forumDAO.ListRootComments(ctx, postID, page, pageSize, sortBy)
+	if err != nil {
+		return nil, forumcontracts.PageResult{}, err
+	}
+	resultPage := pageResult(page, pageSize, total)
+	if len(roots) == 0 {
+		emptyItems := []forumcontracts.ForumCommentNode{}
+		s.setCommentTreeCacheBestEffort(ctx, postID, page, pageSize, sortBy, emptyItems, resultPage)
+		return emptyItems, resultPage, nil
+	}
+	allComments, err := s.forumDAO.ListCommentsByPostID(ctx, postID)
+	if err != nil {
+		return nil, forumcontracts.PageResult{}, err
+	}
+	sharedNodes := commenttree.BuildForumCommentTree(filterCommentsForRoots(allComments, roots), 0)
+	s.setCommentTreeCacheBestEffort(ctx, postID, page, pageSize, sortBy, sharedNodes, resultPage)
+	return personalizeCommentNodesForActor(sharedNodes, actorUserID), resultPage, nil
+}
+
+// CreateComment 创建帖子评论或多层回复。
+func (s *Service) CreateComment(ctx context.Context, req forumcontracts.CreateForumCommentRequest) (*forumcontracts.ForumCommentNode, error) {
+	if err := s.Ready(); err != nil {
+		return nil, err
+	}
+	if req.ActorUserID == 0 || req.PostID == 0 || strings.TrimSpace(req.Content) == "" {
+		return nil, respond.MissingParam
+	}
+	if err := validateRuneMax(req.Content, maxCommentLen); err != nil {
+		return nil, err
+	}
+	idempotencyKey := strings.TrimSpace(req.IdempotencyKey)
+	if idempotencyKey != "" {
+		existing, err := s.forumDAO.FindCommentByIdempotencyKey(ctx, req.ActorUserID, idempotencyKey)
+		if err != nil {
+			return nil, err
+		}
+		if existing != nil {
+			return commentModelToNode(*existing, req.ActorUserID), nil
+		}
+	}
+
+	var created forummodel.ForumComment
+	if err := s.forumDAO.Transaction(ctx, func(txDAO *forumdao.ForumDAO) error {
+		if _, err := txDAO.LockPublishedPost(ctx, req.PostID); err != nil {
+			return normalizeRecordNotFound(err, respond.UserTaskClassNotFound)
+		}
+		if req.ParentCommentID != nil {
+			parent, err := txDAO.FindCommentByID(ctx, *req.ParentCommentID)
+			if err != nil {
+				return normalizeRecordNotFound(err, respond.MissingParam)
+			}
+			if parent.PostID != req.PostID {
+				return respond.MissingParam
+			}
+		}
+		created = forummodel.ForumComment{
+			PostID:          req.PostID,
+			ParentCommentID: req.ParentCommentID,
+			UserID:          req.ActorUserID,
+			Content:         strings.TrimSpace(req.Content),
+			Status:          forummodel.ForumCommentStatusVisible,
+			IdempotencyKey:  stringPtrFromNonEmpty(idempotencyKey),
+		}
+		if err := txDAO.CreateComment(ctx, &created); err != nil {
+			return err
+		}
+		return txDAO.AddPostCounter(ctx, req.PostID, "comment_count", 1)
+	}); err != nil {
+		return nil, err
+	}
+	s.bumpCommentTreeVersionBestEffort(req.PostID)
+	return commentModelToNode(created, req.ActorUserID), nil
+}
+
+// DeleteComment 软删除当前用户自己的评论。
+func (s *Service) DeleteComment(ctx context.Context, actorUserID uint64, commentID uint64) (*forumcontracts.DeleteForumCommentResult, error) {
+	if err := s.Ready(); err != nil {
+		return nil, err
+	}
+	if actorUserID == 0 || commentID == 0 {
+		return nil, respond.MissingParam
+	}
+
+	var deletedAt *string
+	var changedPostID uint64
+	status := forummodel.ForumCommentStatusDeleted
+	if err := s.forumDAO.Transaction(ctx, func(txDAO *forumdao.ForumDAO) error {
+		comment, err := txDAO.LockCommentByID(ctx, commentID)
+		if err != nil {
+			return normalizeRecordNotFound(err, respond.MissingParam)
+		}
+		if comment.UserID != actorUserID {
+			return respond.ErrUnauthorized
+		}
+		if comment.Status == forummodel.ForumCommentStatusDeleted {
+			deletedAt = formatTimePtr(comment.DeletedAt)
+			return nil
+		}
+		now := time.Now()
+		if err := txDAO.SoftDeleteComment(ctx, commentID, now); err != nil {
+			return err
+		}
+		if err := txDAO.AddPostCounter(ctx, comment.PostID, "comment_count", -1); err != nil {
+			return err
+		}
+		changedPostID = comment.PostID
+		deletedAt = formatTimePtr(&now)
+		return nil
+	}); err != nil {
+		return nil, err
+	}
+	if changedPostID != 0 {
+		s.bumpCommentTreeVersionBestEffort(changedPostID)
+	}
+	return &forumcontracts.DeleteForumCommentResult{
+		CommentID: commentID,
+		Status:    status,
+		Content:   "",
+		DeletedAt: deletedAt,
+	}, nil
+}
+
+func commentModelToNode(comment forummodel.ForumComment, actorUserID uint64) *forumcontracts.ForumCommentNode {
+	content := comment.Content
+	if comment.Status == forummodel.ForumCommentStatusDeleted {
+		content = "该评论已删除"
+	}
+	return &forumcontracts.ForumCommentNode{
+		CommentID:       comment.ID,
+		PostID:          comment.PostID,
+		ParentCommentID: comment.ParentCommentID,
+		Content:         content,
+		Status:          comment.Status,
+		Author:          userBrief(comment.UserID),
+		CanDelete:       comment.Status == forummodel.ForumCommentStatusVisible && comment.UserID == actorUserID,
+		CreatedAt:       formatTime(comment.CreatedAt),
+		DeletedAt:       formatTimePtr(comment.DeletedAt),
+		Children:        []forumcontracts.ForumCommentNode{},
+	}
+}
+
+func filterCommentsForRoots(allComments []forummodel.ForumComment, roots []forummodel.ForumComment) []forummodel.ForumComment {
+	filtered := make([]forummodel.ForumComment, 0, len(allComments))
+	included := make(map[uint64]struct{}, len(allComments))
+	for _, root := range roots {
+		filtered = append(filtered, root)
+		included[root.ID] = struct{}{}
+	}
+	candidateSet := make(map[uint64]struct{}, len(allComments))
+	for _, root := range roots {
+		collectDescendantCommentIDs(root.ID, allComments, candidateSet)
+	}
+	for _, comment := range allComments {
+		if _, ok := included[comment.ID]; ok {
+			continue
+		}
+		if _, ok := candidateSet[comment.ID]; ok {
+			filtered = append(filtered, comment)
+			included[comment.ID] = struct{}{}
+		}
+	}
+	return filtered
+}
+
+func collectDescendantCommentIDs(parentID uint64, comments []forummodel.ForumComment, result map[uint64]struct{}) {
+	for _, comment := range comments {
+		if comment.ParentCommentID == nil || *comment.ParentCommentID != parentID {
+			continue
+		}
+		if _, exists := result[comment.ID]; exists {
+			continue
+		}
+		result[comment.ID] = struct{}{}
+		collectDescendantCommentIDs(comment.ID, comments, result)
+	}
+}
+
+func normalizeCommentSort(sortBy string) string {
+	if strings.TrimSpace(sortBy) == "latest" {
+		return "latest"
+	}
+	return "oldest"
+}
+
+func (s *Service) getCommentTreeCacheBestEffort(ctx context.Context, postID uint64, page int, pageSize int, sortBy string) ([]forumcontracts.ForumCommentNode, forumcontracts.PageResult, bool) {
+	if s == nil || s.commentTreeCache == nil {
+		return nil, forumcontracts.PageResult{}, false
+	}
+	items, resultPage, hit, err := s.commentTreeCache.GetCommentTree(ctx, postID, page, pageSize, sortBy)
+	if err != nil {
+		log.Printf("评论树缓存读取失败，已降级回源 DB post_id=%d page=%d page_size=%d sort=%s err=%v", postID, page, pageSize, sortBy, err)
+		return nil, forumcontracts.PageResult{}, false
+	}
+	return items, resultPage, hit
+}
+
+func (s *Service) setCommentTreeCacheBestEffort(ctx context.Context, postID uint64, page int, pageSize int, sortBy string, items []forumcontracts.ForumCommentNode, resultPage forumcontracts.PageResult) {
+	if s == nil || s.commentTreeCache == nil {
+		return
+	}
+	if err := s.commentTreeCache.SetCommentTree(ctx, postID, page, pageSize, sortBy, items, resultPage); err != nil {
+		log.Printf("评论树缓存写入失败，已保持 DB 结果返回 post_id=%d page=%d page_size=%d sort=%s err=%v", postID, page, pageSize, sortBy, err)
+	}
+}
+
+func (s *Service) bumpCommentTreeVersionBestEffort(postID uint64) {
+	if s == nil || s.commentTreeCache == nil || postID == 0 {
+		return
+	}
+
+	// 1. 写库事务已经成功，缓存失效不应再反向影响评论发布/删除结果。
+	// 2. 使用独立短超时 context，避免客户端取消请求后漏掉版本递增。
+	// 3. 失败时只记录日志，旧缓存依靠短 TTL 自然过期作为兜底。
+	cacheCtx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
+	defer cancel()
+	if err := s.commentTreeCache.BumpCommentTreeVersion(cacheCtx, postID); err != nil {
+		log.Printf("评论树缓存版本递增失败，等待短 TTL 自然过期 post_id=%d err=%v", postID, err)
+	}
+}
+
+func personalizeCommentNodesForActor(nodes []forumcontracts.ForumCommentNode, actorUserID uint64) []forumcontracts.ForumCommentNode {
+	if nodes == nil {
+		return []forumcontracts.ForumCommentNode{}
+	}
+	result := make([]forumcontracts.ForumCommentNode, 0, len(nodes))
+	for _, node := range nodes {
+		result = append(result, personalizeCommentNodeForActor(node, actorUserID))
+	}
+	return result
+}
+
+func personalizeCommentNodeForActor(node forumcontracts.ForumCommentNode, actorUserID uint64) forumcontracts.ForumCommentNode {
+	children := make([]forumcontracts.ForumCommentNode, 0, len(node.Children))
+	for _, child := range node.Children {
+		children = append(children, personalizeCommentNodeForActor(child, actorUserID))
+	}
+	node.Children = children
+	node.CanDelete = actorUserID != 0 &&
+		node.Author.UserID == actorUserID &&
+		node.Status == forummodel.ForumCommentStatusVisible
+	return node
+}

backend/services/taskclassforum/sv/errors.go

@@ -0,0 +1,8 @@
+package sv
+
+import "errors"
+
+var (
+	// ErrTaskClassPortMissing 表示计划广场需要访问旧 TaskClass，但 adapter 尚未注入。
+	ErrTaskClassPortMissing = errors.New("taskclassforum taskclass adapter is nil")
+)

backend/services/taskclassforum/sv/helpers.go

@@ -0,0 +1,294 @@
+package sv
+
+import (
+	"encoding/json"
+	"fmt"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/LoveLosita/smartflow/backend/shared/respond"
+	forummodel "github.com/LoveLosita/smartflow/backend/services/taskclassforum/model"
+	forumcontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/taskclassforum"
+)
+
+const (
+	defaultPage     = 1
+	defaultPageSize = 20
+	maxPageSize     = 50
+	maxPostTitleLen = 40
+	maxSummaryLen   = 300
+	maxTagCount     = 5
+	maxTagLength    = 12
+	maxCommentLen   = 500
+	maxImportTitle  = 80
+)
+
+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) forumcontracts.PageResult {
+	return forumcontracts.PageResult{
+		Page:     page,
+		PageSize: pageSize,
+		Total:    int(total),
+		HasMore:  int64(page*pageSize) < total,
+	}
+}
+
+func normalizeTags(tags []string) ([]string, error) {
+	result := make([]string, 0, len(tags))
+	seen := make(map[string]struct{}, len(tags))
+	for _, raw := range tags {
+		tag := strings.TrimSpace(raw)
+		if tag == "" {
+			continue
+		}
+		if len([]rune(tag)) > maxTagLength {
+			return nil, respond.ParamTooLong
+		}
+		if _, exists := seen[tag]; exists {
+			continue
+		}
+		seen[tag] = struct{}{}
+		result = append(result, tag)
+		if len(result) > maxTagCount {
+			return nil, respond.ParamTooLong
+		}
+	}
+	return result, nil
+}
+
+func validateRuneMax(value string, maxLen int) error {
+	if len([]rune(strings.TrimSpace(value))) > maxLen {
+		return respond.ParamTooLong
+	}
+	return nil
+}
+
+func tagsToJSON(tags []string) (string, error) {
+	if tags == nil {
+		tags = []string{}
+	}
+	raw, err := json.Marshal(tags)
+	if err != nil {
+		return "", err
+	}
+	return string(raw), nil
+}
+
+func tagsFromJSON(raw string) []string {
+	var tags []string
+	if err := json.Unmarshal([]byte(raw), &tags); err != nil {
+		return []string{}
+	}
+	return tags
+}
+
+func intSliceToJSONPtr(values []int) (*string, error) {
+	if values == nil {
+		values = []int{}
+	}
+	raw, err := json.Marshal(values)
+	if err != nil {
+		return nil, err
+	}
+	result := string(raw)
+	return &result, nil
+}
+
+func stringSliceToJSONPtr(values []string) (*string, error) {
+	if values == nil {
+		values = []string{}
+	}
+	raw, err := json.Marshal(values)
+	if err != nil {
+		return nil, err
+	}
+	result := string(raw)
+	return &result, nil
+}
+
+func intSliceFromJSONPtr(raw *string) []int {
+	if raw == nil || strings.TrimSpace(*raw) == "" {
+		return []int{}
+	}
+	var values []int
+	if err := json.Unmarshal([]byte(*raw), &values); err != nil {
+		return []int{}
+	}
+	return values
+}
+
+func stringSliceFromJSONPtr(raw *string) []string {
+	if raw == nil || strings.TrimSpace(*raw) == "" {
+		return []string{}
+	}
+	var values []string
+	if err := json.Unmarshal([]byte(*raw), &values); err != nil {
+		return []string{}
+	}
+	return values
+}
+
+func parseSnapshotDate(value string) *time.Time {
+	if strings.TrimSpace(value) == "" {
+		return nil
+	}
+	parsed, err := time.ParseInLocation("2006-01-02", strings.TrimSpace(value), time.Local)
+	if err != nil {
+		return nil
+	}
+	return &parsed
+}
+
+func formatDate(value *time.Time) string {
+	if value == nil || value.IsZero() {
+		return ""
+	}
+	return value.Format("2006-01-02")
+}
+
+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 userBrief(userID uint64) forumcontracts.UserBrief {
+	return forumcontracts.UserBrief{
+		UserID:   userID,
+		Nickname: fmt.Sprintf("用户%d", userID),
+	}
+}
+
+func countersFromPost(post forummodel.ForumPost) forumcontracts.ForumPostCounters {
+	return forumcontracts.ForumPostCounters{
+		LikeCount:    post.LikeCount,
+		CommentCount: post.CommentCount,
+		ImportCount:  post.ImportCount,
+	}
+}
+
+func viewerState(postID uint64, liked map[uint64]bool, imported map[uint64]bool) forumcontracts.ForumPostViewerState {
+	return forumcontracts.ForumPostViewerState{
+		Liked:        liked[postID],
+		ImportedOnce: imported[postID],
+	}
+}
+
+func templateSummaryFromTemplate(template *forummodel.ForumPostTemplate, itemCount int) forumcontracts.TemplateSummary {
+	if template == nil {
+		return forumcontracts.TemplateSummary{}
+	}
+	return forumcontracts.TemplateSummary{
+		TaskCount:      itemCount,
+		Mode:           template.Mode,
+		StartDate:      formatDate(template.StartDate),
+		EndDate:        formatDate(template.EndDate),
+		StrategyLabels: stringSliceFromJSONPtr(template.StrategyLabelsJSON),
+	}
+}
+
+func postBriefFromModel(post forummodel.ForumPost, template *forummodel.ForumPostTemplate, itemCount int, state forumcontracts.ForumPostViewerState) forumcontracts.ForumPostBrief {
+	return forumcontracts.ForumPostBrief{
+		PostID:          post.ID,
+		Title:           post.Title,
+		Summary:         post.Summary,
+		Tags:            tagsFromJSON(post.TagsJSON),
+		Author:          userBrief(post.AuthorUserID),
+		TemplateSummary: templateSummaryFromTemplate(template, itemCount),
+		Counters:        countersFromPost(post),
+		ViewerState:     state,
+		Status:          post.Status,
+		CreatedAt:       formatTime(post.CreatedAt),
+	}
+}
+
+func templateDetailFromModel(template forummodel.ForumPostTemplate, items []forummodel.ForumPostTemplateItem) forumcontracts.TemplateDetail {
+	sort.SliceStable(items, func(i, j int) bool {
+		return items[i].Order < items[j].Order
+	})
+	preview := make([]forumcontracts.TemplateItemPreview, 0, len(items))
+	for _, item := range items {
+		preview = append(preview, forumcontracts.TemplateItemPreview{
+			ItemID:  item.ID,
+			Order:   item.Order,
+			Content: item.Content,
+		})
+	}
+	return forumcontracts.TemplateDetail{
+		Mode:           template.Mode,
+		StartDate:      formatDate(template.StartDate),
+		EndDate:        formatDate(template.EndDate),
+		StrategyLabels: stringSliceFromJSONPtr(template.StrategyLabelsJSON),
+		TaskCount:      len(items),
+		ItemsPreview:   preview,
+	}
+}
+
+func snapshotFromTemplate(post forummodel.ForumPost, template forummodel.ForumPostTemplate, items []forummodel.ForumPostTemplateItem) TaskClassSnapshot {
+	sort.SliceStable(items, func(i, j int) bool {
+		return items[i].Order < items[j].Order
+	})
+	snapshotItems := make([]TaskClassSnapshotItem, 0, len(items))
+	for _, item := range items {
+		snapshotItems = append(snapshotItems, TaskClassSnapshotItem{
+			TaskItemID: item.SourceTaskItemID,
+			Order:      item.Order,
+			Content:    item.Content,
+		})
+	}
+	return TaskClassSnapshot{
+		TaskClassID:        template.SourceTaskClassID,
+		Title:              post.Title,
+		Mode:               template.Mode,
+		StartDate:          formatDate(template.StartDate),
+		EndDate:            formatDate(template.EndDate),
+		SubjectType:        template.SubjectType,
+		DifficultyLevel:    template.DifficultyLevel,
+		CognitiveIntensity: template.CognitiveIntensity,
+		TotalSlots:         template.TotalSlots,
+		AllowFillerCourse:  template.AllowFillerCourse,
+		Strategy:           template.Strategy,
+		ExcludedSlots:      intSliceFromJSONPtr(template.ExcludedSlotsJSON),
+		ExcludedDaysOfWeek: intSliceFromJSONPtr(template.ExcludedDaysOfWeekJSON),
+		StrategyLabels:     stringSliceFromJSONPtr(template.StrategyLabelsJSON),
+		Items:              snapshotItems,
+		ConfigSnapshotJSON: stringFromPtr(template.ConfigSnapshotJSON),
+	}
+}
+
+func stringFromPtr(value *string) string {
+	if value == nil {
+		return ""
+	}
+	return *value
+}
+
+func stringPtrFromNonEmpty(value string) *string {
+	trimmed := strings.TrimSpace(value)
+	if trimmed == "" {
+		return nil
+	}
+	return &trimmed
+}

backend/services/taskclassforum/sv/import.go

@@ -0,0 +1,283 @@
+package sv
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/LoveLosita/smartflow/backend/shared/respond"
+	forumdao "github.com/LoveLosita/smartflow/backend/services/taskclassforum/dao"
+	forummodel "github.com/LoveLosita/smartflow/backend/services/taskclassforum/model"
+	forumcontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/taskclassforum"
+	sharedevents "github.com/LoveLosita/smartflow/backend/shared/events"
+)
+
+// ImportPost 从论坛模板导入当前用户自己的 TaskClass 副本。
+//
+// 职责边界：
+// 1. 同一用户同一帖子只允许导入一次，由 forum_imports 唯一约束兜底；
+// 2. 只通过 TaskClassSnapshotPort 创建 TaskClass，不写 schedule；
+// 3. 只写 forum_imports 和 import_count，Token 奖励后续基于 event_id 消费。
+func (s *Service) ImportPost(ctx context.Context, req forumcontracts.ImportForumPostRequest) (*forumcontracts.ImportForumPostResult, error) {
+	if err := s.Ready(); err != nil {
+		return nil, err
+	}
+	if req.ActorUserID == 0 || req.PostID == 0 {
+		return nil, respond.MissingParam
+	}
+	if strings.TrimSpace(req.TargetTitle) != "" {
+		if err := validateRuneMax(req.TargetTitle, maxImportTitle); err != nil {
+			return nil, err
+		}
+	}
+	if s.taskClassPort == nil {
+		return nil, ErrTaskClassPortMissing
+	}
+
+	idempotencyKey := strings.TrimSpace(req.IdempotencyKey)
+	if idempotencyKey != "" {
+		existing, err := s.forumDAO.FindImportByIdempotencyKey(ctx, req.ActorUserID, idempotencyKey)
+		if err != nil {
+			return nil, err
+		}
+		if existing != nil && existing.Status == forummodel.ForumImportStatusImported {
+			return s.importResultWithCurrentImportCount(ctx, *existing), nil
+		}
+	}
+	existing, err := s.forumDAO.FindImport(ctx, req.PostID, req.ActorUserID)
+	if err != nil {
+		return nil, err
+	}
+	if existing != nil && existing.Status == forummodel.ForumImportStatusImported {
+		return s.importResultWithCurrentImportCount(ctx, *existing), nil
+	}
+	if existing != nil && existing.Status == forummodel.ForumImportStatusFailed && existing.NewTaskClassID != nil {
+		return s.recoverCreatedImport(ctx, req, *existing)
+	}
+	if existing != nil && existing.Status == forummodel.ForumImportStatusPending {
+		return nil, respond.RequestIsProcessing
+	}
+
+	post, template, items, err := s.loadPostTemplate(ctx, req.PostID)
+	if err != nil {
+		return nil, err
+	}
+	snapshot := snapshotFromTemplate(*post, *template, items)
+	targetTitle := strings.TrimSpace(req.TargetTitle)
+	if targetTitle == "" {
+		targetTitle = post.Title
+	}
+
+	pending, err := s.reserveImport(ctx, req, post.AuthorUserID, targetTitle, idempotencyKey)
+	if err != nil {
+		return nil, err
+	}
+	if pending.Status == forummodel.ForumImportStatusImported {
+		return s.importResultWithCurrentImportCount(ctx, *pending), nil
+	}
+
+	created, err := s.taskClassPort.CreateTaskClassFromSnapshot(ctx, req.ActorUserID, snapshot, targetTitle)
+	if err != nil {
+		_ = s.forumDAO.MarkImportFailed(ctx, pending.ID, err.Error(), time.Now())
+		return nil, err
+	}
+	if created == nil {
+		err := respond.InternalError(fmt.Errorf("taskclass adapter returned nil created taskclass"))
+		_ = s.forumDAO.MarkImportFailed(ctx, pending.ID, err.Info, time.Now())
+		return nil, err
+	}
+
+	var imported forummodel.ForumImport
+	var rewardPayload *sharedevents.ForumPostRewardPayload
+	if err := s.forumDAO.Transaction(ctx, func(txDAO *forumdao.ForumDAO) error {
+		if _, err := txDAO.LockPublishedPost(ctx, req.PostID); err != nil {
+			return normalizeRecordNotFound(err, respond.UserTaskClassNotFound)
+		}
+		again, err := txDAO.FindImport(ctx, req.PostID, req.ActorUserID)
+		if err != nil {
+			return err
+		}
+		if again == nil || again.ID != pending.ID {
+			return respond.RequestIsProcessing
+		}
+		if again.Status == forummodel.ForumImportStatusImported {
+			imported = *again
+			return nil
+		}
+		finalizedAt := time.Now()
+		if err := txDAO.FinalizeImport(ctx, pending.ID, created.TaskClassID, created.Title, finalizedAt); err != nil {
+			return err
+		}
+		imported = *again
+		imported.NewTaskClassID = &created.TaskClassID
+		imported.TargetTitle = created.Title
+		imported.Status = forummodel.ForumImportStatusImported
+		if again.Status != forummodel.ForumImportStatusImported {
+			payload := sharedevents.NewForumPostImportedPayload(req.PostID, again.ID, again.AuthorUserID, req.ActorUserID, finalizedAt)
+			if again.EventID != "" {
+				payload.EventID = again.EventID
+			}
+			// 调用目的：导入成功和作者奖励事件必须同事务提交，避免只创建副本却永久漏发奖励。
+			handled, publishErr := s.publishForumRewardEventInTx(ctx, txDAO.GormDB(), payload)
+			if publishErr != nil {
+				return publishErr
+			}
+			if !handled {
+				rewardPayload = &payload
+			}
+			return txDAO.AddPostCounter(ctx, req.PostID, "import_count", 1)
+		}
+		return nil
+	}); err != nil {
+		_ = s.forumDAO.MarkImportFailedAfterTaskClassCreated(ctx, pending.ID, created.TaskClassID, created.Title, err.Error(), time.Now())
+		return nil, err
+	}
+	if rewardPayload != nil {
+		s.publishForumRewardEventBestEffort(*rewardPayload)
+	}
+	result := importResultFromModel(imported)
+	if postAfter, err := s.forumDAO.FindPublishedPost(ctx, req.PostID); err == nil {
+		result.ImportCount = postAfter.ImportCount
+	}
+	return result, nil
+}
+
+func (s *Service) reserveImport(ctx context.Context, req forumcontracts.ImportForumPostRequest, authorUserID uint64, targetTitle string, idempotencyKey string) (*forummodel.ForumImport, error) {
+	var reserved *forummodel.ForumImport
+	if err := s.forumDAO.Transaction(ctx, func(txDAO *forumdao.ForumDAO) error {
+		if _, err := txDAO.LockPublishedPost(ctx, req.PostID); err != nil {
+			return normalizeRecordNotFound(err, respond.UserTaskClassNotFound)
+		}
+		existing, err := txDAO.FindImport(ctx, req.PostID, req.ActorUserID)
+		if err != nil {
+			return err
+		}
+		if existing != nil {
+			switch existing.Status {
+			case forummodel.ForumImportStatusImported:
+				reserved = existing
+				return nil
+			case forummodel.ForumImportStatusPending:
+				return respond.RequestIsProcessing
+			case forummodel.ForumImportStatusFailed:
+				if existing.NewTaskClassID != nil {
+					reserved = existing
+					return nil
+				}
+				if err := txDAO.UpdateImportProcessing(ctx, existing.ID, targetTitle, time.Now()); err != nil {
+					return err
+				}
+				existing.Status = forummodel.ForumImportStatusPending
+				existing.TargetTitle = targetTitle
+				reserved = existing
+				return nil
+			}
+		}
+		item := &forummodel.ForumImport{
+			PostID:         req.PostID,
+			UserID:         req.ActorUserID,
+			AuthorUserID:   authorUserID,
+			TargetTitle:    targetTitle,
+			Status:         forummodel.ForumImportStatusPending,
+			EventID:        forumImportEventID(req.PostID, req.ActorUserID),
+			IdempotencyKey: stringPtrFromNonEmpty(idempotencyKey),
+		}
+		if err := txDAO.CreateImport(ctx, item); err != nil {
+			return err
+		}
+		reserved = item
+		return nil
+	}); err != nil {
+		return nil, err
+	}
+	return reserved, nil
+}
+
+func (s *Service) recoverCreatedImport(ctx context.Context, req forumcontracts.ImportForumPostRequest, existing forummodel.ForumImport) (*forumcontracts.ImportForumPostResult, error) {
+	if existing.NewTaskClassID == nil {
+		return nil, respond.RequestIsProcessing
+	}
+	imported := existing
+	var rewardPayload *sharedevents.ForumPostRewardPayload
+	if err := s.forumDAO.Transaction(ctx, func(txDAO *forumdao.ForumDAO) error {
+		if _, err := txDAO.LockPublishedPost(ctx, req.PostID); err != nil {
+			return normalizeRecordNotFound(err, respond.UserTaskClassNotFound)
+		}
+		again, err := txDAO.FindImport(ctx, req.PostID, req.ActorUserID)
+		if err != nil {
+			return err
+		}
+		if again == nil || again.ID != existing.ID {
+			return respond.RequestIsProcessing
+		}
+		if again.Status == forummodel.ForumImportStatusImported {
+			imported = *again
+			return nil
+		}
+		if again.Status != forummodel.ForumImportStatusFailed || again.NewTaskClassID == nil {
+			return respond.RequestIsProcessing
+		}
+		finalizedAt := time.Now()
+		if err := txDAO.FinalizeImport(ctx, again.ID, *again.NewTaskClassID, again.TargetTitle, finalizedAt); err != nil {
+			return err
+		}
+		imported = *again
+		imported.Status = forummodel.ForumImportStatusImported
+		payload := sharedevents.NewForumPostImportedPayload(req.PostID, again.ID, again.AuthorUserID, req.ActorUserID, finalizedAt)
+		if again.EventID != "" {
+			payload.EventID = again.EventID
+		}
+		// 调用目的：恢复已创建副本的导入记录时，同步补齐奖励 outbox，保证恢复路径和首次成功路径一致。
+		handled, publishErr := s.publishForumRewardEventInTx(ctx, txDAO.GormDB(), payload)
+		if publishErr != nil {
+			return publishErr
+		}
+		if !handled {
+			rewardPayload = &payload
+		}
+		return txDAO.AddPostCounter(ctx, req.PostID, "import_count", 1)
+	}); err != nil {
+		return nil, err
+	}
+	if rewardPayload != nil {
+		s.publishForumRewardEventBestEffort(*rewardPayload)
+	}
+	result := importResultFromModel(imported)
+	if postAfter, err := s.forumDAO.FindPublishedPost(ctx, req.PostID); err == nil {
+		result.ImportCount = postAfter.ImportCount
+	}
+	return result, nil
+}
+
+func importResultFromModel(item forummodel.ForumImport) *forumcontracts.ImportForumPostResult {
+	var newTaskClassID uint64
+	if item.NewTaskClassID != nil {
+		newTaskClassID = *item.NewTaskClassID
+	}
+	return &forumcontracts.ImportForumPostResult{
+		ImportID:       item.ID,
+		PostID:         item.PostID,
+		NewTaskClassID: newTaskClassID,
+		TaskClassTitle: item.TargetTitle,
+		CreatedAt:      formatTime(item.CreatedAt),
+	}
+}
+
+// importResultWithCurrentImportCount 复用已有导入记录时补齐帖子当前导入计数。
+//
+// 职责边界：
+// 1. 只补齐响应展示用的 import_count，不改变 forum_imports 状态；
+// 2. 查询帖子失败时保留基础导入回执，避免幂等重放因为展示字段失败而误报导入失败；
+// 3. 新导入路径仍以事务内 AddPostCounter 为准，这里只处理已导入短路路径。
+func (s *Service) importResultWithCurrentImportCount(ctx context.Context, item forummodel.ForumImport) *forumcontracts.ImportForumPostResult {
+	result := importResultFromModel(item)
+	if post, err := s.forumDAO.FindPublishedPost(ctx, item.PostID); err == nil {
+		result.ImportCount = post.ImportCount
+	}
+	return result
+}
+
+func forumImportEventID(postID uint64, userID uint64) string {
+	return sharedevents.ForumRewardEventID(sharedevents.ForumPostImportedEventType, postID, userID)
+}

backend/services/taskclassforum/sv/like.go

@@ -0,0 +1,140 @@
+package sv
+
+import (
+	"context"
+	"time"
+
+	"github.com/LoveLosita/smartflow/backend/shared/respond"
+	forumdao "github.com/LoveLosita/smartflow/backend/services/taskclassforum/dao"
+	forummodel "github.com/LoveLosita/smartflow/backend/services/taskclassforum/model"
+	forumcontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/taskclassforum"
+	sharedevents "github.com/LoveLosita/smartflow/backend/shared/events"
+)
+
+// LikePost 点赞计划帖子。
+//
+// 职责边界：
+// 1. 保证同一用户同一帖子只有一个 active 点赞状态；
+// 2. 维护帖子 like_count 计数字段；
+// 3. 只在首次创建 like 记录时补发 outbox 事件，取消后重新激活旧记录不重复发奖励。
+func (s *Service) LikePost(ctx context.Context, actorUserID uint64, postID uint64) (forumcontracts.ForumPostCounters, forumcontracts.ForumPostViewerState, error) {
+	if err := s.Ready(); err != nil {
+		return forumcontracts.ForumPostCounters{}, forumcontracts.ForumPostViewerState{}, err
+	}
+	if actorUserID == 0 || postID == 0 {
+		return forumcontracts.ForumPostCounters{}, forumcontracts.ForumPostViewerState{}, respond.MissingParam
+	}
+
+	var rewardPayload *sharedevents.ForumPostRewardPayload
+	if err := s.forumDAO.Transaction(ctx, func(txDAO *forumdao.ForumDAO) error {
+		post, err := txDAO.LockPublishedPost(ctx, postID)
+		if err != nil {
+			return normalizeRecordNotFound(err, respond.UserTaskClassNotFound)
+		}
+		like, err := txDAO.FindLike(ctx, postID, actorUserID)
+		if err != nil {
+			return err
+		}
+		if like == nil {
+			payload, createErr := createActiveLike(ctx, txDAO, post, actorUserID)
+			if createErr != nil {
+				return createErr
+			}
+			// 调用目的：优先把首次点赞奖励事件写入当前事务，保证点赞记录和 outbox 入队原子提交。
+			handled, publishErr := s.publishForumRewardEventInTx(ctx, txDAO.GormDB(), payload)
+			if publishErr != nil {
+				return publishErr
+			}
+			if !handled {
+				rewardPayload = &payload
+			}
+			return nil
+		}
+		if like.Status == forummodel.ForumLikeStatusActive {
+			return nil
+		}
+		if err := txDAO.ActivateLike(ctx, like.ID); err != nil {
+			return err
+		}
+		return txDAO.AddPostCounter(ctx, postID, "like_count", 1)
+	}); err != nil {
+		return forumcontracts.ForumPostCounters{}, forumcontracts.ForumPostViewerState{}, err
+	}
+
+	if rewardPayload != nil {
+		s.publishForumRewardEventBestEffort(*rewardPayload)
+	}
+	return s.postInteractionState(ctx, actorUserID, postID)
+}
+
+// UnlikePost 取消计划帖子点赞。
+func (s *Service) UnlikePost(ctx context.Context, actorUserID uint64, postID uint64) (forumcontracts.ForumPostCounters, forumcontracts.ForumPostViewerState, error) {
+	if err := s.Ready(); err != nil {
+		return forumcontracts.ForumPostCounters{}, forumcontracts.ForumPostViewerState{}, err
+	}
+	if actorUserID == 0 || postID == 0 {
+		return forumcontracts.ForumPostCounters{}, forumcontracts.ForumPostViewerState{}, respond.MissingParam
+	}
+
+	if err := s.forumDAO.Transaction(ctx, func(txDAO *forumdao.ForumDAO) error {
+		if _, err := txDAO.LockPublishedPost(ctx, postID); err != nil {
+			return normalizeRecordNotFound(err, respond.UserTaskClassNotFound)
+		}
+		like, err := txDAO.FindLike(ctx, postID, actorUserID)
+		if err != nil {
+			return err
+		}
+		if like == nil || like.Status != forummodel.ForumLikeStatusActive {
+			return nil
+		}
+		if err := txDAO.CancelLike(ctx, like.ID, time.Now()); err != nil {
+			return err
+		}
+		return txDAO.AddPostCounter(ctx, postID, "like_count", -1)
+	}); err != nil {
+		return forumcontracts.ForumPostCounters{}, forumcontracts.ForumPostViewerState{}, err
+	}
+	return s.postInteractionState(ctx, actorUserID, postID)
+}
+
+func createActiveLike(ctx context.Context, txDAO *forumdao.ForumDAO, post *forummodel.ForumPost, actorUserID uint64) (sharedevents.ForumPostRewardPayload, error) {
+	like := &forummodel.ForumLike{
+		PostID:       post.ID,
+		UserID:       actorUserID,
+		AuthorUserID: post.AuthorUserID,
+		Status:       forummodel.ForumLikeStatusActive,
+		EventID:      forumLikeEventID(post.ID, actorUserID),
+	}
+	if err := txDAO.CreateLike(ctx, like); err != nil {
+		return sharedevents.ForumPostRewardPayload{}, err
+	}
+	if err := txDAO.AddPostCounter(ctx, post.ID, "like_count", 1); err != nil {
+		return sharedevents.ForumPostRewardPayload{}, err
+	}
+
+	likedAt := like.LikedAt
+	if likedAt.IsZero() {
+		likedAt = time.Now()
+	}
+	payload := sharedevents.NewForumPostLikedPayload(post.ID, post.AuthorUserID, actorUserID, likedAt)
+	if like.EventID != "" {
+		payload.EventID = like.EventID
+	}
+	return payload, nil
+}
+
+func (s *Service) postInteractionState(ctx context.Context, actorUserID uint64, postID uint64) (forumcontracts.ForumPostCounters, forumcontracts.ForumPostViewerState, error) {
+	post, err := s.forumDAO.FindPublishedPost(ctx, postID)
+	if err != nil {
+		return forumcontracts.ForumPostCounters{}, forumcontracts.ForumPostViewerState{}, normalizeRecordNotFound(err, respond.UserTaskClassNotFound)
+	}
+	liked, imported, err := s.viewerStateSets(ctx, actorUserID, []uint64{postID})
+	if err != nil {
+		return forumcontracts.ForumPostCounters{}, forumcontracts.ForumPostViewerState{}, err
+	}
+	return countersFromPost(*post), viewerState(postID, liked, imported), nil
+}
+
+func forumLikeEventID(postID uint64, userID uint64) string {
+	return sharedevents.ForumRewardEventID(sharedevents.ForumPostLikedEventType, postID, userID)
+}

backend/services/taskclassforum/sv/post.go

@@ -0,0 +1,339 @@
+package sv
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"sort"
+	"strings"
+
+	"github.com/LoveLosita/smartflow/backend/shared/respond"
+	forumdao "github.com/LoveLosita/smartflow/backend/services/taskclassforum/dao"
+	forummodel "github.com/LoveLosita/smartflow/backend/services/taskclassforum/model"
+	forumcontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/taskclassforum"
+	"gorm.io/gorm"
+)
+
+// ListPosts 查询计划广场帖子列表。
+//
+// 职责边界：
+// 1. 负责分页、排序、关键词和标签筛选的业务口径；
+// 2. 负责补齐模板摘要、当前用户点赞/导入状态；
+// 3. 不读取原作者当前 TaskClass，列表只基于论坛快照表。
+func (s *Service) ListPosts(ctx context.Context, actorUserID uint64, page int, pageSize int, sortBy string, keyword string, tag string) ([]forumcontracts.ForumPostBrief, forumcontracts.PageResult, error) {
+	if err := s.Ready(); err != nil {
+		return nil, forumcontracts.PageResult{}, err
+	}
+	page, pageSize = normalizePage(page, pageSize)
+
+	posts, total, err := s.forumDAO.ListPosts(ctx, forumdao.ListPostsQuery{
+		Page:     page,
+		PageSize: pageSize,
+		Sort:     sortBy,
+		Keyword:  keyword,
+		Tag:      tag,
+	})
+	if err != nil {
+		return nil, forumcontracts.PageResult{}, err
+	}
+	if len(posts) == 0 {
+		return []forumcontracts.ForumPostBrief{}, pageResult(page, pageSize, total), nil
+	}
+
+	postIDs := collectPostIDs(posts)
+	templates, err := s.forumDAO.FindTemplatesByPostIDs(ctx, postIDs)
+	if err != nil {
+		return nil, forumcontracts.PageResult{}, err
+	}
+	itemCounts, err := s.forumDAO.CountTemplateItemsByPostIDs(ctx, postIDs)
+	if err != nil {
+		return nil, forumcontracts.PageResult{}, err
+	}
+	liked, imported, err := s.viewerStateSets(ctx, actorUserID, postIDs)
+	if err != nil {
+		return nil, forumcontracts.PageResult{}, err
+	}
+
+	result := make([]forumcontracts.ForumPostBrief, 0, len(posts))
+	for _, post := range posts {
+		template, ok := templates[post.ID]
+		var templatePtr *forummodel.ForumPostTemplate
+		if ok {
+			templateCopy := template
+			templatePtr = &templateCopy
+		}
+		result = append(result, postBriefFromModel(post, templatePtr, itemCounts[post.ID], viewerState(post.ID, liked, imported)))
+	}
+	return result, pageResult(page, pageSize, total), nil
+}
+
+// ListTags 聚合计划广场已发布帖子的标签。
+func (s *Service) ListTags(ctx context.Context, actorUserID uint64, limit int) ([]forumcontracts.ForumTagItem, error) {
+	_ = actorUserID
+	if err := s.Ready(); err != nil {
+		return nil, err
+	}
+	if limit <= 0 || limit > 50 {
+		limit = 20
+	}
+
+	rawTags, err := s.forumDAO.ListPublishedTagJSONs(ctx)
+	if err != nil {
+		return nil, err
+	}
+	counter := make(map[string]int)
+	for _, raw := range rawTags {
+		for _, tag := range tagsFromJSON(raw) {
+			if strings.TrimSpace(tag) == "" {
+				continue
+			}
+			counter[tag]++
+		}
+	}
+
+	items := make([]forumcontracts.ForumTagItem, 0, len(counter))
+	for tag, count := range counter {
+		items = append(items, forumcontracts.ForumTagItem{Tag: tag, PostCount: count})
+	}
+	sort.SliceStable(items, func(i, j int) bool {
+		if items[i].PostCount == items[j].PostCount {
+			return items[i].Tag < items[j].Tag
+		}
+		return items[i].PostCount > items[j].PostCount
+	})
+	if len(items) > limit {
+		items = items[:limit]
+	}
+	return items, nil
+}
+
+// CreatePost 发布计划，并把旧 TaskClass 复制为论坛快照。
+//
+// 职责边界：
+// 1. 通过 TaskClassSnapshotPort 获取当前用户自己的 TaskClass 快照；
+// 2. 在论坛私有表写帖子、模板和模板条目；
+// 3. 不修改旧 TaskClass，也不写 schedule。
+func (s *Service) CreatePost(ctx context.Context, req forumcontracts.CreateForumPostRequest) (*forumcontracts.ForumPostBrief, error) {
+	if err := s.Ready(); err != nil {
+		return nil, err
+	}
+	if req.ActorUserID == 0 || req.TaskClassID == 0 || strings.TrimSpace(req.Title) == "" {
+		return nil, respond.MissingParam
+	}
+	if err := validateRuneMax(req.Title, maxPostTitleLen); err != nil {
+		return nil, err
+	}
+	if err := validateRuneMax(req.Summary, maxSummaryLen); err != nil {
+		return nil, err
+	}
+	if s.taskClassPort == nil {
+		return nil, ErrTaskClassPortMissing
+	}
+
+	idempotencyKey := strings.TrimSpace(req.IdempotencyKey)
+	if idempotencyKey != "" {
+		existing, err := s.forumDAO.FindPostByIdempotencyKey(ctx, req.ActorUserID, idempotencyKey)
+		if err != nil {
+			return nil, err
+		}
+		if existing != nil {
+			return s.postBriefByID(ctx, req.ActorUserID, existing.ID)
+		}
+	}
+
+	tags, err := normalizeTags(req.Tags)
+	if err != nil {
+		return nil, err
+	}
+	tagsJSON, err := tagsToJSON(tags)
+	if err != nil {
+		return nil, err
+	}
+	snapshot, err := s.taskClassPort.GetOwnedTaskClassSnapshot(ctx, req.ActorUserID, req.TaskClassID)
+	if err != nil {
+		return nil, normalizeRecordNotFound(err, respond.UserTaskClassNotFound)
+	}
+	if snapshot == nil {
+		return nil, respond.UserTaskClassNotFound
+	}
+
+	post, template, items, err := buildPostSnapshotModels(req, idempotencyKey, tagsJSON, *snapshot)
+	if err != nil {
+		return nil, err
+	}
+	if err := s.forumDAO.CreatePostSnapshot(ctx, &post, &template, items); err != nil {
+		return nil, err
+	}
+	return s.postBriefByID(ctx, req.ActorUserID, post.ID)
+}
+
+// GetPost 查询帖子详情和模板快照。
+func (s *Service) GetPost(ctx context.Context, actorUserID uint64, postID uint64) (*forumcontracts.ForumPostDetail, error) {
+	if err := s.Ready(); err != nil {
+		return nil, err
+	}
+	if postID == 0 {
+		return nil, respond.MissingParam
+	}
+
+	post, template, items, err := s.loadPostTemplate(ctx, postID)
+	if err != nil {
+		return nil, err
+	}
+	liked, imported, err := s.viewerStateSets(ctx, actorUserID, []uint64{postID})
+	if err != nil {
+		return nil, err
+	}
+	state := viewerState(postID, liked, imported)
+	return &forumcontracts.ForumPostDetail{
+		Post:     postBriefFromModel(*post, template, len(items), state),
+		Template: templateDetailFromModel(*template, items),
+	}, nil
+}
+
+func (s *Service) postBriefByID(ctx context.Context, actorUserID uint64, postID uint64) (*forumcontracts.ForumPostBrief, error) {
+	post, template, items, err := s.loadPostTemplate(ctx, postID)
+	if err != nil {
+		return nil, err
+	}
+	liked, imported, err := s.viewerStateSets(ctx, actorUserID, []uint64{postID})
+	if err != nil {
+		return nil, err
+	}
+	brief := postBriefFromModel(*post, template, len(items), viewerState(postID, liked, imported))
+	return &brief, nil
+}
+
+func (s *Service) loadPostTemplate(ctx context.Context, postID uint64) (*forummodel.ForumPost, *forummodel.ForumPostTemplate, []forummodel.ForumPostTemplateItem, error) {
+	post, err := s.forumDAO.FindPublishedPost(ctx, postID)
+	if err != nil {
+		return nil, nil, nil, normalizeRecordNotFound(err, respond.UserTaskClassNotFound)
+	}
+	template, err := s.forumDAO.FindTemplateByPostID(ctx, postID)
+	if err != nil {
+		return nil, nil, nil, normalizeRecordNotFound(err, respond.UserTaskClassNotFound)
+	}
+	items, err := s.forumDAO.ListTemplateItemsByPostID(ctx, postID)
+	if err != nil {
+		return nil, nil, nil, err
+	}
+	return post, template, items, nil
+}
+
+func (s *Service) viewerStateSets(ctx context.Context, actorUserID uint64, postIDs []uint64) (map[uint64]bool, map[uint64]bool, error) {
+	if actorUserID == 0 || len(postIDs) == 0 {
+		return map[uint64]bool{}, map[uint64]bool{}, nil
+	}
+	liked, err := s.forumDAO.LikedPostIDSet(ctx, actorUserID, postIDs)
+	if err != nil {
+		return nil, nil, err
+	}
+	imported, err := s.forumDAO.ImportedPostIDSet(ctx, actorUserID, postIDs)
+	if err != nil {
+		return nil, nil, err
+	}
+	return liked, imported, nil
+}
+
+func collectPostIDs(posts []forummodel.ForumPost) []uint64 {
+	result := make([]uint64, 0, len(posts))
+	for _, post := range posts {
+		result = append(result, post.ID)
+	}
+	return result
+}
+
+func buildPostSnapshotModels(req forumcontracts.CreateForumPostRequest, idempotencyKey string, tagsJSON string, snapshot TaskClassSnapshot) (forummodel.ForumPost, forummodel.ForumPostTemplate, []forummodel.ForumPostTemplateItem, error) {
+	configJSON, err := configSnapshotJSON(snapshot)
+	if err != nil {
+		return forummodel.ForumPost{}, forummodel.ForumPostTemplate{}, nil, err
+	}
+	excludedSlotsJSON, err := intSliceToJSONPtr(snapshot.ExcludedSlots)
+	if err != nil {
+		return forummodel.ForumPost{}, forummodel.ForumPostTemplate{}, nil, err
+	}
+	excludedDaysJSON, err := intSliceToJSONPtr(snapshot.ExcludedDaysOfWeek)
+	if err != nil {
+		return forummodel.ForumPost{}, forummodel.ForumPostTemplate{}, nil, err
+	}
+	labelsJSON, err := stringSliceToJSONPtr(snapshot.StrategyLabels)
+	if err != nil {
+		return forummodel.ForumPost{}, forummodel.ForumPostTemplate{}, nil, err
+	}
+
+	post := forummodel.ForumPost{
+		AuthorUserID:      req.ActorUserID,
+		SourceTaskClassID: req.TaskClassID,
+		Title:             strings.TrimSpace(req.Title),
+		Summary:           strings.TrimSpace(req.Summary),
+		TagsJSON:          tagsJSON,
+		IdempotencyKey:    stringPtrFromNonEmpty(idempotencyKey),
+		Status:            forummodel.ForumPostStatusPublished,
+	}
+	template := forummodel.ForumPostTemplate{
+		SourceTaskClassID:      snapshot.TaskClassID,
+		Mode:                   snapshot.Mode,
+		StartDate:              parseSnapshotDate(snapshot.StartDate),
+		EndDate:                parseSnapshotDate(snapshot.EndDate),
+		SubjectType:            snapshot.SubjectType,
+		DifficultyLevel:        snapshot.DifficultyLevel,
+		CognitiveIntensity:     snapshot.CognitiveIntensity,
+		TotalSlots:             snapshot.TotalSlots,
+		AllowFillerCourse:      snapshot.AllowFillerCourse,
+		Strategy:               snapshot.Strategy,
+		ExcludedSlotsJSON:      excludedSlotsJSON,
+		ExcludedDaysOfWeekJSON: excludedDaysJSON,
+		StrategyLabelsJSON:     labelsJSON,
+		ConfigSnapshotJSON:     &configJSON,
+	}
+	snapshotItems := append([]TaskClassSnapshotItem(nil), snapshot.Items...)
+	sort.SliceStable(snapshotItems, func(i, j int) bool {
+		if snapshotItems[i].Order != snapshotItems[j].Order {
+			return snapshotItems[i].Order < snapshotItems[j].Order
+		}
+		return snapshotItems[i].TaskItemID < snapshotItems[j].TaskItemID
+	})
+	items := make([]forummodel.ForumPostTemplateItem, 0, len(snapshotItems))
+	for _, item := range snapshotItems {
+		if strings.TrimSpace(item.Content) == "" {
+			continue
+		}
+		items = append(items, forummodel.ForumPostTemplateItem{
+			SourceTaskItemID: item.TaskItemID,
+			Order:            len(items) + 1,
+			Content:          item.Content,
+		})
+	}
+	return post, template, items, nil
+}
+
+func configSnapshotJSON(snapshot TaskClassSnapshot) (string, error) {
+	if strings.TrimSpace(snapshot.ConfigSnapshotJSON) != "" {
+		return snapshot.ConfigSnapshotJSON, nil
+	}
+	raw, err := json.Marshal(map[string]any{
+		"mode":                  snapshot.Mode,
+		"start_date":            snapshot.StartDate,
+		"end_date":              snapshot.EndDate,
+		"subject_type":          snapshot.SubjectType,
+		"difficulty_level":      snapshot.DifficultyLevel,
+		"cognitive_intensity":   snapshot.CognitiveIntensity,
+		"total_slots":           snapshot.TotalSlots,
+		"allow_filler_course":   snapshot.AllowFillerCourse,
+		"strategy":              snapshot.Strategy,
+		"excluded_slots":        snapshot.ExcludedSlots,
+		"excluded_days_of_week": snapshot.ExcludedDaysOfWeek,
+		"strategy_labels":       snapshot.StrategyLabels,
+	})
+	if err != nil {
+		return "", err
+	}
+	return string(raw), nil
+}
+
+func normalizeRecordNotFound(err error, fallback error) error {
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return fallback
+	}
+	return err
+}

backend/services/taskclassforum/sv/service.go

@@ -0,0 +1,214 @@
+package sv
+
+import (
+	"context"
+	"errors"
+	"log"
+	"strings"
+	"time"
+
+	outboxinfra "github.com/LoveLosita/smartflow/backend/shared/infra/outbox"
+	forumdao "github.com/LoveLosita/smartflow/backend/services/taskclassforum/dao"
+	forumcontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/taskclassforum"
+	sharedevents "github.com/LoveLosita/smartflow/backend/shared/events"
+	"gorm.io/gorm"
+)
+
+const forumRewardPublishTimeout = 800 * time.Millisecond
+
+type transactionalEventPublisher interface {
+	PublishWithTx(ctx context.Context, tx *gorm.DB, req outboxinfra.PublishRequest) error
+}
+
+// CommentTreeCachePort 是计划广场评论树缓存端口。
+//
+// 职责边界：
+// 1. 只暴露“读分页树、写分页树、递增版本”三个能力，避免 service 依赖 Redis 细节；
+// 2. 缓存内容必须是去个性化读模型，不能带入当前用户的 can_delete；
+// 3. Redis 异常不应影响主链路，service 层会降级回源 DB。
+type CommentTreeCachePort interface {
+	GetCommentTree(ctx context.Context, postID uint64, page int, pageSize int, sort string) ([]forumcontracts.ForumCommentNode, forumcontracts.PageResult, bool, error)
+	SetCommentTree(ctx context.Context, postID uint64, page int, pageSize int, sort string, items []forumcontracts.ForumCommentNode, pageResult forumcontracts.PageResult) error
+	BumpCommentTreeVersion(ctx context.Context, postID uint64) error
+}
+
+// TaskClassSnapshotPort 是计划广场读取和写入 TaskClass 快照的端口。
+//
+// 职责边界：
+// 1. P0 先由 legacy adapter 适配旧 TaskClass DAO / Service；
+// 2. 业务层只依赖快照语义，不关心底层来自旧表、旧服务还是后续 RPC；
+// 3. 不负责写 schedule，一键导入只创建当前用户自己的 TaskClass 副本。
+type TaskClassSnapshotPort interface {
+	GetOwnedTaskClassSnapshot(ctx context.Context, userID uint64, taskClassID uint64) (*TaskClassSnapshot, error)
+	CreateTaskClassFromSnapshot(ctx context.Context, userID uint64, snapshot TaskClassSnapshot, targetTitle string) (*CreatedTaskClass, error)
+}
+
+// TaskClassSnapshot 是可分享的 TaskClass 白名单快照。
+//
+// 注意：这里刻意不包含 embedded_time、schedule 绑定和用户私有排程状态。
+type TaskClassSnapshot struct {
+	TaskClassID        uint64
+	Title              string
+	Mode               string
+	StartDate          string
+	EndDate            string
+	SubjectType        string
+	DifficultyLevel    string
+	CognitiveIntensity string
+	TotalSlots         int
+	AllowFillerCourse  bool
+	Strategy           string
+	ExcludedSlots      []int
+	ExcludedDaysOfWeek []int
+	StrategyLabels     []string
+	Items              []TaskClassSnapshotItem
+	ConfigSnapshotJSON string
+}
+
+// TaskClassSnapshotItem 是 TaskClassItem 的可分享条目快照。
+type TaskClassSnapshotItem struct {
+	TaskItemID uint64
+	Order      int
+	Content    string
+}
+
+// CreatedTaskClass 是导入后创建出的当前用户 TaskClass。
+type CreatedTaskClass struct {
+	TaskClassID uint64
+	Title       string
+}
+
+// Options 是计划广场服务的依赖注入参数。
+type Options struct {
+	DB               *gorm.DB
+	TaskClassPort    TaskClassSnapshotPort
+	EventPublisher   outboxinfra.EventPublisher
+	CommentTreeCache CommentTreeCachePort
+}
+
+// Service 承载计划广场服务内部业务编排。
+//
+// 职责边界：
+// 1. 负责帖子、模板快照、点赞、评论、导入记录的事务编排；
+// 2. 不负责 HTTP 参数绑定，也不直接返回 respond.Response；
+// 3. 不持有 TaskClass 原表，只通过 TaskClassSnapshotPort 读取和创建副本。
+type Service struct {
+	db               *gorm.DB
+	forumDAO         *forumdao.ForumDAO
+	taskClassPort    TaskClassSnapshotPort
+	eventPublisher   outboxinfra.EventPublisher
+	commentTreeCache CommentTreeCachePort
+}
+
+func New(opts Options) *Service {
+	return &Service{
+		db:               opts.DB,
+		forumDAO:         forumdao.NewForumDAO(opts.DB),
+		taskClassPort:    opts.TaskClassPort,
+		eventPublisher:   opts.EventPublisher,
+		commentTreeCache: opts.CommentTreeCache,
+	}
+}
+
+// Ready 用于第二步骨架阶段的依赖检查。
+//
+// 后续实现真实用例时，具体方法会做更细的参数校验；这里只先帮助 cmd / 测试快速发现依赖未注入。
+func (s *Service) Ready() error {
+	if s == nil {
+		return errors.New("taskclassforum service is nil")
+	}
+	if s.db == nil {
+		return errors.New("taskclassforum db is nil")
+	}
+	return nil
+}
+
+// publishForumRewardEventBestEffort 在主事务成功后补发论坛奖励 outbox 事件。
+//
+// 职责边界：
+// 1. 这里只处理“事务已经成功提交后的补发”，不再回头影响点赞/导入接口的成功结果；
+// 2. 改用独立短超时 context，避免客户端断开直接打断补发，也避免 outbox 写入长时间拖慢接口尾部；
+// 3. 发布失败时只记日志不返回 error，这是 P0 的明确取舍：先保住主链路，再靠日志和稳定 event_id 排障/补偿。
+func (s *Service) publishForumRewardEventBestEffort(payload sharedevents.ForumPostRewardPayload) {
+	if s == nil || s.eventPublisher == nil {
+		return
+	}
+	if err := payload.Validate(); err != nil {
+		log.Printf(
+			"forum reward outbox payload 非法，跳过发布: event_id=%s post_id=%d import_id=%d source=%s err=%v",
+			payload.EventID,
+			payload.PostID,
+			payload.ImportID,
+			payload.Source,
+			err,
+		)
+		return
+	}
+
+	eventType := strings.TrimSpace(payload.EventType())
+	if eventType == "" {
+		log.Printf(
+			"forum reward outbox 事件类型为空，跳过发布: event_id=%s post_id=%d import_id=%d source=%s",
+			payload.EventID,
+			payload.PostID,
+			payload.ImportID,
+			payload.Source,
+		)
+		return
+	}
+
+	publishCtx, cancel := context.WithTimeout(context.Background(), forumRewardPublishTimeout)
+	defer cancel()
+
+	if err := s.eventPublisher.Publish(publishCtx, outboxinfra.PublishRequest{
+		EventType:    eventType,
+		EventVersion: sharedevents.ForumRewardEventVersion,
+		MessageKey:   payload.MessageKey(),
+		AggregateID:  payload.AggregateID(),
+		EventID:      payload.EventID,
+		Payload:      payload,
+	}); err != nil {
+		log.Printf(
+			"forum reward outbox 发布失败，按 P0 约定忽略主链路错误: event_type=%s event_id=%s post_id=%d import_id=%d actor_user_id=%d err=%v",
+			eventType,
+			payload.EventID,
+			payload.PostID,
+			payload.ImportID,
+			payload.ActorUserID,
+			err,
+		)
+	}
+}
+
+// publishForumRewardEventInTx 尝试把论坛奖励事件写进当前业务事务。
+//
+// 返回值说明：
+// 1. handled=true 表示发布器支持事务写入，调用方不需要再做事务后 best-effort 补发；
+// 2. handled=false 表示当前发布器不支持事务写入，调用方可退回旧的事务后补发路径；
+// 3. error 非空表示 outbox 入队失败，业务事务应一起回滚，避免成功互动永久漏奖。
+func (s *Service) publishForumRewardEventInTx(ctx context.Context, tx *gorm.DB, payload sharedevents.ForumPostRewardPayload) (bool, error) {
+	if s == nil || s.eventPublisher == nil {
+		return false, nil
+	}
+	publisher, ok := s.eventPublisher.(transactionalEventPublisher)
+	if !ok {
+		return false, nil
+	}
+	if err := payload.Validate(); err != nil {
+		return true, err
+	}
+
+	eventType := strings.TrimSpace(payload.EventType())
+	if eventType == "" {
+		return true, errors.New("论坛奖励事件类型为空")
+	}
+
+	return true, publisher.PublishWithTx(ctx, tx, outboxinfra.PublishRequest{
+		EventType:    eventType,
+		EventVersion: sharedevents.ForumRewardEventVersion,
+		MessageKey:   payload.MessageKey(),
+		AggregateID:  payload.AggregateID(),
+		EventID:      payload.EventID,
+		Payload:      payload,
+	})
+}

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,
+		},
+	}
+}

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
+}

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"
+}

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
+}

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
+}

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()    {}

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",
+}

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
+}

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;
+}

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
+}

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),
+	}
+}

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
+}

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)
+}

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
+}

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 "论坛奖励入账"
+	}
+}

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
+}