@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/.claude/docs/identifier-contract.md

@@ -0,0 +1,195 @@
+# Identifier Contract
+
+> Scope: all `backend/` modules
+> Goal: unify the definition, naming, ownership, and database constraints of public business numbers, cross-module business references, request idempotency keys, and third-party object IDs
+
+## 1. Why this must be unified
+
+Once identifier semantics are mixed, the damage compounds over time:
+
+- one field starts carrying both internal business identity and third-party object identity, and later reconciliation, audit, and replay become unreliable
+- runtime code treats a field as an idempotency key, but the database has no matching uniqueness guarantee, which creates duplicate writes under concurrency
+- every module assembles strings differently, and after a few years nobody can tell which segment is a formal object key, which segment is a temporary business fact, and which segment is a migration artifact
+
+These problems cannot be solved by reviewer memory. They need a single contract.
+
+## 2. Industry references
+
+| Decision Point | Industry Pattern | Used By | Our Choice | Rationale |
+|---------------|------------------|---------|------------|-----------|
+| Separate public business numbers from internal primary keys | Internal PK + externally visible business number | Stripe, Shopify | Keep `order_no`, `payment_no`, `member_no`, and similar fields separate from DB primary keys | Public identifiers stay readable, traceable, and safe to expose |
+| Align idempotency scope with DB uniqueness | Request idempotency + matching storage uniqueness | Stripe, AWS | If runtime deduplicates on a field or field set, the database must enforce uniqueness on the same scope | Prevents code from assuming idempotency while storage still allows duplicates |
+| Generate business references in the owner module | Owner-generated namespaced business key | Stripe events, CloudEvents `source + id` | Cross-module business references must come from owner helpers | Prevents downstream string concatenation drift and collisions |
+| Keep provider object IDs provider-scoped | Provider IDs stay provider-scoped and do not replace internal facts | Stripe, PayPal, GitHub webhooks | `provider_*_id`, `external_*_id`, and protocol IDs remain external-object identifiers only | Avoids treating mutable external IDs as internal business facts |
+
+## 3. The four identifier classes
+
+### 3.1 Public business numbers
+
+Definition: stable platform-generated numbers that can be exposed to operators, users, invoices, and receipts.
+
+Typical fields:
+
+- `p_order_orders.order_no`
+- `p_payment_payments.payment_no`
+- `p_payment_transactions.transaction_no`
+- `p_payment_refunds.refund_no`
+- `p_subscription_subscriptions.subscription_no`
+- `p_member_members.member_no`
+
+Rules:
+
+1. A public business number is not a database primary key.
+2. A public business number must have a database unique constraint.
+3. A public business number must not embed business-source semantics or third-party IDs.
+
+### 3.2 Cross-module business reference keys
+
+Definition: a stable key that answers “which business fact or business object caused this record,” and is used for cross-module traceability, replay, and deduplication.
+
+Typical fields:
+
+- `p_credit_grants.source_ref`
+- `p_credit_transactions.reference_id`
+- `p_credit_reservations(reference_type, reference_id)`
+- `p_quota_transactions.reference_id`
+- `p_member_point_ledger.reference_id`
+
+Rules:
+
+1. Business reference keys must be generated by owner helpers. Business services must not assemble them with ad-hoc `fmt.Sprintf`.
+2. When a formal object ID exists, use the formal object key first.
+3. When no formal object ID exists, use an explicitly namespaced stable business-fact key.
+4. If runtime performs exact deduplication on this key, the database must provide a matching unique constraint.
+5. Migration-only retained keys must use the `migration:` namespace and remain fully isolated from runtime formal keys.
+
+Formal syntax:
+
+```text
+<namespace>[:<segment>...]
+```
+
+Allowed characters:
+
+- lowercase letters
+- digits
+- `.`
+- `_`
+- `-`
+- `:`
+- RFC3339 timestamp strings
+
+### 3.3 Request idempotency keys
+
+Definition: a deduplication key for one API request or one fulfillment action. It does not express ownership of a business fact.
+
+Typical fields:
+
+- `p_payment_payments.idempotency_key`
+- `p_promotion_rewards.idempotency_key`
+- `p_mediagen_generations(product_code, idempotency_key)`
+
+Rules:
+
+1. A request idempotency key may come from the caller or from the owner module, as long as it is stable for the operation scope.
+2. The database unique constraint must match the runtime deduplication scope.
+3. A request idempotency key must not reuse a third-party object ID.
+4. A request idempotency key must not be written into cross-module business reference fields.
+
+### 3.4 Third-party and protocol object IDs
+
+Definition: identifiers generated by an external provider, protocol, or delivery system.
+
+Typical fields:
+
+- `provider_order_id`
+- `provider_payment_id`
+- `provider_customer_id`
+- `provider_subscription_id`
+- `provider_refund_id`
+- `provider_product_id`
+- `provider_price_id`
+- `provider_plan_id`
+- `external_message_id`
+- `message_id` (RFC 5322 Message-ID)
+
+Rules:
+
+1. A third-party object ID only expresses external object identity.
+2. A third-party object ID must not be written into internal business-reference fields.
+3. Whether a third-party object ID is unique depends on the provider contract. Never assume it can replace an internal idempotency key.
+
+## 4. Ownership rules
+
+| Class | Generated By | Constraint |
+|------|--------------|------------|
+| Public business numbers | Owner service | Must use a unified generator; callers cannot provide them |
+| Cross-module business reference keys | Owner domain helper | Must be generated by owner helpers; downstream modules cannot assemble them |
+| Request idempotency keys | API owner or caller | Database uniqueness scope must match runtime deduplication scope |
+| Third-party object IDs | External provider or protocol | Store, pass through, and reconcile only; do not treat them as internal primary business semantics |
+
+## 5. Database constraint rules
+
+### 5.1 Business reference keys
+
+If runtime uses any of the following patterns:
+
+- `FindByReferenceID(referenceID)`
+- `FindBySourceRef(sourceRef)`
+- `FindByIdempotencyKey(idempotencyKey)`
+
+then the database must satisfy one of these two conditions:
+
+1. create a unique constraint on the exact same lookup scope
+2. explicitly declare the business relationship as one-to-many and include the full owner scope in runtime lookups
+
+The following mismatch is forbidden:
+
+- runtime performs exact-match deduplication on `reference_id`
+- the database only has a normal index and still allows duplicate rows
+
+### 5.2 Migration-retained keys
+
+When migration data has no formal runtime object, use:
+
+```text
+migration:<product>:...
+```
+
+It is forbidden to place raw source-system primary keys, raw source UUIDs, or raw third-party IDs into runtime business fields without a namespace.
+
+## 6. Migration compliance policy
+
+When an importer contract changes, “fresh import is correct” is not enough.
+
+Rules:
+
+1. A migration table cannot be marked complete based only on a fresh empty-database rerun.
+2. Existing databases that were already imported must be audited against the latest contract.
+3. If existing imported rows are stale, ship one of these paths before calling the table complete:
+   - an in-place repair migration or repair tool
+   - an explicit clean reimport procedure that safely removes the stale slice and rebuilds it with the current importer
+4. Do not hide stale imported data behind runtime compatibility branches.
+5. If a runtime config table can still generate rows that violate the current contract, the migration is still incomplete even if the importer itself is fixed.
+
+## 7. Current audit conclusions
+
+| Field / Table | Class | Current State | Decision |
+|---------------|-------|---------------|----------|
+| `p_credit_grants.source_ref` | Business reference key | Has a global unique constraint | Keep it and continue generating keys only through credit helpers |
+| `p_credit_transactions(reference_type, reference_id)` | Business reference key | Runtime uses the composite semantic | Keep the composite model; do not downgrade it to single-column uniqueness |
+| `p_credit_reservations(reference_type, reference_id)` | Business reference key | Already has a composite unique constraint | Good |
+| `p_quota_transactions.reference_id` | Business reference key | Runtime deduplicates by exact single-column lookup; historical schema only had a normal index | Must add a single-column unique constraint and centralize the helper |
+| `p_member_point_ledger.reference_id` | Business reference key | Already unique, but naming was scattered across listener and service code | Must centralize generation in member helpers |
+| `p_promotion_rewards.idempotency_key` | Request idempotency key | Unique constraint is complete | Keep owner-local idempotency; do not turn it into a cross-module business reference |
+| `p_payment_payments.idempotency_key` | Request idempotency key | Unique constraint is complete | Good |
+| `p_mediagen_generations(product_code, idempotency_key)` | Request idempotency key | Composite scope matches runtime behavior | Good |
+| `provider_*_id`, `external_*_id`, `message_id` | Third-party / protocol object ID | Semantics are clear | Keep them isolated from internal business keys |
+
+## 8. Implementation requirements
+
+1. Before adding any `reference_id`, `source_ref`, or `idempotency_key` field, classify it first.
+2. If it is a business reference key, add the owner helper before writing service or repository code.
+3. If it is a request idempotency key, define the runtime deduplication scope before creating the database unique index.
+4. If it is a third-party object ID, do not use it for internal idempotency or business-reference deduplication.
+5. When modifying legacy modules, extract scattered string generation into domain helpers instead of copying more ad-hoc formats.

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

@@ -0,0 +1,22 @@
+# Specification Index
+
+Read `CLAUDE.md` completely. Files below retain the full OneX specifications and examples. Binding event, E2E and OpenAPI contracts apply according to their declared owner. Platform paths, service names, governance commands and platform tables refer to upstream OneX; generated backend commands are defined by its own `Makefile`.
+
+| File | Content | Priority |
+|------|---------|----------|
+| `api-design.md` | Handler, Service, DTO, VO, Pagination templates | MUST |
+| `module-standards.md` | Directory structures, file creation decision tree | MUST |
+| `error-handling.md` | ErrorType/ErrorCode, BusinessError, Error middleware | MUST |
+| `database.md` | Model template, column types, migration template | MUST |
+| `identifier-contract.md` | Public business numbers, business references, idempotency keys, third-party IDs | MUST |
+| `logging.md` | Logger setup, log levels, correlation IDs | MUST |
+| `platform-boundary.md` | Platform / BFF / Viewer / Auth boundary rules | MUST |
+| `event-runtime-boundary.md` | Outbox relay scope, runtime listener ownership, cross-process event rules | MUST |
+| `e2e-standards.md` | Full-chain E2E design, fixture seeding, relay regression guardrails | MUST |
+| `openapi-contract.md` | OpenAPI 所有权、中文文档导航、投影、兼容性与本地文档契约 | MUST |
+| `check-list.md` | Development workflow, pre-commit checklist | MUST |
+| `architecture-template.md` | Complete Level A/B/C architecture document skeleton | MUST for design |
+| `quality-gates.md` | Full upstream platform quality gates and ownership | Upstream operations |
+| `payment-gateway-onboarding.md` | Complete upstream payment provider onboarding | Upstream integration |
+| `mediagen-provider-onboarding-sop.md` | Complete upstream media provider onboarding | Upstream integration |
+| `mediagen-provider-quick-reference.md` | Dated upstream provider snapshot | Upstream reference |

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

@@ -0,0 +1,314 @@
+# Logging Reference
+
+> Templates and examples. Rules in `CLAUDE.md`.
+
+---
+
+## Logger Initialization
+
+```go
+package logger
+
+import (
+	"fmt"
+
+	"go.uber.org/zap"
+	"go.uber.org/zap/zapcore"
+
+	"{{module}}/internal/core/config"
+)
+
+// New 创建 Zap Logger
+func New(cfg *config.LogConfig) (*zap.Logger, error) {
+	var zapCfg zap.Config
+
+	if cfg.Env == "production" {
+		zapCfg = zap.NewProductionConfig()
+	} else {
+		zapCfg = zap.NewDevelopmentConfig()
+		zapCfg.EncoderConfig.EncodeLevel = zapcore.CapitalColorLevelEncoder
+	}
+
+	zapCfg.Level = zap.NewAtomicLevelAt(parseLevel(cfg.Level))
+	zapCfg.EncoderConfig.TimeKey = "timestamp"
+	zapCfg.EncoderConfig.EncodeTime = zapcore.ISO8601TimeEncoder
+
+	logger, err := zapCfg.Build(
+		zap.AddCallerSkip(0),
+		zap.AddStacktrace(zap.ErrorLevel),
+	)
+	if err != nil {
+		return nil, fmt.Errorf("build logger: %w", err)
+	}
+
+	return logger, nil
+}
+
+func parseLevel(level string) zapcore.Level {
+	switch level {
+	case "debug":
+		return zap.DebugLevel
+	case "info":
+		return zap.InfoLevel
+	case "warn":
+		return zap.WarnLevel
+	case "error":
+		return zap.ErrorLevel
+	case "fatal":
+		return zap.FatalLevel
+	default:
+		return zap.InfoLevel
+	}
+}
+```
+
+---
+
+## Logger Injection
+
+```go
+// 通过构造函数注入 (Wire)
+
+type ConversationService struct {
+	repo   domain.ConversationRepository
+	logger *zap.Logger
+}
+
+func NewConversationService(repo domain.ConversationRepository, logger *zap.Logger) *ConversationService {
+	return &ConversationService{
+		repo:   repo,
+		logger: logger.Named("ConversationService"),
+	}
+}
+```
+
+---
+
+## Log Levels
+
+| Level | When |
+|-------|------|
+| `Fatal` | 应用崩溃，不可恢复（数据库连接断开） — 自动调用 `os.Exit(1)` |
+| `Error` | 系统异常，外部 API 失败（支付网关超时） |
+| `Warn` | 可恢复错误，降级（缓存未命中，重试成功） |
+| `Info` | 业务事件，状态变更（订单创建，用户登录） |
+| `Debug` | 详细调试信息（查询参数，响应数据） |
+
+---
+
+## Log Volume Governance
+
+Production logging must separate durable audit evidence from high-volume request telemetry.
+
+| Signal | Required behavior |
+| --- | --- |
+| Business mutation audit | Always preserve. High-risk audit events must not be dropped when async buffers are full. |
+| Login and security audit | Always preserve through the audit module, not through ad hoc application logs. |
+| HTTP write request | Preserve in access logs. It is the operator entry point for user-impacting changes. |
+| HTTP failure request | Preserve in access logs and stdout request summaries. |
+| Slow request | Preserve in access logs and stdout request summaries. |
+| Successful read request | Do not write all records by default. Use deterministic sampling or metrics/traces. |
+| Health, readiness, metrics, static docs | Exclude from audit/access logs unless a security investigation explicitly requires them. |
+
+Rules:
+
+1. Do not use application logs as the source of truth for business changes. Use `sys_audit_logs` through `audit.Enrich()` or the DomainEvent audit envelope.
+2. Do not emit one info-level stdout log for every successful read request in production.
+3. Do not log request or response bodies, provider credentials, tokens, passwords, email contents, or payment identifiers beyond internal IDs.
+4. Use bounded-cardinality fields only. User IDs, order IDs, and request IDs are allowed as fields; they are not allowed as metric labels.
+5. Buffer overflow logs must be aggregated by time window, not emitted once per dropped entry.
+6. Do not use `zap.Any`, `zap.Reflect`, `zap.ByteString`, or `zap.Binary` in production code. Convert values to typed scalar fields such as IDs, status, count, size, duration, timestamp, error code, or payload type.
+7. Do not use raw field names `payload`, `body`, `raw`, `respBody`, `raw_request`, or `raw_response` in application logs. Use `payloadType`, `payloadBytes`, `responseBytes`, `requestId`, `providerRequestId`, or a redacted digest when diagnostics require correlation.
+
+These log-field rules are enforced by `backend/scripts/check-forbidden-patterns.sh` and therefore run through `make pre-commit`, `.githooks/pre-commit`, and the governance gate.
+
+---
+
+## Structured Logging Examples
+
+```go
+// info - 业务事件（短描述，过去时）
+s.logger.Info("conversation created",
+	zap.Int64("conversationId", conv.ID),
+	zap.Int64("userId", conv.UserID),
+)
+
+// error - Error() field
+s.logger.Error("operation failed",
+	zap.Error(err),
+	zap.Int64("conversationId", id),
+)
+
+// warn - 可恢复
+s.logger.Warn("AI analysis failed, retrying",
+	zap.Int64("messageId", msgID),
+	zap.Int("attempt", 1),
+)
+
+// debug - 详细信息
+s.logger.Debug("processing message",
+	zap.Int64("messageId", msgID),
+)
+```
+
+---
+
+## Request Logging Middleware
+
+```go
+// internal/common/middleware/logging.go
+
+engine.Use(middleware.LoggingWithConfig(logger, cfg.Log))
+```
+
+`LoggingWithConfig` is the only HTTP request summary logger for Gin services. It keeps failures, write requests, and slow requests while allowing successful read requests to stay at debug level or deterministic sampling.
+
+Configuration keys:
+
+| Key | Purpose |
+| --- | --- |
+| `log.request_success_level` | Level for sampled successful read request summaries |
+| `log.request_success_sample_rate` | Deterministic sampling rate for successful read request summaries |
+| `log.request_slow_threshold` | Latency threshold that promotes a request summary to info |
+
+---
+
+## Audit And Access Log Policy
+
+`internal/core/audit.AccessLogPolicy` owns database access-log volume control.
+
+| Condition | `sys_access_logs` write |
+| --- | --- |
+| `POST` / `PUT` / `PATCH` / `DELETE` | Always |
+| HTTP `4xx` / `5xx` | Always |
+| Duration above `audit.access_log.slow_request_threshold` | Always |
+| Successful `GET` / `HEAD` | Deterministic sample by request identity |
+
+Configuration keys:
+
+| Key | Purpose |
+| --- | --- |
+| `audit.access_log.enabled` | Enables access-log database writes |
+| `audit.access_log.success_read_sample_rate` | Deterministic sampling rate for successful read requests |
+| `audit.access_log.slow_request_threshold` | Latency threshold that always records the request |
+| `audit.access_log.record_write_methods` | Preserves mutation entry points |
+| `audit.access_log.record_client_errors` | Preserves client-visible failures |
+
+`sys_audit_logs` must remain a business evidence table. Do not reduce audit-log volume by sampling business mutations.
+
+---
+
+## Write Audit Surface Classification
+
+Write audit coverage is evaluated by source surface, not by raw database writes alone.
+
+| Surface | Required audit path |
+| --- | --- |
+| Operator or external request command | `audit.Enrich()` after successful write, or DomainEvent `AuditChanges` envelope. |
+| Domain event that represents a business state change | DomainEvent `AuditChanges` and optional `AuditMeta`. |
+| Login/logout/security event | Auth event listener writes `sys_login_logs` and `sys_audit_logs`; before/after snapshots are not required. |
+| Repository or persistence adapter | No direct audit call. The owning service command carries audit evidence. |
+| Worker/system task | Use a run ledger plus DomainEvent envelope for user-visible business state changes. |
+| Audit infrastructure | Never self-audit its own buffer flush or log-table writes. |
+
+Rules:
+
+1. Do not call `audit.Enrich()` from repository code.
+2. Do not call `audit.Enrich()` from worker-only contexts; it is request-context enrichment and is a no-op outside HTTP.
+3. Do not rely on comments that mention `audit.Enrich` or `AuditChanges`; the actual call or event field must exist in code.
+4. Private helper writes are audited through the public command that owns the operation.
+5. System events that change user-visible business state must carry `AuditChanges` even when emitted by scheduled jobs.
+
+---
+
+## Correlation ID (Request ID)
+
+```go
+package middleware
+
+import (
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/trace"
+
+	"{{module}}/internal/common/types"
+)
+
+// RequestID 从请求头读取或生成 UUID，设置到 context、响应头和 OTel Span
+func RequestID() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		// 优先读取 X-Request-ID（APISIX 生成），其次 X-Correlation-ID
+		requestID := c.GetHeader(types.HeaderRequestID)
+		if requestID == "" {
+			requestID = c.GetHeader(types.HeaderCorrelationID)
+		}
+		if requestID == "" {
+			requestID = uuid.New().String()
+		}
+
+		// 存入 context
+		c.Set(string(types.ContextKeyRequestID), requestID)
+
+		// 写入响应头
+		c.Header(types.HeaderRequestID, requestID)
+
+		// 注入 OTel Span 属性
+		span := trace.SpanFromContext(c.Request.Context())
+		if span.SpanContext().IsValid() {
+			span.SetAttributes(attribute.String("request.id", requestID))
+		}
+
+		c.Next()
+	}
+}
+
+// GetRequestID 从 gin.Context 获取请求 ID
+func GetRequestID(c *gin.Context) string {
+	if v, ok := c.Get(string(types.ContextKeyRequestID)); ok {
+		if id, ok := v.(string); ok {
+			return id
+		}
+	}
+	return ""
+}
+```
+
+---
+
+## Worker Job Logging
+
+```go
+// 后台任务 - 手动添加 correlation ID
+func (p *AITaskProcessor) ProcessTask(ctx context.Context, task *asynq.Task) error {
+	jobLogger := p.logger.With(
+		zap.String("correlationId", fmt.Sprintf("job-%s", task.ResultWriter().TaskID())),
+		zap.String("taskType", task.Type()),
+	)
+	jobLogger.Info("processing task")
+
+	// ... 处理逻辑
+
+	jobLogger.Info("task completed")
+	return nil
+}
+```
+
+---
+
+## Sensitive Data Redaction
+
+```go
+// 日志中的敏感字段处理
+
+// NEVER 直接记录
+s.logger.Info("user login", zap.String("password", password))   // ❌ 禁止
+s.logger.Info("api call", zap.String("token", token))            // ❌ 禁止
+s.logger.Warn("provider failed", zap.ByteString("respBody", raw)) // ❌ 禁止
+s.logger.Error("job failed", zap.Any("payload", payload))         // ❌ 禁止
+
+// ALWAYS 只记录 ID 和非敏感信息
+s.logger.Info("user logged in", zap.Int64("userId", userID))     // ✅
+s.logger.Info("api call completed", zap.String("provider", "openai"), zap.Duration("latency", d)) // ✅
+s.logger.Warn("provider failed", zap.Int("responseBytes", len(raw)), zap.String("providerRequestId", requestID)) // ✅
+```