@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/pkg/apierror/error.go

@@ -0,0 +1,327 @@
+package apierror
+
+import (
+	"fmt"
+	"net/http"
+)
+
+// ErrorResponse API 统一错误响应
+type ErrorResponse struct {
+	Error ErrorDetail `json:"error"`
+}
+
+// ErrorDetail 错误详情
+type ErrorDetail struct {
+	Type    string       `json:"type"`
+	Code    string       `json:"code"`
+	Message string       `json:"message"`
+	Param   string       `json:"param,omitempty"`
+	Errors  []FieldError `json:"errors,omitempty"`
+}
+
+// FieldError 字段校验错误
+type FieldError struct {
+	Field   string `json:"field"`
+	Message string `json:"message"`
+}
+
+// HTTPResponseMetadata 描述允许投影到 HTTP 响应的受控错误元数据。
+type HTTPResponseMetadata struct {
+	retryAfter string
+}
+
+// RetryAfter 返回经过校验的重试时间提示。
+func (m HTTPResponseMetadata) RetryAfter() string {
+	return m.retryAfter
+}
+
+// HTTPError 统一可由 HTTP writer 输出的类型化错误契约。
+type HTTPError interface {
+	error
+	HTTPStatus() int
+	ToResponse() ErrorResponse
+	HTTPResponseMetadata() HTTPResponseMetadata
+}
+
+// APIError 业务错误
+type APIError struct {
+	Status int
+	Detail ErrorDetail
+
+	responseMetadata HTTPResponseMetadata
+}
+
+func (e *APIError) Error() string {
+	return e.Detail.Message
+}
+
+// HTTPStatus 返回错误对应的 HTTP 状态码。
+func (e *APIError) HTTPStatus() int {
+	return e.Status
+}
+
+// HTTPResponseMetadata 返回经过边界校验的响应元数据。
+func (e *APIError) HTTPResponseMetadata() HTTPResponseMetadata {
+	return e.responseMetadata
+}
+
+// WithParam 为业务错误补充字段定位信息，供前端做字段级展示。
+func (e *APIError) WithParam(param string) *APIError {
+	e.Detail.Param = param
+	return e
+}
+
+// WithErrors 为业务错误补充结构化字段错误列表，供前端做字段级展示。
+func (e *APIError) WithErrors(errors []FieldError) *APIError {
+	e.Detail.Errors = errors
+	return e
+}
+
+// ToResponse 转换为标准错误响应
+func (e *APIError) ToResponse() ErrorResponse {
+	return ErrorResponse{Error: e.Detail}
+}
+
+// ErrorTypeFromStatus 根据 HTTP 状态码推导错误类型
+func ErrorTypeFromStatus(status int) string {
+	switch status {
+	case http.StatusBadRequest:
+		return TypeInvalidRequest
+	case http.StatusUnauthorized:
+		return TypeAuthentication
+	case http.StatusForbidden:
+		return TypeAuthorization
+	case http.StatusNotFound:
+		return TypeNotFound
+	case http.StatusTooManyRequests:
+		return TypeRateLimit
+	case http.StatusGone:
+		return TypeGone
+	default:
+		return TypeAPI
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 通用业务错误
+// ═══════════════════════════════════════════════════════════════
+
+// NotFound 资源未找到
+func NotFound(resource string, id ...any) *APIError {
+	var msg, param string
+	if len(id) > 0 {
+		msg = fmt.Sprintf("%s with id %v was not found", resource, id[0])
+		param = "id"
+	} else {
+		msg = fmt.Sprintf("%s was not found", resource)
+	}
+	return &APIError{
+		Status: http.StatusNotFound,
+		Detail: ErrorDetail{Type: TypeNotFound, Code: CodeResourceNotFound, Message: msg, Param: param},
+	}
+}
+
+// NotFoundWithCode 返回保留业务错误码的资源不存在错误。
+func NotFoundWithCode(code, message string) *APIError {
+	return &APIError{
+		Status: http.StatusNotFound,
+		Detail: ErrorDetail{Type: TypeNotFound, Code: code, Message: message},
+	}
+}
+
+// Gone 资源已永久移除（HTTP 410）
+func Gone(resource string) *APIError {
+	return &APIError{
+		Status: http.StatusGone,
+		Detail: ErrorDetail{Type: TypeGone, Code: CodeResourceGone, Message: fmt.Sprintf("%s has been permanently removed", resource)},
+	}
+}
+
+// AlreadyExists 资源已存在
+func AlreadyExists(resource string, field ...string) *APIError {
+	var msg, param string
+	if len(field) > 0 {
+		msg = fmt.Sprintf("%s with this %s already exists", resource, field[0])
+		param = field[0]
+	} else {
+		msg = fmt.Sprintf("%s already exists", resource)
+	}
+	return &APIError{
+		Status: http.StatusConflict,
+		Detail: ErrorDetail{Type: TypeInvalidRequest, Code: CodeResourceExists, Message: msg, Param: param},
+	}
+}
+
+// InvalidOperation 无效操作
+func InvalidOperation(message string, param ...string) *APIError {
+	e := &APIError{
+		Status: http.StatusBadRequest,
+		Detail: ErrorDetail{Type: TypeInvalidRequest, Code: CodeInvalidOperation, Message: message},
+	}
+	if len(param) > 0 {
+		e.Detail.Param = param[0]
+	}
+	return e
+}
+
+// Forbidden 禁止访问
+func Forbidden(message ...string) *APIError {
+	msg := "Access denied"
+	if len(message) > 0 {
+		msg = message[0]
+	}
+	return &APIError{
+		Status: http.StatusForbidden,
+		Detail: ErrorDetail{Type: TypeAuthorization, Code: CodeAccessDenied, Message: msg},
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 认证相关错误
+// ═══════════════════════════════════════════════════════════════
+
+// Unauthorized 未授权
+func Unauthorized(message ...string) *APIError {
+	msg := "Unauthorized"
+	if len(message) > 0 {
+		msg = message[0]
+	}
+	return &APIError{
+		Status: http.StatusUnauthorized,
+		Detail: ErrorDetail{Type: TypeAuthentication, Code: CodeUnauthorized, Message: msg},
+	}
+}
+
+// InvalidCredentials 凭证错误
+func InvalidCredentials() *APIError {
+	return &APIError{
+		Status: http.StatusUnauthorized,
+		Detail: ErrorDetail{Type: TypeAuthentication, Code: CodeInvalidCredentials, Message: "Invalid email or password"},
+	}
+}
+
+// TokenExpired Token 过期
+func TokenExpired() *APIError {
+	return &APIError{
+		Status: http.StatusUnauthorized,
+		Detail: ErrorDetail{Type: TypeAuthentication, Code: CodeTokenExpired, Message: "Token has expired"},
+	}
+}
+
+// TokenInvalid Token 无效
+func TokenInvalid() *APIError {
+	return &APIError{
+		Status: http.StatusUnauthorized,
+		Detail: ErrorDetail{Type: TypeAuthentication, Code: CodeTokenInvalid, Message: "Invalid token"},
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 校验相关错误
+// ═══════════════════════════════════════════════════════════════
+
+// ValidationFailed 校验失败
+func ValidationFailed(errors []FieldError) *APIError {
+	return &APIError{
+		Status: http.StatusBadRequest,
+		Detail: ErrorDetail{Type: TypeValidation, Code: CodeValidationFailed, Message: "Request validation failed", Errors: errors},
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 限流相关错误
+// ═══════════════════════════════════════════════════════════════
+
+// TooManyRequests 请求过多
+func TooManyRequests() *APIError {
+	return &APIError{
+		Status: http.StatusTooManyRequests,
+		Detail: ErrorDetail{Type: TypeRateLimit, Code: CodeTooManyRequests, Message: "Too many requests, please try again later"},
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// AI 服务相关错误
+// ═══════════════════════════════════════════════════════════════
+
+// AIServiceUnavailable AI 服务不可用
+func AIServiceUnavailable(provider string) *APIError {
+	return &APIError{
+		Status: http.StatusServiceUnavailable,
+		Detail: ErrorDetail{Type: TypeAPI, Code: CodeAIUnavailable, Message: fmt.Sprintf("AI service (%s) is temporarily unavailable", provider)},
+	}
+}
+
+// AIQuotaExceeded AI 配额用尽
+func AIQuotaExceeded() *APIError {
+	return &APIError{
+		Status: http.StatusTooManyRequests,
+		Detail: ErrorDetail{Type: TypeRateLimit, Code: CodeAIQuotaExceeded, Message: "AI usage quota exceeded"},
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 通用构造
+// ═══════════════════════════════════════════════════════════════
+
+// New 创建自定义 APIError
+func New(status int, errorType, code, message string) *APIError {
+	return &APIError{
+		Status: status,
+		Detail: ErrorDetail{Type: errorType, Code: code, Message: message},
+	}
+}
+
+// Internal 内部服务错误
+func Internal(message ...string) *APIError {
+	msg := "Internal server error"
+	if len(message) > 0 {
+		msg = message[0]
+	}
+	return &APIError{
+		Status: http.StatusInternalServerError,
+		Detail: ErrorDetail{Type: TypeAPI, Code: CodeInternalError, Message: msg},
+	}
+}
+
+// BadRequest 请求错误
+func BadRequest(code, message string) *APIError {
+	return &APIError{
+		Status: http.StatusBadRequest,
+		Detail: ErrorDetail{Type: TypeInvalidRequest, Code: code, Message: message},
+	}
+}
+
+// Business 业务规则冲突（422 Unprocessable Entity）
+func Business(code, message string) *APIError {
+	return &APIError{
+		Status: http.StatusUnprocessableEntity,
+		Detail: ErrorDetail{Type: TypeInvalidRequest, Code: code, Message: message},
+	}
+}
+
+// Conflict 资源冲突（409 Conflict）
+func Conflict(code, message string) *APIError {
+	return &APIError{
+		Status: http.StatusConflict,
+		Detail: ErrorDetail{Type: TypeInvalidRequest, Code: code, Message: message},
+	}
+}
+
+// NotImplemented 未实现的功能（501 Not Implemented）。
+//
+// 用于路由已暴露但子模块尚未上线的场景（如 PDF 生成、第三方 webhook 验签）：
+// 客户端可以提前约定 URL 形态，服务端必须 fail-loud 拒绝调用，避免静默
+// 返回伪数据（D5/D6 合规）。
+//
+// 行业对照：HTTP RFC 9110 §15.6.2 — 501 表示"服务器不支持该方法语义"，
+// 与 GitHub `Not Implemented`、Stripe 早期 API beta endpoint 同义。
+func NotImplemented(message string) *APIError {
+	if message == "" {
+		message = "Not implemented"
+	}
+	return &APIError{
+		Status: http.StatusNotImplemented,
+		Detail: ErrorDetail{Type: TypeAPI, Code: CodeNotImplemented, Message: message},
+	}
+}

package/dist/resources/templates/go-backend/pkg/apierror/error_code.go

@@ -0,0 +1,65 @@
+package apierror
+
+// 错误码
+const (
+	// 通用
+	CodeInternalError                = "internal_error"
+	CodeResourceNotFound             = "resource_not_found"
+	CodeResourceExists               = "resource_already_exists"
+	CodeInvalidOperation             = "invalid_operation"
+	CodeValidationFailed             = "invalid_parameters"
+	CodeTooManyRequests              = "rate_limit_exceeded"
+	CodeServiceUnavailable           = "service_unavailable"
+	CodeNotImplemented               = "not_implemented"
+	CodeIdempotencyKeyConflict       = "idempotency_key_conflict"
+	CodeIdempotencyRequestInProgress = "idempotency_request_in_progress"
+
+	// 认证/授权
+	CodeUnauthorized           = "unauthorized"
+	CodeAccessDenied           = "access_denied"
+	CodeInvalidCredentials     = "invalid_credentials" //nolint:gosec // G101: 错误码常量，非凭据
+	CodeTokenExpired           = "token_expired"
+	CodeTokenInvalid           = "token_invalid"
+	CodeRefreshTokenExpired    = "refresh_token_expired" //nolint:gosec // G101: 错误码常量，非凭据
+	CodeAccountDisabled        = "account_disabled"
+	CodeAccountNotVerified     = "account_not_verified"
+	CodeAccountPendingDeletion = "account_pending_deletion"
+
+	// 用户
+	CodeUserNotFound    = "user_not_found"
+	CodeUserExists      = "user_already_exists"
+	CodeEmailRegistered = "email_already_registered"
+	CodeInvalidPassword = "invalid_password"
+	CodePasswordTooWeak = "password_too_weak"
+
+	// AI 服务
+	CodeAIUnavailable     = "ai_service_unavailable"
+	CodeAIQuotaExceeded   = "ai_quota_exceeded"
+	CodeAIInvalidRequest  = "ai_invalid_request"
+	CodeAIContentFiltered = "ai_content_filtered"
+	CodeAIContextTooLong  = "ai_context_too_long"
+
+	// 支付
+	CodePaymentFailed       = "payment_failed"
+	CodePaymentCancelled    = "payment_cancelled"
+	CodePaymentExpired      = "payment_expired"
+	CodeInsufficientBalance = "insufficient_balance"
+
+	// 资源状态
+	// CodeResourceGone 资源已永久下线
+	CodeResourceGone = "resource_gone"
+
+	// 订阅
+	CodeSubscriptionNotFound = "subscription_not_found"
+	CodeSubscriptionExpired  = "subscription_expired"
+	CodeSubscriptionActive   = "subscription_already_active"
+	CodePlanNotAvailable     = "plan_not_available"
+
+	// 工单（Helpdesk）— 入参非法值（domain enum 校验失败）
+	CodeInvalidSourceChannel    = "invalid_source_channel"
+	CodeInvalidSourceType       = "invalid_source_type"
+	CodeInvalidPriority         = "invalid_priority"
+	CodeInvalidTicketType       = "invalid_ticket_type"
+	CodeInvalidTicketCategory   = "invalid_ticket_category"
+	CodeInvalidConversationType = "invalid_conversation_type"
+)

package/dist/resources/templates/go-backend/pkg/apierror/error_test.go

@@ -0,0 +1,41 @@
+package apierror
+
+import (
+	"net/http"
+	"testing"
+)
+
+func TestAPIErrorWithParam(t *testing.T) {
+	apiErr := New(401, TypeAuthentication, "IDENTITY_PASSWORD_OLD_PASSWORD_INVALID", "Invalid old password").
+		WithParam("old_password")
+
+	if apiErr.Detail.Param != "old_password" {
+		t.Fatalf("expected param old_password, got %q", apiErr.Detail.Param)
+	}
+}
+
+func TestAPIErrorWithErrors(t *testing.T) {
+	fieldErrors := []FieldError{
+		{Field: "email", Message: "is required"},
+	}
+
+	apiErr := ValidationFailed(nil).WithErrors(fieldErrors)
+
+	if len(apiErr.Detail.Errors) != 1 {
+		t.Fatalf("expected 1 field error, got %d", len(apiErr.Detail.Errors))
+	}
+	if apiErr.Detail.Errors[0].Field != "email" {
+		t.Fatalf("expected field email, got %q", apiErr.Detail.Errors[0].Field)
+	}
+}
+
+func TestNotFoundWithCodePreservesBusinessContract(t *testing.T) {
+	apiErr := NotFoundWithCode("BENEFIT_UPGRADE_QUOTE_NOT_FOUND", "Benefit upgrade quote not found")
+
+	if apiErr.Status != http.StatusNotFound {
+		t.Fatalf("status = %d, want %d", apiErr.Status, http.StatusNotFound)
+	}
+	if apiErr.Detail.Type != TypeNotFound || apiErr.Detail.Code != "BENEFIT_UPGRADE_QUOTE_NOT_FOUND" {
+		t.Fatalf("detail = %+v", apiErr.Detail)
+	}
+}

package/dist/resources/templates/go-backend/pkg/apierror/error_type.go

@@ -0,0 +1,14 @@
+package apierror
+
+// 错误类型
+const (
+	TypeValidation     = "validation_error"
+	TypeAuthentication = "authentication_error"
+	TypeAuthorization  = "authorization_error"
+	TypeInvalidRequest = "invalid_request_error"
+	TypeRateLimit      = "rate_limit_error"
+	TypeAPI            = "api_error"
+	TypeNotFound       = "not_found_error"
+	// TypeGone 资源已永久移除
+	TypeGone = "gone_error"
+)

package/dist/resources/templates/go-backend/pkg/apierror/http_response.go

@@ -0,0 +1,216 @@
+package apierror
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"io"
+	"mime"
+	"net/http"
+	"strings"
+)
+
+// DecodeHTTPResponse 将下游 OneX 标准错误响应恢复为本地 APIError。
+func DecodeHTTPResponse(status int, headers http.Header, body []byte, fallback *APIError) *APIError {
+	if status < 400 || status >= 600 || !hasCanonicalJSONMediaType(headers.Get("Content-Type")) {
+		return httpResponseFallback(fallback)
+	}
+
+	response, ok := decodeClosedJSONObject(body, "error")
+	if !ok {
+		return httpResponseFallback(fallback)
+	}
+	errorRaw, exists := response["error"]
+	if !exists {
+		return httpResponseFallback(fallback)
+	}
+	detail, ok := decodeHTTPErrorDetail(errorRaw)
+	if !ok {
+		return httpResponseFallback(fallback)
+	}
+	responseMetadata, ok := decodeHTTPResponseMetadata(status, headers)
+	if !ok {
+		return httpResponseFallback(fallback)
+	}
+	return &APIError{
+		Status:           status,
+		Detail:           detail,
+		responseMetadata: responseMetadata,
+	}
+}
+
+func decodeHTTPResponseMetadata(status int, headers http.Header) (HTTPResponseMetadata, bool) {
+	if status != http.StatusTooManyRequests && status != http.StatusServiceUnavailable {
+		return HTTPResponseMetadata{}, true
+	}
+	values := headers.Values("Retry-After")
+	if len(values) == 0 {
+		return HTTPResponseMetadata{}, true
+	}
+	if len(values) != 1 {
+		return HTTPResponseMetadata{}, false
+	}
+	value := strings.Trim(values[0], " \t")
+	if isDelaySeconds(value) {
+		return HTTPResponseMetadata{retryAfter: value}, true
+	}
+	parsed, err := http.ParseTime(value)
+	if err != nil {
+		return HTTPResponseMetadata{}, false
+	}
+	return HTTPResponseMetadata{retryAfter: parsed.UTC().Format(http.TimeFormat)}, true
+}
+
+func isDelaySeconds(value string) bool {
+	if value == "" {
+		return false
+	}
+	for index := range value {
+		if value[index] < '0' || value[index] > '9' {
+			return false
+		}
+	}
+	return true
+}
+
+func decodeHTTPErrorDetail(raw json.RawMessage) (ErrorDetail, bool) {
+	source, ok := decodeClosedJSONObject(raw, "type", "code", "message", "param", "errors")
+	if !ok {
+		return ErrorDetail{}, false
+	}
+	typeRaw, typeExists := source["type"]
+	codeRaw, codeExists := source["code"]
+	messageRaw, messageExists := source["message"]
+	if !typeExists || !codeExists || !messageExists {
+		return ErrorDetail{}, false
+	}
+	errorType, typeOK := decodeNonBlankJSONString(typeRaw)
+	code, codeOK := decodeNonBlankJSONString(codeRaw)
+	message, messageOK := decodeNonBlankJSONString(messageRaw)
+	if !typeOK || !codeOK || !messageOK {
+		return ErrorDetail{}, false
+	}
+
+	detail := ErrorDetail{Type: errorType, Code: code, Message: message}
+	if paramRaw, exists := source["param"]; exists {
+		param, ok := decodeNonBlankJSONString(paramRaw)
+		if !ok {
+			return ErrorDetail{}, false
+		}
+		detail.Param = param
+	}
+	if errorsRaw, exists := source["errors"]; exists {
+		fieldErrors, ok := decodeHTTPFieldErrors(errorsRaw)
+		if !ok {
+			return ErrorDetail{}, false
+		}
+		detail.Errors = fieldErrors
+	}
+	return detail, true
+}
+
+func decodeHTTPFieldErrors(raw json.RawMessage) ([]FieldError, bool) {
+	trimmed := bytes.TrimSpace(raw)
+	if len(trimmed) == 0 || trimmed[0] != '[' {
+		return nil, false
+	}
+	var sources []json.RawMessage
+	if !decodeSingleJSONValue(trimmed, &sources) {
+		return nil, false
+	}
+	fieldErrors := make([]FieldError, len(sources))
+	for index := range sources {
+		source, ok := decodeClosedJSONObject(sources[index], "field", "message")
+		if !ok {
+			return nil, false
+		}
+		fieldRaw, fieldExists := source["field"]
+		messageRaw, messageExists := source["message"]
+		if !fieldExists || !messageExists {
+			return nil, false
+		}
+		field, fieldOK := decodeNonBlankJSONString(fieldRaw)
+		message, messageOK := decodeNonBlankJSONString(messageRaw)
+		if !fieldOK || !messageOK {
+			return nil, false
+		}
+		fieldErrors[index] = FieldError{Field: field, Message: message}
+	}
+	return fieldErrors, true
+}
+
+func decodeNonBlankJSONString(raw json.RawMessage) (string, bool) {
+	if len(raw) == 0 {
+		return "", false
+	}
+	var value string
+	if !decodeSingleJSONValue(raw, &value) || strings.TrimSpace(value) == "" {
+		return "", false
+	}
+	return value, true
+}
+
+func decodeClosedJSONObject(raw []byte, allowedKeys ...string) (map[string]json.RawMessage, bool) {
+	allowed := make(map[string]struct{}, len(allowedKeys))
+	for _, key := range allowedKeys {
+		allowed[key] = struct{}{}
+	}
+
+	decoder := json.NewDecoder(bytes.NewReader(raw))
+	openingToken, err := decoder.Token()
+	opening, ok := openingToken.(json.Delim)
+	if err != nil || !ok || opening != '{' {
+		return nil, false
+	}
+	fields := make(map[string]json.RawMessage, len(allowedKeys))
+	for decoder.More() {
+		keyToken, err := decoder.Token()
+		key, ok := keyToken.(string)
+		if err != nil || !ok {
+			return nil, false
+		}
+		if _, exists := allowed[key]; !exists {
+			return nil, false
+		}
+		if _, duplicate := fields[key]; duplicate {
+			return nil, false
+		}
+		var value json.RawMessage
+		if err := decoder.Decode(&value); err != nil {
+			return nil, false
+		}
+		fields[key] = value
+	}
+	closingToken, err := decoder.Token()
+	closing, ok := closingToken.(json.Delim)
+	if err != nil || !ok || closing != '}' {
+		return nil, false
+	}
+	var trailing json.RawMessage
+	if !errors.Is(decoder.Decode(&trailing), io.EOF) {
+		return nil, false
+	}
+	return fields, true
+}
+
+// decodeSingleJSONValue 只在受控 wire 值间复用单文档规则，避免尾随载荷绕过对象校验。
+func decodeSingleJSONValue[T any](raw []byte, target *T) bool {
+	decoder := json.NewDecoder(bytes.NewReader(raw))
+	if err := decoder.Decode(target); err != nil {
+		return false
+	}
+	var trailing json.RawMessage
+	return errors.Is(decoder.Decode(&trailing), io.EOF)
+}
+
+func hasCanonicalJSONMediaType(contentType string) bool {
+	mediaType, _, err := mime.ParseMediaType(strings.TrimSpace(contentType))
+	return err == nil && strings.EqualFold(mediaType, "application/json")
+}
+
+func httpResponseFallback(fallback *APIError) *APIError {
+	if fallback == nil {
+		return Internal()
+	}
+	return fallback
+}