perf: skill

.agent/skills/new-api/references/handler_example.go

@@ -6,53 +6,50 @@ package references
 import (
 	"net/http"
 
-	"github.com/Rain-kl/Wavelet/internal/service"
-	"github.com/Rain-kl/Wavelet/internal/util"
+	"github.com/Rain-kl/Wavelet/internal/common/response"
 	"github.com/gin-gonic/gin"
 )
 
-// customRequest 客户端请求体 DTO
-type customRequest struct {
-	Payload string `json:"payload" binding:"required,min=1,max=100"`
+// createChannelRequest 客户端请求体 DTO
+type createChannelRequest struct {
+	Name string `json:"name" binding:"required,min=1,max=100"`
 }
 
-// customResponse API 响应体 DTO
-type customResponse struct {
-	Result string `json:"result"`
+// createChannelResponse API 响应体 DTO
+type createChannelResponse struct {
+	ID   int64  `json:"id"`
+	Name string `json:"name"`
 }
 
-// HandleCustomBusiness 示例 API Handler
-// @Summary 示例定制业务接口
-// @Description 接收数据载荷，调用 Service 执行核心逻辑，并返回统一格式的 JSON 结果。
-// @Tags custom
+// CreateChannel 示例：产品域 Handler（应放在 internal/apps/channel/routers.go）
+// @Summary 创建频道
+// @Description 示例：语义路径下的业务接口，而非 /api/v1/custom/...
+// @Tags channel
 // @Accept json
 // @Produce json
-// @Param request body customRequest true "业务请求参数"
-// @Success 200 {object} util.ResponseAny{data=customResponse} "操作成功"
-// @Router /api/v1/custom/business [post]
-func HandleCustomBusiness(c *gin.Context) {
-	// 1. 参数绑定与校验
-	var req customRequest
+// @Param request body createChannelRequest true "业务请求参数"
+// @Success 200 {object} response.Any{data=createChannelResponse} "操作成功"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Router /api/v1/channels [post]
+func CreateChannel(c *gin.Context) {
+	var req createChannelRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
-		c.JSON(http.StatusBadRequest, util.Err("参数校验失败：载荷不能为空且在 1-100 字符内"))
+		response.AbortBadRequest(c, "参数校验失败")
 		return
 	}
 
-	// 2. 模拟获取当前上下文与已登录用户（例如从 Session 中提取）
-	// 通常结合 oauth.LoginRequired() 等中间件使用
+	// 通常结合 oauth.LoginRequired()；此处仅演示从上下文取用户
 	userID := int64(9527)
 
-	// 3. 实例化业务 Service 并调用核心逻辑
-	// 注意传入 c.Request.Context() 以正确传递 OpenTelemetry Tracing 等上下文信息
-	svc := service.NewCustomService()
-	resText, err := svc.ProcessBusinessData(c.Request.Context(), userID, req.Payload)
+	result, err := CreateChannelLogic(c.Request.Context(), userID, req.Name)
 	if err != nil {
-		c.JSON(http.StatusInternalServerError, util.Err(err.Error()))
+		response.AbortBadRequest(c, err.Error())
 		return
 	}
 
-	// 4. 返回符合外层形状规范 { "error_msg": "", "data": ... } 的统一成功响应
-	c.JSON(http.StatusOK, util.OK(customResponse{
-		Result: resText,
+	c.JSON(http.StatusOK, response.OK(createChannelResponse{
+		ID:   result.ID,
+		Name: result.Name,
 	}))
 }

.agent/skills/new-api/references/logics_example.go

@@ -12,21 +12,27 @@ import (
 	"go.uber.org/zap"
 )
 
-// ProcessLocalBusiness 示例的模块内部闭环业务逻辑
-// 1. 存放在 apps/custom/logics.go 下，遵循纯 Go 规范，不强依赖 gin.Context，以便逻辑清晰和便于单元测试。
-// 2. 用于当前应用模块内的简单业务或通用过程。
-func ProcessLocalBusiness(ctx context.Context, userID int64, param string) (string, error) {
-	if param == "" {
-		return "", errors.New("param cannot be empty")
+// channelCreated 示例 logics 返回值（真实代码可用 model 或专用 DTO）
+type channelCreated struct {
+	ID   int64
+	Name string
+}
+
+// CreateChannelLogic 示例：模块内闭环业务（放在 apps/channel/logics.go）
+// 接收 context.Context，不依赖 gin.Context，便于单测与 Worker 复用。
+func CreateChannelLogic(ctx context.Context, userID int64, name string) (*channelCreated, error) {
+	if name == "" {
+		return nil, errors.New("name cannot be empty")
 	}
 
-	logger.Info(ctx, "processing local business inside apps/custom/logics",
+	logger.Info(ctx, "creating channel",
 		zap.Int64("user_id", userID),
-		zap.String("param", param),
+		zap.String("name", name),
 	)
 
-	// 执行轻量级、无需跨模块/多入口复用的本地计算或模型操作
-	result := fmt.Sprintf("Processed local logic for user %d: %s", userID, param)
-
-	return result, nil
+	// 轻量级本地逻辑；复杂持久化可进 model/repository
+	return &channelCreated{
+		ID:   1,
+		Name: fmt.Sprintf("%s (by %d)", name, userID),
+	}, nil
 }

.agent/skills/new-api/references/service_example.go

@@ -12,34 +12,29 @@ import (
 	"go.uber.org/zap"
 )
 
-// CustomService 示例业务 Service 结构体（通常放在 internal/apps/custom/service.go 中）
-type CustomService struct {
-	// 这里可以注入数据库连接、配置对象或者其他基础服务的客户端
-	// 例如：db *gorm.DB
+// ChannelService 示例有状态 Service（放在 internal/apps/channel/service.go）
+// 需要注入 DB/客户端时使用；简单逻辑优先 logics.go 纯函数。
+type ChannelService struct {
+	// 例如：repo ChannelRepository
 }
 
-// NewCustomService 创建 CustomService 实例的构造函数
-func NewCustomService() *CustomService {
-	return &CustomService{}
+// NewChannelService 构造函数
+func NewChannelService() *ChannelService {
+	return &ChannelService{}
 }
 
-// ProcessBusinessData 演示核心业务处理逻辑的 Service 方法
-// 1. 首位参数必须是 context.Context，以传播链路追踪 (OTel) 和超时控制。
-// 2. 方法签名应该只包含纯 Go 的参数与返回值，禁止导入 Gin 或与 HTTP 相关的协议依赖。
-// 3. 将可能发生的核心异常通过 error 返回给上层，而不是在这一层转换成 HTTP 状态码。
-func (s *CustomService) ProcessBusinessData(ctx context.Context, userID int64, payload string) (string, error) {
-	if payload == "" {
-		return "", errors.New("payload cannot be empty")
+// Create 核心业务：首位参数必须是 context.Context；禁止依赖 Gin。
+func (s *ChannelService) Create(ctx context.Context, userID int64, name string) (int64, error) {
+	if name == "" {
+		return 0, errors.New("name cannot be empty")
 	}
 
-	// 模拟执行业务逻辑...
-	logger.Info(ctx, "processing custom business data in service",
+	logger.Info(ctx, "channel service create",
 		zap.Int64("user_id", userID),
-		zap.String("payload", payload),
+		zap.String("name", name),
 	)
 
-	// 这里可以包含数据库读写、事务控制、或者远程 API 调用等复杂逻辑。
-	result := fmt.Sprintf("Success processed data for user %d: %s", userID, payload)
-
-	return result, nil
+	// DB 事务、远程调用等
+	_ = fmt.Sprintf("user=%d name=%s", userID, name)
+	return 1, nil
 }