@stackonward/cli 0.0.1 → 1.0.0

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

@@ -0,0 +1,369 @@
+# Database Reference
+
+> Templates and examples. Rules in `CLAUDE.md`.
+
+---
+
+## Column Type Mapping
+
+| Data Type | PostgreSQL Type | Go Type | Notes |
+|-----------|-----------------|---------|-------|
+| Primary Key | `bigserial` | `int64` | Auto-increment primary key |
+| Foreign Key | `bigint` | `int64` | Logical foreign-key reference only |
+| Product Code | `varchar(50)` | `string` | Product code in `snake_case`, referencing `p_products.code` |
+| Status | `varchar(20)` | `string` | String enum constant |
+| Boolean | `boolean` | `bool` | Prefer `is_xxx` naming |
+| JSON | `jsonb` | `datatypes.JSON` or a custom struct | Supports indexing |
+| Text | `text` | `string` | Unlimited length |
+| Varchar | `varchar(n)` | `string` | Explicit max length |
+| Timestamp | `timestamptz(3)` | `time.Time` | Millisecond precision |
+| Money | `decimal(19,4)` | `string` | Keep string semantics in code |
+| Nullable | any + `NULL` | `*T` or `sql.NullXxx` | Use pointer or nullable wrapper |
+
+## Identifier Classes
+
+Before designing table columns, classify identifier fields using [identifier-contract.md](./identifier-contract.md):
+
+- Public business numbers: `order_no`, `payment_no`, `member_no`
+- Cross-module business reference keys: `source_ref`, `reference_id`
+- Request idempotency keys: `idempotency_key`
+- Third-party or protocol object IDs: `provider_*_id`, `external_*_id`, `message_id`
+
+It is forbidden to mix these four semantics into one field.
+
+### Migration Compliance Rule
+
+For migration-owned tables, verify them in two clearly separated scopes:
+
+1. current importer truth: clean database -> `migrate-up` -> latest import tool
+2. retained imported databases, if they must continue to exist, via an explicit repair path or clean reimport procedure
+
+Do not mix stale pre-rerun data into the statement about whether the latest importer contract is correct.
+
+### Product Code Convention
+
+Every table that carries product scope **must** use the following unified column definition:
+
+```go
+// Go struct tag
+ProductCode string `gorm:"column:product_code;type:varchar(50);not null;index;comment:产品编码" json:"product_code"`
+```
+
+```sql
+-- SQL column
+product_code VARCHAR(50) NOT NULL
+```
+
+| Rule | Detail |
+|------|--------|
+| Field name | `product_code` (NEVER: `product_id`, `app_id`) |
+| Column type | `VARCHAR(50)` (NEVER: `varchar(20)`, `varchar(32)`, `varchar(64)`) |
+| Value format | `snake_case`, for example `ai_chat`, `ai_assistant` |
+| Value constraint | `^[a-z][a-z0-9_]{1,49}$` |
+| Enum source | `internal/common/types.Product` (single source of truth) |
+| Logical base reference | `p_products.code` (logical foreign key, no physical FK constraint) |
+
+---
+
+## FORBIDDEN: Foreign Key Constraints (CRITICAL)
+
+**Do not create FOREIGN KEY constraints on application tables.** The industry-standard pattern used by large platforms such as Alibaba, Meituan, Google, and Stripe is to enforce referential integrity in the application layer and keep the database focused on storage and indexing.
+
+| Problem | Impact |
+|---------|--------|
+| Cascading locks | Parent-row DELETE or UPDATE locks child rows and increases deadlock risk under concurrency |
+| DDL blocking | `ALTER TABLE` must lock all FK-related tables |
+| Sharding limits | Cross-database foreign keys are not available |
+| Write overhead | Every INSERT or UPDATE needs FK existence checks |
+
+**Preferred alternatives**:
+- Service-layer existence checks before writing (`SELECT 1 WHERE id = ?`)
+- Soft delete via `deleted_at` instead of `CASCADE DELETE`
+- Asynchronous consistency scans for orphaned references
+
+```sql
+-- FORBIDDEN
+ALTER TABLE orders ADD CONSTRAINT fk_user FOREIGN KEY (user_id) REFERENCES users(id);
+
+-- CORRECT: index the column, do not create a foreign key
+CREATE INDEX idx_orders_user_id ON orders (user_id);
+```
+
+---
+
+## Index Design Standards
+
+Indexes must be justified by a query path, uniqueness contract, or operational investigation path.
+
+| Scenario | Required index shape |
+| --- | --- |
+| Product-scoped table | `product_code` as the left prefix of the hot-path composite index |
+| User list within product | `(product_code, user_id, created_at DESC)` or the exact equality filters followed by the sort column |
+| Status work queue | Partial index over the active state set, for example `WHERE status IN ('pending', 'running')` |
+| Soft-delete uniqueness | Partial unique index with `WHERE deleted_at IS NULL` |
+| Provider callback idempotency | Unique index on provider code plus provider event/object ID and owning scope |
+| Large append-only time-series table | Partition by time plus BRIN index on the timestamp column |
+| Failure investigation | Partial index on failed rows, for example `WHERE is_success = false` |
+| Trace or request lookup | Partial index on `trace_id` or `request_id` with non-empty predicate |
+
+Rules:
+
+1. Do not create a single-column low-cardinality index unless the query path proves it is selective enough.
+2. Do not create overlapping duplicate indexes. If two indexes share table, columns, uniqueness, and predicate, keep one owner index.
+3. Do not add an index only because a column exists. The owning repository query must be able to use it.
+4. Every runtime exact-match deduplication scope must have a matching unique database constraint.
+5. Index names use `idx_<table>_<columns>` for normal indexes and `uk_<table>_<scope>` for unique indexes.
+6. Every new `CREATE INDEX` migration must include `查询路径：` and `索引理由：` comments immediately above the statement.
+
+Index evidence comment format:
+
+```sql
+-- 查询路径：internal/platform/order/infrastructure/persistence.go ListByUser
+-- 索引理由：product_code/user_id 等值过滤后按 created_at 倒序分页。
+CREATE INDEX IF NOT EXISTS idx_p_order_orders_product_user_created
+    ON p_order_orders (product_code, user_id, created_at DESC);
+```
+
+The evidence must point to a real repository or service query. A migration that only makes an audit report count go down is not a valid index design.
+
+---
+
+## Log And Audit Table Storage Standards
+
+Audit and access tables are operational infrastructure, not ordinary CRUD tables.
+
+| Table | Required storage contract |
+| --- | --- |
+| `sys_access_logs` | Weekly range partitions, default partition, short retention, BRIN on `created_at`, partial indexes for failure and trace lookup |
+| `sys_audit_logs` | Monthly range partitions, default partition, long compliance retention, BRIN on `created_at`, actor/resource/category/risk indexes |
+| `sys_login_logs` | Monthly range partitions, default partition, security retention, failed-login partial index, IP and identity lookup indexes |
+
+Rules:
+
+1. Partition maintenance must create future partitions before data arrives.
+2. Default partitions are mandatory for log tables so writes do not fail when a future partition is missing.
+3. Dropping old access-log partitions is allowed by retention policy; sampling business audit records is not allowed.
+4. High-volume successful read traffic should be controlled before database write, not cleaned up after unbounded insertion.
+5. Migrations that touch these tables must preserve the default partition, BRIN time index, and failure investigation indexes.
+
+---
+
+## Base Model
+
+```go
+// internal/core/database/base_model.go
+
+// BaseModel 基础模型，所有实体嵌入
+type BaseModel struct {
+	// 主键 ID
+	ID int64 `gorm:"column:id;primaryKey;autoIncrement;comment:主键 ID" json:"id"`
+	// 创建时间
+	CreatedAt time.Time `gorm:"column:created_at;autoCreateTime:milli;comment:创建时间" json:"created_at"`
+	// 更新时间
+	UpdatedAt time.Time `gorm:"column:updated_at;autoUpdateTime:milli;comment:更新时间" json:"updated_at"`
+}
+
+// SoftDeleteModel 支持软删除的基础模型
+type SoftDeleteModel struct {
+	BaseModel
+	// 删除时间
+	DeletedAt gorm.DeletedAt `gorm:"column:deleted_at;index;comment:删除时间" json:"-"`
+}
+```
+
+---
+
+## Entity Example
+
+```go
+// internal/platform/user/domain/model.go
+
+// User 用户实体
+type User struct {
+	database.SoftDeleteModel
+	// 用户名
+	Name string `gorm:"column:name;type:varchar(100);not null;comment:用户名"`
+	// 邮箱
+	Email string `gorm:"column:email;type:varchar(255);not null;uniqueIndex;comment:邮箱"`
+	// 用户角色
+	Role string `gorm:"column:role;type:varchar(20);not null;default:user;comment:用户角色"`
+	// 用户状态
+	Status string `gorm:"column:status;type:varchar(20);not null;default:active;index;comment:用户状态"`
+	// 头像 URL
+	AvatarURL *string `gorm:"column:avatar_url;type:varchar(500);comment:头像 URL"`
+	// 扩展元数据
+	Metadata datatypes.JSON `gorm:"column:metadata;type:jsonb;comment:扩展元数据"`
+}
+
+// TableName 指定表名
+func (User) TableName() string {
+	return "p_user_users"
+}
+```
+
+---
+
+## Migration Template (golang-migrate)
+
+```sql
+-- migrations/000001_create_users.up.sql
+
+CREATE TABLE "p_user_users" (
+    "id"               BIGSERIAL PRIMARY KEY,
+    "name"             VARCHAR(100) NOT NULL,
+    "email"            VARCHAR(255) NOT NULL,
+    "role"             VARCHAR(20) NOT NULL DEFAULT 'user',
+    "status"           VARCHAR(20) NOT NULL DEFAULT 'active',
+    "avatar_url"       VARCHAR(500),
+    "metadata"         JSONB,
+    "created_at"       TIMESTAMPTZ(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at"       TIMESTAMPTZ(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "deleted_at"       TIMESTAMPTZ(3)
+);
+
+CREATE UNIQUE INDEX "uk_users_email" ON "p_user_users" ("email");
+CREATE INDEX "idx_users_status" ON "p_user_users" ("status");
+CREATE INDEX "idx_users_deleted_at" ON "p_user_users" ("deleted_at");
+```
+
+```sql
+-- migrations/000001_create_users.down.sql
+
+DROP TABLE IF EXISTS "p_user_users";
+```
+
+---
+
+## GORM Database Connection
+
+```go
+// internal/core/database/database.go
+
+// NewDB 创建 GORM 数据库连接
+func NewDB(cfg *config.DatabaseConfig, logger *zap.Logger) (*gorm.DB, error) {
+	dsn := fmt.Sprintf(
+		"host=%s port=%d user=%s password=%s dbname=%s sslmode=disable TimeZone=Asia/Shanghai",
+		cfg.Host, cfg.Port, cfg.User, cfg.Password, cfg.Name,
+	)
+	db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{
+		Logger:                                   zapgorm2.New(logger),
+		NamingStrategy:                           schema.NamingStrategy{SingularTable: true},
+		DisableForeignKeyConstraintWhenMigrating: true,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("connect database: %w", err)
+	}
+
+	sqlDB, err := db.DB()
+	if err != nil {
+		return nil, fmt.Errorf("get sql.DB: %w", err)
+	}
+	sqlDB.SetMaxOpenConns(cfg.MaxOpenConns)
+	sqlDB.SetMaxIdleConns(cfg.MaxIdleConns)
+	sqlDB.SetConnMaxLifetime(cfg.ConnMaxLifetime)
+
+	return db, nil
+}
+```
+
+---
+
+## Query Patterns
+
+```go
+// 指定字段查询
+var users []domain.User
+db.Select("id", "name", "email").
+	Where("status = ?", "active").
+	Find(&users)
+
+// 分页查询
+var users []domain.User
+var total int64
+db.Model(&domain.User{}).
+	Select("id", "name", "status", "created_at").
+	Where("status = ?", "active").
+	Count(&total).
+	Offset(types.CalcOffset(page, pageSize)).
+	Limit(pageSize).
+	Order("created_at DESC").
+	Find(&users)
+
+// 预加载关联（避免 N+1）
+var conversations []domain.Conversation
+db.Preload("Messages").
+	Where("user_id = ?", userID).
+	Find(&conversations)
+
+// Join 查询
+db.Select("conversations.id, COUNT(messages.id) as message_count").
+	Joins("LEFT JOIN messages ON messages.conversation_id = conversations.id").
+	Group("conversations.id").
+	Find(&conversations)
+```
+
+---
+
+## Repository Pattern
+
+```go
+// internal/platform/user/domain/repository.go
+
+// UserRepository 用户仓储接口
+type UserRepository interface {
+	Create(ctx context.Context, user *User) error
+	FindByID(ctx context.Context, id int64) (*User, error)
+	FindByEmail(ctx context.Context, email string) (*User, error)
+	FindAll(ctx context.Context, filter UserFilter, page, pageSize int) ([]User, int64, error)
+	Update(ctx context.Context, user *User) error
+	SoftDelete(ctx context.Context, id int64) error
+}
+
+// UserFilter 查询筛选条件
+type UserFilter struct {
+	Status *string
+	Role   *string
+}
+```
+
+```go
+// internal/platform/user/infrastructure/persistence.go
+
+type userRepository struct {
+	db *gorm.DB
+}
+
+// NewUserRepository 创建 UserRepository 实现
+func NewUserRepository(db *gorm.DB) domain.UserRepository {
+	return &userRepository{db: db}
+}
+
+func (r *userRepository) FindAll(ctx context.Context, filter domain.UserFilter, page, pageSize int) ([]domain.User, int64, error) {
+	var users []domain.User
+	var total int64
+
+	query := database.GetDB(ctx, r.db).Model(&domain.User{})
+	if filter.Status != nil {
+		query = query.Where("status = ?", *filter.Status)
+	}
+	if filter.Role != nil {
+		query = query.Where("role = ?", *filter.Role)
+	}
+
+	if err := query.Count(&total).Error; err != nil {
+		return nil, 0, fmt.Errorf("count users: %w", err)
+	}
+
+	err := query.
+		Select("id", "name", "email", "role", "status", "created_at").
+		Offset(types.CalcOffset(page, pageSize)).
+		Limit(pageSize).
+		Order("created_at DESC").
+		Find(&users).Error
+	if err != nil {
+		return nil, 0, fmt.Errorf("find users: %w", err)
+	}
+
+	return users, total, nil
+}
+```

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

@@ -0,0 +1,161 @@
+# E2E Standards
+
+This document defines the binding design and execution rules for backend full-chain E2E tests.
+
+It is a rules document, not a sample implementation guide.
+
+## Final Goal
+
+E2E tests prove that an externally visible workflow remains correct across:
+
+- HTTP entrypoints
+- database state transitions
+- outbox relay delivery
+- worker side effects
+- final access behavior
+
+If a workflow crosses runtime boundaries and can break user-facing truth, it needs an E2E contract test.
+
+## Industry Alignment
+
+| Decision Point | Industry Pattern | Used By | Our Choice | Rationale |
+| --- | --- | --- | --- | --- |
+| Test isolation | Fresh fixture data per test | Playwright, Cypress, GitHub integration suites | Unique fixture identities and business rows | Prevents cross-test state bleed and makes failures reproducible. |
+| System contract tests | Black-box entrypoint + durable state assertions | Stripe API tests, GitHub integration tests | Public API action + DB/side-effect verification | Cross-runtime workflows must be proven from outside the service boundary. |
+| Background verification | Poll durable terminal state, not transient logs | AWS async workflow testing | Bounded polling on DB/API terminal state | Logs are hints; durable state is the contract. |
+| Async architecture regression guard | Exact event contract tests beside E2E | Stripe-style explicit event typing | Relay whitelist unit tests + E2E | One catches config drift; the other catches runtime drift. |
+| Fixture setup | Direct seed only for prerequisites outside the behavior under test | Large platform integration suites | Seed prerequisites via DB, execute target action via public API | Keeps setup fast without bypassing the workflow under test. |
+
+## When E2E Is Mandatory
+
+Add or update an E2E when the change touches any of these:
+
+- auth / session lifecycle
+- account deletion / irreversible state machines
+- outbox relay routing
+- worker-driven cleanup or notifications
+- billing, subscription, quota, entitlement, or credit side effects
+- product bootstrap or projection repair
+
+## Binding Rules
+
+### 1. Enter Through the Real Public Interface
+
+Rules:
+
+- The action under test must enter through HTTP, gateway, queue, or another real public trigger.
+- The workflow under test must not be executed by direct repository or SQL mutation.
+
+Allowed:
+
+- seed prerequisites directly in DB
+- call the real public endpoint for the behavior under test
+
+Forbidden:
+
+- inserting the main state transition directly with SQL
+- calling an internal service method instead of the public entrypoint when testing API behavior
+
+### 2. Seed Only Prerequisites
+
+Direct DB seed is allowed only for data that is not the subject of the test itself.
+
+Examples:
+
+- catalog plan rows
+- template rows
+- API key rows needed to verify revocation
+- product-scoped dependent rows needed to verify cleanup
+
+Forbidden:
+
+- seeding the deletion request row when testing account deletion
+- seeding final identity/user deleted state and then calling the endpoint
+
+### 3. Assert Three Layers of Truth
+
+Every full-chain E2E must assert all three:
+
+- authoritative database state
+- externally visible access behavior
+- downstream side effects
+
+For account closure, this means:
+
+- identity / user / product_user terminal rows
+- viewer / refresh / login denial
+- subscription, API key, setting, and product-data cleanup
+
+### 4. Poll Durable State, Never Logs
+
+Rules:
+
+- Use bounded polling against DB rows or public APIs.
+- Wait for terminal conditions only.
+- Fail with an explicit timeout tied to the missing contract.
+
+Forbidden:
+
+- sleeping a fixed duration and hoping the worker finished
+- asserting on log text as the primary contract
+
+### 5. Pair E2E with Relay Whitelist Tests
+
+If the E2E depends on cross-process events:
+
+- add a unit test for `ProvideRelayConfig()`
+- assert the exact event whitelist and reject dangerous wildcards
+
+Reason:
+
+- the unit test catches config drift such as `user.deleted` becoming `user.*`
+- the E2E catches runtime drift such as listener duplication or missing cleanup
+
+### 6. Design for Reuse
+
+Reusable E2E helpers must:
+
+- create unique fixture identifiers
+- expose small helper steps, not one giant opaque setup
+- use the same base clients and DB helpers as other suites
+- avoid hardcoded business defaults that can drift from runtime config
+
+## Canonical Structure
+
+Recommended shape:
+
+1. register fixture account through public auth API
+2. wait for required projections
+3. seed prerequisite business rows directly in DB
+4. execute the public action under test
+5. wait for durable terminal state
+6. assert final access behavior
+7. assert downstream cleanup
+
+## Commands
+
+Run the stack first:
+
+```bash
+make docker-dev
+```
+
+Run one focused suite:
+
+```bash
+go test -tags e2e -count=1 -v ./tests/e2e/accountclosure/...
+```
+
+Run all E2E suites only when the environment is stable enough for the broader blast radius:
+
+```bash
+make test-e2e
+```
+
+## Review Checklist
+
+- Did the test enter through the real public interface?
+- Did it seed only prerequisites, not the behavior under test?
+- Did it assert DB state, access contract, and side effects?
+- Did it avoid fixed sleeps and use bounded polling?
+- Did it add or update the relay whitelist regression test in the same change?