@stackonward/cli 0.0.1 → 1.0.0

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

@@ -0,0 +1,449 @@
+# Architecture Document Template
+
+> Design documents produced in plan mode must follow this skeleton.
+> After completing a new module's design document, archive it at `docs/platform/{module}-architecture.md`.
+
+---
+
+## Level A: New Module / Major Architecture Change
+
+Complete architecture document, must include all of the following sections. Refer to existing documents in `docs/platform/`.
+
+### Mandatory Skeleton
+
+```markdown
+# {Module Name} Architecture Design Document
+
+> **Version**: 1.0
+> **Module Complexity**: Full DDD / Simplified DDD / Flat
+> **Tech Stack**: Go 1.24 + Gin + GORM + PostgreSQL 16 + Redis 7.0 [+ Asynq]
+> **Design Reference**: {Industry reference, e.g. Stripe API, Shopify Order}
+
+---
+
+## 1. Architecture Overview
+
+### 1.1 Module Position in the System
+
+[ASCII diagram: Client → Gateway → BFF → This Module → Dependent Modules → Infrastructure]
+
+### 1.2 Core Capabilities
+
+| Capability | Description |
+|------------|-------------|
+| {Capability 1} | {One-line description} |
+
+### 1.3 Design Principles
+
+| Principle | Application in This Module |
+|-----------|---------------------------|
+| {Principle} | {Specific application} |
+
+### 1.4 Module Complexity Assessment
+
+{Answer the complexity decision tree: Does it have a state machine? → Does it have complex domain logic? → Which Tier?}
+
+---
+
+## 2. Core Concept Definitions
+
+### 2.1 Concept Relationship Diagram
+
+[ASCII diagram: Relationships between entities (1:N, N:M, reference)]
+
+### 2.2 Concept Description Table
+
+| Concept | Definition | Go Type | Persistence |
+|---------|------------|---------|-------------|
+| {Entity} | {One-line definition} | `domain.Xxx` | `p_{module}_xxx` |
+
+---
+
+## 3. Database Design
+
+### 3.1 Table Structure Overview
+
+| Table Name | Description | Row Volume |
+|------------|-------------|------------|
+| `p_{module}_xxx` | {Purpose} | {Estimate} |
+
+### 3.2 Detailed Table Definitions
+
+Each table must include:
+
+| Column | Type | Nullable | Default | Comment |
+|--------|------|----------|---------|---------|
+| `id` | `bigserial` | NO | — | Primary key |
+| ... | ... | ... | ... | ... |
+
+Index definitions:
+
+| Index | Columns | Type | Purpose |
+|-------|---------|------|---------|
+| ... | ... | unique/btree/gin | ... |
+
+### 3.3 Migration Files
+
+```sql
+-- Complete SQL, ready to execute
+CREATE TABLE p_{module}_xxx (
+    ...
+);
+```
+
+---
+
+## 4. Directory Structure Design
+
+### 4.1 Complete Directory Tree
+
+```
+internal/platform/{module}/
+├── module.go          # Module facade
+├── provider.go        # Wire ProviderSet
+├── domain/
+│   ├── model.go       # {List each Entity}
+│   ├── enum.go        # {List each enum}
+│   ├── repository.go  # {List each repository interface}
+│   └── events.go      # {If domain events exist}
+├── application/
+│   ├── service.go     # {List each Service}
+│   ├── handler.go     # {List each Handler}
+│   ├── dto.go         # {List each Request DTO}
+│   ├── vo.go          # {List each Response VO}
+│   └── listener.go    # {If event listeners exist}
+└── infrastructure/
+    └── persistence.go # {List repository implementations}
+```
+
+### 4.2 Package Split Decision
+
+{Answer the package split rules from CLAUDE.md: Does application/ need sub-domain splitting? Does domain/ need splitting by aggregate root?}
+
+---
+
+## 5. Domain Model Design
+
+### 5.1 Aggregate Root
+
+```go
+type Xxx struct {
+    database.BaseModel
+    // Field definitions (with GORM tag + comment tag)
+}
+
+func (x *Xxx) TableName() string { return "p_{module}_xxx" }
+```
+
+### 5.2 State Machine (if applicable)
+
+```
+State transition diagram:
+  pending → processing, cancelled
+  processing → completed, failed
+  completed → refunded (terminal)
+  cancelled (terminal)
+  failed (terminal)
+```
+
+```go
+var xxxTransitions = map[XxxStatus][]XxxStatus{
+    XxxStatusPending: {XxxStatusProcessing, XxxStatusCancelled},
+    ...
+}
+```
+
+### 5.3 Behavior Methods
+
+| Method Signature | Purpose | Caller |
+|------------------|---------|--------|
+| `IsXxx() bool` | {Condition check} | Service |
+| `CanTransitionTo(target) bool` | {State transition validity} | Service |
+| `TransitionTo(target) error` | {Execute state transition} | Service |
+
+### 5.4 Repository Interface
+
+```go
+type XxxRepository interface {
+    FindByID(ctx context.Context, id int64) (*Xxx, error)
+    Save(ctx context.Context, entity *Xxx) error
+    // Add as needed
+}
+```
+
+### 5.5 Domain Events
+
+| Event | Trigger | Consumer |
+|-------|---------|----------|
+| `XxxCreatedEvent` | After successful creation | {module} Listener |
+
+---
+
+## 6. Application Service Design
+
+### 6.1 Service Method List
+
+| Method | Parameters | Return | Business Rules |
+|--------|------------|--------|----------------|
+| `CreateXxx(ctx, req)` | `CreateXxxRequest` | `*XxxResponse, error` | {Key logic} |
+
+### 6.2 Key Workflows
+
+{Describe main business flows in steps:}
+
+```
+CreateXxx:
+  1. Validate input
+  2. Check business rules (call model methods)
+  3. Persist
+  4. Publish event with AuditChanges when the operation owns a domain event
+  5. Otherwise call audit.Enrich() after successful write; never use both audit paths
+  6. Return VO
+```
+
+---
+
+## 7. API Interface Design
+
+### 7.1 Endpoint List
+
+| Method | Path | Auth | Handler | Description |
+|--------|------|------|---------|-------------|
+| POST | `/api/v1/xxx` | authenticated | `CreateXxx` | Create |
+| GET | `/api/v1/xxx/:id` | authenticated | `GetXxx` | Query |
+
+### 7.2 Request/Response Examples
+
+**POST /api/v1/xxx**
+
+Request:
+```json
+{
+    "name": "example",
+    "type": "standard"
+}
+```
+
+Response (201):
+```json
+{
+    "id": 1,
+    "name": "example",
+    "type": "standard",
+    "status": "pending",
+    "created_at": "2026-01-01T00:00:00Z"
+}
+```
+
+Error (422):
+```json
+{
+    "error": {
+        "type": "business_error",
+        "code": "xxx_limit_exceeded",
+        "message": "Cannot create more than 10 items"
+    }
+}
+```
+
+---
+
+## 8. Event-Driven Integration (if cross-module interaction exists)
+
+### 8.1 Published Events
+
+| Event | Definition Location | Trigger |
+|-------|---------------------|---------|
+| `XxxCreatedEvent` | `sharedevents/events.go` | After successful creation |
+
+### 8.2 Consumed Events
+
+| Event | Source Module | Handling Logic |
+|-------|--------------|----------------|
+| `PaymentSucceededEvent` | payment | Update order status |
+
+---
+
+## 9. Wire Injection Design
+
+### 9.1 ProviderSet
+
+```go
+var ProviderSet = wire.NewSet(
+    NewModule,
+    application.NewXxxService,
+    application.NewXxxHandler,
+    infrastructure.NewXxxRepository,
+)
+```
+
+### 9.2 Injection per cmd/
+
+| cmd/ | Injected Content | Notes |
+|------|------------------|-------|
+| template-app | `*Module` | Full module (routes + listeners) |
+| worker | `*XxxListener` | Event listeners only (no Handler) |
+
+---
+
+## 10. Design Decisions
+
+| Decision | Choice | Alternatives | Rationale |
+|----------|--------|--------------|-----------|
+| {Decision 1} | {Choice} | {Alternative} | {Reason} |
+
+---
+
+## 11. Implementation Plan
+
+### Wave 1: Foundation
+| File | Change |
+|------|--------|
+| `domain/model.go` | Create entities + behavior methods |
+| `domain/enum.go` | Status enums + transition rules |
+
+### Wave 2: Infrastructure
+| File | Change |
+|------|--------|
+
+### Wave 3: Application
+| File | Change |
+|------|--------|
+
+### Wave 4: Assembly
+| File | Change |
+|------|--------|
+
+### Wave 5: Verification
+- `go build ./...`
+- `make wire`
+- Quantitative verification (grep counts)
+
+---
+
+## 12. P1-P11 Verification
+
+| Principle | Status | Notes |
+|-----------|--------|-------|
+| P1 Domain model has behavior | ✓ | {Specific notes} |
+| P2 Service uses model methods | ✓ | |
+| P3 Module is self-registering | ✓ | |
+| P4 Handler has zero logic | ✓ | |
+| P5 Inject minimum dependencies | ✓ | |
+| P6 File placement | ✓ | |
+| P7 Entity never exposed | ✓ | |
+| P8 End-to-end traceability | ✓ | |
+| P9 Correct status codes | ✓ | |
+| P10 No deferred code | ✓ | |
+| P11 Audit on writes | ✓ | |
+```
+
+### Optional Sections (add as needed)
+
+Include the following sections based on module characteristics:
+
+| Section | When Needed | Reference |
+|---------|-------------|-----------|
+| Security Design | Involves authentication, encryption, permissions | identity-architecture.md |
+| Caching Strategy | Has Redis caching requirements | user-settings-architecture.md |
+| Strategy Engine / Provider Abstraction | Multi-channel/multi-vendor integration | notification-architecture.md |
+| Privacy Compliance (GDPR) | Stores personal data | user-architecture.md |
+| Monitoring & Operations | Prometheus metrics / alerting | ratelimit-architecture.md |
+| Internationalization | i18n requirements | appversion-architecture.md |
+
+---
+
+## Level B: Feature Addition / Significant Change
+
+Adding features to an existing module or making significant changes. Does not require a full architecture document, but must produce all of the following sections:
+
+```markdown
+# {Feature Name} Design Document
+
+## 1. Change Scope
+
+| Dimension | Impact |
+|-----------|--------|
+| Modules | {List of affected modules} |
+| Database Tables | {List of affected tables} |
+| API Endpoints | {New/modified endpoints} |
+| Events | {New/modified events} |
+| Wire | {Affected cmd/ apps} |
+
+## 2. Industry Reference
+
+{How does the industry solve this problem? Who was referenced?}
+
+## 3. Database Changes
+
+For each new/modified field:
+| Column | Type | Nullable | Default | Comment | Table |
+|--------|------|----------|---------|---------|-------|
+
+Migration SQL:
+```sql
+ALTER TABLE ...
+```
+
+## 4. Domain Model Changes
+
+New/modified entity fields and behavior methods.
+Include state machine changes (if any).
+
+## 5. API Changes
+
+Complete request/response contracts for new/modified endpoints.
+
+## 6. Data Flow
+
+For each new field, trace the full path:
+Source → DTO → Service → Repository → Entity → VO → Response
+
+## 7. Implementation Plan
+
+File change list organized by Wave.
+
+## 8. P1-P11 Verification
+
+Confirm each affected principle one by one.
+```
+
+---
+
+## Level C: Bug Fix / Minor Change
+
+Small-scope fixes or adjustments. Must produce:
+
+```markdown
+# {Bug/Change} Fix Design
+
+## 1. Root Cause Analysis
+
+{What is the problem, why it happens, scope of impact}
+
+## 2. Fix Design
+
+{Specific approach, not just "fix the bug"}
+
+## 3. Affected Files
+
+| File | Change |
+|------|--------|
+| ... | ... |
+
+## 4. Verification Method
+
+{How to confirm the fix works and doesn't introduce new issues}
+```
+
+---
+
+## Task Level Decision
+
+```
+Is this a new module or major architecture change?
+  → YES: Level A (full architecture document)
+  → NO: Does it touch 3+ files or change schema/API?
+    → YES: Level B (focused design document)
+    → NO: Level C (fix design)
+```

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

@@ -0,0 +1,155 @@
+# Development Checklist
+
+> Workflow and quality gates. Rules in `CLAUDE.md`.
+
+---
+
+## Feature Development Workflow
+
+1. Design（架构评审）
+2. Implementation
+3. Self-review（对照 CLAUDE.md FORBIDDEN 表）
+4. Pre-commit validation
+
+---
+
+## Pre-Commit Checklist
+
+- [ ] `make build` passes
+- [ ] `make lint` passes (golangci-lint)
+- [ ] No `fmt.Println` / `log.Println`
+- [ ] No commented-out code
+- [ ] No unused imports (`goimports` 自动处理)
+- [ ] Layer dependencies correct (handler → service → repository)
+- [ ] No circular package imports
+- [ ] DTO and Model in correct files
+- [ ] No hardcoded secrets
+- [ ] Input validation on all endpoints (binding tags)
+- [ ] Unit tests for new services
+- [ ] Cross-process relay whitelist uses exact public event names for partial aggregate families (`user.deleted`, not `user.*`)
+- [ ] Worker listeners consume durable public events only; source projection listeners stay in the source runtime
+- [ ] Cross-runtime workflows have an E2E contract test that asserts DB state, access behavior, and side effects
+- [ ] Write operations in Service carry before/after snapshots through DomainEvent `AuditChanges`, or call `audit.Enrich()` when no domain event is published (writes to `sys_audit_logs`)
+- [ ] Auth events (login/logout/password_change etc.) auto dual-written to `sys_audit_logs` + `sys_login_logs` by AuditListener
+- [ ] HTTP requests auto-written to `sys_access_logs` by AuditMiddleware (no manual work needed)
+- [ ] Repository/persistence adapters do not call `audit.Enrich`; owning service commands or DomainEvent envelopes carry audit evidence
+- [ ] Worker/system events that change user-visible state carry DomainEvent `AuditChanges`
+- [ ] Successful read-request logs are sampled or debug-level; failures, writes, and slow requests remain preserved
+- [ ] New log/audit table migrations preserve default partitions, BRIN time indexes, and failure/trace lookup indexes
+- [ ] New index migrations include `查询路径：` and `索引理由：` comments tied to a real repository/service query
+- [ ] `make pre-commit` passes before local commit
+- [ ] `make pre-push` passes before pushing a branch for review
+- [ ] `make test` passes
+
+---
+
+## Code Review Checklist
+
+### Naming
+- [ ] Files: snake_case (Go 标准)
+- [ ] Types: PascalCase, match purpose
+- [ ] Methods: verb prefix, `EnsureXxx` panics / `CheckXxx` returns bool / `IsXxx` returns bool
+- [ ] unexported types/functions for internal use only
+
+### Handler
+- [ ] struct with injected dependencies
+- [ ] `RegisterRoutes(rg *gin.RouterGroup)` method
+- [ ] No try-catch pattern (return error, middleware handles)
+- [ ] Uses `response.OK()` / `response.Error()` helpers, not raw `c.JSON()`
+- [ ] No business logic, no existence checks — pure delegation to Service
+
+### Service
+- [ ] Single file < 500 lines
+- [ ] No type definitions inline (move to `dto.go`, `vo.go`, `model.go`)
+- [ ] Uses injected `*zap.Logger`
+- [ ] Publishes events via `EventBus` for cross-module communication
+- [ ] Returns `*XxxResponse` (VO), NEVER domain model
+- [ ] ALL write operations carry before/after snapshots through DomainEvent `AuditChanges` or request-context `audit.Enrich(ctx, changes, metadata)`, never both
+- [ ] `audit.Enrich()` called ONLY after successful write, NEVER on error path
+- [ ] Status-change operations capture `oldStatus` before mutation for before snapshot
+
+### Model (Entity)
+- [ ] Embeds `database.BaseModel` or `database.SoftDeleteModel`
+- [ ] All columns have `comment` tag (Chinese)
+- [ ] Indexes on FK and high-frequency query fields
+- [ ] `TableName()` method returns prefixed table name
+
+### Wire
+- [ ] `provider.go` defines `ProviderSet` with `wire.NewSet(...)`
+- [ ] Interface bindings: `wire.Bind(new(domain.XxxRepository), new(*xxxRepository))`
+- [ ] No manual construction in `main.go`
+
+### Error Handling
+- [ ] Uses `apierror.NotFound()` / `apierror.Business()` etc., no raw error strings
+- [ ] Error messages in English only
+- [ ] Wraps errors with `fmt.Errorf("context: %w", err)` for stack context
+- [ ] `errors.As()` / `errors.Is()` for error type checking
+
+### Logging
+- [ ] `*zap.Logger` injected via constructor
+- [ ] `logger.Named("ServiceName")` for context
+- [ ] Structured fields: `zap.Int64("userId", id)`, NOT string formatting
+- [ ] No sensitive data in logs (passwords, tokens, PII)
+- [ ] No per-request info-level log for every successful read endpoint in production
+- [ ] Buffer overflow logs are aggregated, not emitted once per dropped entry
+
+### Code Quality
+- [ ] No duplicate code
+- [ ] No magic numbers/strings (use constants)
+- [ ] Imports: stdlib → external → internal
+- [ ] No circular package dependencies
+- [ ] `context.Context` as first parameter in all service/repo methods
+- [ ] Error return as last return value
+
+---
+
+## Pre-Commit Validation Report
+
+```
+Pre-Commit Validation
+=====================
+Files changed: [list]
+Specs checked:
+  - CLAUDE.md FORBIDDEN table: PASS/FAIL (CRITICAL)
+  - api-design.md: PASS/FAIL
+  - module-standards.md: PASS/FAIL
+  - error-handling.md: PASS/FAIL
+  - database.md: PASS/FAIL
+  - logging.md: PASS/FAIL
+  - event-runtime-boundary.md: PASS/FAIL
+  - e2e-standards.md: PASS/FAIL
+  - openapi-contract.md: PASS/FAIL
+  - check-list.md: PASS/FAIL
+Violations found: [list or "None"]
+Ready to commit: YES/NO
+```
+
+---
+
+## Useful Commands
+
+```bash
+# 格式化代码
+goimports -w .
+gofmt -w .
+
+# 静态分析
+make lint                     # golangci-lint
+go vet ./...                  # Go 内置 vet
+
+# 测试
+make test                     # 全部测试
+go test -v ./internal/...     # 带详细输出
+go test -race ./...           # 竞态检测
+go test -coverprofile=coverage.out ./... && go tool cover -html=coverage.out  # 覆盖率
+
+# 依赖
+go mod tidy                   # 清理依赖
+go mod verify                 # 验证依赖完整性
+
+# 代码生成
+make wire                     # Wire DI 生成
+make openapi-generate         # OpenAPI 投影与运行时制品
+make openapi-check            # 契约、确定性与 tracked 制品校验
+make openapi-breaking         # 受保护基线与外部承诺兼容性校验
+```