@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/.claude/docs/error-handling.md

@@ -0,0 +1,558 @@
+# Error Handling Templates
+
+> Implementation code for errors and middleware. Rules are in `CLAUDE.md`.
+
+---
+
+## ErrorType Constants
+
+```go
+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"
+)
+```
+
+## ErrorCode Constants
+
+```go
+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"
+)
+```
+
+## APIError Type
+
+```go
+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},
+	}
+}
+```
+
+## Error Response Helper
+
+```go
+// Error 根据 error 类型自动选择状态码和响应格式
+func Error(c *gin.Context, err error) {
+	var httpErr apierror.HTTPError
+	if errors.As(err, &httpErr) {
+		status := httpErr.HTTPStatus()
+		// 410 Gone 响应附加 noindex 头，通知搜索引擎不再索引
+		if status == http.StatusGone {
+			c.Header("X-Robots-Tag", "noindex, nofollow")
+		}
+		if status == http.StatusTooManyRequests || status == http.StatusServiceUnavailable {
+			if retryAfter := httpErr.HTTPResponseMetadata().RetryAfter(); retryAfter != "" {
+				c.Header(types.HeaderRetryAfter, retryAfter)
+			}
+		}
+		c.JSON(status, httpErr.ToResponse())
+		return
+	}
+
+	// 未知错误：注入 Gin context 供 logging middleware 输出错误详情，返回通用 500
+	_ = c.Error(err)
+	internal := apierror.Internal("Internal server error")
+	c.JSON(internal.Status, internal.ToResponse())
+}
+
+```
+
+## Recovery Middleware
+
+```go
+package middleware
+
+import (
+	"fmt"
+	"net/http"
+	"runtime/debug"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+
+	"{{module}}/internal/common/requestprivacy"
+	"{{module}}/pkg/apierror"
+)
+
+// Recovery 捕获 panic 并返回 500 APIError 响应
+func Recovery(logger *zap.Logger) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		defer func() {
+			if r := recover(); r != nil {
+				stack := string(debug.Stack())
+
+				logger.Error("panic recovered",
+					zap.String("panic_type", fmt.Sprintf("%T", r)),
+					zap.String("stack", stack),
+					zap.String("method", c.Request.Method),
+					zap.String("path", requestprivacy.SanitizeRequestTarget(
+						c.Request.URL,
+						requestprivacy.RouteTemplateOrUnmatched(c.FullPath()),
+						requestprivacy.RedactSensitiveQueryValues,
+					)),
+					zap.String("clientIP", c.ClientIP()),
+				)
+
+				apiErr := apierror.Internal("Internal server error")
+				c.AbortWithStatusJSON(http.StatusInternalServerError, apiErr.ToResponse())
+			}
+		}()
+		c.Next()
+	}
+}
+```
+
+## Validation Error Formatting
+
+```go
+// ValidationError 格式化 go-playground/validator 的校验错误
+func ValidationError(c *gin.Context, err error) {
+	var ve validator.ValidationErrors
+	if !errors.As(err, &ve) {
+		// 非 validator 校验错误，按普通错误处理
+		apiErr := apierror.BadRequest(apierror.CodeValidationFailed, err.Error())
+		c.JSON(apiErr.Status, apiErr.ToResponse())
+		return
+	}
+
+	fieldErrors := make([]apierror.FieldError, 0, len(ve))
+	for _, fe := range ve {
+		fieldErrors = append(fieldErrors, apierror.FieldError{
+			Field:   fe.Field(),
+			Message: formatValidationMessage(fe),
+		})
+	}
+
+	apiErr := apierror.ValidationFailed(fieldErrors)
+	c.JSON(apiErr.Status, apiErr.ToResponse())
+}
+
+// formatValidationMessage 将 validator tag 转换为可读的错误消息
+func formatValidationMessage(fe validator.FieldError) string {
+	switch fe.Tag() {
+	case "required":
+		return "is required"
+	case "email":
+		return "must be a valid email"
+	case "min":
+		return "must be at least " + fe.Param()
+	case "max":
+		return "must be at most " + fe.Param()
+	case "len":
+		return "must have length " + fe.Param()
+	case "oneof":
+		return "must be one of: " + fe.Param()
+	case "uuid":
+		return "must be a valid UUID"
+	case "url":
+		return "must be a valid URL"
+	case "gte":
+		return "must be greater than or equal to " + fe.Param()
+	case "lte":
+		return "must be less than or equal to " + fe.Param()
+	case "gt":
+		return "must be greater than " + fe.Param()
+	case "lt":
+		return "must be less than " + fe.Param()
+	default:
+		return "failed on " + fe.Tag() + " validation"
+	}
+}
+```

package/dist/resources/templates/go-backend/.claude/docs/event-runtime-boundary.md

@@ -0,0 +1,124 @@
+# Event Runtime Boundary Standards
+
+This document defines the binding runtime split between `platform-api`, `admin-api`, `worker`, and the transactional outbox relay.
+
+It is a rules document, not a sample implementation guide.
+
+## Final Boundary
+
+- Aggregate-owner projections run in the runtime that owns the source aggregate state machine.
+- Cross-process side effects run only from durable outbox events.
+- `worker` consumes downstream public events only; it does not rebuild source projections.
+- Partial aggregate families must use explicit event-name whitelists, not broad wildcards.
+- Every irreversible cross-process workflow must have one E2E contract test plus one relay whitelist regression test.
+
+## Industry Alignment
+
+| Decision Point | Industry Pattern | Used By | Our Choice | Rationale |
+| --- | --- | --- | --- | --- |
+| State change + async publish | Transactional Outbox | AWS Prescriptive Guidance, Shopify, Stripe-style event platforms | Transactional outbox | Prevents committed state without downstream delivery and removes dual-write races. |
+| Public event contract | Explicit event type contract | Stripe Events, GitHub Webhooks | Explicit cross-process event whitelist | Downstream consumers must depend on stable named events, not accidental aggregate-wide fan-out. |
+| Projection ownership | Source service owns source projections | Stripe-style service ownership, AWS service boundaries | `platform-api` owns identity/user projection listeners | Source truth and projection repair must stay in the runtime that owns the lifecycle. |
+| Background processing | Worker consumes durable side effects only | AWS async workers, Shopify job workers | `worker` handles downstream cleanup and notifications only | Prevents duplicate projection work, duplicate bootstrap side effects, and split-brain lifecycle handling. |
+| Account closure orchestration | Immediate access revocation + async cleanup saga | Auth0, AWS account closure, GitHub account deletion | Identity-led closure saga | Authentication truth closes first; cleanup follows via durable events. |
+
+## Binding Rules
+
+### 1. Source Aggregate Listeners Stay with the Source Runtime
+
+Rules:
+
+- `identity.*` source lifecycle listeners run in `platform-api`.
+- User projection listeners that materialize `p_user_users` and `p_user_product_users` from identity events run in `platform-api`.
+- `worker` must not register source listeners that create or repair identity/user projections.
+- `admin-api` may write its own outbox events when it owns a write path, but it must not subscribe to source aggregate events just to recreate platform projections.
+
+Forbidden:
+
+- Registering `IdentityEventListener` in `worker`
+- Registering `UserEventListener` in `worker`
+- Replaying identity bootstrap side effects from both `platform-api` and `worker`
+
+### 2. Cross-Process Delivery Must Use Public Durable Events
+
+Rules:
+
+- Any event needed by another runtime must be written to `sys_outbox_events`.
+- Cross-process subscriptions consume `internal/sharedevents` public contracts only.
+- The relay whitelist in `ProvideRelayConfig()` is a public API surface and must be reviewed like an external contract.
+
+Forbidden:
+
+- Depending on in-process `eventbus.PublishAsync()` for worker-visible side effects
+- Publishing private domain payloads directly to another runtime
+- Treating relay config as an implementation detail
+
+### 3. Wildcards Are Allowed Only for Full Public Families
+
+Rules:
+
+- Use aggregate wildcards only when every event in that family is intentionally public and schema-stable across runtimes.
+- Use exact event names when only one or a few events in the family are public.
+- `user.deleted` must stay explicit because `user.created` and `user.updated` are local projection concerns, not worker-wide side effects.
+
+Examples:
+
+- Allowed: `payment.*`, `order.*`, `subscription.*`
+- Required exact match: `user.deleted`
+
+Forbidden:
+
+- `user.*` in relay config
+- Adding a wildcard because it is “easier”
+- Reusing a human-readable reason string as a machine routing key
+
+### 4. Worker Owns Side Effects, Not Source Truth
+
+Worker responsibilities:
+
+- notifications
+- API key revocation
+- subscription cleanup
+- quota / entitlement / credit side effects
+- product data cleanup
+
+Worker must not own:
+
+- identity status projection
+- user bootstrap projection
+- default profile creation
+- product-user bootstrap reconciliation
+
+### 5. Account Closure Event Flow
+
+Canonical flow:
+
+1. `POST /api/v1/deletion/request`
+2. Identity service revokes sessions and updates identity lifecycle
+3. Identity service writes durable identity outbox event
+4. `platform-api` local listeners project user and product-user lifecycle changes
+5. User service writes durable `user.deleted`
+6. Relay publishes `user.deleted` to cross-process consumers
+7. `worker` executes cleanup side effects
+
+Key guarantee:
+
+- Access revocation must complete before asynchronous cleanup is considered successful.
+
+### 6. Required Regression Coverage
+
+For every new cross-process workflow:
+
+- add one unit test that asserts the exact `ProvideRelayConfig()` whitelist
+- add one E2E test that proves the externally observable terminal state
+
+The unit test protects configuration drift.
+The E2E test protects runtime orchestration drift.
+
+## Review Checklist
+
+- Does this new listener belong to the source runtime or the side-effect runtime?
+- Is the event public enough to cross process, or is it only a local projection event?
+- Is the relay whitelist exact where the aggregate family is only partially public?
+- Does `worker` consume durable public events only?
+- Does the E2E test assert state rows, access contract, and downstream cleanup?