@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/.claude/docs/payment-gateway-onboarding.md

@@ -0,0 +1,283 @@
+# Payment Gateway Onboarding Playbook
+
+> **Upstream scope**: this complete OneX provider playbook applies to work in the upstream payment module. A product backend consumes that platform capability through its authenticated contract; these source paths and provider credentials do not belong to the product repository. Verify the current upstream module and provider contract before executing the playbook.
+
+> **目的**：新接入一个支付 provider（card rail 类，非 IAP）从 0 到 production 的完整流程。目标是让 **新 engineer / AI agent 首周独立接第 7 个 provider**，不问现任。
+>
+> **范围**：card-rail HTTP provider（Stripe / PayPal / Airwallex / Payssion / Adyen / Checkout.com / 2Checkout 等）。**不**覆盖 Apple IAP / Google Play（客户端驱动，单独设计）。
+>
+> **最后更新**：2026-08-06（ProviderOperation 命令与资源生命周期契约）
+
+---
+
+## Table of Contents
+
+1. [前置：ops-side 申请 sandbox](#1-前置ops-side-申请-sandbox)
+2. [实现 Go Gateway Builder](#2-实现-go-gateway-builder)
+3. [配置 DB：`p_config_payment_configs` 新增 row](#3-配置-dbp_config_payment_configs-新增-row)
+4. [配置 DB：`p_config_payment_decline_rules` seed](#4-配置-dbp_config_payment_decline_rules-seed)
+5. [Wire DI 注册 Builder](#5-wire-di-注册-builder)
+6. [契约测试 `contract_test.go` 加 provider 分支](#6-契约测试-contract_testgo-加-provider-分支)
+7. [Staging 部署 + 真实小额测试](#7-staging-部署--真实小额测试)
+8. [上线检查清单](#8-上线检查清单)
+9. [已知陷阱](#9-已知陷阱)
+
+---
+
+## 1. 前置：ops-side 申请 sandbox
+
+> 本步骤为 **ops 工作**，不计入"30 分钟 code leap"目标。部分 provider 需数天到数周 KYC。
+
+| Provider | Sandbox 类型 | 获取路径 | 预计时间 |
+|---------|------------|---------|---------|
+| Stripe | Test Mode（自服务）| dashboard.stripe.com → Developers → API keys → 测试模式 | 5 分钟 |
+| PayPal | Sandbox 账户 | developer.paypal.com → Apps & Credentials → Sandbox | 30 分钟 |
+| Airwallex | 商户申请 | 联系商务 → KYC → Sandbox credential | 1-2 周 |
+| Payssion | 商户申请 | payssion.com → contact | 1 周 |
+| Checkout.com | 自服务 | checkout.com → Signup → Sandbox | 30 分钟 |
+| Adyen | 商户申请 | adyen.com → Get Started → 企业 KYC | 2 周+ |
+
+获取到 sandbox 后：
+- 将 secret 加密后插入 `p_config_payment_configs`（见 §3）
+- 将 test key 放入 `.env.dev`（本地）+ CI secret（若启用 live sandbox CI）
+
+---
+
+## 2. 实现 Go Gateway Builder
+
+目标目录：`backend/internal/platform/trade/payment/infrastructure/gateway/{provider}/`
+
+参考 `stripe/` 的文件结构：
+
+```
+{provider}/
+  gateway.go        — provider 私有 HTTP 客户端、Webhook 与查询实现
+  provider_operation.go — 实现真实支持的 ProviderOperation capability
+  auth.go           — provider 鉴权（OAuth token 刷新 / API key 签名）
+  api.go            — provider REST client（http.Client 封装）
+  gateway_test.go   — 单点 smoke test（独立于 contract matrix）
+  test_clock.go     — 若 provider 支持 time-travel（Stripe 独有），实现 SandboxClockGateway
+```
+
+### 2.1 实现基础 `domain.PaymentGateway`
+
+```go
+package {provider}
+
+import (
+    "github.com/onex-platform/backend/internal/platform/trade/payment/domain"
+)
+
+type Gateway struct {
+    logger *zap.Logger
+    client *Client
+    config domain.GatewayConfig
+}
+
+// Builder 构造 Gateway 实例（registered into ProvideGatewayBuilders map）
+func Builder(deps domain.GatewayBuilderDeps) (domain.PaymentGateway, error) {
+    // 解码 config.Secrets → provider-specific credential 结构
+    // 构造 Client + Gateway
+    // return &Gateway{...}, nil
+}
+
+func (g *Gateway) Provider() string { return "{provider}" }
+
+func (g *Gateway) VerifyWebhookSignature(rawBody []byte, headers map[string]string) error { ... }
+
+func (g *Gateway) ParseWebhookEvent(payload []byte) (*domain.PaymentEvent, error) { ... }
+
+func (g *Gateway) CreateRefund(ctx context.Context, req *domain.CreateRefundGatewayRequest) (*domain.RefundGatewayResult, error) { ... }
+
+func (g *Gateway) GetPaymentStatus(ctx context.Context, providerPaymentID string) (*domain.PaymentGatewayStatus, error) { ... }
+```
+
+`PaymentGateway` 不表示“可以发起客户在场支付”。每个远端操作都必须通过真实支持的 operation capability 暴露，不得在基础接口中留下返回“不支持”的占位方法。
+
+### 2.2 实现 ProviderOperation capability
+
+客户在场支付至少实现 `PaymentCreationGateway`；只有 provider 真实存在服务端二阶段确认时才实现 `PaymentConfirmationGateway`：
+
+```go
+var _ domain.PaymentCreationGateway = (*Gateway)(nil)
+
+func (g *Gateway) CreatePayment(
+    ctx context.Context,
+    request *domain.ProviderOperationRequest,
+) (*domain.ProviderOperationResult, error) {
+    // provider 私有请求映射、幂等键透传和返回事实归一化
+}
+```
+
+成功结果必须在 `ProviderOperationResult.Resources` 返回全部真实 `ProviderOperationResource`，并把用户交互所需的短期上下文放入版本化 `ProviderOperationPresentation`。PSP 名词（Stripe Checkout Session、PayPal Order、Airwallex PaymentIntent）只能出现在 adapter 内部与对应的 `ProviderResourceKind` 中。
+
+### 2.3 按真实能力实现其他 sub-interface
+
+按 provider 实际能力实现：
+
+- `CustomerGateway` — 有 customer vault 能力（Stripe Customers / Airwallex Customers）
+- `MerchantInitiatedPaymentGateway` — 支持基于已建立授权的商户发起扣款
+- `HostedSubscriptionGateway` — provider 自己托管 recurring
+- `ProviderResourceQueryGateway` — 能查询已知 PSP 资源
+- `ProviderResourceDiscoveryGateway` — 能按不变商户引用发现创建效果
+- `ProviderResourceLifecycleGateway` — 能取消或撤销已知 PSP 资源
+- `RefundExecutionGateway` — 能对类型化收款资源发起退款
+- `SandboxClockGateway` — provider 支持时钟推进（**仅 Stripe**）
+
+> **原则**：不能可靠实现的能力**不要实现**。Resolver 返回 `ok=false`，命令执行器返回类型化的 capability 错误；禁止返回 `nil, nil`。
+
+### 2.4 Webhook 解析
+
+- `ParseWebhookEvent` 必须返回统一的 `*domain.PaymentEvent` 结构
+- 事件 type 映射参考 `stripe/gateway.go` 的 `mapWebhookEventType()`
+- adapter 必须把每个参与运行时关联的 PSP 对象写入
+  `PaymentEvent.ProviderResources`；application 不会从 raw provider ID 或 ID 前缀
+  推断资源类型
+- `payment_intent`、`payment_attempt`、`provider_order` 始终归 Payment 所有；只有
+  `charge`、`capture` 在写入对应 PaymentTransaction 时转移 owner。Airwallex
+  `int_*` 必须声明为 `payment_intent`、`att_*` 声明为 `payment_attempt`；PayPal
+  captured payment 必须声明为 `capture`
+- 未知/不处理的事件类型返回 `domain.NewWebhookEventSkippedError(domain.WebhookSkipReasonUnsupportedEventType)`
+
+### 2.5 Idempotency Key
+
+- 每个 provider mutation 必须使用 `request.ProviderIdempotencyKey`
+- provider 各自的 idempotency 头规范：
+  - Stripe: `Idempotency-Key` header
+  - PayPal: `PayPal-Request-Id` header
+  - Airwallex: `request_id` 请求体字段
+  - Payssion: query param `pm_orderid`
+
+---
+
+## 3. 配置 DB：`p_config_payment_configs` 新增 row
+
+通过 migration 或 admin UI（`/commerce/payments/gateways/`）插入：
+
+```sql
+INSERT INTO p_config_payment_configs (
+    product_code, provider, is_active, is_default,
+    secrets_encrypted, metadata
+) VALUES (
+    'product_beta', '{provider}', true, false,
+    '<ENCRYPTED_JSON>',  -- 调 crypto.Encryptor 加密
+    '{"environment": "sandbox"}'::jsonb
+);
+```
+
+- **每个产品** 独立配置（`productCode:provider` 为 cache key）
+- `is_default=true` 至多 1 条/产品，Factory 调 `GetDefaultGateway(productCode)` 时返回它
+- `secrets_encrypted` 通过 `internal/core/crypto.Encryptor.Encrypt(plaintext)` 生成；解密由 Factory 自动完成
+
+---
+
+## 4. 配置 DB：`p_config_payment_decline_rules` seed
+
+通过新 migration（或运营 admin 的 workflow）seed 该 provider 的 decline 规则：
+
+```sql
+INSERT INTO p_config_payment_decline_rules (product_code, provider, raw_code, decline_type, reason_text) VALUES
+    ('default', '{provider}', '{raw_code_1}', 'hard', 'Friendly message 1'),
+    ('default', '{provider}', '{raw_code_2}', 'soft', 'Friendly message 2'),
+    ...
+```
+
+- `product_code='default'` 是无差异基线；产品差异化按需插入 `product_code=<productCode>` 行（FindRule 会优先匹配精确 product，再 fallback 到 default）
+- `decline_type` 仅 `hard` / `soft`；运营后续可改 `reason_text` 但改不了 `decline_type`
+- 未 seed 的 raw_code 在运行时会触发 `ErrDeclineRuleNotConfigured` → 上层 fail-loud 为 Hard decline 并 alert 运营
+
+**最小 seed 集合**：从 provider 官方 decline code 文档提取 **最常见的 20-30 条**（full list 可能有 100+，但头部 20 覆盖 95% 流量）。
+
+---
+
+## 5. Wire DI 注册 Builder
+
+编辑 `backend/internal/platform/trade/payment/provider.go`：
+
+```go
+func ProvideGatewayBuilders() map[string]domain.GatewayBuilder {
+    return map[string]domain.GatewayBuilder{
+        "stripe":      stripe.Builder,
+        "paypal":      paypal.Builder,
+        "airwallex":   airwallex.Builder,
+        "apple_iap":   appleiap.Builder,
+        "google_play": googleplay.Builder,
+        "payssion":    payssion.Builder,
+        "{provider}":  {provider}.Builder,  // ← 新增一行
+    }
+}
+```
+
+然后：
+
+```bash
+cd backend
+make wire   # 重新生成 wire_gen.go
+go build ./...
+go vet ./...
+```
+
+---
+
+## 6. 契约测试 `contract_test.go` 加 provider 分支
+
+在 `CapabilityMatrix` 中声明该 provider 真实支持的 operation 与可选能力，并增加 builder runner。矩阵会同时验证：
+
+- adapter 可由最小合法配置构造；
+- `PaymentCreationGateway` / `PaymentConfirmationGateway` 与真实 PSP 流程一致；
+- 熔断装饰器不会丢失或伪造 capability；
+- IAP 类 provider 不会被误声明为服务端支付创建能力。
+
+```bash
+go test -tags contract -run TestContract ./internal/platform/trade/payment/infrastructure/gateway/...
+```
+
+---
+
+## 7. Staging 部署 + 真实小额测试
+
+1. 部署到 staging：`make docker-dev` 或既有 CI pipeline
+2. admin 登入 → `/commerce/payments/gateways/` → 确认新 provider row 展示
+3. 通过平台 CheckoutSession API 用 sandbox 支付方式发起真实 checkout：
+   - `ProviderCommand` 以 `create_payment` 执行且持久化唯一 PSP resource；
+   - PayKit 只消费版本化 `ProviderOperationPresentation`，不探测 provider 字段；
+   - 跳转或嵌入式 provider 流程使用 test card 成功；
+   - webhook 回调命中 `ParseWebhookEvent` 并与同一 PSP resource 收敛；
+   - DB 中 Payment、ProviderResource、ProviderCommand 与资金流水所有者一致。
+4. 测试 refund：调 admin 或 API 发 refund → provider 返回 success → DB 出现 refund row
+5. 测试 decline：用 `4000000000000002`（Stripe 测试 decline card）→ `ClassifyDecline` 命中 seeded rule → 记录 `expired_card` 或 `generic_decline` 决议
+
+---
+
+## 8. 上线检查清单
+
+- [ ] go build ./... 通过
+- [ ] go vet ./... 通过
+- [ ] make wire 重新生成无冲突
+- [ ] migration (`000XXX_payment_config_{provider}.up.sql`) 在 staging 执行成功
+- [ ] decline rules seed 覆盖该 provider 常见 code（最少 20 条）
+- [ ] admin UI 能看到并切换默认 gateway（若需要）
+- [ ] staging 完整 E2E：checkout → pay → webhook → DB truth → refund
+- [ ] `stripe/paypal/airwallex/payssion` 既有 provider 的 E2E 仍绿（零 regression）
+- [ ] Sentry / log 无新错误类型
+- [ ] decline rule 触发 `ErrDeclineRuleNotConfigured` 时告警链路可观测
+- [ ] 本 playbook 结尾的"已知陷阱"对新 provider 无遗漏
+
+---
+
+## 9. 已知陷阱
+
+| 陷阱 | 避免方式 |
+|------|---------|
+| Provider 返回的 webhook payload schema 升级 | `ParseWebhookEvent` 对未知字段宽容（json.RawMessage），失败时返回 `WebhookEventSkippedError` 而非 panic |
+| Idempotency key 长度超限 | 部分 provider 限制 40/64/255 字符，统一用 `internal/common/idempotency` helper 截断 |
+| Webhook 签名验证的 secret 和 checkout 用的 API key 不同 | provider config 分字段存储 `api_key` vs `webhook_secret` |
+| `decline_type` 分类错误导致金融事故 | 工程锁定字段只能 migration 改；admin UI 对 `decline_type` readonly（enforce in frontend + backend DTO） |
+| Stripe test-mode 有 100 req/s rate limit | 契约测试每 provider 加 `resilience.RateLimiter`（onex 已有），避免 CI 误触发限流 |
+| `productCode:provider` cache 未失效 | admin 改配置后必须调 `Factory.InvalidateCache(productCode)`；见 `p_config_payment_configs` 更新流 |
+| 新 provider decline_type 假设成"soft" fallback | 本 playbook 明确：未 seed 的 raw_code 进入 fail-loud Hard decline，不 fallback，避免过度重试 chargeback |
+| 新 provider 只实现基础 `PaymentGateway` | 客户在场支付必须额外实现 `PaymentCreationGateway`；否则产品政策启动校验失败 |
+
+---
+
+**维护**：本文档随新 provider 接入时追加陷阱；每次 breaking change（如 PaymentGateway 接口新增方法）必须同步更新 §2.1。

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

@@ -0,0 +1,191 @@
+# Platform Boundary Standards
+
+This document defines the binding responsibility split between OneX platform services, external product BFFs, APISIX, and product frontends.
+
+It is a current-state rules document, not a migration guide.
+
+## Final Boundary
+
+- Identity issuance and session lifecycle belong to `platform-api`.
+- The authenticated viewer projection belongs to `platform-api`.
+- Product business orchestration belongs to the product-owned BFF outside this repository.
+- APISIX performs routing and policy enforcement only.
+- Product-specific naming and presentation mapping belong to the product BFF or frontend, never to OneX platform modules.
+- OneX does not contain product BFF routes, product projections, or product frontend adapters.
+
+## Industry Alignment
+
+| Decision Point | Industry Pattern | Used By | OneX Choice | Rationale |
+| --- | --- | --- | --- | --- |
+| Login, registration, OAuth, refresh | Centralized identity service | OIDC providers, Auth0, Cognito, Keycloak | `platform-api` owns `/api/v1/auth/*` | Token issuance, revocation, credential linking, and OAuth state machines have one owner. |
+| Post-login bootstrap | Separate authenticated-user read model | OIDC UserInfo, GitHub authenticated-user bootstrap | `GET /api/v1/viewer` | Authentication responses remain security-focused while viewer carries post-auth state. |
+| Subscription identifiers | Raw billing identifiers, presentation mapped outside the billing control plane | Stripe subscriptions and prices | Viewer returns raw `tier_code`, `plan_code`, and `plan_name` | The platform cannot infer product marketing tiers. |
+| Frontend subscription status | Business-facing access state derived from provider lifecycle | Stripe-style access projection | Viewer exposes `active`, `canceled`, or `expired` | Product clients do not couple bootstrap to provider-specific lifecycle detail. |
+| Gateway responsibility | Routing, authentication, rate limiting, and header policy | AWS API Gateway, Kong, APISIX | APISIX routes and enforces edge policy only | Response composition belongs to the application owner. |
+
+## Binding Rules
+
+### 1. Auth Responses Return Credentials Only
+
+Allowed:
+
+```json
+{
+  "access_token": "...",
+  "refresh_token": "...",
+  "expires_in": 3600,
+  "token_type": "Bearer",
+  "is_new_user": false
+}
+```
+
+Auth responses must not contain credits, subscriptions, product pricing, feature flags, or a second response envelope.
+
+Clients authenticate first and then fetch viewer state. Anything beyond credentials belongs outside the authentication VO.
+
+### 2. Viewer Is the Authenticated Bootstrap Read Model
+
+Route:
+
+- `GET /api/v1/viewer?product_code=sample_product`
+
+Responsibilities:
+
+- return the current user identity projection;
+- return the product-context subscription projection;
+- return the product-context credit summary and buckets;
+- provide one stable bootstrap contract for authenticated product sessions.
+
+Forbidden:
+
+- client fan-out across user, credit, and subscription endpoints during bootstrap;
+- duplicate viewer aggregation in a product BFF;
+- gateway-side viewer response composition.
+
+An external product BFF may proxy this contract through its single public product origin, but it must not redefine or persist the platform projection.
+
+### 3. Viewer Subscription Contract Uses Raw Identifiers and Business Status
+
+```json
+{
+  "subscription": {
+    "tier_code": "premium",
+    "plan_id": 301,
+    "plan_code": "sample_product_pro_monthly",
+    "plan_name": "Sample Product Pro Monthly",
+    "status": "canceled",
+    "subscription_id": 101,
+    "current_period_end": "2026-04-30T10:00:00.000Z",
+    "next_renewal_at": "2026-05-01T10:00:00.000Z",
+    "cancel_at_period_end": true
+  }
+}
+```
+
+Rules:
+
+- `tier_code`, `plan_code`, and `plan_name` are raw platform identifiers.
+- `status` is one of `active`, `canceled`, or `expired`.
+- Raw provider status remains in the subscription domain and subscription APIs.
+- Detailed `system_status` remains in subscription-owned admin and internal contracts.
+- A user without an active paid subscription may have `tier_code="free"` and `status="expired"`.
+
+Mapping:
+
+- `system_status=active` and `cancel_at_period_end=false` => `active`
+- `system_status=active` and `cancel_at_period_end=true` => `canceled`
+- `system_status=grace_period` => `active`
+- `system_status=suspended` => `canceled`
+- `system_status=expired` => `expired`
+
+### 4. Viewer Credit Contract Uses Summary and Buckets
+
+```json
+{
+  "credits": {
+    "total_available": 1800,
+    "total_frozen": 200,
+    "unit": "credits",
+    "buckets": [
+      {
+        "grant_type_code": "subscription",
+        "available": 1200,
+        "unit": "credits"
+      },
+      {
+        "grant_type_code": "top_up",
+        "available": 500,
+        "unit": "credits"
+      },
+      {
+        "grant_type_code": "bonus",
+        "available": 100,
+        "unit": "credits"
+      }
+    ]
+  }
+}
+```
+
+Rules:
+
+- totals and buckets are scoped by the requested product context;
+- grant type codes are platform identifiers, not product marketing labels;
+- product clients may localize labels but must preserve the codes.
+
+### 5. Contracts Use Platform-Native Semantics
+
+Canonical names include:
+
+- `display_name`
+- `subscription.tier_code`
+- `subscription.plan_code`
+- `subscription.plan_name`
+- `subscription.status`
+- `credits.total_available`
+- `credits.total_frozen`
+- `credits.buckets[].grant_type_code`
+- `current_period_end`
+- `next_renewal_at`
+
+Product-facing copy may map these fields at the product boundary. OneX contracts must not introduce product-specific aliases or legacy response envelopes.
+
+### 6. Product BFFs Own Product Workflows, Not Platform Identity
+
+External product BFFs may own product workflows, product projections, product feed aggregation, and product-only operational views.
+
+They must not own token issuance, credential lifecycle, OAuth state, session revocation, or the canonical viewer projection.
+
+| Contract | Owner | Purpose |
+| --- | --- | --- |
+| `/api/v1/auth/*` | `platform-api` | Identity and session lifecycle |
+| `/api/v1/viewer` | `platform-api` | Authenticated bootstrap projection |
+| `/api/v1/users/me` | `platform-api` | Platform user profile |
+| Product business routes | External product BFF | Product workflow and presentation contracts |
+| OneX internal platform routes | Owning OneX platform module | BFF-to-platform capability calls |
+
+### 7. Product Frontends Use One Public Product Origin
+
+A product frontend configures one product API origin. APISIX may route platform-owned and BFF-owned paths behind that origin, but the frontend must not select infrastructure services by feature.
+
+Forbidden:
+
+- multiple public base URLs selected by feature;
+- direct coupling to OneX internal routes;
+- client-side re-wrapping of platform responses into legacy envelopes;
+- product label heuristics inside OneX control-plane contracts.
+
+### 8. Gateway Does Not Shape Response Objects
+
+APISIX owns host and path routing, authentication enforcement, rate limiting, CORS, and header policy.
+
+APISIX does not own viewer composition, authentication payload shaping, response envelopes, or product naming translation.
+
+## Review Checklist
+
+- Does an authentication endpoint return credentials only?
+- Does authenticated bootstrap reuse viewer instead of client fan-out?
+- Does every product workflow remain outside OneX product-neutral modules?
+- Does a new field use platform-native semantics?
+- Does the product frontend use one public product origin?
+- Does the gateway avoid response composition?

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

@@ -0,0 +1,112 @@
+# Quality Gate Standard
+
+> **Owner scope**: the OneX branch protection, platform governance audit, Admin checks and hook commands below describe the upstream platform gates. Product backend gates are the concrete targets in its own `Makefile`. This full reference does not assert that OneX CI jobs or Admin sources exist in a generated backend.
+
+> Mandatory engineering gates for local commits, pull requests, and main-branch protection.
+
+---
+
+## Industry Alignment
+
+| Decision Point | Industry Pattern | Used By | Our Choice | Rationale |
+| --- | --- | --- | --- | --- |
+| Main branch protection | Required status checks before merge | GitHub protected branches | Required CI jobs on `main` pull requests | Local hooks can be bypassed; CI is the authoritative merge gate. |
+| Local developer feedback | Git hooks for pre-commit and pre-push checks | Git client hooks | Versioned `.githooks` adapters | Fail fast before code leaves the workstation. |
+| Existing quality debt | Ratcheting baseline | SRE error-budget practice | Block new governance findings against the target branch baseline | Current debt can be burned down incrementally without allowing regressions. |
+| Cross-layer architecture | Dependency direction and package-boundary checks | OpenSSF Scorecard, golangci-lint | `platform-audit` architecture analyzer | Architecture rules must be executable, not only documented. |
+| Database index approval | Query-path-backed index review | PostgreSQL production tuning practice | Every new index must cite owning query path and index rationale | Indexes are write-amplifying storage contracts, not field-existence checkboxes. |
+
+---
+
+## Required Main-Branch Gates
+
+Pull requests targeting `main` must pass these required checks:
+
+- `Lint`
+- `Backend Governance Gate`
+- `Admin Typecheck`
+- `Build`
+- `Test`
+
+Repository branch protection must require the checks above before merge. Direct pushes to `main` are forbidden except for repository administrators performing incident recovery.
+
+---
+
+## Local Hook Gates
+
+Versioned hooks live under `.githooks`.
+
+```bash
+scripts/install-git-hooks.sh
+```
+
+The hook contract is:
+
+| Hook | Command | Purpose |
+| --- | --- | --- |
+| `pre-commit` | `cd backend && make pre-commit` | Static contract checks, migration sequence check, index evidence check, platform governance audit. |
+| `pre-push` | `cd backend && make pre-push` | All pre-commit gates plus `go test ./...`. |
+
+Local hooks are advisory acceleration. The CI checks above are the authoritative merge gate.
+
+---
+
+## Governance Ratchet
+
+`backend/scripts/governance-gate.sh` compares the generated platform audit report with the target branch report.
+
+Rules:
+
+1. A pull request may reduce findings.
+2. A pull request may keep the same finding count while changing unrelated code.
+3. A pull request must not increase findings by severity and code.
+4. `backend/internal/platform/datagovernance/auditdata/platform-audit.json` must match the generated report counts.
+5. Once a finding class reaches zero, it must remain zero.
+
+The embedded report includes schema, API, write-audit, and architecture findings. Architecture findings cover backend import direction and admin API/query/view ownership boundaries.
+
+When all existing findings are eliminated, CI must set:
+
+```bash
+GOVERNANCE_STRICT_ZERO=1
+```
+
+Strict mode rejects any governance finding.
+
+---
+
+## Index Evidence Gate
+
+Every new `CREATE INDEX` in migration `000683` and later must carry both comments immediately above the statement:
+
+```sql
+-- 查询路径：<owning repository/service path and operation>
+-- 索引理由：<equality filters, range/sort column, uniqueness or investigation path>
+CREATE INDEX ...
+```
+
+The evidence must name a real business query path. It is invalid to justify an index only because a table contains `product_code`, `deleted_at`, `status`, or another common column.
+
+Reviewer checklist:
+
+1. Verify the named repository or service actually executes the query.
+2. Verify left-prefix order matches equality filters before range or sort fields.
+3. Verify partial-index predicates match the query predicate exactly.
+4. Verify write amplification is acceptable for the table write volume.
+5. Verify an exact-match runtime dedupe lookup has a matching unique index.
+
+---
+
+## Required Commands
+
+```bash
+cd backend
+make pre-commit
+make pre-push
+make governance-audit
+
+cd ../admin
+pnpm run check:type
+```
+
+CI runs `bash scripts/governance-gate.sh --mode ci` and must use full git history so the target branch baseline is available.

package/dist/resources/templates/go-backend/.dockerignore

@@ -0,0 +1,6 @@
+.git
+.env
+.env.*
+bin
+coverage.*
+node_modules

package/dist/resources/templates/go-backend/.env.example

@@ -0,0 +1,13 @@
+APP_ENV=local
+APP_NAME={{projectName}}-api
+APP_HOST=127.0.0.1
+APP_PORT=3100
+DATABASE_HOST=localhost
+DATABASE_PORT=5432
+DATABASE_USERNAME={{projectName}}
+DATABASE_NAME={{projectName}}
+DATABASE_PASSWORD=
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=
+DATABASE_URL=

package/dist/resources/templates/go-backend/.gitattributes

@@ -0,0 +1,2 @@
+# Preserve upstream vendored bundles byte-for-byte.
+internal/core/apidocs/assets/scalar-api-reference.js -whitespace linguist-vendored