wavelet init

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

@@ -0,0 +1,58 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package references
+
+import (
+	"net/http"
+
+	"github.com/Rain-kl/Wavelet/internal/service"
+	"github.com/Rain-kl/Wavelet/internal/util"
+	"github.com/gin-gonic/gin"
+)
+
+// customRequest 客户端请求体 DTO
+type customRequest struct {
+	Payload string `json:"payload" binding:"required,min=1,max=100"`
+}
+
+// customResponse API 响应体 DTO
+type customResponse struct {
+	Result string `json:"result"`
+}
+
+// HandleCustomBusiness 示例 API Handler
+// @Summary 示例定制业务接口
+// @Description 接收数据载荷，调用 Service 执行核心逻辑，并返回统一格式的 JSON 结果。
+// @Tags custom
+// @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
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, util.Err("参数校验失败：载荷不能为空且在 1-100 字符内"))
+		return
+	}
+
+	// 2. 模拟获取当前上下文与已登录用户（例如从 Session 中提取）
+	// 通常结合 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)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, util.Err(err.Error()))
+		return
+	}
+
+	// 4. 返回符合外层形状规范 { "error_msg": "", "data": ... } 的统一成功响应
+	c.JSON(http.StatusOK, util.OK(customResponse{
+		Result: resText,
+	}))
+}

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

@@ -0,0 +1,32 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package references
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+	"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")
+	}
+
+	logger.Info(ctx, "processing local business inside apps/custom/logics",
+		zap.Int64("user_id", userID),
+		zap.String("param", param),
+	)
+
+	// 执行轻量级、无需跨模块/多入口复用的本地计算或模型操作
+	result := fmt.Sprintf("Processed local logic for user %d: %s", userID, param)
+
+	return result, nil
+}

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

@@ -0,0 +1,45 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package references
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+	"go.uber.org/zap"
+)
+
+// CustomService 示例业务 Service 结构体（通常放在 internal/apps/custom/service.go 中）
+type CustomService struct {
+	// 这里可以注入数据库连接、配置对象或者其他基础服务的客户端
+	// 例如：db *gorm.DB
+}
+
+// NewCustomService 创建 CustomService 实例的构造函数
+func NewCustomService() *CustomService {
+	return &CustomService{}
+}
+
+// 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")
+	}
+
+	// 模拟执行业务逻辑...
+	logger.Info(ctx, "processing custom business data in service",
+		zap.Int64("user_id", userID),
+		zap.String("payload", payload),
+	)
+
+	// 这里可以包含数据库读写、事务控制、或者远程 API 调用等复杂逻辑。
+	result := fmt.Sprintf("Success processed data for user %d: %s", userID, payload)
+
+	return result, nil
+}