@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/core/audit/actor_resolver.go

@@ -0,0 +1,36 @@
+package audit
+
+import "context"
+
+// ResolvedIdentityReference 是登录审计里 identity_id 的可读投影。
+type ResolvedIdentityReference struct {
+	Email       string
+	DisplayName string
+}
+
+// ResolvedPrincipalReference 是 IAM 主体 ID 的可读投影。
+type ResolvedPrincipalReference struct {
+	DisplayName string
+	IdentityID  *int64
+	Email       string
+}
+
+// ActorResolver 解析审计记录里的主体引用为可读名称
+// 定义在 audit 包内，由外部注入实现（避免 core/ 依赖 platform/）
+type ActorResolver interface {
+	ResolveActorNames(ctx context.Context, actorIDs []int64) (map[int64]string, error)
+	ResolveIdentityContacts(ctx context.Context, identityIDs []int64) (map[int64]ResolvedIdentityReference, error)
+	ResolvePrincipalIdentities(ctx context.Context, principalIDs []int64) (map[int64]ResolvedPrincipalReference, error)
+}
+
+// ActorReferenceMatches 是外部主体目录检索返回的权威引用集合。
+type ActorReferenceMatches struct {
+	ActorIDs     []int64
+	IdentityIDs  []int64
+	PrincipalIDs []int64
+}
+
+// ActorReferenceSearcher 由主体目录所有者实现；检索失败必须返回错误。
+type ActorReferenceSearcher interface {
+	Search(context.Context, string) (ActorReferenceMatches, error)
+}

package/dist/resources/templates/go-backend/internal/core/audit/constants.go

@@ -0,0 +1,30 @@
+package audit
+
+import "strings"
+
+// skipPaths 不记录审计的路径前缀列表
+var skipPaths = []string{
+	"/health",
+	"/ready",
+	"/live",
+	"/metrics",
+	"/favicon.ico",
+	"/static/",
+}
+
+// skipMethods 不记录审计的 HTTP 方法
+var skipMethods = []string{
+	"OPTIONS",
+}
+
+func isAuditExcludedPath(path string) bool {
+	if path == "/docs" || strings.HasPrefix(path, "/docs/") {
+		return true
+	}
+	for _, prefix := range skipPaths {
+		if strings.HasPrefix(path, prefix) {
+			return true
+		}
+	}
+	return false
+}

package/dist/resources/templates/go-backend/internal/core/audit/context.go

@@ -0,0 +1,119 @@
+package audit
+
+import "context"
+
+// enrichmentKey context 键类型（unexported，防止外部包冲突）
+type enrichmentKey struct{}
+
+// AuditEnrichment 审计增强容器，由中间件注入 context，业务层写入
+type AuditEnrichment struct {
+	// 变更前后快照
+	Changes *ChangesPayload
+	// 扩展元数据
+	Metadata *MetadataPayload
+	// 审计资源覆盖
+	ResourceOverride *ResourceOverride
+	// 同一请求内需要额外落库的审计事实
+	AdditionalEntries []AdditionalAuditEntry
+}
+
+// ResourceOverride 覆盖路由推断出的审计资源
+type ResourceOverride struct {
+	ResourceType string
+	ResourceID   string
+	ProductCode  string
+}
+
+// AdditionalAuditEntry 同一 HTTP 请求内的附加审计事实。
+type AdditionalAuditEntry struct {
+	Action           AuditAction
+	Category         AuditCategory
+	RiskLevel        RiskLevel
+	ResourceOverride ResourceOverride
+	Changes          *ChangesPayload
+	Metadata         *MetadataPayload
+}
+
+// NewEnrichmentContext 创建包含审计增强容器的 context（由中间件调用）
+func NewEnrichmentContext(ctx context.Context) context.Context {
+	return context.WithValue(ctx, enrichmentKey{}, &AuditEnrichment{})
+}
+
+// Enrich 向当前请求的审计条目附加变更详情和元数据
+// 在非 HTTP 上下文（Worker/EventListener）中为 no-op
+func Enrich(ctx context.Context, changes *ChangesPayload, metadata *MetadataPayload) {
+	e := getEnrichment(ctx)
+	if e == nil {
+		return
+	}
+	if changes != nil {
+		e.Changes = changes
+	}
+	if metadata != nil {
+		e.Metadata = metadata
+	}
+}
+
+// EnrichChanges 仅设置变更快照
+func EnrichChanges(ctx context.Context, changes *ChangesPayload) {
+	e := getEnrichment(ctx)
+	if e == nil {
+		return
+	}
+	e.Changes = changes
+}
+
+// EnrichMetadata 仅设置扩展元数据
+func EnrichMetadata(ctx context.Context, metadata *MetadataPayload) {
+	e := getEnrichment(ctx)
+	if e == nil {
+		return
+	}
+	e.Metadata = metadata
+}
+
+// EnrichResource 设置审计资源归属
+func EnrichResource(ctx context.Context, resourceType string, resourceID string) {
+	e := getEnrichment(ctx)
+	if e == nil {
+		return
+	}
+	if e.ResourceOverride == nil {
+		e.ResourceOverride = &ResourceOverride{}
+	}
+	e.ResourceOverride.ResourceType = resourceType
+	e.ResourceOverride.ResourceID = resourceID
+}
+
+// EnrichResourceProductCode 设置审计资源产品归属
+func EnrichResourceProductCode(ctx context.Context, productCode string) {
+	e := getEnrichment(ctx)
+	if e == nil {
+		return
+	}
+	if e.ResourceOverride == nil {
+		e.ResourceOverride = &ResourceOverride{}
+	}
+	e.ResourceOverride.ProductCode = productCode
+}
+
+// EnrichAdditional 追加同一请求内的第二条审计事实。
+func EnrichAdditional(ctx context.Context, entry AdditionalAuditEntry) {
+	e := getEnrichment(ctx)
+	if e == nil {
+		return
+	}
+	e.AdditionalEntries = append(e.AdditionalEntries, entry)
+}
+
+// getEnrichment 从 context 获取审计增强容器
+func getEnrichment(ctx context.Context) *AuditEnrichment {
+	if ctx == nil {
+		return nil
+	}
+	v, ok := ctx.Value(enrichmentKey{}).(*AuditEnrichment)
+	if !ok {
+		return nil
+	}
+	return v
+}

package/dist/resources/templates/go-backend/internal/core/audit/context_test.go

@@ -0,0 +1,310 @@
+package audit
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestNewEnrichmentContext 验证中间件创建的 context 包含空的增强容器
+func TestNewEnrichmentContext(t *testing.T) {
+	ctx := NewEnrichmentContext(context.Background())
+	require.NotNil(t, ctx)
+
+	e := getEnrichment(ctx)
+	require.NotNil(t, e, "enrichment container must exist after NewEnrichmentContext")
+	assert.Nil(t, e.Changes, "Changes should be nil on fresh container")
+	assert.Nil(t, e.Metadata, "Metadata should be nil on fresh container")
+	assert.Nil(t, e.ResourceOverride, "ResourceOverride should be nil on fresh container")
+}
+
+// TestEnrichStoresChanges 验证 Enrich 将 ChangesPayload 写入 context
+func TestEnrichStoresChanges(t *testing.T) {
+	ctx := NewEnrichmentContext(context.Background())
+
+	changes := &ChangesPayload{
+		Before: map[string]any{"status": "active"},
+		After:  map[string]any{"status": "suspended"},
+	}
+	Enrich(ctx, changes, nil)
+
+	e := getEnrichment(ctx)
+	require.NotNil(t, e.Changes)
+	assert.Equal(t, changes, e.Changes)
+	assert.Nil(t, e.Metadata)
+}
+
+// TestEnrichStoresMetadata 验证 Enrich 将 MetadataPayload 写入 context
+func TestEnrichStoresMetadata(t *testing.T) {
+	ctx := NewEnrichmentContext(context.Background())
+
+	meta := &MetadataPayload{
+		Reason:    "admin manual adjustment",
+		SessionID: 42,
+	}
+	Enrich(ctx, nil, meta)
+
+	e := getEnrichment(ctx)
+	require.NotNil(t, e.Metadata)
+	assert.Equal(t, meta, e.Metadata)
+	assert.Nil(t, e.Changes)
+}
+
+// TestEnrichStoresBothPayloads 验证 Enrich 同时设置 Changes 和 Metadata
+func TestEnrichStoresBothPayloads(t *testing.T) {
+	ctx := NewEnrichmentContext(context.Background())
+
+	changes := &ChangesPayload{After: map[string]any{"id": int64(1), "name": "foo"}}
+	meta := &MetadataPayload{Reason: "create resource"}
+	Enrich(ctx, changes, meta)
+
+	e := getEnrichment(ctx)
+	assert.Equal(t, changes, e.Changes)
+	assert.Equal(t, meta, e.Metadata)
+}
+
+// TestEnrichReplacesOnSecondCall 验证多次调用 Enrich 以最后一次为准（replace 语义）
+func TestEnrichReplacesOnSecondCall(t *testing.T) {
+	ctx := NewEnrichmentContext(context.Background())
+
+	first := &ChangesPayload{Before: map[string]any{"status": "active"}}
+	second := &ChangesPayload{Before: map[string]any{"status": "suspended"}}
+
+	Enrich(ctx, first, nil)
+	Enrich(ctx, second, nil)
+
+	e := getEnrichment(ctx)
+	// 第二次调用覆盖第一次 — replace 语义
+	assert.Equal(t, second, e.Changes)
+}
+
+// TestEnrichNilChangesDoesNotClear 验证传入 nil changes 时不覆盖已有值
+func TestEnrichNilChangesDoesNotClear(t *testing.T) {
+	ctx := NewEnrichmentContext(context.Background())
+
+	changes := &ChangesPayload{After: map[string]any{"id": int64(99)}}
+	Enrich(ctx, changes, nil)
+
+	// 再次调用，changes 为 nil，不应清空已有值
+	Enrich(ctx, nil, nil)
+
+	e := getEnrichment(ctx)
+	assert.Equal(t, changes, e.Changes, "nil changes must not overwrite existing value")
+}
+
+// TestEnrichNilMetadataDoesNotClear 验证传入 nil metadata 时不覆盖已有值
+func TestEnrichNilMetadataDoesNotClear(t *testing.T) {
+	ctx := NewEnrichmentContext(context.Background())
+
+	meta := &MetadataPayload{Reason: "initial reason"}
+	Enrich(ctx, nil, meta)
+
+	Enrich(ctx, nil, nil)
+
+	e := getEnrichment(ctx)
+	assert.Equal(t, meta, e.Metadata, "nil metadata must not overwrite existing value")
+}
+
+// TestEnrichIsNoOpWithoutEnrichmentContext 验证在未经 NewEnrichmentContext 的 context 中
+// 调用 Enrich 是安全的 no-op（不 panic，不 crash）
+func TestEnrichIsNoOpWithoutEnrichmentContext(t *testing.T) {
+	// 裸 context，没有 enrichment 容器
+	ctx := context.Background()
+
+	assert.NotPanics(t, func() {
+		Enrich(ctx, &ChangesPayload{After: map[string]any{"x": 1}}, nil)
+	})
+}
+
+// TestEnrichIsNoOpWithNilContext 验证传入 nil context 时 Enrich 不 panic
+func TestEnrichIsNoOpWithNilContext(t *testing.T) {
+	assert.NotPanics(t, func() {
+		//nolint:staticcheck // 验证 nil context 输入保持 no-op 契约。
+		Enrich(nil, &ChangesPayload{After: map[string]any{"y": 2}}, nil)
+	})
+}
+
+// TestEnrichChangesOnlyHelper 验证 EnrichChanges 便捷函数
+func TestEnrichChangesOnlyHelper(t *testing.T) {
+	ctx := NewEnrichmentContext(context.Background())
+
+	changes := &ChangesPayload{Before: nil, After: map[string]any{"id": int64(7)}}
+	EnrichChanges(ctx, changes)
+
+	e := getEnrichment(ctx)
+	assert.Equal(t, changes, e.Changes)
+	assert.Nil(t, e.Metadata)
+}
+
+// TestEnrichMetadataOnlyHelper 验证 EnrichMetadata 便捷函数
+func TestEnrichMetadataOnlyHelper(t *testing.T) {
+	ctx := NewEnrichmentContext(context.Background())
+
+	meta := &MetadataPayload{
+		ErrorCode:           "subscription_expired",
+		RelatedResourceID:   "sub-123",
+		RelatedResourceType: "subscription",
+	}
+	EnrichMetadata(ctx, meta)
+
+	e := getEnrichment(ctx)
+	assert.Equal(t, meta, e.Metadata)
+	assert.Nil(t, e.Changes)
+}
+
+// TestEnrichResourceHelper 验证 EnrichResource 写入审计资源覆盖字段
+func TestEnrichResourceHelper(t *testing.T) {
+	ctx := NewEnrichmentContext(context.Background())
+
+	EnrichResource(ctx, "export", "task-123")
+
+	e := getEnrichment(ctx)
+	require.NotNil(t, e.ResourceOverride)
+	assert.Equal(t, "export", e.ResourceOverride.ResourceType)
+	assert.Equal(t, "task-123", e.ResourceOverride.ResourceID)
+	assert.Empty(t, e.ResourceOverride.ProductCode)
+}
+
+// TestEnrichResourceProductCodeHelper 验证产品归属可独立补充
+func TestEnrichResourceProductCodeHelper(t *testing.T) {
+	ctx := NewEnrichmentContext(context.Background())
+
+	EnrichResource(ctx, "export", "task-123")
+	EnrichResourceProductCode(ctx, "product_beta")
+
+	e := getEnrichment(ctx)
+	require.NotNil(t, e.ResourceOverride)
+	assert.Equal(t, "export", e.ResourceOverride.ResourceType)
+	assert.Equal(t, "task-123", e.ResourceOverride.ResourceID)
+	assert.Equal(t, "product_beta", e.ResourceOverride.ProductCode)
+}
+
+// TestEnrichResourceProductCodeCreatesOverride 验证仅覆盖产品时也能建立资源覆盖容器
+func TestEnrichResourceProductCodeCreatesOverride(t *testing.T) {
+	ctx := NewEnrichmentContext(context.Background())
+
+	EnrichResourceProductCode(ctx, "product_beta")
+
+	e := getEnrichment(ctx)
+	require.NotNil(t, e.ResourceOverride)
+	assert.Empty(t, e.ResourceOverride.ResourceType)
+	assert.Empty(t, e.ResourceOverride.ResourceID)
+	assert.Equal(t, "product_beta", e.ResourceOverride.ProductCode)
+}
+
+// TestEnrichAdditionalAppendsEntries 验证同一请求内可追加多条审计事实
+func TestEnrichAdditionalAppendsEntries(t *testing.T) {
+	ctx := NewEnrichmentContext(context.Background())
+
+	entry := AdditionalAuditEntry{
+		Action:    ActionCreate,
+		Category:  CategorySystem,
+		RiskLevel: RiskLevelHigh,
+		ResourceOverride: ResourceOverride{
+			ResourceType: string(AuditResourceIAMCredential),
+			ResourceID:   "34",
+		},
+		Changes: &ChangesPayload{After: map[string]any{"key_prefix": "iamk_public"}},
+		Metadata: &MetadataPayload{
+			RelatedResourceType: string(AuditResourceIAMServiceAccount),
+			RelatedResourceID:   "12",
+		},
+	}
+	EnrichAdditional(ctx, entry)
+
+	e := getEnrichment(ctx)
+	require.Len(t, e.AdditionalEntries, 1)
+	assert.Equal(t, entry, e.AdditionalEntries[0])
+}
+
+// TestEnrichChangesHelperIsNoOpWithoutContainer 验证 EnrichChanges 在无容器时安全
+func TestEnrichChangesHelperIsNoOpWithoutContainer(t *testing.T) {
+	ctx := context.Background()
+	assert.NotPanics(t, func() {
+		EnrichChanges(ctx, &ChangesPayload{After: map[string]any{"z": 3}})
+	})
+}
+
+// TestEnrichMetadataHelperIsNoOpWithoutContainer 验证 EnrichMetadata 在无容器时安全
+func TestEnrichMetadataHelperIsNoOpWithoutContainer(t *testing.T) {
+	ctx := context.Background()
+	assert.NotPanics(t, func() {
+		EnrichMetadata(ctx, &MetadataPayload{Reason: "test"})
+	})
+}
+
+// TestEnrichResourceHelperIsNoOpWithoutContainer 验证 EnrichResource 在无容器时安全
+func TestEnrichResourceHelperIsNoOpWithoutContainer(t *testing.T) {
+	ctx := context.Background()
+	assert.NotPanics(t, func() {
+		EnrichResource(ctx, "export", "task-123")
+	})
+}
+
+// TestEnrichResourceHelperIsNoOpWithNilContext 验证 EnrichResource 在 nil context 时安全
+func TestEnrichResourceHelperIsNoOpWithNilContext(t *testing.T) {
+	assert.NotPanics(t, func() {
+		//nolint:staticcheck // 验证 nil context 输入保持 no-op 契约。
+		EnrichResource(nil, "export", "task-123")
+	})
+}
+
+// TestEnrichResourceProductCodeHelperIsNoOpWithoutContainer 验证产品覆盖在无容器时安全
+func TestEnrichResourceProductCodeHelperIsNoOpWithoutContainer(t *testing.T) {
+	ctx := context.Background()
+	assert.NotPanics(t, func() {
+		EnrichResourceProductCode(ctx, "product_beta")
+	})
+}
+
+// TestEnrichResourceProductCodeHelperIsNoOpWithNilContext 验证产品覆盖在 nil context 时安全
+func TestEnrichResourceProductCodeHelperIsNoOpWithNilContext(t *testing.T) {
+	assert.NotPanics(t, func() {
+		//nolint:staticcheck // 验证 nil context 输入保持 no-op 契约。
+		EnrichResourceProductCode(nil, "product_beta")
+	})
+}
+
+// TestGetEnrichmentReturnsNilForBareContext 验证 getEnrichment 在无容器 context 中返回 nil
+func TestGetEnrichmentReturnsNilForBareContext(t *testing.T) {
+	ctx := context.Background()
+	e := getEnrichment(ctx)
+	assert.Nil(t, e)
+}
+
+// TestGetEnrichmentReturnsNilForNilContext 验证 getEnrichment 在 nil context 中返回 nil
+func TestGetEnrichmentReturnsNilForNilContext(t *testing.T) {
+	//nolint:staticcheck // 验证 nil context 输入保持 no-op 契约。
+	e := getEnrichment(nil)
+	assert.Nil(t, e)
+}
+
+// TestGetEnrichmentReturnsSamePointer 验证同一 context 上多次取出的指针相同（共享同一容器）
+func TestGetEnrichmentReturnsSamePointer(t *testing.T) {
+	ctx := NewEnrichmentContext(context.Background())
+
+	e1 := getEnrichment(ctx)
+	e2 := getEnrichment(ctx)
+	assert.Same(t, e1, e2, "getEnrichment must return the same pointer for the same context")
+}
+
+// TestEnrichContextIsolation 验证不同 context 实例之间的增强数据互不影响
+func TestEnrichContextIsolation(t *testing.T) {
+	ctx1 := NewEnrichmentContext(context.Background())
+	ctx2 := NewEnrichmentContext(context.Background())
+
+	changes1 := &ChangesPayload{After: map[string]any{"owner": "alice"}}
+	changes2 := &ChangesPayload{After: map[string]any{"owner": "bob"}}
+
+	Enrich(ctx1, changes1, nil)
+	Enrich(ctx2, changes2, nil)
+
+	e1 := getEnrichment(ctx1)
+	e2 := getEnrichment(ctx2)
+
+	assert.Equal(t, changes1, e1.Changes)
+	assert.Equal(t, changes2, e2.Changes)
+	assert.NotEqual(t, e1.Changes, e2.Changes)
+}