@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/common/types/subscription_entitlement.go

@@ -0,0 +1,24 @@
+package types
+
+import "time"
+
+// IsSubscriptionPeriodActiveAt 判断订阅周期在指定服务端时刻是否仍然有效。
+//
+// 到期时间缺失时采用故障关闭策略，避免仅凭持久化的 active 状态继续授予权益；
+// 在到期边界时刻即视为失效，续费成功必须先把周期推进到未来。
+func IsSubscriptionPeriodActiveAt(expiresAt *time.Time, evaluatedAt time.Time) bool {
+	if expiresAt == nil || evaluatedAt.IsZero() {
+		return false
+	}
+	return evaluatedAt.Before(*expiresAt)
+}
+
+// ActiveSubscriptionTierAt 返回指定时刻仍有效的订阅等级。
+//
+// 未知等级、免费等级或已到期周期统一收敛为 free，防止脏投影造成越权。
+func ActiveSubscriptionTierAt(tier Tier, expiresAt *time.Time, evaluatedAt time.Time) Tier {
+	if !tier.IsValid() || tier == TierFree || !IsSubscriptionPeriodActiveAt(expiresAt, evaluatedAt) {
+		return TierFree
+	}
+	return tier
+}

package/dist/resources/templates/go-backend/internal/common/types/subscription_entitlement_test.go

@@ -0,0 +1,35 @@
+package types
+
+import (
+	"testing"
+	"time"
+)
+
+func TestActiveSubscriptionTierAt(t *testing.T) {
+	evaluatedAt := time.Date(2026, 7, 13, 1, 58, 11, 90_000_000, time.UTC)
+	future := evaluatedAt.Add(time.Nanosecond)
+	past := evaluatedAt.Add(-time.Nanosecond)
+
+	tests := []struct {
+		name      string
+		tier      Tier
+		expiresAt *time.Time
+		at        time.Time
+		want      Tier
+	}{
+		{name: "future period remains active", tier: TierPremium, expiresAt: &future, at: evaluatedAt, want: TierPremium},
+		{name: "exact boundary is expired", tier: TierPremium, expiresAt: &evaluatedAt, at: evaluatedAt, want: TierFree},
+		{name: "past period is expired", tier: TierStandard, expiresAt: &past, at: evaluatedAt, want: TierFree},
+		{name: "missing expiry fails closed", tier: TierPremium, at: evaluatedAt, want: TierFree},
+		{name: "unknown tier fails closed", tier: Tier("unknown"), expiresAt: &future, at: evaluatedAt, want: TierFree},
+		{name: "missing evaluation time fails closed", tier: TierPremium, expiresAt: &future, want: TierFree},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := ActiveSubscriptionTierAt(tt.tier, tt.expiresAt, tt.at); got != tt.want {
+				t.Fatalf("ActiveSubscriptionTierAt() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}

package/dist/resources/templates/go-backend/internal/common/types/tier.go

@@ -0,0 +1,72 @@
+package types
+
+// ═══════════════════════════════════════════════════════════════
+// Tier — 平台级订阅 / lifetime 等级（单一真相源）
+// ═══════════════════════════════════════════════════════════════
+//
+// 所有模块（user / catalog / order / credit / entitlement）共享此定义，
+// 避免"一处错处处错"的分散重复（Stripe / Shopify 都采用跨模块共享枚举，
+// 不是每个模块各自维护一份 tier 映射表）。
+//
+// 使用方式：
+//   - user.domain.ProductUser.SubscriptionTier / LifetimeTier 字段类型
+//   - catalog.domain.Plan.Tier 存储同一 string 枚举值
+//   - 跨模块比较等级使用 Rank() / Higher() 方法，禁止重新定义 rank map
+
+// Tier 平台统一的会员等级枚举
+type Tier string
+
+const (
+	// TierFree 未付费 / 默认等级（rank=0）
+	TierFree Tier = "free"
+	// TierBasic 基础（rank=1）
+	TierBasic Tier = "basic"
+	// TierStandard 标准（rank=2）
+	TierStandard Tier = "standard"
+	// TierPremium 高级（rank=3）
+	TierPremium Tier = "premium"
+	// TierEnterprise 企业（rank=4，留作大客户自定义层级）
+	TierEnterprise Tier = "enterprise"
+)
+
+// tierRanks 等级排名：数字越大权益越高。不可导出，强制外部通过 Rank() 访问。
+var tierRanks = map[Tier]int{
+	TierFree:       0,
+	TierBasic:      1,
+	TierStandard:   2,
+	TierPremium:    3,
+	TierEnterprise: 4,
+}
+
+// validTiers 合法 tier 集合，用于 IsValid 快速校验
+var validTiers = map[Tier]struct{}{
+	TierFree:       {},
+	TierBasic:      {},
+	TierStandard:   {},
+	TierPremium:    {},
+	TierEnterprise: {},
+}
+
+// Rank 返回 tier 的数字排名；未知 tier 返回 0（free 语义），避免越权。
+func (t Tier) Rank() int {
+	if r, ok := tierRanks[t]; ok {
+		return r
+	}
+	return 0
+}
+
+// Higher 比较两个 tier，返回权益更高者；相等或未知返回左侧。
+// CQRS 双投影场景（subscription_tier + lifetime_tier）用此方法计算 effective_tier。
+func (t Tier) Higher(other Tier) Tier {
+	if other.Rank() > t.Rank() {
+		return other
+	}
+	return t
+}
+
+// IsValid 判断 tier 是否在合法枚举集合内。
+// 投影侧收到外部系统（catalog 配置 / webhook）的 tier 字符串时做防御性校验。
+func (t Tier) IsValid() bool {
+	_, ok := validTiers[t]
+	return ok
+}

package/dist/resources/templates/go-backend/internal/common/types/types.go

@@ -0,0 +1,411 @@
+package types
+
+import (
+	"time"
+)
+
+// ContextKey gin.Context 存储键类型，避免字符串键冲突
+type ContextKey string
+
+const (
+	// ContextKeyRequestID 请求 ID
+	ContextKeyRequestID ContextKey = "requestId"
+	// ContextKeyUserIdentity 网关注入的用户身份
+	ContextKeyUserIdentity ContextKey = "userIdentity"
+	// ContextKeySessionID 网关注入的会话 ID
+	ContextKeySessionID ContextKey = "sessionId"
+	// ContextKeyAccessTokenJTI 网关注入的访问令牌 JTI
+	ContextKeyAccessTokenJTI ContextKey = "accessTokenJti"
+	// ContextKeyAccessTokenExpiresAt 网关注入的访问令牌过期时间
+	ContextKeyAccessTokenExpiresAt ContextKey = "accessTokenExpiresAt"
+	// ContextKeyProductCode 当前请求的产品标识
+	ContextKeyProductCode ContextKey = "productCode"
+	// ContextKeyClientContext 客户端上下文信息
+	ContextKeyClientContext ContextKey = "clientContext"
+	// ContextKeyTenantID 租户 ID
+	ContextKeyTenantID ContextKey = "tenantId"
+	// ContextKeyTenant 租户信息
+	ContextKeyTenant ContextKey = "tenant"
+	// ContextKeyStartTime 请求开始时间
+	ContextKeyStartTime ContextKey = "startTime"
+	// ContextKeyPermissions 用户权限列表
+	ContextKeyPermissions ContextKey = "permissions"
+	// ContextKeyReferralCode 归因推广码（Cookie 归因中间件提取）
+	ContextKeyReferralCode ContextKey = "referralCode"
+)
+
+// 外部请求 Header（客户端发送）
+const (
+	HeaderRequestID               = "X-Request-ID"
+	HeaderCorrelationID           = "X-Correlation-ID"
+	HeaderClientType              = "X-Client-Type"
+	HeaderClientVersion           = "X-Client-Version"
+	HeaderClientPlatform          = "X-Client-Platform"
+	HeaderClientLocale            = "X-Client-Locale"
+	HeaderClientTimezone          = "X-Client-Timezone"
+	HeaderClientTimezoneOffset    = "X-Client-Timezone-Offset"
+	HeaderClientScreenWidth       = "X-Client-Screen-Width"
+	HeaderClientScreenHeight      = "X-Client-Screen-Height"
+	HeaderClientViewportWidth     = "X-Client-Viewport-Width"
+	HeaderClientViewportHeight    = "X-Client-Viewport-Height"
+	HeaderClientColorDepth        = "X-Client-Color-Depth"
+	HeaderClientPixelRatio        = "X-Client-Pixel-Ratio"
+	HeaderClientTouchPoints       = "X-Client-Touch-Points"
+	HeaderClientJavaEnabled       = "X-Client-Java-Enabled"
+	HeaderClientJavaScriptEnabled = "X-Client-JavaScript-Enabled"
+	HeaderClientCookiesEnabled    = "X-Client-Cookies-Enabled"
+	HeaderDeviceID                = "X-Device-ID"
+	HeaderIdempotencyKey          = "X-Idempotency-Key"
+	HeaderCheckoutSessionToken    = "X-Checkout-Session-Token"
+	HeaderCheckoutReturnState     = "X-Checkout-Return-State"
+	HeaderAppVersion              = "X-App-Version"
+	HeaderReferralCode            = "X-Referral-Code"
+	HeaderAttributionSource       = "X-Attribution-Source"
+	HeaderAttributionTouchID      = "X-Attribution-Touch-ID"
+	HeaderAttributionCampaignID   = "X-Attribution-Campaign-ID"
+)
+
+// 服务间 Header（可信内部调用方注入）
+const (
+	HeaderInternalUserID      = "X-Internal-User-ID"
+	HeaderOneXProductCode     = "X-OneX-Product-Code"
+	HeaderOneXApplicationCode = "X-OneX-Application-Code"
+	HeaderOneXGuestCapability = "X-Onex-Guest-Capability"
+)
+
+// 内部 Header（APISIX 注入，客户端不可伪造）
+const (
+	HeaderUserID          = "X-User-ID"        // 内部业务用户 ID，仅服务端 session 解析后写入上下文
+	HeaderUserPublicID    = "X-User-Public-ID" // 外部可见用户 ID（来自 JWT.sub）
+	HeaderIdentityID      = "X-Identity-ID"    // 认证身份 ID（来自 JWT.iid），仅 auth/MFA/audit 使用
+	HeaderUserType        = "X-User-Type"
+	HeaderSessionID       = "X-Session-ID"
+	HeaderTokenJTI        = "X-Token-JTI"
+	HeaderTokenExpiresAt  = "X-Token-Expires-At"
+	HeaderTenantID        = "X-Tenant-ID"
+	HeaderAuthProductCode = "X-Auth-Product-Code"
+	HeaderProductCode     = "X-Product-Code"
+	HeaderXForwardedFor   = "X-Forwarded-For"
+	HeaderXRealIP         = "X-Real-IP"
+	HeaderXForwardedProto = "X-Forwarded-Proto"
+
+	// APISIX GeoIP 插件注入的地理位置 Header
+	HeaderGeoIPCountryCode = "X-GeoIP-Country-Code"
+	HeaderGeoIPCity        = "X-GeoIP-City"
+)
+
+// 响应 Header
+const (
+	HeaderRateLimitLimit     = "X-RateLimit-Limit"
+	HeaderRateLimitRemaining = "X-RateLimit-Remaining"
+	HeaderRateLimitReset     = "X-RateLimit-Reset"
+	HeaderRetryAfter         = "Retry-After"
+)
+
+// UserIdentity 网关注入的认证身份上下文。
+//
+// UserID 是业务 user.id（由 session 真相源解析）— 所有业务对象关联此 ID。
+// UserPublicID 是外部可见 user.public_id（来自 JWT.sub）— API/媒体元数据使用。
+// IdentityID 是认证 identity.id（来自 JWT.iid）— 仅 auth/MFA/audit 使用。
+// Type 是身份类型（user / admin / super_admin）。
+type UserIdentity struct {
+	// 业务用户 ID（从 session 解析）
+	UserID UserID
+	// 外部可见用户 ID（从 X-User-Public-ID，对应 JWT.sub）
+	UserPublicID string
+	// 认证身份 ID（从 JWT.iid，仅 auth/MFA/audit 使用）
+	IdentityID IdentityID
+	// 用户类型（从 X-User-Type）: user, admin, super_admin
+	Type string
+	// 主租户 ID（从 X-Tenant-ID）
+	TenantID string
+	// 允许访问的租户 ID 列表（预留扩展）
+	TenantIDs []string
+}
+
+// ClientContext 客户端上下文
+type ClientContext struct {
+	// 客户端类型: mobile, web, desktop
+	Type string
+	// 客户端版本: semver 格式
+	Version string
+	// 客户端平台: iOS, Android, Web, macOS, Windows
+	Platform string
+	// 设备 ID（移动端设备号 / Web 端指纹）
+	DeviceID string
+	// 客户端 IP（从 X-Real-IP 或 X-Forwarded-For）
+	IP string
+	// Accept-Language 原始值
+	AcceptLanguage string
+	// 客户端当前界面 locale
+	Locale string
+	// 客户端时区（IANA）
+	Timezone string
+	// 客户端时区偏移（分钟）
+	TimezoneOffsetMinutes *int
+	// 屏幕宽度
+	ScreenWidth *int
+	// 屏幕高度
+	ScreenHeight *int
+	// 视口宽度
+	ViewportWidth *int
+	// 视口高度
+	ViewportHeight *int
+	// 颜色深度
+	ColorDepth *int
+	// 设备像素比
+	PixelRatio *float64
+	// 最大触点数
+	TouchPoints *int
+	// Java 是否启用
+	JavaEnabled *bool
+	// JavaScript 是否启用
+	JavaScriptEnabled *bool
+	// Cookie 是否启用
+	CookiesEnabled *bool
+	// GeoIP 国家代码
+	GeoCountryCode string
+	// GeoIP 城市
+	GeoCity string
+}
+
+// UserRole 用户角色
+type UserRole string
+
+const (
+	UserRoleGuest      UserRole = "guest"
+	UserRoleUser       UserRole = "user"
+	UserRoleVIP        UserRole = "vip"
+	UserRoleAdmin      UserRole = "admin"
+	UserRoleSuperAdmin UserRole = "super_admin"
+)
+
+// Product 产品类型
+type Product string
+
+const (
+	ProductPlatform Product = "platform"
+)
+
+// Operation 媒体生成操作类型（Shared Kernel）
+//
+// 由 mediagen 平台层与产品层共享消费。
+// 值的来源参考 Replicate operation taxonomy / Fal.ai model categories /
+// Wavespeed & Vidu API conventions。
+//
+// mediagen/domain.Operation 通过 `type Operation = types.Operation` 别名
+// 引用此类型以保持平台层 API 稳定；产品层 DTO/VO 直接使用 types.Operation。
+type Operation string
+
+const (
+	// OperationTextToImage 文生图
+	OperationTextToImage Operation = "t2i"
+	// OperationImageToImage 图生图
+	OperationImageToImage Operation = "i2i"
+	// OperationTextToVideo 文生视频
+	OperationTextToVideo Operation = "t2v"
+	// OperationImageToVideo 图生视频
+	OperationImageToVideo Operation = "i2v"
+	// OperationVideoExtend 视频延展
+	OperationVideoExtend Operation = "extend"
+	// OperationLipSync 口型同步
+	OperationLipSync Operation = "lip_sync"
+	// OperationUpscale 超分
+	OperationUpscale Operation = "upscale"
+	// OperationFrameExtract 视频帧提取
+	OperationFrameExtract Operation = "frame_extract"
+)
+
+// IsValid 校验操作类型合法
+func (o Operation) IsValid() bool {
+	switch o {
+	case OperationTextToImage, OperationImageToImage,
+		OperationTextToVideo, OperationImageToVideo,
+		OperationVideoExtend, OperationLipSync,
+		OperationUpscale, OperationFrameExtract:
+		return true
+	default:
+		return false
+	}
+}
+
+// String 实现 fmt.Stringer
+func (o Operation) String() string { return string(o) }
+
+// TenantStatus 租户状态
+type TenantStatus string
+
+const (
+	TenantStatusActive    TenantStatus = "active"
+	TenantStatusSuspended TenantStatus = "suspended"
+	TenantStatusPending   TenantStatus = "pending"
+	TenantStatusDisabled  TenantStatus = "disabled"
+	TenantStatusTrial     TenantStatus = "trial"
+)
+
+// RequestContext 请求上下文信息
+//
+// 业务 UserID 与认证 IdentityID 严格分离：UserID 关联 p_user_users.id，
+// IdentityID 关联 p_identity_identities.id。两者类型不同，编译期阻止混用。
+type RequestContext struct {
+	// 请求 ID
+	RequestID string `json:"request_id"`
+	// 业务用户 ID（p_user_users.id）
+	UserID *UserID `json:"user_id,omitempty"`
+	// 租户 ID
+	TenantID string `json:"tenant_id,omitempty"`
+	// 客户端 IP
+	IP string `json:"ip"`
+	// User-Agent
+	UserAgent string `json:"user_agent"`
+	// 请求时间
+	Timestamp time.Time `json:"timestamp"`
+	// 认证身份 ID（p_identity_identities.id，仅 auth/MFA/audit 使用）
+	IdentityID *IdentityID `json:"identity_id,omitempty"`
+	// 会话 ID
+	SessionID *int64 `json:"session_id,omitempty"`
+	// 客户端 ID
+	ClientID string `json:"client_id,omitempty"`
+	// 认证保障级别
+	Aal string `json:"aal,omitempty"`
+}
+
+// TenantInfo 租户基本信息
+type TenantInfo struct {
+	// 租户唯一标识
+	ID string `json:"id"`
+	// 租户名称
+	Name string `json:"name,omitempty"`
+	// 租户状态
+	Status TenantStatus `json:"status,omitempty"`
+}
+
+// SortOrder 排序方向
+type SortOrder string
+
+const (
+	SortOrderASC  SortOrder = "ASC"
+	SortOrderDESC SortOrder = "DESC"
+)
+
+// PageParams 基础分页参数（仅 Page + PageSize，不含排序）
+//
+// 大多数 DTO 应嵌入此类型而不是自行定义 Page/PageSize 字段。
+// 需要排序时嵌入 PaginationQuery。管理端使用 AdminPageParams；明确的大批量只读接口使用 BulkPageParams。
+type PageParams struct {
+	// 页码，从 1 开始
+	Page int `form:"page" binding:"omitempty,min=1"`
+	// 每页条数（上限 100）
+	PageSize int `form:"page_size" binding:"omitempty,min=1,max=100"`
+}
+
+// 分页默认值
+const (
+	DefaultPage      = 1
+	DefaultPageSize  = 20
+	MaxPageSize      = 100
+	AdminMaxPageSize = 200
+	BulkMaxPageSize  = 1000
+	DefaultSortField = "created_at"
+	DefaultSortOrder = SortOrderDESC
+)
+
+// Normalize 填充默认值并裁剪越界值
+func (p *PageParams) Normalize() {
+	if p.Page < 1 {
+		p.Page = DefaultPage
+	}
+	if p.PageSize < 1 || p.PageSize > MaxPageSize {
+		p.PageSize = DefaultPageSize
+	}
+}
+
+// Offset 计算 SQL OFFSET
+func (p *PageParams) Offset() int {
+	return (p.Page - 1) * p.PageSize
+}
+
+// CalcOffset 根据页码和每页条数计算 SQL OFFSET（供未嵌入 PageParams 的函数使用）
+func CalcOffset(page, pageSize int) int {
+	return (page - 1) * pageSize //nolint:I2 // 此函数本身即 I2 要求的共享 helper
+}
+
+// AdminPageParams 管理端分页参数（page_size 上限 200，用于下拉选择器等场景）
+type AdminPageParams struct {
+	// 页码，从 1 开始
+	Page int `form:"page" binding:"omitempty,min=1"`
+	// 每页条数（管理端上限 200）
+	PageSize int `form:"page_size" binding:"omitempty,min=1,max=200"`
+}
+
+// Normalize 填充默认值并裁剪越界值
+func (p *AdminPageParams) Normalize() {
+	if p.Page < 1 {
+		p.Page = DefaultPage
+	}
+	if p.PageSize < 1 || p.PageSize > AdminMaxPageSize {
+		p.PageSize = DefaultPageSize
+	}
+}
+
+// Offset 计算 SQL OFFSET
+func (p *AdminPageParams) Offset() int {
+	return (p.Page - 1) * p.PageSize
+}
+
+// BulkPageParams 大批量只读查询分页参数（page_size 上限 1000）
+//
+// 仅用于明确需要单次交付大量轻量列表项的只读接口，普通用户接口仍使用 PageParams。
+type BulkPageParams struct {
+	// 页码，从 1 开始
+	Page int `form:"page" binding:"omitempty,min=1"`
+	// 每页条数（大批量只读查询上限 1000）
+	PageSize int `form:"page_size" binding:"omitempty,min=1,max=1000"`
+}
+
+// Normalize 填充默认值并裁剪越界值
+func (p *BulkPageParams) Normalize() {
+	if p.Page < 1 {
+		p.Page = DefaultPage
+	}
+	if p.PageSize < 1 || p.PageSize > BulkMaxPageSize {
+		p.PageSize = DefaultPageSize
+	}
+}
+
+// Offset 计算 SQL OFFSET
+func (p *BulkPageParams) Offset() int {
+	return (p.Page - 1) * p.PageSize
+}
+
+// ToPageParams 转换为通用分页参数，避免管理端列表误暴露排序契约。
+func (p AdminPageParams) ToPageParams() PageParams {
+	return PageParams(p)
+}
+
+// PaginationQuery 带排序的分页查询参数
+//
+// 适用于需要排序的列表接口。仅含 Page/PageSize 时嵌入 PageParams 即可。
+type PaginationQuery struct {
+	PageParams
+	// 排序字段
+	SortBy string `form:"sort_by"`
+	// 排序方向
+	SortOrder SortOrder `form:"sort_order" binding:"omitempty,oneof=ASC DESC"`
+}
+
+// Normalize 填充默认值（含排序）
+func (q *PaginationQuery) Normalize() {
+	q.PageParams.Normalize()
+	if q.SortBy == "" {
+		q.SortBy = DefaultSortField
+	}
+	if q.SortOrder == "" {
+		q.SortOrder = DefaultSortOrder
+	}
+}
+
+// Offset 计算 SQL OFFSET（委托给 PageParams）
+func (q *PaginationQuery) Offset() int {
+	return q.PageParams.Offset()
+}