diff --git a/backend/cmd/taskclassforum/main.go b/backend/cmd/taskclassforum/main.go new file mode 100644 index 0000000..ddf8f48 --- /dev/null +++ b/backend/cmd/taskclassforum/main.go @@ -0,0 +1,32 @@ +package main + +import ( + "log" + + "github.com/LoveLosita/smartflow/backend/bootstrap" + forumdao "github.com/LoveLosita/smartflow/backend/services/taskclassforum/dao" + forumrpc "github.com/LoveLosita/smartflow/backend/services/taskclassforum/rpc" + forumsv "github.com/LoveLosita/smartflow/backend/services/taskclassforum/sv" + "github.com/spf13/viper" +) + +func main() { + if err := bootstrap.LoadConfig(); err != nil { + log.Fatalf("failed to load config: %v", err) + } + + db, err := forumdao.OpenDBFromConfig() + if err != nil { + log.Fatalf("failed to connect taskclassforum database: %v", err) + } + + // 1. 当前阶段只启动计划广场自身 RPC 壳。 + // 2. TaskClass legacy adapter 会在第三步业务主链路接入，避免现在抢改 task 模块。 + // 3. 未实现的业务方法会明确返回 Unimplemented，而不是伪装成可用能力。 + svc := forumsv.New(forumsv.Options{DB: db}) + forumrpc.Start(forumrpc.ServerOptions{ + ListenOn: viper.GetString("taskclassforum.rpc.listenOn"), + Timeout: viper.GetDuration("taskclassforum.rpc.timeout"), + Service: svc, + }) +} diff --git a/backend/cmd/tokenstore/main.go b/backend/cmd/tokenstore/main.go new file mode 100644 index 0000000..70eb44b --- /dev/null +++ b/backend/cmd/tokenstore/main.go @@ -0,0 +1,32 @@ +package main + +import ( + "log" + + "github.com/LoveLosita/smartflow/backend/bootstrap" + tokenstoredao "github.com/LoveLosita/smartflow/backend/services/tokenstore/dao" + tokenstorerpc "github.com/LoveLosita/smartflow/backend/services/tokenstore/rpc" + tokenstoresv "github.com/LoveLosita/smartflow/backend/services/tokenstore/sv" + "github.com/spf13/viper" +) + +func main() { + if err := bootstrap.LoadConfig(); err != nil { + log.Fatalf("failed to load config: %v", err) + } + + db, err := tokenstoredao.OpenDBFromConfig() + if err != nil { + log.Fatalf("failed to connect tokenstore database: %v", err) + } + + // 1. 当前阶段只启动 token-store 自身 RPC 壳和本服务私有表迁移。 + // 2. user/auth 授额出口后续通过 GrantOutlet adapter 切入，避免现在制造冲突。 + // 3. 未实现的业务方法会明确返回 Unimplemented，而不是伪装成可用能力。 + svc := tokenstoresv.New(tokenstoresv.Options{DB: db}) + tokenstorerpc.Start(tokenstorerpc.ServerOptions{ + ListenOn: viper.GetString("tokenstore.rpc.listenOn"), + Timeout: viper.GetDuration("tokenstore.rpc.timeout"), + Service: svc, + }) +} diff --git a/backend/services/taskclassforum/dao/connect.go b/backend/services/taskclassforum/dao/connect.go new file mode 100644 index 0000000..37d9c4d --- /dev/null +++ b/backend/services/taskclassforum/dao/connect.go @@ -0,0 +1,61 @@ +package dao + +import ( + "fmt" + + forummodel "github.com/LoveLosita/smartflow/backend/services/taskclassforum/model" + "github.com/spf13/viper" + "gorm.io/driver/mysql" + "gorm.io/gorm" +) + +// OpenDBFromConfig 创建计划广场服务自己的数据库句柄，并迁移本服务私有表。 +// +// 职责边界： +// 1. 只迁移 forum_* 表，不迁移 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. 唯一约束交给 GORM tag 生成，保证点赞和导入幂等有数据库兜底； +// 3. 失败时直接返回错误，避免服务在 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) + } + return nil +} diff --git a/backend/services/taskclassforum/model/forum.go b/backend/services/taskclassforum/model/forum.go new file mode 100644 index 0000000..f179a29 --- /dev/null +++ b/backend/services/taskclassforum/model/forum.go @@ -0,0 +1,180 @@ +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 ( + // ForumImportStatusImported 表示导入已成功创建当前用户自己的 TaskClass 副本。 + ForumImportStatusImported = "imported" +) + +// 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;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数组"` + 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;not null;comment:导入后创建的当前用户TaskClass ID"` + TargetTitle string `gorm:"column:target_title;type:varchar(80);comment:导入后的TaskClass标题"` + Status string `gorm:"column:status;type:varchar(32);not null;default:'imported';comment:imported"` + 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:导入请求幂等键"` + 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" +} diff --git a/backend/services/taskclassforum/rpc/errors.go b/backend/services/taskclassforum/rpc/errors.go new file mode 100644 index 0000000..2305fe1 --- /dev/null +++ b/backend/services/taskclassforum/rpc/errors.go @@ -0,0 +1,76 @@ +package rpc + +import ( + "errors" + "log" + "strings" + + "github.com/LoveLosita/smartflow/backend/respond" + forumsv "github.com/LoveLosita/smartflow/backend/services/taskclassforum/sv" + "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) + } + if errors.Is(err, forumsv.ErrNotImplemented) { + return status.Error(codes.Unimplemented, err.Error()) + } + 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 +} diff --git a/backend/services/taskclassforum/rpc/handler.go b/backend/services/taskclassforum/rpc/handler.go new file mode 100644 index 0000000..0b0d641 --- /dev/null +++ b/backend/services/taskclassforum/rpc/handler.go @@ -0,0 +1,412 @@ +package rpc + +import ( + "context" + "errors" + + "github.com/LoveLosita/smartflow/backend/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 +} diff --git a/backend/services/taskclassforum/rpc/pb/taskclassforum.pb.go b/backend/services/taskclassforum/rpc/pb/taskclassforum.pb.go new file mode 100644 index 0000000..a61606c --- /dev/null +++ b/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() {} diff --git a/backend/services/taskclassforum/rpc/pb/taskclassforum_grpc.pb.go b/backend/services/taskclassforum/rpc/pb/taskclassforum_grpc.pb.go new file mode 100644 index 0000000..1d112c2 --- /dev/null +++ b/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", +} diff --git a/backend/services/taskclassforum/rpc/server.go b/backend/services/taskclassforum/rpc/server.go new file mode 100644 index 0000000..5d190ca --- /dev/null +++ b/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:9082" + 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 +} diff --git a/backend/services/taskclassforum/rpc/taskclassforum.proto b/backend/services/taskclassforum/rpc/taskclassforum.proto new file mode 100644 index 0000000..c143de8 --- /dev/null +++ b/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; +} diff --git a/backend/services/taskclassforum/sv/service.go b/backend/services/taskclassforum/sv/service.go new file mode 100644 index 0000000..0b0ca8c --- /dev/null +++ b/backend/services/taskclassforum/sv/service.go @@ -0,0 +1,179 @@ +package sv + +import ( + "context" + "errors" + + forumcontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/taskclassforum" + "gorm.io/gorm" +) + +// ErrNotImplemented 表示 RPC 骨架已接线，但对应业务用例还在后续步骤实现。 +var ErrNotImplemented = errors.New("taskclassforum service method not implemented") + +// 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 +} + +// Service 承载计划广场服务内部业务编排。 +// +// 职责边界： +// 1. 负责帖子、模板快照、点赞、评论、导入记录的事务编排； +// 2. 不负责 HTTP 参数绑定，也不直接返回 respond.Response； +// 3. 不拥有 TaskClass 原表，只通过 TaskClassSnapshotPort 读取和创建副本。 +type Service struct { + db *gorm.DB + taskClassPort TaskClassSnapshotPort +} + +func New(opts Options) *Service { + return &Service{ + db: opts.DB, + taskClassPort: opts.TaskClassPort, + } +} + +// 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 +} + +// ListPosts 是计划列表用例占位，第三步实现真实查询。 +func (s *Service) ListPosts(ctx context.Context, actorUserID uint64, page int, pageSize int, sort string, keyword string, tag string) ([]forumcontracts.ForumPostBrief, forumcontracts.PageResult, error) { + _ = ctx + _ = actorUserID + _ = page + _ = pageSize + _ = sort + _ = keyword + _ = tag + return nil, forumcontracts.PageResult{}, ErrNotImplemented +} + +// ListTags 是标签列表用例占位，第三步实现真实聚合查询。 +func (s *Service) ListTags(ctx context.Context, actorUserID uint64, limit int) ([]forumcontracts.ForumTagItem, error) { + _ = ctx + _ = actorUserID + _ = limit + return nil, ErrNotImplemented +} + +// CreatePost 是发布计划用例占位，第三步会通过 TaskClassSnapshotPort 读取旧计划快照。 +func (s *Service) CreatePost(ctx context.Context, req forumcontracts.CreateForumPostRequest) (*forumcontracts.ForumPostBrief, error) { + _ = ctx + _ = req + return nil, ErrNotImplemented +} + +// GetPost 是计划详情用例占位，第三步实现帖子和模板快照读取。 +func (s *Service) GetPost(ctx context.Context, actorUserID uint64, postID uint64) (*forumcontracts.ForumPostDetail, error) { + _ = ctx + _ = actorUserID + _ = postID + return nil, ErrNotImplemented +} + +// LikePost 是点赞用例占位，第三步实现唯一约束和计数更新。 +func (s *Service) LikePost(ctx context.Context, actorUserID uint64, postID uint64) (forumcontracts.ForumPostCounters, forumcontracts.ForumPostViewerState, error) { + _ = ctx + _ = actorUserID + _ = postID + return forumcontracts.ForumPostCounters{}, forumcontracts.ForumPostViewerState{}, ErrNotImplemented +} + +// UnlikePost 是取消点赞用例占位，第三步实现幂等撤销。 +func (s *Service) UnlikePost(ctx context.Context, actorUserID uint64, postID uint64) (forumcontracts.ForumPostCounters, forumcontracts.ForumPostViewerState, error) { + _ = ctx + _ = actorUserID + _ = postID + return forumcontracts.ForumPostCounters{}, forumcontracts.ForumPostViewerState{}, ErrNotImplemented +} + +// ListComments 是评论树查询用例占位，第三步实现根评论分页和服务层组树。 +func (s *Service) ListComments(ctx context.Context, actorUserID uint64, postID uint64, page int, pageSize int, sort string) ([]forumcontracts.ForumCommentNode, forumcontracts.PageResult, error) { + _ = ctx + _ = actorUserID + _ = postID + _ = page + _ = pageSize + _ = sort + return nil, forumcontracts.PageResult{}, ErrNotImplemented +} + +// CreateComment 是发表评论或回复用例占位，第三步实现父子评论校验和幂等。 +func (s *Service) CreateComment(ctx context.Context, req forumcontracts.CreateForumCommentRequest) (*forumcontracts.ForumCommentNode, error) { + _ = ctx + _ = req + return nil, ErrNotImplemented +} + +// DeleteComment 是删除自己评论用例占位，第三步实现软删除和权限判断。 +func (s *Service) DeleteComment(ctx context.Context, actorUserID uint64, commentID uint64) (*forumcontracts.DeleteForumCommentResult, error) { + _ = ctx + _ = actorUserID + _ = commentID + return nil, ErrNotImplemented +} + +// ImportPost 是一键导入用例占位，第三步会保证同一用户同一帖子只导入一次。 +func (s *Service) ImportPost(ctx context.Context, req forumcontracts.ImportForumPostRequest) (*forumcontracts.ImportForumPostResult, error) { + _ = ctx + _ = req + return nil, ErrNotImplemented +} diff --git a/backend/services/tokenstore/dao/connect.go b/backend/services/tokenstore/dao/connect.go new file mode 100644 index 0000000..e5af2ba --- /dev/null +++ b/backend/services/tokenstore/dao/connect.go @@ -0,0 +1,179 @@ +package dao + +import ( + "fmt" + + 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_* 表，不迁移 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. 通过唯一约束保证 order_no、event_id 和幂等键不会重复写入； +// 3. 失败时直接返回错误，避免服务在 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) + } + 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: 2, + Status: tokenmodel.TokenRewardRuleStatusActive, + }, + } +} diff --git a/backend/services/tokenstore/model/token.go b/backend/services/tokenstore/model/token.go new file mode 100644 index 0000000..c33f52b --- /dev/null +++ b/backend/services/tokenstore/model/token.go @@ -0,0 +1,155 @@ +package model + +import "time" + +const ( + // TokenProductStatusActive 表示商品可在 Token 商店展示和购买。 + TokenProductStatusActive = "active" + // TokenProductStatusInactive 表示商品已下架，不再对前端展示。 + TokenProductStatusInactive = "inactive" +) + +const ( + // TokenOrderStatusPending 表示订单已创建，等待支付确认。 + TokenOrderStatusPending = "pending" + // TokenOrderStatusPaid 表示订单已确认支付，等待写入获取账本。 + TokenOrderStatusPaid = "paid" + // TokenOrderStatusGranted 表示订单已经写入 token_grants 获取账本。 + TokenOrderStatusGranted = "granted" + // TokenOrderStatusClosed 表示订单关闭，P0 暂不实现复杂关闭流程。 + TokenOrderStatusClosed = "closed" +) + +const ( + // TokenGrantStatusRecorded 表示 Token 获取事实已记录在 token-store 内。 + TokenGrantStatusRecorded = "recorded" + // TokenGrantStatusApplied 表示后续已同步到 user/auth 权威额度。 + TokenGrantStatusApplied = "applied" + // TokenGrantStatusSkipped 表示命中奖励规则或幂等条件后跳过发放。 + TokenGrantStatusSkipped = "skipped" + // TokenGrantStatusFailed 表示记录或后续同步失败，可按 event_id 重试。 + TokenGrantStatusFailed = "failed" +) + +const ( + // TokenGrantSourcePurchase 表示购买 Token 商品产生的获取记录。 + TokenGrantSourcePurchase = "purchase" + // TokenGrantSourceForumLike 表示计划被点赞产生的作者奖励。 + TokenGrantSourceForumLike = "forum_like" + // TokenGrantSourceForumImport 表示计划被导入产生的作者奖励。 + TokenGrantSourceForumImport = "forum_import" + // TokenGrantSourceManual 预留人工补偿来源，P0 不做管理后台。 + TokenGrantSourceManual = "manual" +) + +const ( + // TokenRewardRuleStatusActive 表示奖励规则启用。 + TokenRewardRuleStatusActive = "active" + // TokenRewardRuleStatusInactive 表示奖励规则停用。 + TokenRewardRuleStatusInactive = "inactive" +) + +// TokenProduct 是 Token 商店商品表。 +// +// 职责边界： +// 1. P0 从表读取商品，由 seed 初始化 2-3 个固定商品； +// 2. 不承载真实支付渠道配置，也不做商品管理后台； +// 3. 下单时会复制商品快照到订单，避免后续改价影响历史订单。 +type TokenProduct struct { + ID uint64 `gorm:"column:id;primaryKey;autoIncrement"` + SKU string `gorm:"column:sku;type:varchar(64);not null;uniqueIndex:uk_token_products_sku;comment:商品稳定编码"` + Name string `gorm:"column:name;type:varchar(80);not null;comment:商品名称"` + Description string `gorm:"column:description;type:varchar(255);comment:商品描述"` + TokenAmount int64 `gorm:"column:token_amount;not null;comment:商品包含Token数量"` + PriceCent int64 `gorm:"column:price_cent;not null;comment:价格，单位分"` + Currency string `gorm:"column:currency;type:varchar(16);not null;default:'CNY';comment:币种"` + Badge string `gorm:"column:badge;type:varchar(32);comment:前端角标"` + Status string `gorm:"column:status;type:varchar(32);not null;default:'active';index:idx_token_products_status_sort,priority:1;comment:active/inactive"` + SortOrder int `gorm:"column:sort_order;not null;default:0;index:idx_token_products_status_sort,priority:2;comment:展示排序"` + CreatedAt time.Time `gorm:"column:created_at;autoCreateTime;comment:创建时间"` + UpdatedAt time.Time `gorm:"column:updated_at;autoUpdateTime;comment:更新时间"` +} + +func (TokenProduct) TableName() string { + return "token_products" +} + +// TokenOrder 是 Token 商品订单表。 +// +// 职责边界： +// 1. 记录用户购买商品的订单状态机； +// 2. P0 只支持 mock paid，不接真实支付网关； +// 3. granted 只表示已写入 token-store 获取账本，不代表已同步到 user/auth 权威额度。 +type TokenOrder struct { + ID uint64 `gorm:"column:id;primaryKey;autoIncrement"` + OrderNo string `gorm:"column:order_no;type:varchar(64);not null;uniqueIndex:uk_token_orders_order_no;comment:订单号"` + UserID uint64 `gorm:"column:user_id;not null;uniqueIndex:uk_token_orders_user_idem,priority:1;index:idx_token_orders_user_status_created,priority:1;comment:下单用户ID"` + ProductID uint64 `gorm:"column:product_id;not null;index:idx_token_orders_product;comment:商品ID"` + ProductSKU string `gorm:"column:product_sku;type:varchar(64);not null;comment:商品SKU快照"` + ProductName string `gorm:"column:product_name;type:varchar(80);not null;comment:商品名称快照"` + ProductSnapshotJSON string `gorm:"column:product_snapshot_json;type:json;not null;comment:商品完整快照JSON"` + Quantity int `gorm:"column:quantity;not null;default:1;comment:购买数量"` + TokenAmount int64 `gorm:"column:token_amount;not null;comment:订单总Token数量"` + AmountCent int64 `gorm:"column:amount_cent;not null;comment:订单总金额，单位分"` + Currency string `gorm:"column:currency;type:varchar(16);not null;default:'CNY';comment:币种"` + Status string `gorm:"column:status;type:varchar(32);not null;default:'pending';index:idx_token_orders_user_status_created,priority:2;comment:pending/paid/granted/closed"` + PaymentMode string `gorm:"column:payment_mode;type:varchar(32);not null;default:'mock';comment:支付模式，P0为mock"` + IdempotencyKey *string `gorm:"column:idempotency_key;type:varchar(128);uniqueIndex:uk_token_orders_user_idem,priority:2;comment:创建订单幂等键"` + PaidAt *time.Time `gorm:"column:paid_at;comment:支付确认时间"` + GrantedAt *time.Time `gorm:"column:granted_at;comment:写入获取账本时间"` + CreatedAt time.Time `gorm:"column:created_at;autoCreateTime;index:idx_token_orders_user_status_created,priority:3;comment:创建时间"` + UpdatedAt time.Time `gorm:"column:updated_at;autoUpdateTime;comment:更新时间"` +} + +func (TokenOrder) TableName() string { + return "token_orders" +} + +// TokenGrant 是 Token 获取账本表。 +// +// 职责边界： +// 1. 记录购买、论坛点赞奖励、论坛导入奖励等 Token 获取事实； +// 2. event_id 是最终幂等边界，避免订单或 outbox 重试重复发放； +// 3. P0 不直接修改 users 表，quota_applied 默认为 false。 +type TokenGrant struct { + ID uint64 `gorm:"column:id;primaryKey;autoIncrement"` + EventID string `gorm:"column:event_id;type:varchar(128);not null;uniqueIndex:uk_token_grants_event;comment:幂等事件ID"` + UserID uint64 `gorm:"column:user_id;not null;index:idx_token_grants_user_source_created,priority:1;comment:获得Token的用户ID"` + Source string `gorm:"column:source;type:varchar(32);not null;index:idx_token_grants_user_source_created,priority:2;comment:purchase/forum_like/forum_import/manual"` + SourceLabel string `gorm:"column:source_label;type:varchar(64);comment:前端展示来源"` + SourceRefID *uint64 `gorm:"column:source_ref_id;index:idx_token_grants_source_ref;comment:来源业务ID，如order_id/post_id/import_id"` + OrderID *uint64 `gorm:"column:order_id;index:idx_token_grants_order;comment:购买订单ID，非购买来源为空"` + Amount int64 `gorm:"column:amount;not null;comment:获取Token数量"` + Status string `gorm:"column:status;type:varchar(32);not null;default:'recorded';index:idx_token_grants_status;comment:recorded/applied/skipped/failed"` + QuotaApplied bool `gorm:"column:quota_applied;not null;default:false;comment:是否已同步到user/auth权威额度"` + Description string `gorm:"column:description;type:varchar(255);comment:前端展示描述"` + AppliedAt *time.Time `gorm:"column:applied_at;comment:同步到权威额度时间"` + LastError *string `gorm:"column:last_error;type:text;comment:后续同步失败原因"` + CreatedAt time.Time `gorm:"column:created_at;autoCreateTime;index:idx_token_grants_user_source_created,priority:3;comment:创建时间"` + UpdatedAt time.Time `gorm:"column:updated_at;autoUpdateTime;comment:更新时间"` +} + +func (TokenGrant) TableName() string { + return "token_grants" +} + +// TokenRewardRule 是社区奖励规则表。 +// +// 职责边界： +// 1. P0 可用 seed 初始化点赞、导入奖励额度； +// 2. 不提供管理后台，规则调整先通过配置或 seed 变更； +// 3. 规则命中后的最终发放仍以 token_grants.event_id 幂等为准。 +type TokenRewardRule struct { + ID uint64 `gorm:"column:id;primaryKey;autoIncrement"` + Source string `gorm:"column:source;type:varchar(32);not null;uniqueIndex:uk_token_reward_rules_source;comment:forum_like/forum_import"` + Name string `gorm:"column:name;type:varchar(80);not null;comment:规则名称"` + Amount int64 `gorm:"column:amount;not null;comment:奖励Token数量"` + Status string `gorm:"column:status;type:varchar(32);not null;default:'active';index:idx_token_reward_rules_status;comment:active/inactive"` + ConfigJSON *string `gorm:"column:config_json;type:json;comment:预留扩展配置"` + CreatedAt time.Time `gorm:"column:created_at;autoCreateTime;comment:创建时间"` + UpdatedAt time.Time `gorm:"column:updated_at;autoUpdateTime;comment:更新时间"` +} + +func (TokenRewardRule) TableName() string { + return "token_reward_rules" +} diff --git a/backend/services/tokenstore/rpc/errors.go b/backend/services/tokenstore/rpc/errors.go new file mode 100644 index 0000000..8fb504f --- /dev/null +++ b/backend/services/tokenstore/rpc/errors.go @@ -0,0 +1,72 @@ +package rpc + +import ( + "errors" + "log" + "strings" + + "github.com/LoveLosita/smartflow/backend/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 +} diff --git a/backend/services/tokenstore/rpc/handler.go b/backend/services/tokenstore/rpc/handler.go new file mode 100644 index 0000000..7763d4b --- /dev/null +++ b/backend/services/tokenstore/rpc/handler.go @@ -0,0 +1,288 @@ +package rpc + +import ( + "context" + "errors" + + "github.com/LoveLosita/smartflow/backend/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 +} + +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), + } +} + +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 +} diff --git a/backend/services/tokenstore/rpc/pb/tokenstore.pb.go b/backend/services/tokenstore/rpc/pb/tokenstore.pb.go new file mode 100644 index 0000000..249f9e7 --- /dev/null +++ b/backend/services/tokenstore/rpc/pb/tokenstore.pb.go @@ -0,0 +1,209 @@ +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"` +} + +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() {} diff --git a/backend/services/tokenstore/rpc/pb/tokenstore_grpc.pb.go b/backend/services/tokenstore/rpc/pb/tokenstore_grpc.pb.go new file mode 100644 index 0000000..1c5fd54 --- /dev/null +++ b/backend/services/tokenstore/rpc/pb/tokenstore_grpc.pb.go @@ -0,0 +1,171 @@ +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" +) + +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) +} + +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 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) +} + +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 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) + }), + }, + Streams: []grpc.StreamDesc{}, + Metadata: "tokenstore.proto", +} diff --git a/backend/services/tokenstore/rpc/server.go b/backend/services/tokenstore/rpc/server.go new file mode 100644 index 0000000..e02628c --- /dev/null +++ b/backend/services/tokenstore/rpc/server.go @@ -0,0 +1,73 @@ +package rpc + +import ( + "errors" + "log" + "strings" + "time" + + "github.com/LoveLosita/smartflow/backend/services/tokenstore/rpc/pb" + tokenstoresv "github.com/LoveLosita/smartflow/backend/services/tokenstore/sv" + "github.com/zeromicro/go-zero/core/service" + "github.com/zeromicro/go-zero/zrpc" + "google.golang.org/grpc" +) + +const ( + defaultListenOn = "0.0.0.0:9083" + 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 +} diff --git a/backend/services/tokenstore/rpc/tokenstore.proto b/backend/services/tokenstore/rpc/tokenstore.proto new file mode 100644 index 0000000..bc3eb33 --- /dev/null +++ b/backend/services/tokenstore/rpc/tokenstore.proto @@ -0,0 +1,141 @@ +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); +} + +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; +} + +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; +} diff --git a/backend/services/tokenstore/sv/service.go b/backend/services/tokenstore/sv/service.go new file mode 100644 index 0000000..b2a360b --- /dev/null +++ b/backend/services/tokenstore/sv/service.go @@ -0,0 +1,107 @@ +package sv + +import ( + "context" + "errors" + + 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 + grantOutlet TokenGrantOutlet +} + +func New(opts Options) *Service { + return &Service{ + db: 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 +} + +// ListProducts 是商品列表用例占位，第四步实现真实查询。 +func (s *Service) ListProducts(ctx context.Context, actorUserID uint64) ([]tokencontracts.TokenProductView, error) { + _ = ctx + _ = actorUserID + return nil, ErrNotImplemented +} + +// GetSummary 是 Token 概览用例占位，第四步实现 grant 账本聚合。 +func (s *Service) GetSummary(ctx context.Context, actorUserID uint64) (*tokencontracts.TokenSummary, error) { + _ = ctx + _ = actorUserID + return nil, ErrNotImplemented +} + +// CreateOrder 是创建订单用例占位，第四步实现商品读取、订单幂等和金额快照。 +func (s *Service) CreateOrder(ctx context.Context, req tokencontracts.CreateTokenOrderRequest) (*tokencontracts.TokenOrderView, error) { + _ = ctx + _ = req + return nil, ErrNotImplemented +} + +// ListOrders 是订单列表用例占位，第四步实现用户维度分页查询。 +func (s *Service) ListOrders(ctx context.Context, req tokencontracts.ListTokenOrdersRequest) ([]tokencontracts.TokenOrderView, tokencontracts.PageResult, error) { + _ = ctx + _ = req + return nil, tokencontracts.PageResult{}, ErrNotImplemented +} + +// GetOrder 是订单详情用例占位，第四步实现订单归属校验。 +func (s *Service) GetOrder(ctx context.Context, actorUserID uint64, orderID uint64) (*tokencontracts.TokenOrderView, error) { + _ = ctx + _ = actorUserID + _ = orderID + return nil, ErrNotImplemented +} + +// MockPaidOrder 是 P0 mock paid 用例占位，第四步实现支付态流转和 grant 账本。 +func (s *Service) MockPaidOrder(ctx context.Context, req tokencontracts.MockPaidOrderRequest) (*tokencontracts.TokenOrderView, error) { + _ = ctx + _ = req + return nil, ErrNotImplemented +} + +// ListGrants 是 Token 获取记录用例占位，第四步实现账本分页查询。 +func (s *Service) ListGrants(ctx context.Context, req tokencontracts.ListTokenGrantsRequest) ([]tokencontracts.TokenGrantView, tokencontracts.PageResult, error) { + _ = ctx + _ = req + return nil, tokencontracts.PageResult{}, ErrNotImplemented +} diff --git a/backend/shared/contracts/taskclassforum/types.go b/backend/shared/contracts/taskclassforum/types.go new file mode 100644 index 0000000..f7007d9 --- /dev/null +++ b/backend/shared/contracts/taskclassforum/types.go @@ -0,0 +1,143 @@ +package taskclassforum + +// PageResult 是计划广场分页响应的跨层契约。 +// +// 职责边界： +// 1. 只描述分页元数据，不负责查询和排序逻辑； +// 2. Items 由具体接口决定，避免为了 P0 引入复杂泛型到 RPC 边界； +// 3. HTTP 层和 RPC 层需要保持字段语义一致。 +type PageResult struct { + Page int `json:"page"` + PageSize int `json:"page_size"` + Total int `json:"total"` + HasMore bool `json:"has_more"` +} + +// UserBrief 是计划广场前端展示作者和评论人的最小用户信息。 +type UserBrief struct { + UserID uint64 `json:"user_id"` + Nickname string `json:"nickname"` + AvatarURL string `json:"avatar_url"` +} + +// TemplateSummary 是列表卡片里的模板摘要。 +type TemplateSummary struct { + TaskCount int `json:"task_count"` + Mode string `json:"mode"` + StartDate string `json:"start_date"` + EndDate string `json:"end_date"` + StrategyLabels []string `json:"strategy_labels"` +} + +// ForumPostCounters 是帖子计数字段快照。 +type ForumPostCounters struct { + LikeCount int64 `json:"like_count"` + CommentCount int64 `json:"comment_count"` + ImportCount int64 `json:"import_count"` +} + +// ForumPostViewerState 是当前登录用户相对该帖子的状态。 +type ForumPostViewerState struct { + Liked bool `json:"liked"` + ImportedOnce bool `json:"imported_once"` +} + +// ForumTagItem 是计划广场标签筛选区的最小展示单元。 +type ForumTagItem struct { + Tag string `json:"tag"` + PostCount int `json:"post_count"` +} + +// ForumPostBrief 是计划列表和详情头部共用的帖子摘要。 +type ForumPostBrief struct { + PostID uint64 `json:"post_id"` + Title string `json:"title"` + Summary string `json:"summary"` + Tags []string `json:"tags"` + Author UserBrief `json:"author"` + TemplateSummary TemplateSummary `json:"template_summary"` + Counters ForumPostCounters `json:"counters"` + ViewerState ForumPostViewerState `json:"viewer_state"` + Status string `json:"status"` + CreatedAt string `json:"created_at"` +} + +// TemplateItemPreview 是详情页展示的任务条目快照。 +type TemplateItemPreview struct { + ItemID uint64 `json:"item_id"` + Order int `json:"order"` + Content string `json:"content"` +} + +// TemplateDetail 是论坛模板快照的前端展示结构。 +type TemplateDetail struct { + Mode string `json:"mode"` + StartDate string `json:"start_date"` + EndDate string `json:"end_date"` + StrategyLabels []string `json:"strategy_labels"` + TaskCount int `json:"task_count"` + ItemsPreview []TemplateItemPreview `json:"items_preview"` +} + +// ForumPostDetail 是计划详情接口响应主体。 +type ForumPostDetail struct { + Post ForumPostBrief `json:"post"` + Template TemplateDetail `json:"template"` +} + +// ForumCommentNode 是服务层组装后的多层评论树节点。 +type ForumCommentNode struct { + CommentID uint64 `json:"comment_id"` + PostID uint64 `json:"post_id"` + ParentCommentID *uint64 `json:"parent_comment_id"` + Content string `json:"content"` + Status string `json:"status"` + Author UserBrief `json:"author"` + CanDelete bool `json:"can_delete"` + CreatedAt string `json:"created_at"` + DeletedAt *string `json:"deleted_at"` + Children []ForumCommentNode `json:"children"` +} + +// CreateForumPostRequest 是发布计划请求契约。 +type CreateForumPostRequest struct { + ActorUserID uint64 `json:"actor_user_id"` + TaskClassID uint64 `json:"task_class_id"` + Title string `json:"title"` + Summary string `json:"summary"` + Tags []string `json:"tags"` + IdempotencyKey string `json:"idempotency_key"` +} + +// CreateForumCommentRequest 是发表评论或回复请求契约。 +type CreateForumCommentRequest struct { + ActorUserID uint64 `json:"actor_user_id"` + PostID uint64 `json:"post_id"` + Content string `json:"content"` + ParentCommentID *uint64 `json:"parent_comment_id"` + IdempotencyKey string `json:"idempotency_key"` +} + +// ImportForumPostRequest 是一键导入请求契约。 +type ImportForumPostRequest struct { + ActorUserID uint64 `json:"actor_user_id"` + PostID uint64 `json:"post_id"` + TargetTitle string `json:"target_title"` + IdempotencyKey string `json:"idempotency_key"` +} + +// DeleteForumCommentResult 是删除评论后的状态回执。 +type DeleteForumCommentResult struct { + CommentID uint64 `json:"comment_id"` + Status string `json:"status"` +} + +// ImportForumPostResult 是一键导入后的回执。 +type ImportForumPostResult struct { + ImportID uint64 `json:"import_id"` + PostID uint64 `json:"post_id"` + NewTaskClassID uint64 `json:"new_task_class_id"` + TaskClassTitle string `json:"task_class_title"` + ImportCount int64 `json:"import_count"` + CreatedAt string `json:"created_at"` +} diff --git a/backend/shared/contracts/tokenstore/types.go b/backend/shared/contracts/tokenstore/types.go new file mode 100644 index 0000000..ff98025 --- /dev/null +++ b/backend/shared/contracts/tokenstore/types.go @@ -0,0 +1,109 @@ +package tokenstore + +// PageResult 是 token-store 分页响应的跨层契约。 +type PageResult struct { + Page int `json:"page"` + PageSize int `json:"page_size"` + Total int `json:"total"` + HasMore bool `json:"has_more"` +} + +// TokenSummary 是 Token 商店概览响应。 +// +// 职责边界： +// 1. P0 展示 token-store 已记录的获取事实； +// 2. 不承诺这些 Token 已经同步到 user/auth 权威额度； +// 3. 后续接入 user/auth 后可把 QuotaSyncStatus 调整为 synced。 +type TokenSummary struct { + RecordedTokenTotal int64 `json:"recorded_token_total"` + AppliedTokenTotal int64 `json:"applied_token_total"` + PendingApplyTokenTotal int64 `json:"pending_apply_token_total"` + QuotaSyncStatus string `json:"quota_sync_status"` + Tip string `json:"tip"` +} + +// TokenProductView 是商品卡片展示结构。 +type TokenProductView struct { + ProductID uint64 `json:"product_id"` + 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"` +} + +// TokenGrantView 是 Token 获取记录展示结构。 +type TokenGrantView struct { + GrantID uint64 `json:"grant_id"` + EventID string `json:"event_id"` + Source string `json:"source"` + SourceLabel string `json:"source_label"` + Amount int64 `json:"amount"` + Status string `json:"status"` + QuotaApplied bool `json:"quota_applied"` + Description string `json:"description"` + CreatedAt string `json:"created_at"` +} + +// TokenOrderView 是订单展示结构。 +type TokenOrderView struct { + OrderID uint64 `json:"order_id"` + OrderNo string `json:"order_no"` + Status string `json:"status"` + TokenAmount int64 `json:"token_amount"` + AmountCent int64 `json:"amount_cent"` + PriceText string `json:"price_text"` + Currency string `json:"currency"` + PaymentMode string `json:"payment_mode"` + Grant *TokenGrantView `json:"grant"` + CreatedAt string `json:"created_at"` + PaidAt *string `json:"paid_at"` + GrantedAt *string `json:"granted_at"` +} + +// CreateTokenOrderRequest 是创建订单请求契约。 +type CreateTokenOrderRequest struct { + ActorUserID uint64 `json:"actor_user_id"` + ProductID uint64 `json:"product_id"` + Quantity int `json:"quantity"` + IdempotencyKey string `json:"idempotency_key"` +} + +// ListTokenOrdersRequest 是订单列表查询契约。 +type ListTokenOrdersRequest struct { + ActorUserID uint64 `json:"actor_user_id"` + Page int `json:"page"` + PageSize int `json:"page_size"` + Status string `json:"status"` +} + +// MockPaidOrderRequest 是 P0 mock paid 请求契约。 +type MockPaidOrderRequest struct { + ActorUserID uint64 `json:"actor_user_id"` + OrderID uint64 `json:"order_id"` + MockChannel string `json:"mock_channel"` + IdempotencyKey string `json:"idempotency_key"` +} + +// ListTokenGrantsRequest 是 Token 获取记录列表查询契约。 +type ListTokenGrantsRequest struct { + ActorUserID uint64 `json:"actor_user_id"` + Page int `json:"page"` + PageSize int `json:"page_size"` + Source string `json:"source"` +} + +// TokenGrantRecord 是 token-store 内部发放出口使用的获取事实。 +type TokenGrantRecord struct { + EventID string `json:"event_id"` + UserID uint64 `json:"user_id"` + Source string `json:"source"` + SourceRefID uint64 `json:"source_ref_id"` + OrderID uint64 `json:"order_id"` + Amount int64 `json:"amount"` + Description string `json:"description"` +} diff --git a/docs/backend/学习计划论坛与Token商店PRD.md b/docs/backend/学习计划论坛与Token商店PRD.md deleted file mode 100644 index a8ecc1e..0000000 --- a/docs/backend/学习计划论坛与Token商店PRD.md +++ /dev/null @@ -1,203 +0,0 @@ -# 学习计划论坛与 Token 商店 PRD - -## 1. 文档定位 - -本文只记录当前需要讨论和快速推进的核心产品口径，不展开完整交互稿、运营后台和支付细节。 - -本轮目标是新增两个终态服务模块： - -1. `taskclass-forum`：支持用户分享 TaskClass 学习计划，并让其他用户一键导入。 -2. `token-store`：支持 Token 商品购买、活动奖励和发放账本。 - -两个模块后续都放在 `backend/services` 下，以独立服务为目标设计；当前仓库工作区未干净前只讨论 PRD，不进入代码实现。 - -## 2. 背景与目标 - -当前产品已经具备用户自建 TaskClass、智能排程和 Token 额度门禁能力。下一阶段希望补上社区化与商业化闭环： - -1. 用户可以把自己的复习计划分享出去，形成可浏览、可点赞、可评论、可复用的学习计划论坛。 -2. 其他用户可以一键导入计划模板，快速生成自己的 TaskClass。 -3. 被点赞、被导入等社区行为可以转化为 Token 激励。 -4. 用户可以通过 Token 商店购买或领取 Token，为后续高频 Agent 使用建立基础商业闭环。 - -## 3. 模块一：学习计划论坛 - -### 3.1 产品定位 - -学习计划论坛不是普通帖子论坛，而是“帖子 + TaskClass 模板快照”的社区。 - -用户发布时，系统从用户自己的 TaskClass 复制一份模板快照。其他用户导入时，再从快照生成自己的 TaskClass 副本。 - -快照原则： - -1. 发布后不直接引用原作者的 `task_classes` / `task_items`。 -2. 原作者后续修改自己的计划，不影响已发布模板。 -3. 导入用户拿到的是自己的 TaskClass 副本，后续可自由编辑。 -4. 不分享 `embedded_time`、schedule 绑定、用户私有排程状态。 - -### 3.2 P0 功能 - -1. 发布学习计划：用户选择一个 TaskClass，填写标题、简介、标签后发布。 -2. 浏览列表：支持分页查看公开计划，按最新、点赞数、导入数排序。 -3. 查看详情：展示计划说明、TaskClass 配置摘要和任务条目预览。 -4. 点赞：同一用户对同一帖子只能点赞一次，可取消点赞。 -5. 评论：支持基础评论列表和发表评论，P0 不做楼中楼。 -6. 一键导入：从论坛模板复制出当前用户自己的 TaskClass。 -7. 基础激励：模板获得点赞或导入后，可触发 Token 奖励事件。 - -### 3.3 P0 不做 - -1. 不做复杂推荐算法。 -2. 不做关注、私信、用户主页。 -3. 不做富文本编辑器，先用纯文本简介。 -4. 不做审核后台，先预留状态字段。 -5. 不直接把模板应用进 schedule；导入后由用户走现有 TaskClass / 排程链路。 - -### 3.4 核心实体 - -1. `forum_posts`：帖子主体，记录作者、标题、简介、状态、点赞数、评论数、导入数。 -2. `forum_post_templates`：TaskClass 快照，记录模式、日期范围、策略、约束配置等。 -3. `forum_post_template_items`：TaskClassItem 快照，只记录 order/content 等模板信息。 -4. `forum_likes`：点赞幂等记录。 -5. `forum_comments`：评论记录。 -6. `forum_imports`：导入记录，记录从哪个帖子导入到哪个用户和新 TaskClass ID。 - -### 3.5 关键流程 - -发布流程： - -1. 用户选择自己的 TaskClass。 -2. `taskclass-forum` 通过 TaskClass 读取端口拿到完整模板。 -3. 服务过滤私有字段，生成论坛快照。 -4. 写入帖子和模板快照。 - -导入流程： - -1. 用户点击一键导入。 -2. `taskclass-forum` 读取帖子模板快照。 -3. 通过 TaskClass 写入端口为当前用户创建 TaskClass 副本。 -4. 写入导入记录并增加导入计数。 -5. 可异步发布 Token 奖励事件。 - -## 4. 模块二：Token 商店 - -### 4.1 产品定位 - -Token 商店负责 Token 的购买、奖励、发放和账本，不负责登录鉴权，也不直接承载 Agent 消耗统计。 - -`user/auth` 继续负责用户 Token quota 的权威判断；`token-store` 只负责产生“发放 Token”的业务事实，并通过跨服务契约通知 `user/auth` 增加用户额度。 - -### 4.2 P0 功能 - -1. 商品列表：展示可购买 Token 包。 -2. 创建订单：用户选择商品生成订单。 -3. 支付确认：P0 先支持 mock paid 或管理端确认 paid，不接真实支付网关。 -4. Token 发放：订单支付成功后发放 Token。 -5. 奖励发放：支持论坛点赞、导入等事件触发奖励。 -6. 发放账本：所有发放必须有幂等 event_id，避免重复加额度。 - -### 4.3 P0 不做 - -1. 不接真实微信 / 支付宝 / Stripe。 -2. 不做退款、发票、优惠券。 -3. 不做复杂会员体系。 -4. 不直接改 `users.token_usage`，避免和消费统计混淆。 - -### 4.4 核心实体 - -1. `token_products`：Token 商品。 -2. `token_orders`：订单。 -3. `token_grants`：Token 发放账本，记录购买、奖励、补偿等来源。 -4. `token_reward_rules`：奖励规则，P0 可先用配置或简单表。 - -### 4.5 关键流程 - -购买流程： - -1. 用户选择商品并创建订单。 -2. 订单进入 `pending`。 -3. P0 通过 mock paid 或管理端确认，把订单置为 `paid`。 -4. `token-store` 写入 token grant 账本。 -5. `token-store` 调用 `user/auth` 的额度发放能力。 -6. 发放成功后订单进入 `granted`。 - -奖励流程： - -1. 论坛产生点赞或导入事件。 -2. `token-store` 按奖励规则判断是否发放。 -3. 写入 token grant 账本。 -4. 调用 `user/auth` 增加额度。 - -## 5. 服务边界 - -### 5.1 `taskclass-forum` - -负责： - -1. 论坛帖子、点赞、评论、导入记录。 -2. TaskClass 模板快照。 -3. 导入时的模板复制编排。 -4. 发布社区行为事件，供 Token 激励消费。 - -不负责： - -1. TaskClass 原始表所有权。 -2. schedule 写入和排程应用。 -3. Token 额度发放。 -4. 用户登录鉴权。 - -### 5.2 `token-store` - -负责： - -1. 商品、订单、发放账本。 -2. 社区奖励规则。 -3. 幂等发放。 -4. 调用 `user/auth` 增加 Token 额度。 - -不负责： - -1. JWT、登录、注册。 -2. Agent 消耗统计。 -3. TaskClass 论坛内容。 -4. 真实第三方支付回调，P0 只预留状态机。 - -### 5.3 与现有服务关系 - -1. 论坛读取和导入 TaskClass 时，先通过端口适配旧 `TaskClassService/DAO`。 -2. 后续 `task-class` 独立成服务后，只替换端口适配器。 -3. 论坛 P0 不直接写 schedule，避免被 `schedule` 未拆服务影响。 -4. Token 商店不直接改 users 表，通过 `user/auth` 契约发放额度。 - -## 6. 事件与激励 - -P0 建议事件： - -1. `forum.post.liked`：帖子被点赞。 -2. `forum.post.imported`：帖子被导入。 -3. `token.grant.requested`：请求发放 Token。 -4. `token.grant.completed`：Token 发放完成。 - -奖励口径先从简单规则开始： - -1. 每个帖子每个用户首次点赞只奖励一次。 -2. 每个帖子每个用户首次导入只奖励一次。 -3. 同一 event_id 的 Token 发放必须幂等。 -4. 奖励额度先走配置，不在 PRD 阶段定死。 - -## 7. 当前推进策略 - -1. 当前工作区存在其它拆服务改动，本阶段只提交 PRD。 -2. 等工作区干净后，从集成分支新开功能分支或单独 git worktree。 -3. 实现时两个服务主体可以并行推进。 -4. `gateway/router`、`shared/contracts`、`shared/ports`、`outbox route`、`config` 由主代理统一收口。 -5. 先做 P0 闭环，再扩展审核、真实支付和推荐排序。 - -## 8. 待讨论问题 - -1. 论坛展示名使用“学习计划论坛”“计划广场”还是“模板市场”。 -2. 点赞奖励是否给作者、点赞者，还是双方都给。 -3. 导入奖励是否需要上限，避免刷导入。 -4. 评论是否需要删除、举报、审核状态。 -5. Token 发放应增加 `user/auth` 的 `GrantTokenQuota`，还是命名为 `AdjustTokenLimit`。 -6. P0 是否需要前端先隐藏评论，只保留后端能力。 diff --git a/docs/backend/计划广场与Token商店后端实施方案.md b/docs/backend/计划广场与Token商店后端实施方案.md new file mode 100644 index 0000000..2d1bd8e --- /dev/null +++ b/docs/backend/计划广场与Token商店后端实施方案.md @@ -0,0 +1,816 @@ +# 计划广场与 Token 商店后端实施方案 + +## 1. 文档定位 + +本文记录当前需要讨论和快速推进的核心产品口径、前后端接口契约、服务边界、事件口径和实施计划，不展开完整交互稿、运营后台和真实支付细节。 + +本轮目标是新增两个终态服务模块： + +1. `taskclass-forum`：支持用户分享 TaskClass 学习计划，并让其他用户一键导入。 +2. `token-store`：支持 Token 商品购买、活动奖励和发放账本。 + +两个模块后续都放在 `backend/services` 下，以独立服务为目标设计；当前仓库工作区未干净前只讨论方案，不进入代码实现。 + +## 2. 背景与目标 + +当前产品已经具备用户自建 TaskClass、智能排程和 Token 额度门禁能力。下一阶段希望补上社区化与商业化闭环： + +1. 用户可以把自己的复习计划分享出去，形成可浏览、可点赞、可评论、可复用的计划广场。 +2. 其他用户可以一键导入计划模板，快速生成自己的 TaskClass。 +3. 被点赞、被导入等社区行为可以转化为 Token 激励。 +4. 用户可以通过 Token 商店购买或领取 Token，为后续高频 Agent 使用建立基础商业闭环。 + +## 3. 模块一：学习计划论坛 + +### 3.1 产品定位 + +计划广场不是普通帖子论坛，而是“帖子 + TaskClass 模板快照”的社区。 + +对外展示名先使用“计划广场”。 + +用户发布时，系统从用户自己的 TaskClass 复制一份模板快照。其他用户导入时，再从快照生成自己的 TaskClass 副本。 + +快照原则： + +1. 发布后不直接引用原作者的 `task_classes` / `task_items`。 +2. 原作者后续修改自己的计划，不影响已发布模板。 +3. 导入用户拿到的是自己的 TaskClass 副本，后续可自由编辑。 +4. 不分享 `embedded_time`、schedule 绑定、用户私有排程状态。 + +### 3.2 P0 功能 + +1. 发布学习计划：用户选择一个 TaskClass，填写标题、简介、标签后发布。 +2. 浏览列表：支持分页查看公开计划，按最新、点赞数、导入数排序。 +3. 查看详情：展示计划说明、TaskClass 配置摘要和任务条目预览。 +4. 点赞：同一用户对同一帖子只能点赞一次，可取消点赞。 +5. 评论：支持发表评论、多层回复和删除自己的评论，接口返回评论树 JSON。 +6. 一键导入：从论坛模板复制出当前用户自己的 TaskClass。 +7. 基础激励：模板获得点赞或导入后，可触发 Token 奖励事件。 + +### 3.3 P0 不做 + +1. 不做复杂推荐算法。 +2. 不做关注、私信、用户主页。 +3. 不做富文本编辑器，先用纯文本简介。 +4. 不做审核后台和管理员删评，先预留状态字段。 +5. 不直接把模板应用进 schedule；导入后由用户走现有 TaskClass / 排程链路。 +6. P0 暂不做评论举报和管理员审核流。 + +### 3.4 核心实体 + +1. `forum_posts`：帖子主体，记录作者、标题、简介、状态、点赞数、评论数、导入数。 +2. `forum_post_templates`：TaskClass 快照，记录模式、日期范围、策略、约束配置等。 +3. `forum_post_template_items`：TaskClassItem 快照，只记录 order/content 等模板信息。 +4. `forum_likes`：点赞幂等记录。 +5. `forum_comments`：评论记录，使用 `parent_comment_id` 表达多层回复关系。 +6. `forum_imports`：导入记录，记录从哪个帖子导入到哪个用户和新 TaskClass ID。 + +### 3.5 关键流程 + +发布流程： + +1. 用户选择自己的 TaskClass。 +2. `taskclass-forum` 通过 TaskClass 读取端口拿到完整模板。 +3. 服务过滤私有字段，生成论坛快照。 +4. 写入帖子和模板快照。 + +评论流程： + +1. 用户可以直接评论帖子，也可以回复任意一条评论。 +2. 评论表用 `parent_comment_id` 记录父评论，根评论的 `parent_comment_id` 为空。 +3. 列表查询先按帖子读取扁平评论，再由服务层组装成多层评论树。 +4. 删除评论时 P0 只允许用户删除自己的评论，并采用软删除，保留子回复结构，避免整棵回复树断链。 +5. P0 暂不引入管理员删评、举报和审核流，后续如需治理再单独扩展。 + +导入流程： + +1. 用户点击一键导入。 +2. `taskclass-forum` 读取帖子模板快照。 +3. 通过 TaskClass 写入端口为当前用户创建 TaskClass 副本。 +4. 写入导入记录并增加导入计数。 +5. 可异步发布 Token 奖励事件。 + +## 4. 模块二：Token 商店 + +### 4.1 产品定位 + +Token 商店负责 Token 的购买、奖励、发放和账本，不负责登录鉴权，也不直接承载 Agent 消耗统计。 + +`user/auth` 继续负责用户 Token quota 的权威判断；`token-store` 只负责产生“获取 Token / 发放 Token”的业务事实和账本。本轮不新增或修改 `user/auth` 契约，先在 `token-store` 内封装 Token 获取途径和后续发放出口，等主线合并稳定后再切到 `user/auth` 的权威额度发放能力。 + +### 4.2 P0 功能 + +1. 商品列表：展示可购买 Token 包。 +2. 创建订单：用户选择商品生成订单。 +3. 支付确认：P0 先支持 mock paid 或管理端确认 paid，不接真实支付网关。 +4. Token 发放记录：订单支付成功后写入发放账本，并通过本服务内部端口封装后续发放出口。 +5. 奖励发放：支持论坛点赞、导入等事件触发奖励。 +6. 发放账本：所有发放必须有幂等 event_id，避免后续重复加额度。 + +### 4.3 P0 不做 + +1. 不接真实微信 / 支付宝 / Stripe。 +2. 不做退款、发票、优惠券。 +3. 不做复杂会员体系。 +4. 不直接改 `users.token_usage`，避免和消费统计混淆。 + +### 4.4 核心实体 + +1. `token_products`：Token 商品，P0 从表读取，并通过 seed 初始化 2-3 个商品，不做管理后台。 +2. `token_orders`：订单。 +3. `token_grants`：Token 发放账本，记录购买、奖励、补偿等来源。 +4. `token_reward_rules`：奖励规则，P0 可先用配置或简单表。 + +### 4.5 关键流程 + +购买流程： + +1. 用户选择商品并创建订单。 +2. 订单进入 `pending`。 +3. P0 通过 mock paid 或管理端确认，把订单置为 `paid`。 +4. `token-store` 写入 token grant 账本。 +5. `token-store` 通过内部发放端口记录本次 Token 获取事实，本轮不修改 `user/auth`。 +6. 发放记录写入成功后订单进入 `granted`；后续切到 `user/auth` 时只替换发放端口实现。 + +奖励流程： + +1. 论坛产生点赞或导入事件。 +2. `token-store` 按奖励规则判断是否发放。 +3. 写入 token grant 账本。 +4. 通过内部发放端口记录奖励获取事实；后续切到 `user/auth` 时只替换发放端口实现。 + +## 5. 服务边界 + +### 5.1 `taskclass-forum` + +负责： + +1. 论坛帖子、点赞、评论、导入记录。 +2. TaskClass 模板快照。 +3. 导入时的模板复制编排。 +4. 发布社区行为事件，供 Token 激励消费。 + +不负责： + +1. TaskClass 原始表所有权。 +2. schedule 写入和排程应用。 +3. Token 额度发放。 +4. 用户登录鉴权。 + +### 5.2 `token-store` + +负责： + +1. 商品、订单、发放账本。 +2. 社区奖励规则。 +3. 幂等发放。 +4. 封装 Token 获取途径和后续发放出口。 + +不负责： + +1. JWT、登录、注册。 +2. Agent 消耗统计。 +3. TaskClass 论坛内容。 +4. 真实第三方支付回调，P0 只预留状态机。 + +### 5.3 与现有服务关系 + +1. 论坛读取和导入 TaskClass 时，先通过端口适配旧 `TaskClassService/DAO`。 +2. 后续 `task-class` 独立成服务后，只替换端口适配器。 +3. 论坛 P0 不直接写 schedule，避免被 `schedule` 未拆服务影响。 +4. Token 商店本轮不直接改 users 表，也不新增或修改 `user/auth` 契约；先封装自己的 Token 获取途径和后续发放出口，等合并后再切到 `user/auth`。 + +### 5.4 并行迁移细则 + +1. 当前 `task` / `task-class` 还没有完成服务迁移时，本轮不改它们的核心模块，也不提前给它们补新的 RPC 边界，避免和另一条拆分线发生合并冲突。 +2. `taskclass-forum` 的实现层可以先通过 legacy adapter 复用现有 DAO / Service，必要时也可以直接读旧表，但这类直连只能收敛在 adapter 内，不能扩散到论坛业务层。 +3. 论坛业务层只依赖“读取 TaskClass 快照”和“写入 TaskClass 副本”这类端口，不关心底层是 DAO、Service 还是后续 RPC。 +4. 等 `task-class` 侧完成独立服务后，论坛只替换 adapter，不回改论坛领域逻辑，不重写帖子、点赞、评论和导入编排。 +5. 这轮优先保证论坛和 Token 商店自己的边界稳定，`task` 相关能力保持当前状态即可，等主线合并后再按统一节奏推进下一步迁移。 + +### 5.5 理想内部结构 + +参考 `userauth` 样板和微服务迁移总纲，两个新模块都按“`cmd` 进程入口 + `gateway/api` HTTP 适配 + `gateway/client` RPC client + `services` 服务主体”的结构推进。 + +命名约定： + +1. 产品和事件域继续使用 `taskclass-forum`、`token-store`，方便和方案、topic、事件名保持一致。 +2. Go 目录和包名建议使用 `taskclassforum`、`tokenstore`，对齐当前 `userauth` 样板，避免包名里出现连字符。 +3. 如果后续统一目录规范改成带连字符目录，也只调整目录名和 import，不改变服务内职责分层。 + +推荐目标树： + +这里是两套服务边缘入口： + +1. `gateway/api` 下放 HTTP API 入口，每个服务一个子目录。 +2. `gateway/client` 下放 zrpc client / error 反解，每个服务一个子目录。 +3. 旧 `gateway/userapi`、`gateway/userauth` 暂不在本轮调整，后续合并时再统一处理。 + +```text +backend/ +├── cmd/ +│ ├── taskclassforum/ +│ │ └── main.go +│ └── tokenstore/ +│ └── main.go +├── gateway/ +│ ├── api/ +│ │ ├── taskclassforum/ +│ │ │ ├── handler.go +│ │ │ └── routes.go +│ │ └── tokenstore/ +│ │ ├── handler.go +│ │ └── routes.go +│ └── client/ +│ ├── taskclassforum/ +│ │ ├── client.go +│ │ └── errors.go +│ └── tokenstore/ +│ ├── client.go +│ └── errors.go +├── services/ +│ ├── taskclassforum/ +│ │ ├── sv/ +│ │ │ ├── service.go +│ │ │ ├── post.go +│ │ │ ├── like.go +│ │ │ ├── comment.go +│ │ │ └── import.go +│ │ ├── dao/ +│ │ │ ├── connect.go +│ │ │ ├── post.go +│ │ │ ├── template.go +│ │ │ ├── like.go +│ │ │ ├── comment.go +│ │ │ └── import.go +│ │ ├── model/ +│ │ │ ├── forum_post.go +│ │ │ ├── forum_post_template.go +│ │ │ ├── forum_post_template_item.go +│ │ │ ├── forum_like.go +│ │ │ ├── forum_comment.go +│ │ │ └── forum_import.go +│ │ ├── internal/ +│ │ │ ├── adapter/ +│ │ │ ├── snapshot/ +│ │ │ ├── commenttree/ +│ │ │ └── event/ +│ │ └── rpc/ +│ │ ├── pb/ +│ │ ├── taskclassforum.proto +│ │ ├── errors.go +│ │ ├── handler.go +│ │ └── server.go +│ └── tokenstore/ +│ ├── sv/ +│ │ ├── service.go +│ │ ├── product.go +│ │ ├── order.go +│ │ ├── grant.go +│ │ └── reward.go +│ ├── dao/ +│ │ ├── connect.go +│ │ ├── product.go +│ │ ├── order.go +│ │ ├── grant.go +│ │ └── reward_rule.go +│ ├── model/ +│ │ ├── token_product.go +│ │ ├── token_order.go +│ │ ├── token_grant.go +│ │ └── token_reward_rule.go +│ ├── internal/ +│ │ ├── adapter/ +│ │ ├── paymentmock/ +│ │ ├── grant/ +│ │ ├── reward/ +│ │ └── event/ +│ └── rpc/ +│ ├── pb/ +│ ├── tokenstore.proto +│ ├── errors.go +│ ├── handler.go +│ └── server.go +└── shared/ + ├── contracts/ + │ ├── taskclassforum/ + │ └── tokenstore/ + ├── events/ + └── ports/ +``` + +目录职责： + +1. `cmd//main.go` 只负责读取配置、初始化资源、启动 go-zero zrpc 服务，不承载业务规则。 +2. `gateway/api/` 只负责 HTTP 参数绑定、鉴权后用户 ID 注入、调用对应 client、复用 `respond` 返回前端，不直接访问服务数据库。 +3. `gateway/client/` 只放 zrpc client 和错误反解；不要把 client 放进 `cmd`，也不要让 gateway 直接 import 服务端 DAO / model。 +4. `services//sv` 是服务主业务编排层，负责事务顺序、幂等判断、状态流转和跨端口调用。 +5. `services//dao` 只负责本服务数据库访问；`model` 只放本服务私有表模型，不放跨服务 DTO。 +6. `services//internal` 只放服务私有子能力，外部服务禁止直接 import。 +7. `services//rpc` 对齐 `userauth`，放 proto、server、handler、errors 和生成后的 `pb`。 +8. `shared/contracts`、`shared/events`、`shared/ports` 只放跨服务契约、事件 payload 和端口接口，不放 DAO、model、sv 或业务状态机。 + +`taskclassforum/internal` 建议职责： + +1. `adapter/`：承载 TaskClass 端口实现。P0 先放 legacy adapter，复用旧 DAO / Service 或临时直读旧表；后续替换为 task-class RPC adapter。 +2. `snapshot/`：负责 TaskClass 原始数据到论坛模板快照的过滤、复制和字段白名单，避免分享 `embedded_time`、schedule 绑定和私有排程状态。 +3. `commenttree/`：负责把 `forum_comments` 扁平记录组装成多层评论树，并处理软删除节点的展示兜底。 +4. `event/`：负责组装 `forum.post.liked`、`forum.post.imported` 等领域事件 payload；事件投递仍走全局 outbox 路由和服务 catalog。 + +`tokenstore/internal` 建议职责： + +1. `adapter/`：承载后续 `user/auth` 额度发放适配点。P0 先封装 `token-store` 自己的 Token 获取途径和发放出口，不新增或修改 `user/auth` 契约，也禁止直接改 `users` 表。 +2. `paymentmock/`：只处理 P0 mock paid 状态确认，不承载真实支付网关逻辑。 +3. `grant/`：封装 `token_grants` 幂等账本写入、event_id 去重和 grant 状态流转。 +4. `reward/`：封装论坛点赞、导入等奖励规则判断，P0 可先走配置或简单表。 +5. `event/`：负责组装 `token.grant.requested`、`token.grant.completed` 等事件 payload；后续真实异步化时复用服务级 outbox 基线。 + +## 6. 事件与激励 + +P0 建议事件： + +1. `forum.post.liked`：帖子被点赞。 +2. `forum.post.imported`：帖子被导入。 +3. `token.grant.requested`：请求发放 Token。 +4. `token.grant.completed`：Token 发放完成。 + +奖励口径先从简单规则开始： + +1. 点赞奖励先只给帖子作者，每个帖子每个用户首次点赞只奖励一次。 +2. 同一用户对同一计划只允许导入一次，导入奖励随该次导入记录一次。 +3. 同一 event_id 的 Token 发放必须幂等。 +4. 奖励额度先走配置，不在本方案阶段定死。 + +Outbox 使用口径： + +1. P0 用户可见主链路不强依赖 outbox：发布、点赞、评论、导入、下单、mock paid、写 grant 账本都应在服务自己的同步事务里完成。 +2. Outbox 用于异步副作用：论坛点赞 / 导入奖励事件、后续搜索索引同步、通知、排行榜刷新、运营统计，以及后续 `token-store` 到 `user/auth` 的权威额度同步。 +3. 第一版如果为了赶进度先同步写奖励账本，也必须保留事件名、payload 和 `event_id` 规则，后续切到 outbox 消费时不改业务语义。 +4. 新服务后续接入服务级 outbox 时，建议使用独立表、topic 和 consumer group，不回退到共享 outbox。 + +## 7. 后端契约初版 + +本节把前端对接草案收束成后端 P0 契约。若后续实现时发现字段和现有模型存在细小出入，允许在保持语义不变的前提下微调字段名，但必须同步更新 `docs/frontend/计划广场与Token商店对接说明.md`。 + +### 7.1 通用 HTTP 约定 + +1. 所有接口统一挂在 `/api/v1` 下。 +2. P0 默认都需要登录态，`user_id` 由 gateway 从 JWT 注入，前端不传 `user_id`。 +3. 响应复用项目统一壳：`status`、`info`、`data`。 +4. 写接口优先支持 `X-Idempotency-Key`，避免前端重复点击造成重复发布、重复评论、重复导入或重复下单。 +5. 时间字段统一返回 ISO 8601 字符串，带时区。 +6. 分页统一使用 `page`、`page_size`、`total`、`has_more`。 + +### 7.2 计划广场 HTTP 契约 + +| 功能 | 方法 | 路径 | 幂等 | +| --- | --- | --- | --- | +| 计划列表 | `GET` | `/api/v1/plan-square/posts` | 否 | +| 热门标签 | `GET` | `/api/v1/plan-square/tags` | 否 | +| 发布计划 | `POST` | `/api/v1/plan-square/posts` | 是 | +| 计划详情 | `GET` | `/api/v1/plan-square/posts/{post_id}` | 否 | +| 点赞 | `POST` | `/api/v1/plan-square/posts/{post_id}/like` | 由唯一约束兜底 | +| 取消点赞 | `DELETE` | `/api/v1/plan-square/posts/{post_id}/like` | 否 | +| 评论树 | `GET` | `/api/v1/plan-square/posts/{post_id}/comments` | 否 | +| 发表评论 / 回复 | `POST` | `/api/v1/plan-square/posts/{post_id}/comments` | 是 | +| 删除自己的评论 | `DELETE` | `/api/v1/plan-square/comments/{comment_id}` | 否 | +| 一键导入 | `POST` | `/api/v1/plan-square/posts/{post_id}/import` | 是 | + +核心请求 DTO： + +```go +type CreateForumPostRequest struct { + TaskClassID uint64 `json:"task_class_id"` + Title string `json:"title"` + Summary string `json:"summary"` + Tags []string `json:"tags"` +} + +type CreateForumCommentRequest struct { + Content string `json:"content"` + ParentCommentID *uint64 `json:"parent_comment_id"` +} + +type ImportForumPostRequest struct { + TargetTitle string `json:"target_title"` +} +``` + +核心响应 DTO： + +```go +type ForumPostBrief struct { + PostID uint64 `json:"post_id"` + Title string `json:"title"` + Summary string `json:"summary"` + Tags []string `json:"tags"` + Author UserBrief `json:"author"` + TemplateSummary TemplateSummary `json:"template_summary"` + Counters ForumPostCounters `json:"counters"` + ViewerState ForumPostViewerState `json:"viewer_state"` + Status string `json:"status"` + CreatedAt string `json:"created_at"` +} + +type ForumPostDetail struct { + Post ForumPostBrief `json:"post"` + Template TemplateDetail `json:"template"` +} + +type ForumCommentNode struct { + CommentID uint64 `json:"comment_id"` + PostID uint64 `json:"post_id"` + ParentCommentID *uint64 `json:"parent_comment_id"` + Content string `json:"content"` + Status string `json:"status"` + Author UserBrief `json:"author"` + CanDelete bool `json:"can_delete"` + CreatedAt string `json:"created_at"` + DeletedAt *string `json:"deleted_at"` + Children []ForumCommentNode `json:"children"` +} +``` + +字段口径： + +1. `ForumPostBrief.status` P0 先使用 `published`，后续审核可扩展 `hidden`、`deleted`、`pending_review`。 +2. `ForumCommentNode.status` P0 使用 `visible`、`deleted`。 +3. `CanDelete` 由后端根据当前用户判断，前端只按字段展示删除入口。 +4. `TemplateDetail.items_preview` 来自论坛快照，不读取原作者当前 TaskClass。 +5. 一键导入成功只返回新 TaskClass ID，不直接写 schedule。 + +### 7.3 Token 商店 HTTP 契约 + +| 功能 | 方法 | 路径 | 幂等 | +| --- | --- | --- | --- | +| Token 概览 | `GET` | `/api/v1/token-store/summary` | 否 | +| 商品列表 | `GET` | `/api/v1/token-store/products` | 否 | +| 创建订单 | `POST` | `/api/v1/token-store/orders` | 是 | +| 订单列表 | `GET` | `/api/v1/token-store/orders` | 否 | +| 订单详情 | `GET` | `/api/v1/token-store/orders/{order_id}` | 否 | +| mock paid | `POST` | `/api/v1/token-store/orders/{order_id}/mock-paid` | 是 | +| Token 获取记录 | `GET` | `/api/v1/token-store/grants` | 否 | + +核心请求 DTO： + +```go +type CreateTokenOrderRequest struct { + ProductID uint64 `json:"product_id"` + Quantity int `json:"quantity"` +} + +type MockPaidOrderRequest struct { + MockChannel string `json:"mock_channel"` +} +``` + +核心响应 DTO： + +```go +type TokenSummary struct { + RecordedTokenTotal int64 `json:"recorded_token_total"` + AppliedTokenTotal int64 `json:"applied_token_total"` + PendingApplyTokenTotal int64 `json:"pending_apply_token_total"` + QuotaSyncStatus string `json:"quota_sync_status"` + Tip string `json:"tip"` +} + +type TokenProductView struct { + ProductID uint64 `json:"product_id"` + 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"` +} + +type TokenOrderView struct { + OrderID uint64 `json:"order_id"` + OrderNo string `json:"order_no"` + Status string `json:"status"` + TokenAmount int64 `json:"token_amount"` + AmountCent int64 `json:"amount_cent"` + PriceText string `json:"price_text"` + Currency string `json:"currency"` + PaymentMode string `json:"payment_mode"` + Grant *TokenGrantView `json:"grant"` + CreatedAt string `json:"created_at"` + PaidAt *string `json:"paid_at"` + GrantedAt *string `json:"granted_at"` +} + +type TokenGrantView struct { + GrantID uint64 `json:"grant_id"` + EventID string `json:"event_id"` + Source string `json:"source"` + SourceLabel string `json:"source_label"` + Amount int64 `json:"amount"` + Status string `json:"status"` + QuotaApplied bool `json:"quota_applied"` + Description string `json:"description"` + CreatedAt string `json:"created_at"` +} +``` + +字段口径： + +1. `TokenSummary.quota_sync_status` P0 返回 `not_connected`，后续可扩展 `partial`、`synced`。 +2. `TokenOrderView.status` 使用 `pending`、`paid`、`granted`、`closed`。 +3. `TokenGrantView.status` 使用 `recorded`、`applied`、`skipped`、`failed`。 +4. `quota_applied` P0 默认为 `false`，因为本轮不改 `user/auth`。 +5. 前端 P0 展示“累计获取 Token”，不要展示为权威可用额度。 + +### 7.4 RPC 服务契约 + +RPC 只承载 gateway 到服务主体的跨进程调用，不暴露给前端。字段可以按 proto 生成规则转成 snake_case JSON，但语义必须和 HTTP DTO 保持一致。 + +`taskclassforum` P0 方法： + +```protobuf +service TaskClassForumService { + rpc ListPosts(ListForumPostsRequest) returns (ListForumPostsResponse); + rpc ListTags(ListForumTagsRequest) returns (ListForumTagsResponse); + rpc CreatePost(CreateForumPostRPCRequest) returns (CreateForumPostRPCResponse); + rpc GetPost(GetForumPostRequest) returns (GetForumPostResponse); + rpc LikePost(LikeForumPostRequest) returns (LikeForumPostResponse); + rpc UnlikePost(UnlikeForumPostRequest) returns (UnlikeForumPostResponse); + rpc ListComments(ListForumCommentsRequest) returns (ListForumCommentsResponse); + rpc CreateComment(CreateForumCommentRPCRequest) returns (CreateForumCommentRPCResponse); + rpc DeleteComment(DeleteForumCommentRequest) returns (DeleteForumCommentResponse); + rpc ImportPost(ImportForumPostRPCRequest) returns (ImportForumPostRPCResponse); +} +``` + +`tokenstore` P0 方法： + +```protobuf +service TokenStoreService { + rpc GetSummary(GetTokenSummaryRequest) returns (GetTokenSummaryResponse); + rpc ListProducts(ListTokenProductsRequest) returns (ListTokenProductsResponse); + rpc CreateOrder(CreateTokenOrderRPCRequest) returns (CreateTokenOrderRPCResponse); + rpc ListOrders(ListTokenOrdersRequest) returns (ListTokenOrdersResponse); + rpc GetOrder(GetTokenOrderRequest) returns (GetTokenOrderResponse); + rpc MockPaidOrder(MockPaidOrderRequest) returns (MockPaidOrderResponse); + rpc ListGrants(ListTokenGrantsRequest) returns (ListTokenGrantsResponse); +} +``` + +RPC 入参通用规则： + +1. 所有需要用户态的方法都带 `actor_user_id`，由 gateway 注入。 +2. 写方法带 `idempotency_key`，由 gateway 从 `X-Idempotency-Key` 读取。 +3. 列表方法带 `page`、`page_size`、筛选字段和排序字段。 +4. RPC 层错误使用 go-zero / gRPC `error` 返回，gateway client 负责转成项目统一响应。 + +### 7.5 服务内部端口契约 + +`taskclassforum` 依赖 TaskClass 端口： + +```go +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) +} +``` + +端口口径： + +1. `GetOwnedTaskClassSnapshot` 只能读取当前用户自己的 TaskClass。 +2. `TaskClassSnapshot` 必须剔除 `embedded_time`、schedule 绑定和用户私有排程状态。 +3. P0 实现为 legacy adapter，可复用旧 DAO / Service 或收敛式直读旧表。 +4. 后续 `task-class` 服务拆出后，只替换 adapter。 + +`tokenstore` 内部发放端口： + +```go +type TokenGrantOutlet interface { + RecordAcquisition(ctx context.Context, grant TokenGrantRecord) error +} +``` + +端口口径： + +1. P0 只记录 `token-store` 自己的获取事实和账本，不新增或修改 `user/auth` 契约。 +2. 禁止直接修改 `users` 表。 +3. 后续切到 `user/auth` 时新增 adapter 实现，服务编排层不重写。 + +### 7.6 事件契约 + +P0 事件按当前服务级 outbox 思路设计，但不要求主链路第一版强依赖异步投递；如果第一版先同步写账本，也必须按下面 event_id 生成规则保留幂等口径。 + +`forum.post.liked`： + +```json +{ + "event_id": "forum.post.liked:{post_id}:{actor_user_id}", + "post_id": 10001, + "author_user_id": 88, + "actor_user_id": 91, + "reward_receiver_user_id": 88, + "reward_amount": 1, + "occurred_at": "2026-05-04T21:05:00+08:00" +} +``` + +`forum.post.imported`： + +```json +{ + "event_id": "forum.post.imported:{post_id}:{actor_user_id}", + "post_id": 10001, + "import_id": 70001, + "author_user_id": 88, + "actor_user_id": 91, + "new_task_class_id": 430, + "reward_receiver_user_id": 88, + "reward_amount": 2, + "occurred_at": "2026-05-04T21:10:00+08:00" +} +``` + +`token.grant.requested`： + +```json +{ + "event_id": "order:80001:paid", + "user_id": 91, + "source": "purchase", + "amount": 100, + "description": "购买基础 Token 包", + "occurred_at": "2026-05-04T21:00:00+08:00" +} +``` + +`token.grant.completed`： + +```json +{ + "event_id": "order:80001:paid", + "grant_id": 90001, + "user_id": 91, + "source": "purchase", + "amount": 100, + "status": "recorded", + "quota_applied": false, + "occurred_at": "2026-05-04T21:00:01+08:00" +} +``` + +事件口径： + +1. 点赞奖励只给作者，取消点赞不回滚已记录奖励。 +2. 同一用户对同一计划只允许导入一次，导入奖励随该次导入记录一次。 +3. Token 发放 P0 的 `quota_applied` 为 `false`，后续接入 `user/auth` 后再变成真实同步状态。 +4. 事件 payload 放 `backend/shared/events`；服务私有处理逻辑留在各自 `internal/event` 或 `sv`。 +5. 事件不要阻塞用户主流程；异步消费失败时依赖 `event_id` 和 grant 账本幂等重试。 + +### 7.7 幂等与唯一约束 + +论坛侧： + +1. `forum_likes` 对 `(post_id, user_id)` 建唯一约束。 +2. `forum_imports` 对 `(post_id, user_id)` 建唯一约束，同一用户同一计划只允许导入一次，并保留 `event_id`；奖励去重依赖 `token_grants.event_id`。 +3. 评论创建支持 `X-Idempotency-Key`，避免重复提交。 +4. 删除评论是软删除，重复删除同一条自己的评论返回成功态。 + +Token 侧： + +1. `token_orders.order_no` 唯一。 +2. `token_grants.event_id` 唯一，是所有发放事实的最终幂等边界。 +3. mock paid 重复调用同一订单时，不重复创建 grant。 +4. 创建订单使用 `X-Idempotency-Key` 时，同一用户同一 key 返回同一订单。 + +### 7.8 错误码初版 + +| status | 场景 | 前端处理 | +| --- | --- | --- | +| `40001` | 参数错误 | 展示 `info` | +| `40003` | 未登录或登录态失效 | 跳登录 | +| `40004` | 资源不存在或已下架 | 展示空态或返回列表 | +| `40009` | 重复操作，如已点赞 | 以返回状态刷新 UI | +| `40013` | 无权限，如删除他人评论 | 展示 `info` | +| `40029` | 请求过于频繁 | 展示稍后重试 | +| `50000` | 服务内部错误 | 展示通用失败提示 | + +错误处理口径： + +1. 业务错误不要把 RPC 内部错误原文透给前端。 +2. gateway client 负责把服务错误转成统一响应。 +3. 幂等重复不应默认作为失败；能返回已有结果时优先返回已有结果。 + +## 8. 当前推进策略 + +1. 当前工作区存在其它拆服务改动，本阶段只提交方案文档。 +2. 等工作区干净后，从集成分支新开功能分支或单独 git worktree。 +3. 实现时两个服务主体可以并行推进。 +4. `gateway/router`、`shared/contracts`、`shared/ports`、`outbox route`、`config` 由主代理统一收口。 +5. 先做 P0 闭环，再扩展审核、真实支付和推荐排序。 +6. `task` / `task-class` 未迁出前，论坛侧优先走 legacy adapter，不提前把本轮推进绑死在 task 迁移完成之后。 + +## 9. 已确认口径 + +1. 论坛展示名使用“计划广场”。 +2. 点赞奖励只给帖子作者。 +3. 同一用户对同一计划只允许导入一次，前端根据 `imported_once` 刷新按钮状态，奖励随该次导入记录一次。 +4. 评论 P0 支持用户删除自己的评论，暂不引入管理员删评、举报和审核流。 +5. 评论层级后端不硬限制，数据库只存 `parent_comment_id`，服务层负责组装评论树；前端可以按体验做折叠或缩进。 +6. Token 发放本轮不改 `user/auth`，先在 `token-store` 内封装 Token 获取途径和后续发放出口，后续合并稳定后再切到 `user/auth` 的权威额度发放能力。 +7. Token 商品从 `token_products` 表读取，P0 通过 seed 初始化商品，不做管理后台。 +8. 前端正常展示评论，不隐藏评论能力。 + +## 10. 实施计划 + +### 10.1 P0 实施原则 + +1. 本轮先把 `taskclass-forum` 和 `token-store` 两个新服务跑通，不改 `task` / `task-class` 核心模块，不改 `user/auth` 契约。 +2. 论坛依赖 TaskClass 的能力必须收敛在 legacy adapter 内，后续 `task-class` RPC 合并后只替换 adapter。 +3. Token 获取和发放先记录在 `token-store` 自己的账本里，不直接改 `users` 表。 +4. 搜索 P0 先走 MySQL，服务层预留 `PostSearchPort`；后续需要中文分词、相关性排序或内容检索时，再替换为 Elasticsearch / OpenSearch adapter。 +5. 商品 P0 从 `token_products` 表读取，通过 seed 初始化 2-3 个商品；不做商品管理后台。 +6. 同一用户对同一计划只允许导入一次，后端通过唯一约束兜底，前端通过 `imported_once` 刷新按钮状态。 +7. 评论层级不硬限制，表里只存 `parent_comment_id`，服务层按帖子组装评论树。 +8. Outbox 总线只承载异步副作用，不承载 P0 用户可见主链路，避免联调期被 relay / consumer 状态拖慢。 + +### 10.2 表结构与迁移 + +第一步先落服务私有表和必要唯一约束： + +1. 计划广场表：`forum_posts`、`forum_post_templates`、`forum_post_template_items`、`forum_likes`、`forum_comments`、`forum_imports`。 +2. Token 商店表：`token_products`、`token_orders`、`token_grants`、`token_reward_rules`。 +3. `forum_likes` 建 `(post_id, user_id)` 唯一约束。 +4. `forum_imports` 建 `(post_id, user_id)` 唯一约束，保证同一用户同一计划只导入一次。 +5. `forum_comments` 建 `post_id`、`parent_comment_id`、`created_at` 索引，支撑按帖子读取扁平评论后组树。 +6. `token_orders.order_no` 唯一，`token_grants.event_id` 唯一。 +7. `token_products` 通过 seed 初始化商品，后续如要管理后台再单独扩展。 + +### 10.3 服务骨架 + +第二步搭建目录和进程骨架： + +1. 新增 `backend/cmd/taskclassforum`、`backend/cmd/tokenstore`。 +2. 新增 `backend/services/taskclassforum`、`backend/services/tokenstore`，内部按 `sv`、`dao`、`model`、`internal`、`rpc` 分层。 +3. 新增 `backend/gateway/api/taskclassforum`、`backend/gateway/api/tokenstore` 承载 HTTP 入口。 +4. 新增 `backend/gateway/client/taskclassforum`、`backend/gateway/client/tokenstore` 承载 zrpc client 和错误反解。 +5. `gateway/router`、配置、outbox route、shared contracts 由主代理统一收口，避免多处同时改同一个装配点。 + +### 10.4 计划广场 P0 + +第三步实现计划广场闭环： + +1. 发布计划：读取用户自己的 TaskClass，生成论坛模板快照，写入帖子和模板表。 +2. 列表和详情：先用 MySQL 查询 `title`、`summary`、`tags`、状态和计数字段，支持 `latest`、`likes`、`imports` 排序。 +3. 点赞 / 取消点赞：用唯一约束保证同一用户只点赞一次，点赞奖励事件只给作者。 +4. 评论：发表评论、回复任意评论、删除自己的评论；删除采用软删除，保留子回复结构。 +5. 评论树：按帖子读取扁平评论，服务层按 `parent_comment_id` 组装树；后端不限制层级。 +6. 一键导入：同一用户同一帖子只允许导入一次，只生成当前用户自己的 TaskClass，不写 schedule。 + +### 10.5 Token 商店 P0 + +第四步实现 Token 商店闭环： + +1. 商品列表从 `token_products` 表读取，P0 商品由 seed 提供。 +2. 创建订单：写入 `token_orders`，状态为 `pending`。 +3. mock paid：把订单置为已支付，并写入 `token_grants`。 +4. 获取记录：从 `token_grants` 分页查询购买、点赞奖励、导入奖励等记录。 +5. Token 概览：展示 `token-store` 已记录的累计获取 Token；P0 不展示为 `user/auth` 权威可用额度。 +6. 预留 `TokenGrantOutlet`，后续切到 `user/auth` 时只替换发放出口。 + +### 10.6 Outbox 总线接入 + +第五步按复杂度分两档推进 outbox： + +1. P0 主链路同步闭环：计划发布、点赞状态、评论、导入、订单、mock paid 和 grant 账本都同步写入本服务数据库。 +2. P0 可同步写奖励账本，但必须按 `forum.post.liked`、`forum.post.imported` 生成稳定 `event_id`，保证后续切异步时可复用同一幂等边界。 +3. 若本轮顺手接入服务级 outbox，建议新增 `taskclass_forum_outbox_messages`、`token_store_outbox_messages`，对应 topic 为 `smartflow.taskclass-forum.outbox`、`smartflow.token-store.outbox`。 +4. 对应 consumer group 建议为 `smartflow-taskclass-forum-outbox-consumer`、`smartflow-token-store-outbox-consumer`，延续当前服务级 topic / group 隔离规则。 +5. `taskclass-forum` 适合发布 `forum.post.liked`、`forum.post.imported`、后续 `forum.post.published`、`forum.post.updated`、`forum.post.deleted`。 +6. `token-store` 适合发布 `token.grant.requested`、`token.grant.completed`，后续接 `user/auth` 时再消费或转发到权威额度同步。 +7. 搜索索引、排行榜、通知、运营统计都走 outbox 异步消费，不进入 HTTP 主事务。 +8. relay / consumer 失败时不得影响用户已经成功的主操作，通过 outbox 重试和 `token_grants.event_id` 幂等兜底。 + +### 10.7 缓存策略 + +P0 不引入复杂缓存，优先靠表结构、索引和分页控制复杂度： + +1. 评论树 P0 不做整树缓存。评论是强互动数据，新增、回复、删除都会影响树结构，缓存失效成本高；当前场景多数用户看完即切，直接查库并组树更简单。 +2. 评论接口按根评论分页，后端读取当前页根评论及其子孙评论后组树，避免一次拉完整帖子全部评论。 +3. 帖子列表和详情 P0 可先不缓存；如果出现热点，再对列表首屏或详情头部做短 TTL 缓存，并在点赞、评论、导入后按帖子维度失效。 +4. 点赞数、评论数、导入数优先存 `forum_posts` 计数字段，写操作事务内增减，避免每次列表都聚合统计。 +5. `token_products` 读取频率高、变化少，可做短 TTL 缓存；但 P0 直接读表也可以接受。 +6. 后续若上 Elasticsearch，只缓存搜索索引，不改变前端接口和论坛业务编排。 + +### 10.8 联调与验收 + +最后按接口闭环做 smoke： + +1. 发布计划后，列表和详情能看到模板快照。 +2. 点赞成功后，点赞状态和计数刷新，作者获得一条 Token 获取记录。 +3. 评论支持多层回复；删除自己的评论后，子回复仍保留。 +4. 同一用户同一计划第二次导入被后端拒绝或返回已导入状态，前端按钮状态保持一致。 +5. mock paid 后订单进入 `granted`，`token_grants` 只写一条幂等记录。 +6. Token 概览展示累计获取 Token，但不声称已经同步到 `user/auth` 权威可用额度。 +7. 如果本轮接入 outbox，需要额外验证事件写入、投递、消费失败重试和幂等不重复发放。 diff --git a/docs/frontend/计划广场与Token商店对接说明.md b/docs/frontend/计划广场与Token商店对接说明.md new file mode 100644 index 0000000..0fef1d0 --- /dev/null +++ b/docs/frontend/计划广场与Token商店对接说明.md @@ -0,0 +1,1062 @@ +# 计划广场与 Token 商店前端对接说明 + +## 1. 文档目标 + +本文面向前端页面设计和接口联调，先把 P0 页面所需接口、字段、状态和交互流程定成初版。 + +当前确认口径： + +1. 论坛展示名使用“计划广场”。 +2. 前端正常展示评论，评论支持多层回复。 +3. 用户可以删除自己的评论；P0 暂不引入管理员删评、举报和审核流。 +4. 点赞奖励只给帖子作者。 +5. 同一用户对同一计划只允许导入一次，奖励随该次导入记录一次。 +6. Token 发放本轮不改 `user/auth`，先在 `token-store` 内封装 Token 获取途径和后续发放出口。 + +## 2. 通用约定 + +### 2.1 鉴权 + +P0 所有接口都需要登录态。 + +```http +Authorization: Bearer +``` + +### 2.2 统一响应壳 + +成功响应： + +```json +{ + "status": "10000", + "info": "success", + "data": {} +} +``` + +失败响应： + +```json +{ + "status": "40004", + "info": "计划不存在或已下架", + "data": null +} +``` + +前端处理建议： + +1. `status === "10000"` 视为成功。 +2. 非成功状态优先展示 `info`。 +3. 表单类错误可按接口返回的 `info` 直接提示，不需要前端硬编码太多文案。 + +### 2.3 幂等请求头 + +以下写操作建议前端带 `X-Idempotency-Key`： + +1. 发布计划。 +2. 发表评论。 +3. 一键导入。 +4. 创建订单。 +5. mock paid。 + +```http +X-Idempotency-Key: plan_square_publish_1710000000000_abcd +``` + +### 2.4 时间格式 + +所有时间字段使用 ISO 8601 字符串，带时区。 + +```json +"2026-05-04T20:30:00+08:00" +``` + +### 2.5 分页结构 + +分页接口统一返回： + +```json +{ + "items": [], + "page": 1, + "page_size": 20, + "total": 125, + "has_more": true +} +``` + +## 3. 页面总览 + +### 3.1 计划广场 + +前端建议页面： + +1. 计划广场列表页：展示公开计划卡片，支持排序、标签筛选和搜索。 +2. 计划详情页 / 详情抽屉：展示计划说明、任务条目预览、点赞、评论和导入按钮。 +3. 发布计划弹窗 / 页面：选择自己的 TaskClass，填写标题、简介、标签后发布。 +4. 评论区：展示多层评论树，支持回复和删除自己的评论。 + +### 3.2 Token 商店 + +前端建议页面： + +1. Token 商品页：展示 Token 包商品卡片。 +2. 订单确认 / mock paid 页：P0 可直接展示“确认支付”按钮。 +3. Token 获取记录页：展示购买、点赞奖励、导入奖励等账本记录。 +4. Token 概览组件：展示本服务记录的累计获取 Token。P0 不承诺已经同步到 `user/auth` 可用额度。 + +## 4. 路由总览 + +### 4.1 计划广场接口 + +| 功能 | 方法 | 路径 | +| --- | --- | --- | +| 计划列表 | `GET` | `/api/v1/plan-square/posts` | +| 热门标签 | `GET` | `/api/v1/plan-square/tags` | +| 发布计划 | `POST` | `/api/v1/plan-square/posts` | +| 计划详情 | `GET` | `/api/v1/plan-square/posts/{post_id}` | +| 点赞 | `POST` | `/api/v1/plan-square/posts/{post_id}/like` | +| 取消点赞 | `DELETE` | `/api/v1/plan-square/posts/{post_id}/like` | +| 评论树 | `GET` | `/api/v1/plan-square/posts/{post_id}/comments` | +| 发表评论 / 回复 | `POST` | `/api/v1/plan-square/posts/{post_id}/comments` | +| 删除自己的评论 | `DELETE` | `/api/v1/plan-square/comments/{comment_id}` | +| 一键导入 | `POST` | `/api/v1/plan-square/posts/{post_id}/import` | + +发布计划时，TaskClass 下拉列表复用现有接口： + +```http +GET /api/v1/task-class/list +``` + +### 4.2 Token 商店接口 + +| 功能 | 方法 | 路径 | +| --- | --- | --- | +| Token 概览 | `GET` | `/api/v1/token-store/summary` | +| 商品列表 | `GET` | `/api/v1/token-store/products` | +| 创建订单 | `POST` | `/api/v1/token-store/orders` | +| 订单列表 | `GET` | `/api/v1/token-store/orders` | +| 订单详情 | `GET` | `/api/v1/token-store/orders/{order_id}` | +| mock paid | `POST` | `/api/v1/token-store/orders/{order_id}/mock-paid` | +| Token 获取记录 | `GET` | `/api/v1/token-store/grants` | + +## 5. 计划广场接口详情 + +### 5.1 计划列表 + +```http +GET /api/v1/plan-square/posts?page=1&page_size=20&sort=latest&keyword=数学&tag=考研 +``` + +查询参数： + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `page` | number | 否 | 默认 `1` | +| `page_size` | number | 否 | 默认 `20`，最大建议 `50` | +| `sort` | string | 否 | `latest` / `likes` / `imports` | +| `keyword` | string | 否 | 搜索标题和简介 | +| `tag` | string | 否 | 标签筛选 | + +成功响应： + +```json +{ + "status": "10000", + "info": "success", + "data": { + "items": [ + { + "post_id": 10001, + "title": "30 天高数强化复习计划", + "summary": "适合期末前一个月快速过完重点题型。", + "tags": ["高数", "期末", "30天"], + "author": { + "user_id": 88, + "nickname": "小鹿同学", + "avatar_url": "" + }, + "template_summary": { + "task_count": 24, + "mode": "date_range", + "start_date": "2026-05-05", + "end_date": "2026-06-04", + "strategy_labels": ["每日推进", "错题复盘"] + }, + "counters": { + "like_count": 128, + "comment_count": 32, + "import_count": 45 + }, + "viewer_state": { + "liked": false, + "imported_once": true + }, + "status": "published", + "created_at": "2026-05-04T20:30:00+08:00" + } + ], + "page": 1, + "page_size": 20, + "total": 125, + "has_more": true + } +} +``` + +前端展示建议： + +1. 卡片主标题用 `title`。 +2. 副文案用 `summary`，最多展示两到三行。 +3. 标签 chips 用 `tags`。 +4. 统计区展示点赞、评论、导入次数。 +5. `viewer_state.liked` 控制点赞按钮初始态。 + +### 5.2 热门标签 + +```http +GET /api/v1/plan-square/tags?limit=20 +``` + +成功响应： + +```json +{ + "status": "10000", + "info": "success", + "data": { + "items": [ + { "tag": "考研", "post_count": 30 }, + { "tag": "高数", "post_count": 18 } + ] + } +} +``` + +### 5.3 发布计划 + +```http +POST /api/v1/plan-square/posts +Content-Type: application/json +X-Idempotency-Key: plan_square_publish_1710000000000_abcd +``` + +请求体： + +```json +{ + "task_class_id": 42, + "title": "30 天高数强化复习计划", + "summary": "适合期末前一个月快速过完重点题型。", + "tags": ["高数", "期末", "30天"] +} +``` + +字段限制： + +| 字段 | 规则 | +| --- | --- | +| `task_class_id` | 必填，只能选择当前用户自己的 TaskClass | +| `title` | 必填，建议 4 到 40 字 | +| `summary` | 可选，建议 0 到 300 字 | +| `tags` | 可选，最多 5 个，每个最多 12 字 | + +成功响应： + +```json +{ + "status": "10000", + "info": "success", + "data": { + "post_id": 10001, + "title": "30 天高数强化复习计划", + "status": "published", + "created_at": "2026-05-04T20:30:00+08:00" + } +} +``` + +前端流程建议： + +1. 先调用 `GET /api/v1/task-class/list` 获取用户自己的计划。 +2. 用户选择一个 TaskClass 后填写发布信息。 +3. 发布成功后跳转到详情页或刷新计划广场列表。 + +### 5.4 计划详情 + +```http +GET /api/v1/plan-square/posts/{post_id} +``` + +成功响应： + +```json +{ + "status": "10000", + "info": "success", + "data": { + "post": { + "post_id": 10001, + "title": "30 天高数强化复习计划", + "summary": "适合期末前一个月快速过完重点题型。", + "tags": ["高数", "期末", "30天"], + "author": { + "user_id": 88, + "nickname": "小鹿同学", + "avatar_url": "" + }, + "counters": { + "like_count": 128, + "comment_count": 32, + "import_count": 45 + }, + "viewer_state": { + "liked": false, + "imported_once": true + }, + "created_at": "2026-05-04T20:30:00+08:00" + }, + "template": { + "mode": "date_range", + "start_date": "2026-05-05", + "end_date": "2026-06-04", + "strategy_labels": ["每日推进", "错题复盘"], + "task_count": 24, + "items_preview": [ + { + "item_id": 90001, + "order": 1, + "content": "复习极限与连续，完成基础例题。" + }, + { + "item_id": 90002, + "order": 2, + "content": "整理导数公式，完成 10 道综合题。" + } + ] + } + } +} +``` + +说明： + +1. `items_preview` 是模板快照，不是原作者当前 TaskClass。 +2. 不展示 `embedded_time`、schedule 绑定和用户私有排程状态。 +3. 评论区单独调用评论树接口，避免详情首屏过重。 + +### 5.5 点赞 + +```http +POST /api/v1/plan-square/posts/{post_id}/like +``` + +成功响应： + +```json +{ + "status": "10000", + "info": "success", + "data": { + "post_id": 10001, + "liked": true, + "like_count": 129, + "reward_hint": { + "receiver": "author", + "status": "recorded", + "amount": 1 + } + } +} +``` + +说明： + +1. 同一用户对同一帖子只能点赞一次。 +2. 点赞奖励只给作者。 +3. 取消点赞不回滚已经记录的作者奖励，避免账本反复冲正。 + +### 5.6 取消点赞 + +```http +DELETE /api/v1/plan-square/posts/{post_id}/like +``` + +成功响应： + +```json +{ + "status": "10000", + "info": "success", + "data": { + "post_id": 10001, + "liked": false, + "like_count": 128 + } +} +``` + +### 5.7 评论树 + +```http +GET /api/v1/plan-square/posts/{post_id}/comments?page=1&page_size=20&sort=oldest +``` + +查询参数： + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `page` | number | 否 | 根评论分页，默认 `1` | +| `page_size` | number | 否 | 根评论分页大小，默认 `20` | +| `sort` | string | 否 | `oldest` / `latest`，默认 `oldest` | + +成功响应： + +```json +{ + "status": "10000", + "info": "success", + "data": { + "items": [ + { + "comment_id": 50001, + "post_id": 10001, + "parent_comment_id": null, + "content": "这个计划很适合期末冲刺。", + "status": "visible", + "author": { + "user_id": 91, + "nickname": "西瓜同学", + "avatar_url": "" + }, + "can_delete": true, + "created_at": "2026-05-04T20:40:00+08:00", + "deleted_at": null, + "children": [ + { + "comment_id": 50002, + "post_id": 10001, + "parent_comment_id": 50001, + "content": "我也准备照这个导入一份。", + "status": "visible", + "author": { + "user_id": 92, + "nickname": "青柠同学", + "avatar_url": "" + }, + "can_delete": false, + "created_at": "2026-05-04T20:42:00+08:00", + "deleted_at": null, + "children": [] + } + ] + } + ], + "page": 1, + "page_size": 20, + "total": 32, + "has_more": true + } +} +``` + +评论状态： + +| `status` | 前端展示 | +| --- | --- | +| `visible` | 正常展示 `content` | +| `deleted` | 展示“该评论已删除”，保留子回复 | + +### 5.8 发表评论 / 回复 + +```http +POST /api/v1/plan-square/posts/{post_id}/comments +Content-Type: application/json +X-Idempotency-Key: plan_square_comment_1710000000000_abcd +``` + +请求体： + +```json +{ + "content": "这个计划很适合期末冲刺。", + "parent_comment_id": null +} +``` + +回复某条评论时： + +```json +{ + "content": "我也准备照这个导入一份。", + "parent_comment_id": 50001 +} +``` + +字段限制： + +| 字段 | 规则 | +| --- | --- | +| `content` | 必填，建议 1 到 500 字 | +| `parent_comment_id` | 可选，传 `null` 表示根评论 | + +成功响应： + +```json +{ + "status": "10000", + "info": "success", + "data": { + "comment_id": 50003, + "post_id": 10001, + "parent_comment_id": 50001, + "content": "我也准备照这个导入一份。", + "status": "visible", + "can_delete": true, + "created_at": "2026-05-04T20:45:00+08:00" + } +} +``` + +### 5.9 删除自己的评论 + +```http +DELETE /api/v1/plan-square/comments/{comment_id} +``` + +成功响应： + +```json +{ + "status": "10000", + "info": "success", + "data": { + "comment_id": 50003, + "status": "deleted", + "content": "", + "deleted_at": "2026-05-04T20:50:00+08:00" + } +} +``` + +说明： + +1. 只能删除自己的评论。 +2. 删除是软删除，不删除子回复。 +3. 非本人删除返回失败，前端展示 `info` 即可。 + +### 5.10 一键导入 + +```http +POST /api/v1/plan-square/posts/{post_id}/import +Content-Type: application/json +X-Idempotency-Key: plan_square_import_1710000000000_abcd +``` + +请求体： + +```json +{ + "target_title": "我的 30 天高数强化计划" +} +``` + +字段说明： + +| 字段 | 必填 | 说明 | +| --- | --- | --- | +| `target_title` | 否 | 导入后的 TaskClass 名称；不传则后端生成默认名称 | + +成功响应： + +```json +{ + "status": "10000", + "info": "success", + "data": { + "import_id": 70001, + "post_id": 10001, + "new_task_class_id": 430, + "task_class_title": "我的 30 天高数强化计划", + "import_count": 46, + "reward_hint": { + "receiver": "author", + "status": "recorded", + "amount": 2 + }, + "next_action": { + "type": "open_task_class", + "task_class_id": 430 + }, + "created_at": "2026-05-04T20:55:00+08:00" + } +} +``` + +说明： + +1. 一键导入只创建当前用户自己的 TaskClass 副本。 +2. 不直接写 schedule。 +3. 同一用户同一帖子只允许导入一次；导入成功后前端根据返回结果刷新 `imported_once` 和按钮状态。 + +## 6. Token 商店接口详情 + +### 6.1 Token 概览 + +```http +GET /api/v1/token-store/summary +``` + +成功响应： + +```json +{ + "status": "10000", + "info": "success", + "data": { + "recorded_token_total": 120, + "applied_token_total": 0, + "pending_apply_token_total": 120, + "quota_sync_status": "not_connected", + "tip": "当前为 Token 获取记录，后续会切换到 user/auth 权威额度。" + } +} +``` + +字段说明： + +| 字段 | 说明 | +| --- | --- | +| `recorded_token_total` | `token-store` 内已经记录的累计获取 Token | +| `applied_token_total` | 已同步到权威额度的 Token，P0 通常为 `0` | +| `pending_apply_token_total` | 已记录但尚未同步到权威额度的 Token | +| `quota_sync_status` | `not_connected` / `partial` / `synced` | + +前端展示建议： + +1. P0 可以展示“累计获取 Token”，不要写成“当前可用 Token”。 +2. `quota_sync_status === "not_connected"` 时，展示轻提示，不阻塞购买流程。 + +### 6.2 商品列表 + +```http +GET /api/v1/token-store/products +``` + +说明： + +1. 商品从 `token_products` 表读取。 +2. P0 商品由后端 seed 初始化，不做商品管理后台。 + +成功响应： + +```json +{ + "status": "10000", + "info": "success", + "data": { + "items": [ + { + "product_id": 1, + "name": "基础 Token 包", + "description": "适合轻量使用 Agent。", + "token_amount": 100, + "price_cent": 990, + "price_text": "¥9.90", + "currency": "CNY", + "badge": "入门", + "status": "active", + "sort_order": 10 + }, + { + "product_id": 2, + "name": "进阶 Token 包", + "description": "适合高频规划和复盘。", + "token_amount": 300, + "price_cent": 1990, + "price_text": "¥19.90", + "currency": "CNY", + "badge": "推荐", + "status": "active", + "sort_order": 20 + } + ] + } +} +``` + +前端展示建议： + +1. 只展示 `status === "active"` 的商品。 +2. `badge` 可作为角标，不保证一定有值。 + +### 6.3 创建订单 + +```http +POST /api/v1/token-store/orders +Content-Type: application/json +X-Idempotency-Key: token_order_1710000000000_abcd +``` + +请求体： + +```json +{ + "product_id": 1, + "quantity": 1 +} +``` + +成功响应： + +```json +{ + "status": "10000", + "info": "success", + "data": { + "order_id": 80001, + "order_no": "TS202605042055000001", + "status": "pending", + "product_snapshot": { + "product_id": 1, + "name": "基础 Token 包", + "token_amount": 100 + }, + "quantity": 1, + "token_amount": 100, + "amount_cent": 990, + "price_text": "¥9.90", + "currency": "CNY", + "payment_mode": "mock", + "payment_action": { + "type": "mock_paid", + "label": "确认支付" + }, + "created_at": "2026-05-04T20:55:00+08:00" + } +} +``` + +### 6.4 订单列表 + +```http +GET /api/v1/token-store/orders?page=1&page_size=20&status=pending +``` + +查询参数： + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `page` | number | 否 | 默认 `1` | +| `page_size` | number | 否 | 默认 `20` | +| `status` | string | 否 | `pending` / `paid` / `granted` / `closed` | + +成功响应： + +```json +{ + "status": "10000", + "info": "success", + "data": { + "items": [ + { + "order_id": 80001, + "order_no": "TS202605042055000001", + "status": "pending", + "product_name": "基础 Token 包", + "token_amount": 100, + "price_text": "¥9.90", + "created_at": "2026-05-04T20:55:00+08:00", + "paid_at": null, + "granted_at": null + } + ], + "page": 1, + "page_size": 20, + "total": 1, + "has_more": false + } +} +``` + +订单状态： + +| `status` | 前端含义 | +| --- | --- | +| `pending` | 待支付 | +| `paid` | 已支付，等待写入获取记录 | +| `granted` | 已写入 Token 获取记录 | +| `closed` | 已关闭 | + +### 6.5 订单详情 + +```http +GET /api/v1/token-store/orders/{order_id} +``` + +成功响应： + +```json +{ + "status": "10000", + "info": "success", + "data": { + "order_id": 80001, + "order_no": "TS202605042055000001", + "status": "pending", + "product_snapshot": { + "product_id": 1, + "name": "基础 Token 包", + "token_amount": 100 + }, + "quantity": 1, + "token_amount": 100, + "amount_cent": 990, + "price_text": "¥9.90", + "currency": "CNY", + "payment_mode": "mock", + "grant": null, + "created_at": "2026-05-04T20:55:00+08:00", + "paid_at": null, + "granted_at": null + } +} +``` + +### 6.6 mock paid + +```http +POST /api/v1/token-store/orders/{order_id}/mock-paid +Content-Type: application/json +X-Idempotency-Key: token_mock_paid_1710000000000_abcd +``` + +请求体： + +```json +{ + "mock_channel": "dev" +} +``` + +成功响应： + +```json +{ + "status": "10000", + "info": "success", + "data": { + "order_id": 80001, + "order_no": "TS202605042055000001", + "status": "granted", + "paid_at": "2026-05-04T21:00:00+08:00", + "granted_at": "2026-05-04T21:00:01+08:00", + "grant": { + "grant_id": 90001, + "event_id": "order:80001:paid", + "source": "purchase", + "amount": 100, + "status": "recorded", + "quota_applied": false + } + } +} +``` + +说明： + +1. P0 不接真实支付网关。 +2. `status === "granted"` 表示已经写入 `token-store` 获取记录。 +3. `quota_applied === false` 表示本轮未同步到 `user/auth` 权威额度。 + +### 6.7 Token 获取记录 + +```http +GET /api/v1/token-store/grants?page=1&page_size=20&source=purchase +``` + +查询参数： + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `page` | number | 否 | 默认 `1` | +| `page_size` | number | 否 | 默认 `20` | +| `source` | string | 否 | `purchase` / `forum_like` / `forum_import` / `manual` | + +成功响应： + +```json +{ + "status": "10000", + "info": "success", + "data": { + "items": [ + { + "grant_id": 90001, + "event_id": "order:80001:paid", + "source": "purchase", + "source_label": "购买 Token 包", + "amount": 100, + "status": "recorded", + "quota_applied": false, + "description": "购买基础 Token 包", + "created_at": "2026-05-04T21:00:01+08:00" + }, + { + "grant_id": 90002, + "event_id": "forum.post.liked:10001:91", + "source": "forum_like", + "source_label": "计划被点赞", + "amount": 1, + "status": "recorded", + "quota_applied": false, + "description": "你的计划《30 天高数强化复习计划》获得点赞", + "created_at": "2026-05-04T21:05:00+08:00" + } + ], + "page": 1, + "page_size": 20, + "total": 2, + "has_more": false + } +} +``` + +获取记录状态： + +| `status` | 前端含义 | +| --- | --- | +| `recorded` | 已记录获取事实，P0 默认状态 | +| `applied` | 已同步到权威额度，后续切 `user/auth` 后使用 | +| `skipped` | 幂等重复或规则不发放 | +| `failed` | 写入或后续发放失败 | + +## 7. 页面交互建议 + +### 7.1 计划广场列表页 + +1. 首屏调用计划列表接口，默认 `sort=latest`。 +2. 顶部筛选可放搜索框、排序切换和热门标签。 +3. 卡片 CTA 建议包含“查看详情”和“一键导入”。 +4. 点赞按钮可在卡片上直接操作，成功后用接口返回的 `like_count` 覆盖本地计数。 + +### 7.2 计划详情页 + +1. 进入详情页先拉计划详情。 +2. 评论区单独拉评论树。 +3. 发表评论或删除评论成功后，建议重新拉评论树，避免多层结构局部更新出错。 +4. 一键导入成功后，可弹出成功反馈，并提供“查看我的 TaskClass”入口。 + +### 7.3 发布计划 + +1. 打开发布弹窗时调用现有 `GET /api/v1/task-class/list`。 +2. 用户选择 TaskClass 后填写标题、简介、标签。 +3. 发布按钮需要防重复点击，并发送 `X-Idempotency-Key`。 +4. 发布成功后跳转详情页或刷新列表。 + +### 7.4 Token 商店 + +1. 首屏并行调用 Token 概览和商品列表。 +2. 商品卡片点击“购买”后创建订单。 +3. P0 下单后展示 mock paid 确认按钮。 +4. mock paid 成功后刷新 Token 概览和获取记录。 +5. P0 文案建议使用“累计获取 Token”，暂不写“可用 Token 已到账”。 + +## 8. 前端类型参考 + +```ts +type ApiResponse = { + status: string + info: string + data: T +} + +type PageData = { + items: T[] + page: number + page_size: number + total: number + has_more: boolean +} + +type UserBrief = { + user_id: number + nickname: string + avatar_url: string +} + +type PlanSquarePostCard = { + post_id: number + title: string + summary: string + tags: string[] + author: UserBrief + template_summary: { + task_count: number + mode: string + start_date: string + end_date: string + strategy_labels: string[] + } + counters: { + like_count: number + comment_count: number + import_count: number + } + viewer_state: { + liked: boolean + imported_once: boolean + } + status: 'published' + created_at: string +} + +type CommentNode = { + comment_id: number + post_id: number + parent_comment_id: number | null + content: string + status: 'visible' | 'deleted' + author: UserBrief + can_delete: boolean + created_at: string + deleted_at: string | null + children: CommentNode[] +} + +type TokenProduct = { + product_id: number + name: string + description: string + token_amount: number + price_cent: number + price_text: string + currency: 'CNY' + badge: string + status: 'active' | 'inactive' + sort_order: number +} + +type TokenGrant = { + grant_id: number + event_id: string + source: 'purchase' | 'forum_like' | 'forum_import' | 'manual' + source_label: string + amount: number + status: 'recorded' | 'applied' | 'skipped' | 'failed' + quota_applied: boolean + description: string + created_at: string +} +``` + +## 9. P0 不需要前端处理的内容 + +1. 不做计划推荐算法，只做排序和筛选。 +2. 不做关注、私信、用户主页。 +3. 不做富文本，简介和评论都是纯文本。 +4. 不做管理员删评、举报和审核后台。 +5. 不接真实支付网关。 +6. 不直接展示 `user/auth` 权威可用额度，除非后续接口已经切通。