@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/core/eventstream/noop.go

@@ -0,0 +1,22 @@
+package eventstream
+
+import "context"
+
+// NoopEventStreamPublisher 空实现的事件流发布者
+//
+// 用于不需要 Redis Stream 分发的 cmd/ 场景（如 identity-api）。
+// 所有方法为空操作，不会产生任何副作用。
+type NoopEventStreamPublisher struct{}
+
+// NewNoopEventStreamPublisher 创建空实现的事件流发布者
+func NewNoopEventStreamPublisher() *NoopEventStreamPublisher {
+	return &NoopEventStreamPublisher{}
+}
+
+func (n *NoopEventStreamPublisher) Publish(_ context.Context, _ StreamEvent) error {
+	return nil
+}
+
+func (n *NoopEventStreamPublisher) Close() error {
+	return nil
+}

package/dist/resources/templates/go-backend/internal/core/eventstream/provider.go

@@ -0,0 +1,20 @@
+package eventstream
+
+import "github.com/google/wire"
+
+// ProviderSet Redis Stream 事件流发布 Wire 依赖注入集合
+//
+// 提供真实的 Redis Stream 发布实现。
+// 前置依赖：*redis.Client, *zap.Logger
+var ProviderSet = wire.NewSet(
+	NewRedisStreamPublisher,
+	wire.Bind(new(EventStreamPublisher), new(*RedisStreamPublisher)),
+)
+
+// NoopProviderSet 空实现的事件流发布 Wire 依赖注入集合
+//
+// 用于不需要 Redis Stream 分发的 cmd/ 场景。
+var NoopProviderSet = wire.NewSet(
+	NewNoopEventStreamPublisher,
+	wire.Bind(new(EventStreamPublisher), new(*NoopEventStreamPublisher)),
+)

package/dist/resources/templates/go-backend/internal/core/eventstream/publisher.go

@@ -0,0 +1,38 @@
+package eventstream
+
+import (
+	"context"
+	"encoding/json"
+	"time"
+)
+
+// EventStreamPublisher 事件流发布接口
+//
+// 抽象事件分发通道（Redis Stream / Kafka），业务代码通过此接口发布跨服务事件。
+// 实现可替换，便于未来从 Redis Stream 迁移到 Kafka。
+type EventStreamPublisher interface {
+	// Publish 发布事件到对应 Stream
+	Publish(ctx context.Context, event StreamEvent) error
+	// Close 关闭发布者连接
+	Close() error
+}
+
+// StreamEvent 事件流消息
+type StreamEvent struct {
+	// 事件唯一标识（outbox event ID，消费端用于幂等去重）
+	EventID string
+	// 事件类型（如 "subscription.created"）
+	EventType string
+	// 聚合根 ID
+	AggregateID string
+	// 事件发生时间
+	OccurredAt time.Time
+	// 产品编码（消费端按此过滤，只处理自己产品的事件）
+	ProductCode string
+	// 事件载荷（JSON）
+	Payload json.RawMessage
+	// 事件元数据（JSON，包含 user_id, trace_id 等）
+	Metadata json.RawMessage
+	// 事件 schema 版本（用于消费端兼容性判断）
+	SchemaVersion string
+}

package/dist/resources/templates/go-backend/internal/core/eventstream/redis.go

@@ -0,0 +1,109 @@
+package eventstream
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	"github.com/redis/go-redis/v9"
+	"go.uber.org/zap"
+
+	"{{module}}/internal/common/utils"
+)
+
+// streamMaxLen Redis Stream 近似裁剪上限
+// 每个 Stream 保留约 10000 条消息，~130MB 总内存（13 streams × 10K × ~1KB）
+const streamMaxLen int64 = 10000
+
+// RedisStreamPublisher Redis Stream 事件发布者
+//
+// 将事件通过 XADD 写入按领域分组的 Redis Stream。
+// 使用近似裁剪（MAXLEN ~）控制内存占用。
+type RedisStreamPublisher struct {
+	client *redis.Client
+	logger *zap.Logger
+}
+
+// NewRedisStreamPublisher 创建 Redis Stream 发布者
+func NewRedisStreamPublisher(client *redis.Client, logger *zap.Logger) *RedisStreamPublisher {
+	return &RedisStreamPublisher{
+		client: client,
+		logger: logger.Named("RedisStreamPublisher"),
+	}
+}
+
+// Publish 发布事件到 Redis Stream
+//
+// 根据事件类型路由到对应 Stream，使用 XADD + MAXLEN ~ 写入。
+// 失败返回 error，由调用方（Outbox Relay）决定重试策略。
+func (p *RedisStreamPublisher) Publish(ctx context.Context, event StreamEvent) error {
+	// 路由到目标 Stream
+	streamKey, err := ResolveStream(event.EventType)
+	if err != nil {
+		return fmt.Errorf("resolve stream: %w", err)
+	}
+
+	// 提取 product_code 到顶层字段，方便消费端快速过滤
+	productCode := event.ProductCode
+	if productCode == "" {
+		// 从 metadata 中提取 product_code 作为 fallback
+		productCode = extractProductCode(event.Metadata)
+	}
+
+	// XADD 写入 Stream（* 自动生成消息 ID，MAXLEN ~ 近似裁剪）
+	args := &redis.XAddArgs{
+		Stream: streamKey,
+		MaxLen: streamMaxLen,
+		Approx: true,
+		Values: map[string]any{
+			"event_id":       event.EventID,
+			"event_type":     event.EventType,
+			"aggregate_id":   event.AggregateID,
+			"occurred_at":    event.OccurredAt.Format(utils.RFC3339Milli),
+			"product_code":   productCode,
+			"payload":        string(event.Payload),
+			"metadata":       string(event.Metadata),
+			"schema_version": event.SchemaVersion,
+		},
+	}
+
+	messageID, err := p.client.XAdd(ctx, args).Result()
+	if err != nil {
+		return fmt.Errorf("xadd to stream %s: %w", streamKey, err)
+	}
+
+	p.logger.Debug("event published to stream",
+		zap.String("stream", streamKey),
+		zap.String("messageId", messageID),
+		zap.String("eventType", event.EventType),
+		zap.String("eventId", event.EventID),
+	)
+
+	return nil
+}
+
+// Close 关闭发布者（Redis 客户端由外部管理，此处为 noop）
+func (p *RedisStreamPublisher) Close() error {
+	return nil
+}
+
+// extractProductCode 从 metadata JSON 中提取 product_code
+func extractProductCode(metadata json.RawMessage) string {
+	if len(metadata) == 0 {
+		return ""
+	}
+	var m map[string]any
+	if err := json.Unmarshal(metadata, &m); err != nil {
+		return ""
+	}
+	if v, ok := m["product_code"].(string); ok {
+		return v
+	}
+	// Extra 字段中可能包含 product_code
+	if extra, ok := m["extra"].(map[string]any); ok {
+		if v, ok := extra["product_code"].(string); ok {
+			return v
+		}
+	}
+	return ""
+}

package/dist/resources/templates/go-backend/internal/core/eventstream/routing.go

@@ -0,0 +1,104 @@
+package eventstream
+
+import (
+	"fmt"
+	"strings"
+)
+
+// streamRouting 事件域前缀到 Redis Stream 的显式路由映射
+//
+// 按限界上下文分组，而非按事件名前缀一一对应。
+// 新增事件域前缀必须在此注册，未注册的域前缀会在 ValidateRouting 时被检测到。
+var streamRouting = map[string]string{
+	// Identity 限界上下文（认证 + 权限 + 用户身份）
+	"identity": "onex:events:identity",
+	"auth":     "onex:events:identity",
+	"rbac":     "onex:events:identity",
+	// User 领域
+	"user":         "onex:events:user",
+	"product_user": "onex:events:user",
+	// Trade 限界上下文（订单 + 支付）
+	"order":   "onex:events:order",
+	"payment": "onex:events:payment",
+	"iap":     "onex:events:payment",
+	// Subscription 领域
+	"subscription": "onex:events:subscription",
+	// Billing 限界上下文（发票 + 积分 + 退款凭证）
+	"invoice":     "onex:events:billing",
+	"credit":      "onex:events:billing",
+	"credit_note": "onex:events:billing",
+	// Quota 领域
+	"quota": "onex:events:quota",
+	// Catalog + Marketing 领域
+	"catalog": "onex:events:catalog",
+	"coupon":  "onex:events:catalog",
+	// 实体商务领域
+	"commerce_command": "onex:events:commerce",
+	"checkout":         "onex:events:commerce",
+	"inventory":        "onex:events:commerce",
+	"delivery":         "onex:events:commerce",
+	"fulfillment":      "onex:events:commerce",
+	"merchandise":      "onex:events:commerce",
+	// Notification 领域
+	"notification": "onex:events:notification",
+	"inbox":        "onex:events:notification",
+	// Communication runtime 领域
+	"campaign": "onex:events:communication",
+	// Storage 领域
+	"file":  "onex:events:storage",
+	"media": "onex:events:storage",
+	// Platform 基础设施
+	"product":          "onex:events:platform",
+	"setting":          "onex:events:platform",
+	"apikey":           "onex:events:platform",
+	"ratelimit":        "onex:events:platform",
+	"appversion":       "onex:events:platform",
+	"export":           "onex:events:platform",
+	"integrationevent": "onex:events:platform",
+	// CMS (Content) 领域
+	"article":  "onex:events:cms",
+	"redirect": "onex:events:cms",
+	"comment":  "onex:events:cms",
+	// AI 产品领域
+	"conversation":    "onex:events:ai",
+	"message":         "onex:events:ai",
+	"analysis":        "onex:events:ai",
+	"reply":           "onex:events:ai",
+	"ai_provider":     "onex:events:ai",
+	"ai_model":        "onex:events:ai",
+	"ai_routing":      "onex:events:ai",
+	"ai_config":       "onex:events:ai",
+	"investigation":   "onex:events:ai",
+	"prompt_version":  "onex:events:ai",
+	"eval_suite_run":  "onex:events:ai",
+	"eval_regression": "onex:events:ai",
+	"experiment":      "onex:events:ai",
+	"mediagen":        "onex:events:mediagen",
+}
+
+// ResolveStream 解析事件类型到目标 Redis Stream key
+//
+// 从事件类型名称提取域前缀（第一个 "." 之前的部分），查路由表。
+// 未注册的域前缀返回 error，防止静默丢失事件。
+func ResolveStream(eventType string) (string, error) {
+	prefix := strings.Split(eventType, ".")[0]
+	stream, ok := streamRouting[prefix]
+	if !ok {
+		return "", fmt.Errorf("no stream route for event domain %q (event: %s)", prefix, eventType)
+	}
+	return stream, nil
+}
+
+// ValidateRouting 验证所有已注册事件类型是否在路由表中有对应映射
+//
+// 接受事件类型列表（通常从 sharedevents/registry.go 的 payloadFactories 获取），
+// 返回所有缺失路由的事件类型。启动时调用，快速发现配置遗漏。
+func ValidateRouting(eventTypes []string) []string {
+	var missing []string
+	for _, et := range eventTypes {
+		if _, err := ResolveStream(et); err != nil {
+			missing = append(missing, et)
+		}
+	}
+	return missing
+}

package/dist/resources/templates/go-backend/internal/core/eventstream/routing_test.go

@@ -0,0 +1,71 @@
+package eventstream
+
+import "testing"
+
+func TestResolveStreamRoutesPhysicalCommercePrefixes(t *testing.T) {
+	tests := []struct {
+		name      string
+		eventType string
+	}{
+		{name: "commerce command", eventType: "commerce_command.failed"},
+		{name: "checkout", eventType: "checkout.quote.reserved"},
+		{name: "inventory", eventType: "inventory.reservation.expired"},
+		{name: "delivery", eventType: "delivery.task.delivered"},
+		{name: "fulfillment", eventType: "fulfillment.order.created"},
+		{name: "merchandise", eventType: "merchandise.item.created"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			stream, err := ResolveStream(tt.eventType)
+			if err != nil {
+				t.Fatalf("ResolveStream(%q) returned error: %v", tt.eventType, err)
+			}
+			if stream != "onex:events:commerce" {
+				t.Fatalf("ResolveStream(%q) = %q, want %q", tt.eventType, stream, "onex:events:commerce")
+			}
+		})
+	}
+}
+
+func TestResolveStreamRoutesIntegrationEventPlatformPrefix(t *testing.T) {
+	stream, err := ResolveStream("integrationevent.probe.executed")
+	if err != nil {
+		t.Fatalf("ResolveStream returned error: %v", err)
+	}
+	if stream != "onex:events:platform" {
+		t.Fatalf("ResolveStream = %q, want %q", stream, "onex:events:platform")
+	}
+}
+
+func TestResolveStreamRoutesProductContextToPlatform(t *testing.T) {
+	stream, err := ResolveStream("product.context.changed")
+	if err != nil {
+		t.Fatalf("ResolveStream returned error: %v", err)
+	}
+	if stream != "onex:events:platform" {
+		t.Fatalf("ResolveStream = %q, want %q", stream, "onex:events:platform")
+	}
+}
+
+func TestResolveStreamReturnsErrorForUnknownPrefix(t *testing.T) {
+	_, err := ResolveStream("unknown_domain.event.created")
+	if err == nil {
+		t.Fatal("expected unknown event prefix to return error")
+	}
+}
+
+func TestValidateRoutingReportsUnknownPrefix(t *testing.T) {
+	missing := ValidateRouting([]string{
+		"checkout.quote.reserved",
+		"unknown_domain.event.created",
+		"delivery.task.delivered",
+	})
+
+	if len(missing) != 1 {
+		t.Fatalf("ValidateRouting returned %v, want one missing event", missing)
+	}
+	if missing[0] != "unknown_domain.event.created" {
+		t.Fatalf("ValidateRouting missing event = %q, want %q", missing[0], "unknown_domain.event.created")
+	}
+}

package/dist/resources/templates/go-backend/internal/core/geoip/model.go

@@ -0,0 +1,19 @@
+package geoip
+
+// GeoLocation IP 地理定位结果
+type GeoLocation struct {
+	// ISO 3166-1 alpha-2 国家代码
+	Country string
+	// 国家名称（英文）
+	CountryName string
+	// 地区/州代码
+	RegionCode string
+	// 城市名称（英文）
+	City string
+	// 时区
+	Timezone string
+	// 纬度
+	Latitude float64
+	// 经度
+	Longitude float64
+}

package/dist/resources/templates/go-backend/internal/core/geoip/service.go

@@ -0,0 +1,88 @@
+package geoip
+
+import (
+	"net"
+
+	"github.com/oschwald/geoip2-golang"
+	"go.uber.org/zap"
+
+	"{{module}}/internal/core/config"
+)
+
+// Service GeoIP 地理定位服务，基于 MaxMind GeoLite2。
+// 包内裸 Service 命名是 Go idiom（geoip.Service），对应 scanner T2 regex 盲点。
+type Service struct { //nolint:T2 // bare Service in dedicated package is idiomatic
+	reader *geoip2.Reader
+	logger *zap.Logger
+}
+
+// New 创建 GeoIP 服务，数据库路径为空或文件不存在时静默降级为无操作模式
+func New(logger *zap.Logger, cfg *config.Config) *Service {
+	if cfg.GeoIP.DatabasePath == "" {
+		logger.Info("geoip disabled: no database path configured")
+		return &Service{logger: logger.Named("GeoIP")}
+	}
+
+	reader, err := geoip2.Open(cfg.GeoIP.DatabasePath)
+	if err != nil {
+		logger.Warn("geoip disabled: failed to open database",
+			zap.String("path", cfg.GeoIP.DatabasePath),
+			zap.Error(err),
+		)
+		return &Service{logger: logger.Named("GeoIP")}
+	}
+
+	logger.Info("geoip enabled", zap.String("path", cfg.GeoIP.DatabasePath))
+	return &Service{reader: reader, logger: logger.Named("GeoIP")}
+}
+
+// Lookup 根据 IP 地址查询地理位置，返回 nil 表示无法定位
+func (s *Service) Lookup(ip string) *GeoLocation {
+	if s.reader == nil {
+		return nil
+	}
+
+	parsedIP := net.ParseIP(ip)
+	if parsedIP == nil {
+		return nil
+	}
+
+	record, err := s.reader.City(parsedIP)
+	if err != nil {
+		return nil
+	}
+
+	result := &GeoLocation{}
+	if record.Country.IsoCode != "" {
+		result.Country = record.Country.IsoCode
+	}
+	if name, ok := record.Country.Names["en"]; ok && name != "" {
+		result.CountryName = name
+	}
+	if len(record.Subdivisions) > 0 && record.Subdivisions[0].IsoCode != "" {
+		result.RegionCode = record.Subdivisions[0].IsoCode
+	}
+	if name, ok := record.City.Names["en"]; ok && name != "" {
+		result.City = name
+	}
+	if record.Location.TimeZone != "" {
+		result.Timezone = record.Location.TimeZone
+	}
+	result.Latitude = record.Location.Latitude
+	result.Longitude = record.Location.Longitude
+
+	if result.Country == "" && result.CountryName == "" && result.RegionCode == "" &&
+		result.City == "" && result.Timezone == "" {
+		return nil
+	}
+
+	return result
+}
+
+// Close 关闭 GeoIP 数据库
+func (s *Service) Close() error {
+	if s.reader != nil {
+		return s.reader.Close()
+	}
+	return nil
+}