@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/AGENTS.md

@@ -0,0 +1,1139 @@
+# {{projectName}} Backend
+
+> **适用范围**：本文件完整继承 OneX Go 工程标准。产品后端的运行入口为 `cmd/product-api` 和 `cmd/worker`；平台 Identity、IAM、交易、Viewer、产品注册表及其服务拓扑属于上游 OneX。文中的平台模块、表、路由和运维命令按该所有者解释，不表示本仓库重新实现平台业务。通用编码、安全、事务、审计、事件、契约、测试规则均适用于本仓库。具体运行命令以本仓库 `Makefile` 为准，平台专属质量门禁在 OneX 执行。
+> **规则优先级**：用户明确范围与语义影响分级优先；审计路径遵循本文 Audit 的事件信封或请求上下文二选一，不产生重复记录。
+> **来源**：`docs/standards-provenance.json` 记录原文版本、完整性和逐项适配。
+
+
+> **Stack**: Go 1.24 | Gin | GORM | PostgreSQL 16 | Redis 7.0 | Asynq
+> **Architecture**: Full-stack Monorepo (backend/ + frontend/ + admin/) — 无自建网关，使用 APISIX
+> **Products**: Multi-product platform architecture (unified platform API + external product BFFs routed by APISIX)
+
+---
+
+## Product Backend Commands
+
+Run in the generated backend directory:
+
+```bash
+make build
+make test
+make test-cov
+make test-race
+make lint
+make wire
+make run-api
+make run-worker
+make migrate-up
+make migrate-down
+make migrate-create name=create_resource
+make migrate-version
+make docker-dev
+make docker-down
+make openapi-install
+make openapi-generate
+make openapi-check
+make openapi-test
+make openapi-sdk
+make openapi-breaking
+make openapi-conformance
+make openapi-clean-deletion
+make test-migrations
+make check
+```
+
+## Upstream Platform Commands
+
+> 所有 `make` 命令在 `backend/` 目录下执行。
+
+```bash
+# Development (run from backend/)
+make run-platform              # Platform API (:3002)
+make run-worker               # Worker (daemon)
+make docker-dev               # Docker 全栈开发环境（Air 热重载，不需要手动 rebuild）
+make docker-down              # 停止 Docker 开发环境
+
+# Build (run from backend/)
+make build                    # 构建全部 cmd/
+make build-platform            # 构建 Platform API
+make build-worker             # 构建 Worker
+
+# Database (run from backend/)
+make migrate-up               # 执行 golang-migrate 迁移
+make migrate-down             # 回滚上次迁移
+make migrate-create name=xxx  # 创建新迁移文件
+
+# Quality (run from backend/)
+make lint                     # golangci-lint run
+make test                     # go test ./...
+make test-cov                 # 覆盖率
+make test-e2e                 # E2E 测试
+
+# Code Generation (run from backend/)
+make generate                 # 生成 Wire 与 OpenAPI 制品
+make openapi-generate         # 生成 OpenAPI 投影与运行时制品
+make openapi-check            # 校验契约、确定性与 tracked 制品
+make openapi-breaking         # 校验受保护基线与外部承诺兼容性
+make wire                     # 生成 Wire 依赖注入代码
+```
+
+---
+
+## Upstream Platform Project Structure
+
+```
+backend/                          # Go 后端服务
+  cmd/
+    platform-api/                 # 统一平台服务 (:3002) - Identity + Commerce + Credit + Quota
+    admin-api/                    # Admin BFF (:3003) - 管理后台路由
+    worker/                       # 后台任务 (Asynq consumer)
+  internal/
+    core/                         # 基础设施
+      config/ database/ cache/ logger/ errors/       # 基础: 配置/DB/缓存/日志/错误
+      eventbus/ queue/ httpclient/                   # 通信: 事件总线/队列/HTTP
+      health/ schedule/ observability/               # 运维: 健康检查/定时/可观测性
+      resilience/ distlock/                          # 弹性: 熔断重试/分布式锁
+    common/                       # 通用工具
+      middleware/ response/ validator/ types/ bffadapter/
+    platform/                     # 平台领域
+      identity/                   #   认证 (JWT + OAuth2)
+      user/                       #   用户管理
+      notification/               #   通知系统
+      tenant/                     #   租户管理
+    sharedevents/                 # 跨模块事件契约
+  pkg/
+    apierror/                     # 可导出的 API 错误定义
+  migrations/                     # SQL 迁移文件 (golang-migrate)
+  configs/                        # 配置文件 (YAML)
+  deployments/                    # Docker Compose / K8s
+frontend/                         # 前端应用 (planned)
+admin/                            # 管理后台 (planned)
+```
+
+产品业务代码、产品 BFF 和产品专属数据模型位于独立产品仓库，不属于 OneX `backend/internal/`。
+
+---
+
+## Import Path
+
+```
+module: {{module}}
+
+{{module}}/internal/core/config
+{{module}}/internal/core/database
+github.com/onex-platform/backend/internal/platform/identity
+{{module}}/pkg/apierror
+```
+
+---
+
+## Key Patterns
+
+- **APISIX Gateway**: 外部网关处理路由/限流/认证插件，Go 服务不自建网关
+- **EventBus**: 进程内事件总线，跨模块通信解耦业务逻辑
+- **Google Wire**: 编译时依赖注入，显式依赖图
+- **Zap**: 结构化日志，高性能
+- **GORM**: ORM，Entity 与 Response VO 严格分离
+
+---
+
+## Upstream Platform Environment Variables
+
+```bash
+DATABASE_HOST, DATABASE_PORT, DATABASE_NAME, DATABASE_USERNAME, DATABASE_PASSWORD
+REDIS_HOST, REDIS_PORT, REDIS_PASSWORD
+IDENTITY_ACCESS_TOKEN_ISSUER, IDENTITY_ACCESS_TOKEN_SIGNING_KEY_ID
+IDENTITY_ACCESS_TOKEN_PRIVATE_KEY_PATH, IDENTITY_ACCESS_TOKEN_PUBLIC_KEY_DIRECTORY
+IDENTITY_OAUTH_STATE_SIGNING_SECRET, IDENTITY_PHONE_HASH_KEY
+OPENAI_API_KEY, OPENAI_BASE_URL
+ANTHROPIC_API_KEY
+```
+
+---
+
+## Code Rules Reference
+
+规范模板在 `backend/.claude/docs/` 目录中。
+
+---
+---
+
+# AI Execution Standard & Coding Rules
+
+> Part 1: AI Execution Flow (Phase 1–5) — mandatory workflow for every task
+> Part 2: Coding Rules — project standards and forbidden patterns
+
+---
+
+## Phase 1: Understand
+
+Before touching any code, fully understand the task and its context.
+
+### 1.1 Read project documentation
+
+1. Read this file (execution flow + coding rules)
+2. Read `backend/.claude/docs/` specifications relevant to the task (api-design, module-standards, database, error-handling, etc.)
+3. Read existing architecture docs in `docs/platform/` for affected modules
+4. Read the CLAUDE.md of each affected cmd/ app if applicable
+
+**Read the specs BEFORE designing. Do not rely on memory or assumptions about project conventions.**
+
+### 1.2 Scope the impact
+
+For each task, answer:
+
+- Which modules are affected?
+- Which database tables are affected?
+- Which API endpoints are affected?
+- Does data cross a module boundary?
+- Does this affect Wire dependency graph? Which cmd/ apps need regeneration?
+
+### 1.3 Read all affected source files
+
+Read every file that will be modified. Understand:
+
+- Current function signatures and parameter types
+- Current data structures and their behavior
+- Current data flow: request → handler → service → repository → response
+- Existing patterns and conventions in the file
+
+**DO NOT modify any file you have not read in this session. DO NOT assume what code looks like from memory.**
+
+---
+
+## Phase 2: Design
+
+Design the solution BEFORE writing any code. This is the most important phase.
+
+### 2.1 Research industry standards (MANDATORY)
+
+**Before proposing ANY design, MUST first research industry best practices. This is NOT optional, NOT skippable.**
+
+For every design decision, search and answer: "How does {industry leader} solve this exact problem?"
+
+- Domain modeling → How do Stripe/Shopify/AWS model this entity?
+- API design → How do Stripe API, GitHub API, Slack API handle this?
+- Architecture pattern → How do large-scale Go projects structure this?
+- State management → How do mature platforms handle this lifecycle?
+
+**Research output MUST appear as a concrete table in the design document:**
+
+```markdown
+| Decision Point | Industry Pattern | Used By | Our Choice | Rationale |
+|---------------|-----------------|---------|------------|-----------|
+```
+
+Missing this table = design is incomplete = FORBIDDEN to implement.
+
+**Refactoring / rewriting rule**: Do NOT propose removing, replacing, or rewriting existing architecture until you have analyzed what the current design was trying to do and how industry leaders solve the same problem. "This code looks wrong" is not sufficient justification — you must prove the alternative is the industry-accepted approach.
+
+### 2.2 Define the target state
+
+For each area the task touches, write out the exact desired end state. The design must include concrete code architecture, not just a list of changes.
+
+Required for any design that touches code structure:
+
+- **Entity / Model**: struct fields, behavior methods (signature + purpose), state machine transitions
+- **Interface**: method signatures, which package defines it, which package implements it
+- **API contract**: endpoint, method, request DTO fields, response VO fields, status codes
+- **Database**: column name, type, nullable, default, comment — for every new/changed column
+- **Data flow**: for every new field, trace: Source → DTO → Service → Repository → Entity → VO → Response
+- **Directory structure**: which files go where, why this tier (Full DDD / Simplified / Flat)
+
+**Be concrete, not vague.** "Add a status field" is insufficient. "Add `status VARCHAR(20) NOT NULL DEFAULT 'pending' COMMENT '订单状态'`, with transition map in `enum.go`, behavior methods `IsCancellable()` and `TransitionTo()` on model" is correct.
+
+**Design the code architecture in the plan, not during implementation.** Implementation should be filling in a decided design, not making architecture decisions on the fly.
+
+### 2.3 Validate the design
+
+**Patch vs Design check**: Before proposing any fix, ask: "Am I fixing this in the ONE place that owns this responsibility, or am I adding a workaround somewhere else?" If the answer is workaround, find the right place first.
+
+Check every design decision against the FORBIDDEN Patterns table and coding rules in this file. If any check fails, revise the design before proceeding.
+
+For refactoring or major changes, validate each decision:
+
+```
+Decision: {what you propose}
+Principle: {which rule says the current state is wrong}
+Evidence: {measurable proof — line count, grep count, constructor count}
+Risk: {what could go wrong}
+Mitigation: {how to handle the risk}
+Verdict: PROCEED / REJECT / REVISE
+```
+
+### 2.4 Determine design document level
+
+Classify the task and produce the corresponding design document. See `.claude/docs/architecture-template.md` for full skeleton.
+
+```
+New module or major architecture change?
+  → Level A: full architecture document (all mandatory sections)
+
+Touch 3+ files, or change schema/API?
+  → Level B: focused design document
+
+Otherwise?
+  → Level C: fix design
+```
+
+| Level | What to produce | Destination |
+|-------|----------------|-------------|
+| **A** | Complete architecture document following `.claude/docs/architecture-template.md` | Plan file → archive to `docs/platform/` |
+| **B** | Impact scope, industry reference, schema/model/API changes, data flow, implementation waves | Plan file |
+| **C** | Root cause analysis, fix design, affected files, verification plan | Plan file |
+
+**Every section must be concrete.** Column/Type/Nullable/Default/Comment for every DB field. Method signature, parameters, return type, business rule for every method.
+
+### 2.5 Decision Autonomy
+
+**Inherited from `CLAUDE.md` Phase 2.2.** AI MUST make standard technical decisions autonomously when industry consensus exists. NEVER ask the user to choose between options that have a clear industry-standard answer.
+
+Go-specific autonomous decisions (NEVER ask):
+
+- Repository pattern vs direct DB → Repository (Go DDD standard)
+- Table-driven tests vs individual → Table-driven (Go standard)
+- `context.Context` as first param → Yes (Go standard)
+- Error wrapping style → `fmt.Errorf("operation: %w", err)` (Go 1.13+ standard)
+- Struct validation → `binding` tags on DTO, behavior methods on model (project convention)
+- Module tier selection → Apply the tier decision flow in this file, do NOT ask user
+
+### 2.6 Self-Review Gate (MANDATORY)
+
+**Inherited from `CLAUDE.md` Phase 2.6.** After completing ANY design or implementation, MUST self-review BEFORE presenting to user.
+
+Go-specific self-review additions:
+
+1. Does every new/changed struct field trace through the full data flow? (DTO → Service → Entity → VO)
+2. Does Wire dependency graph remain acyclic?
+3. Are all new exported types documented with GoDoc (Chinese)?
+4. Does every handler call only Service methods (A1/A2 compliance)?
+5. Does every write Service method carry DomainEvent audit fields or call `audit.Enrich()` when no event is published (AU1 compliance)?
+
+### 2.7 Present design for approval
+
+**Approval gate applies ONLY to Level A designs (new modules, major architecture changes).**
+
+Level B/C: present design summary, proceed to implementation immediately.
+
+---
+
+## Phase 3: Plan
+
+After design passes self-review (and user approval for Level A), create the implementation plan.
+
+### 3.1 List all file modifications
+
+For each file: exact path, what function/section to change, what the change is.
+
+### 3.2 Map dependencies
+
+Determine which changes depend on which others. A change depends on another if it imports, references, or extends something defined in the other.
+
+### 3.3 Group into dependency waves
+
+Group changes so that each wave only depends on previous waves being complete. Within each wave, independent changes can be executed in parallel.
+
+---
+
+## Phase 4: Implement
+
+### 4.1 Execute wave by wave
+
+For each wave:
+
+1. Implement all changes in the wave (parallel if independent)
+2. After the wave completes, verify types are consistent with previous waves
+3. Proceed to next wave only when current wave is clean
+
+### 4.2 Read before write (always)
+
+Before modifying each file:
+
+1. Read its current content
+2. Confirm your change is compatible with what is actually there
+3. Then make the modification
+
+### 4.3 Follow existing patterns
+
+When adding code to an existing file, match:
+
+- Naming conventions already used in that file
+- Code style and formatting patterns
+- Comment language and level of detail
+- Import organization
+
+---
+
+## Phase 5: Verify
+
+### 5.1 Build
+
+```bash
+go build ./...
+go vet ./...
+make wire  # regenerate all affected cmd/
+```
+
+All MUST pass. If any fails, fix and rebuild.
+
+### 5.2 Design conformance check
+
+After build passes, verify implementation matches the approved design. Every item in the design document must be implemented. No silent omissions.
+
+### 5.3 Quantitative verification
+
+Grep for expected outcomes with concrete numbers. "It compiles" is necessary but not sufficient. Count the things that should exist.
+
+### 5.4 Rule conformance check
+
+Re-validate against the FORBIDDEN Patterns table below with the actual implemented code. If any rule is violated, fix before marking complete.
+
+### 5.5 Automated review loop (Level A/B)
+
+**Inherited from `CLAUDE.md` Phase 5.5.** For Level A/B deliveries, dispatch review agents and iterate until zero findings BEFORE presenting to user.
+
+Go-specific review dimensions:
+
+- FORBIDDEN pattern scan (S/A/T/C/H/D/AU/E rules)
+- Wire dependency graph validity
+- Handler → Service → Repository layering compliance
+- Audit enrichment coverage (every write op)
+- Industry standard alignment (compare against cited references)
+
+**The user should receive a clean, reviewed deliverable. If the user has to point out "this doesn't follow the Stripe pattern you cited", that is a Phase 5.5 failure.**
+
+---
+---
+
+# Part 2: Coding Rules
+
+---
+
+## Code Separation (CRITICAL)
+
+BEFORE writing ANY code, check: does it contain constants, types, enums, request/response structs, or error definitions?
+If YES, place them in the correct file. NEVER inline complex type definitions in handler/service files.
+
+| Content | NEVER In | ALWAYS In |
+|---------|----------|-----------|
+| constant / magic number (shared) | service, handler | `{package}/constants.go` 或模块级 `const` 块 |
+| constant (single consumer) | — | co-locate in consumer file as unexported `const` |
+| interface (contract) | infrastructure, handler | 消费方所在 package（Go 惯例：接口由使用者定义） |
+| enum (iota / string const) | service, handler | `{package}/enum.go` |
+| type alias | service, handler | `{package}/types.go` |
+| Request struct (user) | handler | `{package}/dto.go` |
+| Request struct (admin) | handler | `{package}/dto_admin.go` |
+| Response VO (user) | anywhere mixed | `{package}/vo.go` (struct + `ToXxxResponse()`) |
+| Response VO (admin) | anywhere mixed | `{package}/vo_admin.go` (struct + `ToAdminXxxResponse()`) |
+| Error sentinel/type | service | `{package}/errors.go` 或 `pkg/apierror/` |
+| Event payload | service | `internal/sharedevents/events.go` |
+| Pagination params | DTO (inline) | Embed `types.PageParams`, `types.AdminPageParams`, or explicitly justified `types.BulkPageParams` from `common/types` |
+
+Go 惯例：相关类型可以按领域分组在同一文件中。例如 `domain/model.go` 可包含同一聚合根的多个 struct。
+
+---
+
+## File Naming
+
+MUST use snake_case (Go 标准)。Go 中不使用类型后缀命名文件，而是按职责命名。
+
+| 职责 | File Pattern | Type Pattern |
+|------|-------------|--------------|
+| HTTP Handler (user) | `handler.go` | `XxxHandler` struct |
+| HTTP Handler (admin) | `handler_admin.go` | `XxxAdminHandler` struct |
+| Service | `service.go` 或 `{name}_service.go` | `XxxService` struct |
+| Repository 接口 | `repository.go` (in domain/) | `XxxRepository` interface |
+| Repository 实现 | `persistence.go` (in infrastructure/) | `xxxRepository` struct (unexported) |
+| Request DTO (user) | `dto.go` | `CreateXxxRequest`, `UpdateXxxRequest` |
+| Request DTO (admin) | `dto_admin.go` | `AdminCreateXxxRequest`, `AdminListXxxRequest` |
+| Response VO (user) | `vo.go` | `XxxResponse` struct + `ToXxxResponse()` |
+| Response VO (admin) | `vo_admin.go` | `AdminXxxResponse` struct + `ToAdminXxxResponse()` |
+| Domain Model | `model.go` | `Xxx` struct (PascalCase, NO suffix) |
+| Enum | `enum.go` | `XxxStatus` type + `const` iota 或 string |
+| Constants | `constants.go` | `const` 块 |
+| Error | `errors.go` | `ErrXxxNotFound` sentinel 或 `XxxError` type |
+| Event | `events.go` (in sharedevents/) | `XxxEvent` struct |
+| Listener | `listener.go` | `XxxListener` struct |
+| Middleware | `{name}.go` (in middleware/) | `XxxMiddleware()` func |
+| Wire Provider | `wire.go` | `InitializeXxx()` injector |
+| Wire Provider Set | `provider.go` | `ProviderSet = wire.NewSet(...)` |
+| Test | `{name}_test.go` | `TestXxx`, `BenchmarkXxx` |
+
+---
+
+## FORBIDDEN Patterns (CRITICAL)
+
+Violation of ANY rule blocks commit. No exceptions.
+
+| ID | Cat | Pattern | Fix |
+|----|-----|---------|-----|
+| S1 | Security | Hardcoded secrets in source | Move to config/env, access via `Config` struct |
+| S2 | Security | Dynamic code execution (`reflect` for dispatch) | Use static mapping (map / switch) |
+| S3 | Security | Sensitive data in logs | Log IDs only, NEVER passwords/tokens/PII |
+| S4 | Security | `os.Getenv()` in business code | Use `Config` struct, load once at startup |
+| A1 | Arch | Business logic in handler | Move ALL logic to Service |
+| A2 | Arch | Repository/DB ops in handler | Call Service methods only |
+| A3 | Arch | Direct cross-package type import bypassing interface | Define interface in consumer package |
+| A4 | Arch | Circular package import | Extract shared types to third package |
+| A5 | Arch | Flat directory (all files in `cmd/*/`) | Organize into `internal/` subpackages |
+| A6 | Arch | Silent init failure (swallowed error) | MUST return error, caller decides |
+| A7 | Arch | `init()` with side effects | Explicit initialization in `main()` or Wire |
+| A8 | Arch | Direct `http.ResponseWriter` manipulation in handler | Use Gin context helpers (`c.JSON()`, `c.Status()`) |
+| A11 | Arch | Gateway plugin callback (`forward-auth` / internal auth bridge / similar) directly targeting a single backend node (`http://service:port/...`) | Route through APISIX internal route or shared upstream policy. Gateway-side callbacks MUST NOT bypass upstream health checks, retries, and load-balancing |
+| A12 | Arch | Production public API exposed behind APISIX with single-node upstream or without APISIX health checks | Use multi-node upstreams with active + passive health checks, explicit timeout/retry policy, and keepalive pool. Single-node upstream is allowed only in local dev hot-reload compose |
+| T1 | Type | `interface{}` / `any` without comment | Add concrete type or justification comment |
+| T2 | Type | Type definitions in service file | Move to `model.go`, `dto.go`, `vo.go`, `enum.go` |
+| T3 | Type | Numeric enum without string method | Use `String()` method 或 string const |
+| T4 | Type | Manual singleton (`sync.Once` + global) | Use Wire DI, single instance by construction |
+| T5 | Type | Exported unexported-type method | Keep type/method export level consistent |
+| C1 | Contract | `return entity` from service to handler | Use `return ToXxxResponse(entity)` |
+| C2 | Contract | `{ "code": 200, "data": ... }` wrapper | Return data directly, use HTTP status codes |
+| C3 | Contract | Response struct as request input | Separate Request (dto.go) and Response (vo.go) |
+| C4 | Contract | Chinese in error messages | English ONLY for all error messages |
+| C5 | Contract | Hardcoded numeric error codes | Use string `ErrorCode` const |
+| H1 | Hygiene | `fmt.Println` / `log.Println` | Use `zap.Logger` |
+| H2 | Hygiene | Non-snake_case filename | Rename to `snake_case.go` |
+| H3 | Hygiene | Panic in handler/service | Return error, middleware handles recovery |
+| H4 | Hygiene | Commented-out code | Delete; git has history |
+| H5 | Hygiene | Unused/speculative code (YAGNI) | Delete; write only what is needed NOW |
+| H6 | Hygiene | Exported type from `internal/` that should be unexported | Unexport; only export what other internal packages need |
+| H7 | Hygiene | Naked return in named return function > 5 lines | Use explicit return |
+| H8 | Hygiene | Underscore import `_` without comment | Add `// for side-effect: xxx` comment |
+| A9 | Arch | ANY re-export in `provider.go` (`var NewFoo = sub.NewFoo` or `type X = sub.X`) | `provider.go` ONLY contains `wire.NewSet(...)` and Wire helper functions. ZERO re-exports of any kind. Callers MUST import the actual sub-package directly |
+| A10 | Arch | Handler/Service/Model in module root directory | Business code MUST go into domain/ application/ infrastructure/ subdirectories |
+| D1 | Deferred | `// TODO:` / `// 待后续` / `// 暂跳过` / `// 暂设` / `// 后续实现` in committed code | Either implement completely OR return explicit error. NEVER defer implementation with comments |
+| D2 | Deferred | Fallback branch for "backward compatibility" / "兼容历史数据" | Single code path only. If format changed, migrate data. NEVER add fallback parsing |
+| D3 | Deferred | `// 迁移完成后应移除` / "should be removed after migration" | Remove NOW. Code that "should be removed later" will never be removed |
+| D4 | Deferred | Try-decrypt, if fail try-plaintext pattern | Decrypt or fail. NEVER silently fall back to unencrypted path |
+| D5 | Deferred | Silent skip of unimplemented feature (`// 暂跳过`, empty handler, log-and-return-nil) | Return typed error (`apierror.BadRequest` / `fmt.Errorf`) for unsupported operations. Caller decides |
+| D6 | Deferred | Noop/stub implementation returning `nil, nil` or hardcoded values for production interfaces | Implement fully OR define proper error: `fmt.Errorf("{operation} is not implemented")` |
+| D7 | Deferred | `placeholder` / `stub` / `dummy` / `mock` in non-test production code | Only in `_test.go` files. Production code must be complete |
+| AU1 | Audit | Service write operation missing audit evidence | Set DomainEvent `AuditChanges`, or call `audit.Enrich(ctx, changes, metadata)` after successful write when no event is published; never both |
+| AU2 | Audit | `audit.Enrich()` called on error path (before write succeeds) | Call ONLY after operation **succeeds**, NEVER before error return |
+| AU3 | Audit | `audit.Enrich()` called in Handler | Audit enrichment is business logic, MUST be called in Service layer |
+| E1 | Enforce | Discovered violation deferred with "先不折腾" / "后续再改" / "合理轻量 pattern" | Fix NOW. Rules have zero exceptions. No "thin CRUD exemption" |
+| E2 | Enforce | Code delivered with known violations and a plan to "fix later" | ALL violations MUST be fixed BEFORE delivery. No partial compliance |
+| E3 | Enforce | Fix applied as patch/workaround without proper design thinking | Every fix must be architecturally sound. No band-aids |
+| E4 | Enforce | Discovered bug/violation excluded with "不在本次范围" / "是新功能" | If the scan found it, fix it. Scope is defined by what's broken, not by what you planned to do |
+| E5 | Enforce | Runtime conversion/adapter to "兼容已存数据" when no production data exists | Change the source format directly. Compatibility layers are only for live production data |
+| IS1 | Identity | Backend handler reads business decision state from `c.GetHeader("X-User-Content-*")` / `c.GetHeader("X-User-Tier-*")` / similar plaintext business header injected by gateway | 通过 `principal.MustGet(c)` / `principal.Get(c)` 读取 backend 自己 resolve 的状态。Identity header（X-User-Public-ID/X-Identity-ID/X-Session-ID）仍由 middleware 解析进 ctx，不直接被业务读 |
+| IS2 | Identity | 同一权益 / 决策 concept 暴露 2+ resolve 路径（service / header / wrapper / sidecar）让 handler 自由选择 | One owner per concept：内容访问唯一调 `accessPolicySvc.ResolveContentAccess`；entitlement limit 唯一调 `EntitlementService.GetLimit`。新增功能必须复用现有 service，不得新建并行 reader |
+| IS3 | Reliability | EventBus listener 关键 side-effect（cache invalidate / projection update / outbox dispatch）失败仅 `Warn` 不 `return err` | `return fmt.Errorf("...: %w", err)` — 让 outbox 自动 retry 直至最终一致。模板：`handleSubscriptionEvent` (`listener.go:85-108`) |
+| IS4 | Cache | `cache.Delete(...)` followed by `cache.Set(...)` (race-prone two-step invalidation) | 单次 `cache.Set(...)` 覆盖即可；写入失败 fail-fast。无 Delete 步骤 |
+| IS5 | Gateway | APISIX / 网关注入"非 identity"业务决策 header 给 backend 信任（违反 Stripe / GitHub / AWS 共识） | 网关只注入 identity（X-User-Public-ID/X-Identity-ID/X-Session-ID），并 strip 客户端伪造的同名 header；业务决策（content access / permissions / tier）由 backend middleware 自己 resolve |
+| DB1 | Database | `FOREIGN KEY` constraint in migration | FORBIDDEN. Application layer ensures integrity. FK causes cascade locks, DDL blocking, sharding incompatibility |
+| DB2 | Database | `SELECT *` in queries | ALWAYS specify columns: `Select("id", "name", "email")` |
+| DB3 | Database | Unbounded list query without pagination | ALWAYS paginate. NEVER return all rows |
+| DB4 | Database | Production/DMS SQL uses unverified dialect-sensitive constructs such as `BEGIN`/`COMMIT`, `CROSS JOIN LATERAL (VALUES ...) AS alias(...)`, positional anonymous row output, or multi-statement repair scripts | Use a single PostgreSQL statement compatible with the production SQL runner; validate syntax locally against PostgreSQL before handing it to operators |
+| R1 | Reuse | `gin.H{}` for API list/paginated response | Use `response.NewPaginated()` or `response.NewList()`. Custom structures use VO struct, NEVER build JSON with `gin.H` |
+| R2 | Reuse | `string` type for sort order field | Use `types.SortOrder` from `common/types`. DTO field type + service comparisons MUST use `types.SortOrderASC` / `types.SortOrderDESC` |
+| R3 | Reuse | Inline pagination normalization `if page < 1 { page = 1 }` duplicated | Extract shared helper or use `types.PaginationQuery.Normalize()`. Same logic MUST NOT appear 2+ times in one module |
+| R4 | Reuse | Manual error construction `c.JSON(400, gin.H{"error": ...})` | Use `response.Error(c, apierror.BadRequest(...))` and other `pkg/apierror` constructors |
+| R5 | Reuse | Custom pagination metadata struct (e.g. `PaginationInfo`) | Use `response.PaginationMeta` from `common/response/pagination.go`. NEVER redefine pagination structs |
+| R6 | Reuse | Handler manually parsing `c.Query()` when DTO already defined | Use `c.ShouldBindQuery(&req)` / `c.ShouldBindUri(&req)` to bind existing DTO struct |
+| R7 | Reuse | Handler returning raw `[]T` slice for list endpoint | ALL list endpoints MUST return `response.NewPaginated()` or `response.NewList()`. Service signature: `(items, total, error)`. DTO MUST embed `types.PageParams`, `types.AdminPageParams`, or explicitly justified `types.BulkPageParams` |
+| R8 | Reuse | Repeating in-memory "keyword filter + page slice" helpers inside a module | Reuse `internal/common/utils.FilterAndPaginate()`; the module provides only the matcher. `common/response/pagination.go` owns HTTP response shape only and MUST NOT contain query/filter logic |
+| L1 | Lint | `ALL_CAPS` constant name (e.g. `QUOTA_INSUFFICIENT`) | Use Go CamelCase with `ErrCode` prefix: `ErrCodeQuotaInsufficient`. String VALUE stays ALL_CAPS |
+| L2 | Lint | `err == gorm.ErrRecordNotFound` direct comparison | Use `errors.Is(err, gorm.ErrRecordNotFound)` — supports wrapped errors |
+| L3 | Lint | `for _, item := range largeStructSlice` (copies struct each iteration) | Use `for i := range slice` + `slice[i]` or `item := &slice[i]` |
+| L4 | Lint | `sb.WriteString(fmt.Sprintf(...))` | Use `fmt.Fprintf(sb, ...)` directly |
+| L5 | Lint | Variable name shadows Go builtin (`copy`, `new`, `len`, `max`, `min`) | Rename: `copy` → `taskCopy`, `new` → `current`, `max` → `maxLimit` |
+| L6 | Lint | `http.NewRequest(...)` without context | Use `http.NewRequestWithContext(ctx, ...)` |
+| L7 | Lint | `math/rand` for non-security purposes without `//nolint:gosec` | Add `//nolint:gosec // {reason}` comment explaining why crypto/rand is not needed |
+| I1 | Infra | Inline `Page int` + `PageSize int` in DTO | Embed `types.PageParams` (user), `types.AdminPageParams` (admin max=200), or `types.BulkPageParams` (explicit high-volume read max=1000). NEVER define pagination fields manually |
+| I2 | Infra | Inline `(page-1)*pageSize` offset calculation | Use `.Offset()` from embedded PageParams/AdminPageParams/BulkPageParams/PaginationQuery |
+| I3 | Infra | `gin.H{}` in handler response body | Use VO struct (vo.go) or anonymous struct. gin.H FORBIDDEN in handlers (R1 also covers list responses) |
+| I4 | Infra | `response.ValidationError(c, fmt.Errorf(...))` for missing required params | Use `response.Error(c, apierror.BadRequest(apierror.CodeValidationFailed, "..."))` or add `middleware.RequireProductCode()` at route level |
+| I5 | Infra | `c.Get("key")` to read context values in handler | Use middleware helpers: `middleware.GetUserID(c)`, `middleware.GetProductCode(c)`, etc. |
+| I6 | Infra | DTO-local custom `Normalize()`/`PageOrDefault()` for pagination | DELETE custom methods. Delegate to the shared `PageParams.Normalize()`, `AdminPageParams.Normalize()`, or `BulkPageParams.Normalize()` implementation |
+| I7 | Infra | External list/search HTTP DTO exposes a generic `limit` parameter | Standard pagination MUST use `types.PageParams` / `types.AdminPageParams` / explicitly justified `types.BulkPageParams`; external contracts allow only `page` + `page_size`. `limit` is allowed only as an explicit domain config field (for example `default_limit`, `max_items`), never as a list-query pagination parameter |
+| TX1 | Transaction | `r.db.WithContext(ctx)` in Repository/Persistence | Use `database.GetDB(ctx, r.db)` — ensures transaction participation |
+| TX2 | Transaction | `middleware.WithTransaction` / `middleware.DBOrTx` | Use `database.TransactionManager.WithTransaction` — single mechanism |
+| TX3 | Transaction | Multiple transaction context keys | Single `database.ctxTxKey{}` — one mechanism, one key |
+| N1 | Enum | 管理端展示或选择使用的枚举值、标签、颜色在 registry 外重复维护 | 在 `internal/common/enums/register_xxx.go` 引用 owner 常量注册，并测试实际消费的值集合。私有实现类型和机器协议值不要求注册为管理端选项 |
+| N2 | Reference | `ReferenceID` / `reference_id` 字段用 `fmt.Sprintf` / 字符串拼接 ad-hoc 构造 | 在 owner domain 的 `reference.go` 定义 helper `XxxReferenceID(xxxID int64) string`，调用方 MUST 通过 helper 生成。See `backend/.claude/docs/identifier-contract.md` §3.2 |
+| N3 | Reference | `ReferenceType` 字段使用字符串字面量（e.g. `"order"` / `"subscription"`） | 在 domain 的 `reference.go` 定义 `ReferenceTypeXxx` 常量，所有写入路径 MUST 引用常量 |
+| N4 | Validator | 写入 `p_credit_transactions` / `p_member_point_ledger` / `p_quota_transactions` 时绕过模块的 `ValidateTransactionFields` 直接调用 `db.Create` / `db.Save` | MUST 通过 repo 的 `Create` / `BatchCreate` 方法，repo 内部强制调用 `credit.ValidateTransactionFields`（或对应模块 validator）。禁止 Service/Handler 直接操作 `*gorm.DB` 写入凭证类表 |
+| LC1 | Locale | Domain model, DTO write path, persisted JSON map, or admin API accepts/stores region locale tags such as `zh-CN` / `en-US` as business locale keys | Internal business locale values MUST use OneX short codes validated by `internal/common/locale.IsShortCode`. External headers/imports may call `NormalizeCode` only at boundary adapters before entering domain/service writes |
+| LC2 | Locale | Duplicated supported-locale lists, locale enum metadata, or fallback locale arrays outside `internal/common/locale` / enum registry helpers | Use `commonlocale.SupportedCodes()`, `commonlocale.DefaultCode`, `commonlocale.AdminDefaultCode`, and shared enum helpers. Migrations may list historical external aliases only to repair old data |
+| LC3 | Locale | Localized text/channel JSON validation implemented with ad-hoc key checks or `map[string]string` loops that do not call the common locale validator | Route all localized-map write validation through `commonlocale.IsShortCode` or a module helper that delegates to it. Invalid locale keys fail fast with validation errors |
+
+`make lint-enums` / `backend/scripts/check-forbidden-patterns.sh` 运行管理端枚举合同测试及标识符、凭证写入静态检查。详细标识符契约见 `backend/.claude/docs/identifier-contract.md`。
+
+---
+
+## Delivery Discipline (CRITICAL)
+
+Every delivery MUST achieve **zero violations** against this spec. There are NO exceptions, NO exemptions, NO deferrals.
+
+| Principle | Detail |
+|-----------|--------|
+| **发现即修正** | Found a violation → fix it NOW in the same delivery. Never defer to "next time" |
+| **无豁免条款** | No pattern is "too simple" or "too thin" to follow the rules. CRUD handler still needs Service layer if rules say so |
+| **设计先行** | Every fix must be properly designed, not patched. If a bug fix requires architectural change, do the architectural change |
+| **不存在后续** | "后续如果需要可以提取" = 现在就提取。"后续处理" = 现在处理 |
+| **交付 = 零违规** | Delivery with known violations is a failed delivery, regardless of how "minor" the violation seems |
+
+### Pre-Delivery Checklist
+
+BEFORE declaring any task complete, run this mental checklist:
+
+1. All files pass FORBIDDEN patterns table (S/A/T/C/H/D/AU/E rules)
+2. Handler layer contains ZERO business logic (A1), ZERO repo calls (A2), ZERO audit calls (AU3)
+3. All write operations in Service carry audit evidence through DomainEvent fields or `audit.Enrich()` (AU1)
+4. No deferred code markers (D1-D7)
+5. `go build ./...` passes
+6. `wire ./cmd/*/` regenerated for all affected cmd directories
+7. No residual imports from refactored/deleted packages
+8. All list/search contracts pass pagination validation: DTOs expose no generic `limit`, Handlers return no raw slices, application layer has no duplicated `filter + slice` helpers, and the `response` package contains no filtering/query logic
+
+Skipping ANY item = failed delivery.
+
+### Pagination Validation
+
+Whenever you modify a list/search endpoint, an options dropdown endpoint, or in-memory application-layer pagination, you MUST validate the pagination contract before delivery:
+
+1. **Parameter layer**
+   - DTOs MUST embed `types.PageParams`, `types.AdminPageParams`, or an explicitly justified `types.BulkPageParams`
+   - Generic pagination MUST NOT define `limit`
+2. **Application layer**
+   - In-memory filtering + slicing MUST reuse `internal/common/utils.FilterAndPaginate()`
+   - The module keeps only the matcher and MUST NOT duplicate a `keyword -> filter -> slice` shell
+3. **Response layer**
+   - List endpoints MUST return `response.NewPaginated()` or `response.NewList()`
+   - `internal/common/response/pagination.go` owns response shape only and MUST NOT contain filtering/query logic
+
+Recommended pre-delivery checks:
+
+```bash
+rg -n 'form:"limit"|json:"limit"' internal
+rg -n 'response\\.OK\\(c,\\s*items\\)|response\\.OK\\(c,\\s*result\\)' internal
+rg -n 'if .*page < 1|\\(page-1\\)\\*pageSize|slice\\(start, start \\+ pageSize\\)' internal
+```
+
+---
+
+## Deferred Code Policy (CRITICAL)
+
+Every line of committed code MUST be production-ready. There are ZERO exceptions.
+
+| Scenario | WRONG | CORRECT |
+|----------|-------|---------|
+| Feature not ready | `// TODO: implement later` | Return `apierror.BadRequest("Feature X is not supported")` |
+| Data format changed | `if newFormat(err) { fallback(oldFormat) }` | Migrate data. Single code path |
+| Encryption bypass | `if decrypt(err) { tryPlaintext() }` | `if decrypt(err) { return err }` |
+| Module not integrated | `// 暂跳过` / empty block | Reject input that requires the module: `return apierror.BadRequest(...)` |
+| Interface not implemented | `return nil, nil` (noop) | `return nil, fmt.Errorf("X is not implemented")` |
+| Partial implementation | Handle case A, `// case B 待后续` | Handle case A, `default: return fmt.Errorf("unsupported: %s", caseType)` |
+
+The principle: **fail loudly, never silently skip**. A production system that returns an error is safer than one that silently does nothing.
+
+---
+
+## API Versioning
+
+- Full URL pattern: `/api/v{N}/{resource}` (e.g. `/api/v1/users`)
+- Version prefix set in router group: `router.Group("/api/v1")`
+- Handler ONLY registers resource path: `v1.GET("/users", h.List)`, NEVER full path
+- Breaking changes: create v2 route group, keep v1 compatible until clients migrate
+
+---
+
+## API Response Rules
+
+| Operation | Status | Body |
+|-----------|--------|------|
+| GET single | 200 | `{ "id": ..., ...fields }` |
+| GET list | 200 | `{ "data": [...], "pagination": {...} }` |
+| POST create | **201** | `{ "id": ..., ...fields }` |
+| PUT/PATCH update | 200 | `{ "id": ..., ...fields }` |
+| DELETE | **204** | Empty body |
+| Error | 4xx/5xx | `{ "error": { "type": "...", "code": "...", "message": "..." } }` |
+
+- Request input: struct + `binding` / `validate` tag, 定义在 `dto.go`
+- Response output: struct + `ToXxxResponse()` 转换函数, 定义在 `vo.go`
+- NEVER return Model/Entity directly. ALWAYS transform via `ToXxxResponse()`
+- NEVER use wrapper format `{ "code": 0, "data": ..., "message": "ok" }`
+
+---
+
+## Error Handling
+
+### Flow
+
+```
+Request → Middleware(Auth/Logging/Recovery) → Handler → Service → Repository
+                                                         │ (return error)
+Response ← Error Middleware ← ─────────────────── error
+```
+
+- Handler: receives error from service, calls `response.Error(c, err)`. NEVER constructs error response manually
+- Service: returns typed errors (`apierror.NotFound(...)`, `apierror.Business(...)`)
+- Middleware: `Recovery` catches panic, `Auth` returns 401/403
+- Messages: English ONLY. Format: `"{Resource} with {field} {value} not found"`
+
+### Error Decision Table
+
+| Scenario | Error Constructor | Status | ErrorCode |
+|----------|------------------|--------|-----------|
+| Resource not found | `apierror.NotFound(...)` | 404 | `resource_not_found` |
+| Duplicate resource | `apierror.Conflict(...)` | 409 | `resource_conflict` |
+| Invalid input | `apierror.BadRequest(...)` / validator | 400 | `invalid_parameters` |
+| No auth / expired token | `apierror.Unauthorized(...)` | 401 | `unauthorized` |
+| No permission | `apierror.Forbidden(...)` | 403 | `forbidden` |
+| Business rule violated | `apierror.Business(code, msg)` | 422 | (domain-specific) |
+| Rate limited | `apierror.TooManyRequests()` | 429 | `rate_limited` |
+| External service failure | `apierror.Internal(...)` | 500 | `internal_error` |
+
+---
+
+## Database Rules
+
+- Embed `BaseModel` from `internal/core/database`
+- Column name: `snake_case` (GORM 默认)。Struct field: `PascalCase`
+- ALL columns MUST have `comment` tag (Chinese)
+- Boolean columns: `is_xxx` 命名 + `bool` type
+- Status columns: `varchar(20)` + string const
+- Timestamps: `timestamptz(3)` (毫秒精度)
+- PK: `bigserial`. FK: `bigint`
+- Money: `decimal(19,4)`, 代码中用 `string`
+- JSON: `jsonb` type, Go 中用 `datatypes.JSON` 或自定义 struct
+- ALWAYS specify fields in queries: `Select("id", "name", "email")`. NEVER `SELECT *`
+- ALWAYS paginate list queries. NEVER unbounded results
+- Use `Preload` or `Joins` to avoid N+1 queries
+
+### Production SQL / DMS Execution Rules
+
+- Production repair SQL MUST be a single statement when the execution tool does not support explicit transactions. Use writable CTEs for atomic multi-table updates.
+- Validate every production SQL statement against PostgreSQL before handing it to operators. Do not rely on visual inspection for CTE, `RETURNING`, JSON, or `LATERAL` syntax.
+- Avoid dialect-sensitive or tool-sensitive constructs in operator-facing SQL: explicit `BEGIN`/`COMMIT`, `CROSS JOIN LATERAL (VALUES ...) AS alias(...)`, anonymous composite row output, and client-specific batch separators.
+- `RETURNING` output MUST use named scalar columns or named JSON object keys. Avoid `RETURNING row(...)` or unnamed `VALUES` outputs that produce `f1`, `f2`, `f3` fields.
+- Destructive or state-changing production SQL MUST include an exact target guard (`id`, business reference, current status, version or timestamp where available) and return `target_count` plus changed row summaries.
+
+---
+
+## Transaction Infrastructure
+
+- **单一机制**: `database.TransactionManager`（位于 `core/database/transaction.go`）
+- **REQUIRED propagation**: `txManager.WithTransaction(ctx, fn)` — 加入已有事务，或新建事务
+- **REQUIRES_NEW**: `txManager.WithNewTransaction(ctx, fn)` — 始终创建独立新事务（用于审计日志、幂等 key 等）
+- **Repository 获取 DB**: `database.GetDB(ctx, r.db)` — Repository 内获取 DB 的**唯一**方式，从 context 提取事务，或回退到普通 DB
+- **Service 不感知 `*gorm.DB`**: 回调签名为 `func(ctx context.Context) error`，Service 层看不到 GORM 类型
+- **Savepoint**: GORM 对嵌套 `Transaction()` 调用自动使用 savepoint，无需额外封装
+- **Options**: `WithNewTransaction` 接受 `...*sql.TxOptions`（来自 stdlib），用于设置隔离级别和只读模式
+
+---
+
+## Logging Rules
+
+- Use `*zap.Logger` field in struct，通过构造函数/Wire 注入
+- NEVER `fmt.Println` / `log.Println` / `log.Fatal`
+- Structured fields first: `logger.Info("order created", zap.Int64("userId", uid), zap.Int64("orderId", oid))`
+- Error logging: `logger.Error("operation failed", zap.Error(err), zap.Int64("contextId", id))`
+- NEVER log passwords, tokens, API keys, PII, card numbers
+- Message: short, past tense (`"order created"`, NOT `"creating order..."`)
+
+---
+
+## Audit Architecture (CloudTrail Envelope Pattern)
+
+Three-layer audit architecture. Audit change data is carried on **DomainEvent envelope fields** (AWS CloudTrail pattern), NOT inside the business Payload.
+
+### Three-Table Architecture
+
+| Table | Source | Retention | Purpose |
+|-------|--------|-----------|---------|
+| `sys_access_logs` | L1 middleware captures all HTTP requests | 30 days | Ops monitoring / operation logs |
+| `sys_audit_logs` | L2 event envelope `AuditChanges` field (business change snapshots) | 7 years | Compliance audit |
+| `sys_login_logs` | L2 events (auth events dual-written, with device/geo info) | 1 year | Security analysis |
+
+### Three Layers
+
+| Layer | Mechanism | Developer Work |
+|-------|-----------|---------------|
+| L1 Middleware | `AuditMiddleware` → `sys_access_logs` | Zero — automatic |
+| L2 Listener | `AuditListener` reads `AuditChanges` / `AuditMeta` from event envelope → `sys_audit_logs` / `sys_login_logs` | Set event envelope fields |
+| L3 Enrichment | `audit.Enrich()` → middleware writes to `sys_audit_logs` | **Only for write ops WITHOUT events** |
+
+### Audit Data Rules (CRITICAL)
+
+**Write operations WITH event publishing**: Set audit data on DomainEvent envelope fields. **FORBIDDEN to also call `audit.Enrich()`** (otherwise L2 + L3 = duplicate records).
+
+```go
+import "{{module}}/internal/core/eventbus"
+
+evt := eventbus.NewDomainEventFromContext(ctx, sharedevents.EventOrderPaid, orderID)
+evt.Payload = &sharedevents.OrderPaidEvent{OrderID: order.ID, Amount: amount}  // typed struct pointer (EP1)
+evt.AuditChanges = &eventbus.AuditChangesPayload{
+    Before: map[string]any{"status": "pending"},
+    After:  map[string]any{"status": "paid", "paid_at": time.Now()},
+}
+evt.AuditMeta = &eventbus.AuditMetadataPayload{Reason: "payment confirmed"}  // optional
+s.eventBus.PublishAsync(ctx, evt)
+// FORBIDDEN: do NOT call audit.Enrich() here
+```
+
+**Write operations WITHOUT event publishing** (pure L3 path): Use `audit.Enrich()`
+
+```go
+import "{{module}}/internal/core/audit"
+
+// Admin ops without events (e.g., AdminResetPassword, UpsertConfig)
+audit.Enrich(ctx, &audit.ChangesPayload{
+    After: map[string]any{"password_reset": true},
+}, nil)
+```
+
+### Decision Flow
+
+```
+After write operation completes →
+  Does this operation publish a domain event?
+    YES → Set audit data on event.AuditChanges (L2 envelope path)
+    NO  → Call audit.Enrich(ctx, changes, metadata) (L3 context path)
+  FORBIDDEN: using both simultaneously
+```
+
+### Exempt Scenarios
+
+| Scenario | Reason |
+|----------|--------|
+| Read-only operations (GET / List / Query) | L1 already captures the request |
+| Worker / Cron background tasks | Covered by L2 event envelope (no HTTP context) |
+| EventBus Listener internals | L2 already captures the event |
+| Technical operations (token rotation, cache refresh) | Not a business state change |
+
+### FORBIDDEN Patterns
+
+| Pattern | Fix |
+|---------|-----|
+| `audit.Enrich()` + `PublishAsync()` in same method | Use envelope fields only, remove Enrich |
+| `_audit_changes` key in `event.Payload` | Deprecated — use `event.AuditChanges` envelope field |
+| `map[string]any` as event Payload | Use typed struct from `sharedevents` |
+
+---
+
+## Comments
+
+- Language: Chinese ONLY. NEVER English comments
+- Style: explain WHY, not WHAT. Skip self-explanatory code
+- GoDoc on ALL exported types, functions, methods
+- NEVER: ticket numbers in comments, commented-out code
+- Struct fields: use `//` comment above field (Chinese description)
+
+---
+
+## OpenAPI Contract
+
+- `api/openapi/services/<service>/openapi.yaml` 是 HTTP 契约唯一事实源，Go handler 不保存契约注释或文档专用 struct tag。
+- 每个 operation 必须声明稳定的 `operationId`、显式 `security`、`summary`、`tags`、`responses`、owner、audience 与 stability。
+- Canonical API 文档语言为 `zh-CN`；人类可见文案、顶层 Tag Object 和 `x-tagGroups` 必须使用中文语义，机器标识禁止本地化改名。
+- 每个 operation 必须且只能使用一个已声明标签；每个顶层标签必须在 `x-tagGroups` 中出现且只出现一次，并保持业务阅读顺序。
+- 修改路由、请求、响应、认证或状态码时，同一变更内更新 owner path/component、Arazzo workflow 和生成制品。
+- registry 中全部 HTTP 服务启动时必须通过 Gin route 与内嵌 internal bundle 的精确集合校验。
+- partner/public 只能由 internal canonical source 投影生成，禁止直接编辑 `dist/`。
+- 详细规则和模板见 `.claude/docs/openapi-contract.md`。
+
+---
+
+## Import Order
+
+Go 标准 goimports 分组：
+
+1. Standard library (`fmt`, `context`, `net/http`)
+2. External packages (`github.com/gin-gonic/gin`, `gorm.io/gorm`)
+3. Internal packages (`github.com/onex-platform/backend/internal/...`)
+
+- NEVER import `internal/` package's unexported types from outside
+- NEVER circular imports between packages
+- Run `goimports` to auto-format
+
+---
+
+## Cross-Module Communication
+
+| Need | Method |
+|------|--------|
+| Data from another module | 定义 interface in consumer package，implementation 通过 Wire 注入 |
+| Notify without coupling | `EventBus.Publish(ctx, event)` |
+
+- Import interface, NEVER concrete implementation across module boundaries
+- Export only what other packages need (最小化导出)
+- Listener 通过 `EventBus.Subscribe()` 注册
+
+### Event Payload Standard (CRITICAL — EP1–EP5)
+
+All `DomainEvent.Payload` MUST be a **typed struct pointer**. Aligned with CloudEvents, Stripe Go SDK, Watermill CQRS. Violations WILL be rejected in review.
+
+| ID | Rule | Correct | Forbidden |
+| --- | --- | --- | --- |
+| EP1 | Publisher sends pointer | `evt.Payload = &sharedevents.XxxEvent{...}` | `evt.Payload = sharedevents.XxxEvent{...}` (value) |
+| EP2 | Registry factory returns pointer | `EventXxx: func() any { return &XxxEvent{} }` | `return XxxEvent{}` |
+| EP3 | Listener asserts pointer only | `switch p := event.Payload.(type) { case *sharedevents.XxxEvent: ...; default: return err }` | Additional `case sharedevents.XxxEvent:` or `case map[string]any:` branches |
+| EP4 | No map[string]any fallback | Registry + Outbox relay both produce pointers; map fallback is dead code (H5 NO PHANTOM CODE) | Retaining legacy `case map[string]any:` for "defensive" reasons |
+| EP5 | Payload immutable after publish | Constructor fills fields; never mutate after `PublishAsync` | Mutating payload inside handler or later code |
+
+**Why pointer?**
+- `json.Unmarshal(&x)` requires a pointer → cross-process Outbox relay ALWAYS produces pointers. Pointer publisher + pointer listener = one uniform type assertion path.
+- `interface{}` boxing escapes value types to heap anyway → no heap-cost benefit to values.
+- Watermill CQRS `Handle(ctx, event *MyEvent) error` signature is industry standard; future bus swap is zero-refactor.
+
+**Standard publisher pattern**:
+```go
+evt := eventbus.NewDomainEventFromContext(ctx, sharedevents.EventUserCheckin, fmt.Sprintf("%d", record.ID))
+evt.Payload = &sharedevents.UserCheckinEvent{
+    UserID:      userID,
+    ProductCode: productCode,
+    CheckinDate: today.Format("2006-01-02"),
+    StreakDays:  streakDays,
+}
+s.eventBus.PublishAsync(ctx, evt)
+```
+
+**Standard listener pattern**:
+```go
+func (l *Listener) handleXxx(ctx context.Context, event eventbus.DomainEvent) error {
+    payload, ok := event.Payload.(*sharedevents.XxxEvent)
+    if !ok {
+        l.logger.Warn("unexpected payload type",
+            zap.String("eventName", event.EventName),
+            zap.String("payloadType", fmt.Sprintf("%T", event.Payload)),
+        )
+        return fmt.Errorf("unexpected payload type %T for event %s", event.Payload, event.EventName)
+    }
+    // ... process payload.UserID / payload.ProductCode / ...
+    return nil
+}
+```
+
+### Platform vs External Product Boundary (CRITICAL — PB1–PB4)
+
+OneX owns reusable platform capabilities under `internal/platform/`. Product-specific workflows, presentation composition, and public BFF contracts belong to external product repositories; `internal/products/` is not an allowed OneX ownership boundary.
+
+| ID | Rule | Correct | Forbidden |
+| --- | --- | --- | --- |
+| PB1 | Platform feature → `internal/platform/` | Checkin, points, member tier, order, and payment remain product-neutral engines | Adding an `internal/products/` implementation or product-specific branch inside a platform module |
+| PB2 | `product_code` is a first-class parameter | Every cross-product entity has `product_code VARCHAR(50)` column + index; every DTO / domain struct threads it through | Hardcoding `"product_beta"` in service logic, SQL, or config keys |
+| PB3 | Product-varying platform rules → DB config, not Go code | Rewards per product live in `p_credit_activity_reward_configs`; new product = INSERT row, zero code change | `if productCode == "sample_product" { amount = 100 }` |
+| PB4 | Client must NOT hardcode platform contract values | Reward amounts, tier thresholds, etc. fetched from API (e.g., `/member/checkin/status` returns `next_reward_amount`) | Frontend `const REWARD = 100` that silently breaks when backend config changes per product |
+
+Checkin reference implementation (as of this writing):
+- Module location: `internal/platform/member/` ✓ PB1
+- `UserCheckinEvent.ProductCode` field + `UserProductScoped` interface ✓ PB2
+- Reward config in `p_credit_activity_reward_configs (product_code, activity_type, base_amount)` ✓ PB3
+- API `/member/checkin/status` returns the upcoming reward amount so clients do not hardcode product-varying policy ✓ PB4
+
+---
+
+## Architecture Decisions
+
+### Module Complexity Tiers
+
+BEFORE creating a new module, determine its complexity tier. Use ONLY the matching structure.
+
+| Tier | Criteria | Structure | Modules |
+|------|----------|-----------|---------|
+| Full DDD | State machine / Saga / CQRS / multi-aggregate | `domain/` + `application/` + `infrastructure/` | identity, notification, order, payment |
+| Simplified DDD | Domain logic without state machine / 2-3 related entities | `domain/` + `application/` + `infrastructure/` | user, tenant |
+| Flat | Pure CRUD / simple queries | `model.go` + `service.go` + `handler.go` + `dto.go` + `vo.go` | audit |
+
+Decision flow: Need state machine/Saga? → Full DDD. Complex domain logic? → Simplified. Otherwise → Flat.
+
+Upgrade path: Flat → Simplified → Full DDD (one-way only, never downgrade).
+
+### Directory Subdivision Rules
+
+After determining the module complexity tier, decide whether each layer needs sub-packages using the rules below.
+
+#### domain/ — Almost Always Flat
+
+| Condition | Structure |
+|-----------|-----------|
+| Default | Single package: model.go, enum.go, repository.go, interfaces.go, events.go |
+| Subdivision trigger | 2+ completely independent aggregate roots (no shared entities) AND files > 12 |
+| Subdivision pattern | `domain/{aggregate}/` |
+
+Identity has 10 entities but all revolve around the Identity aggregate root → stays flat.
+
+#### application/ — Subdivide by Subdomain
+
+| Condition | Structure |
+|-----------|-----------|
+| Service files ≤ 6 AND total files ≤ 15 | Flat: `{name}_service.go` + `handler_{name}.go` |
+| Service files > 6 AND 3+ isolated service groups | Subdivide: `application/{subdomain}/` |
+
+Subdivision decision flow:
+1. Draw service dependency graph
+2. Identify "isolated groups" (may have intra-group coupling, but no inter-group service dependencies)
+3. Isolated groups ≥ 3 AND service files > 6 → MUST subdivide
+
+Standard structure inside each sub-package: service.go, handler.go, dto.go, vo.go (optional).
+Cross-subdomain orchestration (admin handler, listener) stays at application/ root.
+
+#### infrastructure/ — Subdivide by Integration Type
+
+| Condition | Structure |
+|-----------|-----------|
+| GORM repositories only | Flat: persistence.go |
+| 3+ external integrations | Subdirectories by type: channels/, webhooks/, etc. |
+| persistence.go > 1500 lines | Split into persistence_{aggregate}.go |
+
+#### Module Root
+
+{module}/ root ONLY contains assembly files:
+- `module.go` — Module facade (manual assembly)
+- `provider.go` — Wire ProviderSet (only `wire.NewSet`, NEVER constructor re-exports)
+- FORBIDDEN: handler, service, model, or any business code
+
+### VO Naming (CRITICAL)
+
+Two types of "VO" exist in this project. NEVER confuse them.
+
+| Concept | File | Directory | Implementation |
+|---------|------|-----------|---------------|
+| API Response View Object | `vo.go` | `application/` 或 package root | struct + `ToXxxResponse()` func |
+| DDD Value Object | `valueobject.go` | `domain/` | struct with `Equals()` method |
+
+Value Object decision: Use `valueobject.go` ONLY when the value has composite structure (multiple fields that change together) AND invariant constraints (e.g., Money = amount + currency + non-negative check). Simple IDs → primitive type. Status → string const.
+
+### Product vs Tenant
+
+Each brand is a **product**, NOT a tenant.
+
+- Use `ProductContext`, NEVER `TenantContext`
+- OneX 产品数据隔离：`product_code` + IAM + owner-scoped query
+- 产品业务代码隔离：独立产品仓库与独立 BFF 进程
+- Tenant isolation：组织/客户级运行时数据范围，不是 Product 的别名
+
+### Multi-Product Configuration (三层模型)
+
+Platform uses a **three-tier configuration model** with a central product registry.
+
+#### Product Registry
+
+`p_products` is the **single source of truth** for all platform products. Every module that needs per-product configuration references `p_products.code`.
+
+| Rule | Detail |
+|------|--------|
+| **Field name** | `product_code` — ALL modules, NO exceptions (`product_id`, `app_id` FORBIDDEN) |
+| **Column type** | `VARCHAR(50)` — ALL modules, unified width |
+| **Value format** | `snake_case` — regex: `^[a-z][a-z0-9_]{1,49}$` |
+| **Enum source** | `common/types.Product` — single definition, ALL modules reference it |
+
+#### Three Tiers
+
+| Tier | Storage | Content | Example |
+|------|---------|---------|---------|
+| Tier 1: Infrastructure | YAML + env var | DB/Redis/JWT/API keys | `configs/config.yaml` |
+| Tier 2: Platform Module | `p_products` + per-module config tables | Commerce/Notification/OAuth/Tenant | `p_config_product_configs` |
+| Tier 3: Product-Specific | External product repository | Product workflow, presentation, and product-owned data | `<product-repository>/backend/` |
+
+#### Per-Module Config Tables (Tier 2)
+
+Each platform module owns its per-product configuration table. Tables are NOT redundant — each covers a distinct domain:
+
+| Config Table | Module | Responsibility |
+|-------------|--------|---------------|
+| `p_products` | product | Product identity (name, logo, status) |
+| `p_config_product_configs` | commerce/config | Commerce settings (currency, trial, tax) |
+| `p_config_payment_configs` | commerce/config | Payment gateways (provider, secrets) |
+| `p_notification_products` | notification | Channel config (sender, branding, quotas) |
+| `p_identity_oauth_configs` | identity | OAuth providers (client_id, redirect_uri) |
+| `p_tenant_apps` | tenant | Tenant features (feature flags, rate limits) |
+
+All tables use `product_code VARCHAR(50)` to reference `p_products.code`.
+
+See the upstream OneX `backend/.claude/docs/product-registry-design.md` for the platform-owned registry design; its source revision is recorded in `docs/standards-provenance.json`.
+
+### Service Topology
+
+Modular Monolith 架构（Stripe/Shopify 标准）。统一平台 API 服务所有产品，管理后台独立进程。
+
+| App | Port | Purpose |
+|-----|------|---------|
+| `cmd/platform-api/` | 3002 | 统一平台服务（Identity + Commerce + Credit + Quota） |
+| `cmd/admin-api/` | 3003 | 管理后台 BFF（admin dashboard） |
+| `cmd/worker/` | — | 后台任务（Asynq consumer） |
+
+**Per-product domain routing**：APISIX 按 Host + Path 将产品公开合同路由到外部 Product BFF，将平台公开/内部合同路由到对应 OneX 服务。产品前端只配置一个公开产品 origin，不直接选择基础设施服务。
+
+**路由选择性注册**：所有模块实现 nil-safe `RegisterRoutes(public, authenticated, admin *gin.RouterGroup)`。通过传 nil 跳过不需要的路由组：
+- admin-api: `RegisterRoutes(nil, nil, admin)` — 仅注册 admin 路由
+
+**平台适配器**：OneX 进程内跨模块适配器统一在 `internal/common/bffadapter/`；外部 Product BFF 只能通过 OpenAPI HTTP 合同、事件或工作流调用平台能力。
+
+**Outbox Relay**：platform-api 运行统一 Relay，处理所有域的 outbox 事件。admin-api 不调用 `relay.Start()`，admin 写入的 outbox 记录由 platform-api 的 Relay 投递。
+
+**Event runtime boundary**：源聚合投影监听器必须留在拥有该状态机的运行时；`worker` 只消费 durable public events 做下游副作用。`user.deleted` 这类部分公开的事件族必须使用精确白名单，禁止 `user.*` 这类宽泛通配。See `backend/.claude/docs/event-runtime-boundary.md`.
+
+**E2E contract tests**：凡是跨运行时、依赖 relay/worker、会改变最终用户可见真相的工作流，必须同时具备一个全链路 E2E 和一个 `ProvideRelayConfig()` 白名单回归测试。See `backend/.claude/docs/e2e-standards.md`.
+
+**内部服务间调用**：`/internal/v1/` 路由组，通过 IAM 服务账号凭证认证、已认证主体校验、路由资源策略授权保护。
+
+**Gateway upstream policy**：所有挂在 APISIX 后的生产 public API upstream 必须使用多节点 + 主被动健康检查 + 显式 timeout/retries/keepalive。任何 gateway plugin 回调（如 `forward-auth`）必须复用 APISIX 内部路由或共享 upstream，禁止直连单个 backend 实例。
+
+Gateway (APISIX) runs separately, not in Go codebase. Routes: `/api/v1/admin/*` → admin-api (priority 10).
+
+### Event Contracts
+
+Cross-module events MUST be defined in `internal/sharedevents/`, NEVER in the publishing module.
+
+- Event struct: `{Resource}{Action}Event` (e.g., `IdentityCreatedEvent`)
+- Event name const: `Event{Resource}{Action}` = `"{resource}.{action}"` (e.g., `"identity.created"`)
+- Import: `import "{{module}}/internal/sharedevents"`
+
+### Table Naming
+
+| Scope | Prefix | Example |
+|-------|--------|---------|
+| Platform base entity | `p_` | `p_products`, `p_tenants` |
+| Platform module | `p_{module}_` | `p_user_users`, `p_identity_identities` |
+| System | `sys_` | `sys_migrations`, `sys_access_logs`, `sys_audit_logs`, `sys_login_logs`, `sys_outbox_events` |
+
+Product-related columns: ALL tables that reference a product MUST use `product_code VARCHAR(50)` as the column name. NEVER use `product_id`, `app_id`, or other variants.
+
+Product-specific tables are owned by external product repositories and must not be added to the OneX schema.
+
+---
+
+## Dependency Injection (Wire)
+
+- 每个模块提供 `provider.go`，定义 `wire.NewSet(...)`
+- 每个 `cmd/` 提供 `wire.go`，定义 injector function
+- 运行 `make wire` 生成 `wire_gen.go`
+- NEVER 手动编辑 `wire_gen.go`
+- NEVER 在 `main.go` 中手动构造依赖
+
+---
+
+## Commit Discipline
+
+- ONE module, ONE feature per commit
+- Pre-commit: validate against `backend/.claude/docs/` specs
+- MUST NOT commit with any CRITICAL/MUST violation
+
+---
+
+## Scaffold Skills
+
+创建新模块或新管理页时，优先使用脚手架生成骨架代码，再填充业务逻辑：
+
+| Skill | Usage | Purpose |
+|-------|-------|---------|
+| `/scaffold` | `/scaffold {module} --tier={full-ddd\|simplified\|flat}` | 生成 Go 模块骨架（domain + application + infrastructure） |
+| `/scaffold-admin` | `/scaffold-admin {module}/{resource}` | 生成 Admin CRUD 页面（VxeGrid + Modal + Form + API） |
+
+---
+
+## Reference
+
+| Doc | Content |
+|-----|---------|
+| `.claude/docs/architecture-template.md` | Plan mode mandatory skeleton (Level A/B/C) |
+| `backend/.claude/docs/api-design.md` | Handler/Service/DTO/VO templates, pagination |
+| `backend/.claude/docs/module-standards.md` | Tier decision, directory subdivision, VO naming |
+| `backend/.claude/docs/error-handling.md` | Error types, codes, decision table |
+| `backend/.claude/docs/database.md` | Model template, column types, migrations |
+| Upstream OneX `.claude/docs/decisions.md` | Platform Architecture Decision Records; source revision in `docs/standards-provenance.json` |
+| `internal/platform/trade/order/` | Reference: Full DDD module |
+| `internal/platform/trade/module.go` | Reference: Module self-registration |