> 幫我找一下訂單超時退款的邏輯在哪

● 我先看一下項目結(jié)構(gòu)
  └─ Bash(ls -la services/)

● 看起來訂單相關(guān)在 services/order/，先 grep 一下關(guān)鍵詞
  └─ Grep("refund|timeout", path: "services/order", output_mode: "files_with_matches")

● 命中 3 個文件，重點看 refund_handler.go
  └─ Read("services/order/internal/refund/refund_handler.go", offset: 1, limit: 80)

● 這里調(diào)用了 TimeoutPolicy.shouldRefund，跳過去看定義
  └─ Grep("func.*shouldRefund", path: "services/order")

# 項目概覽

這是一個電商平臺的 monorepo，約 80 萬行代碼，模塊如下：

- /services/payment   - 支付服務（Java 17 + Spring Boot 3.x）
- /services/inventory - 庫存服務（Go 1.22）
- /services/order     - 訂單服務（Go 1.22）
- /frontend           - React 18 + Vite + TypeScript
- /infra              - Terraform + Helm
- /docs               - 架構(gòu)與 API 文檔

詳細模塊約定見各目錄下的 CLAUDE.md。

# 全局硬性約定

- 所有對外 API 的變更必須同步更新 `/docs/api-changelog.md`，未更新視為不完整
- 數(shù)據(jù)庫遷移文件放在 `/migrations`，命名格式：`YYYYMMDD_HHmm_描述.sql`
- 禁止直接修改 `/generated` 目錄下的文件（由 buf/protoc 生成）
- 提交前必須本地通過 `make precommit`
- 任何新增依賴需要在 PR 描述里寫明引入理由

# 常用命令

| 場景 | 命令 | 說明 |
|------|------|------|
| 日常單元測試 | `make test-unit` | 約 1 分鐘 |
| 完整測試 | `make test` | 約 20 分鐘，CI 才跑 |
| 啟動本地環(huán)境 | `make dev` | 依賴 Docker Desktop |
| 類型 + lint 檢查 | `make check` | 提交前必跑 |

# 不要做的事

- 不要在 `/services/payment` 里寫新功能時跑全量測試，單跑該模塊即可
- 不要在 PR 里同時混入格式化變更與邏輯變更
- 不要把環(huán)境變量寫進代碼，統(tǒng)一在 `infra/env/` 配置

# /services/payment

## 技術(shù)棧
- Java 17，Spring Boot 3.2.x，Gradle 8
- 數(shù)據(jù)庫：PostgreSQL 15（主）+ Redis 7（限流/冪等）

## 測試與構(gòu)建
- 本模塊測試：`./gradlew :payment:test`
- 集成測試需要 docker-compose：`make payment-it`
- 構(gòu)建產(chǎn)物：`./gradlew :payment:bootJar`

## 關(guān)鍵文件
- `PaymentProcessor.java` —— 入口，**線程安全要求**，修改前必讀類頭注釋
- `gateway/` —— 各支付渠道適配，新增渠道走 `GatewayAdapter` 接口
- `idempotency/` —— 冪等鍵存儲，禁止繞過

## 常見任務索引
- 新增支付渠道：參考 `docs/add-gateway.md`
- 修改對賬邏輯：必須同時更新 `tests/reconciliation/`

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "if [[ \"$CLAUDE_FILE_PATH\" =~ \\.(ts|tsx|js|jsx)$ ]]; then npx prettier --write \"$CLAUDE_FILE_PATH\" && npx eslint --fix \"$CLAUDE_FILE_PATH\"; fi"
          },
          {
            "type": "command",
            "command": "if [[ \"$CLAUDE_FILE_PATH\" =~ \\.go$ ]]; then gofmt -w \"$CLAUDE_FILE_PATH\" && goimports -w \"$CLAUDE_FILE_PATH\"; fi"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/guard-bash.sh"
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# 攔截高危命令：rm -rf /、生產(chǎn)數(shù)據(jù)庫連接、force push 到 main
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // ""')

if echo "$CMD" | grep -qE '(rm\s+-rf\s+/|drop\s+database|--force.*origin/main)'; then
  echo '{"decision":"block","reason":"危險命令已攔截，請人工確認后再執(zhí)行"}'
  exit 0
fi

if echo "$CMD" | grep -qE 'psql.*prod|kubectl.*-n\s+production'; then
  echo '{"decision":"ask","reason":"該命令會接觸生產(chǎn)環(huán)境，請確認意圖"}'
  exit 0
fi

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/session-reflect.sh"
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# 會話結(jié)束時，讓 Claude 自己反思有沒有值得沉淀到 CLAUDE.md 的東西
SESSION_DIR="${CLAUDE_PROJECT_DIR}/.claude/sessions"
mkdir -p "$SESSION_DIR"

cat <<'PROMPT' > "$SESSION_DIR/reflect-prompt.md"
回顧這次會話：
1. 我有沒有走過彎路？是因為缺少哪條上下文？
2. 哪些用戶的糾正應該寫進 CLAUDE.md 讓以后不再犯？
3. 是否發(fā)現(xiàn)了應該寫成 Skill 的可復用模式？

請生成 patch 建議，不要直接修改文件。
PROMPT

# 觸發(fā)一次獨立 Claude 進程做反思，寫到 inbox 等人 review
claude -p "$(cat $SESSION_DIR/reflect-prompt.md)" \
  --output-format json \
  > "$SESSION_DIR/$(date +%Y%m%d-%H%M%S).reflection.json"

.claude/skills/payment-gateway-onboarding/
├── SKILL.md              # 入口文件，含 frontmatter
├── checklist.md          # 接入新支付渠道的 30 項檢查清單
├── templates/
│   ├── adapter.java.tmpl # 適配器模板
│   └── test.java.tmpl    # 測試模板
└── references/
    └── compliance.md     # PCI-DSS 合規(guī)要點（按需讀?。?

---
name: payment-gateway-onboarding
description: 接入新的第三方支付渠道（Stripe / Adyen / 支付寶 / 微信支付等）。當用戶提到"接入支付"、"新增 gateway"、"對接 XX 支付"時使用。
allowed-paths:
  - services/payment/**
---

# 接入新支付渠道

## 第一步：確認信息齊全
在動手前，確認拿到了以下材料（缺一不可）：
- [ ] 渠道方的 API 文檔與沙箱環(huán)境憑證
- [ ] 商戶號 / appid（生產(chǎn) + 沙箱）
- [ ] 回調(diào)簽名算法與公私鑰
- [ ] 合規(guī)備案文檔（見 `references/compliance.md`）

## 第二步：生成骨架
基于 `templates/adapter.java.tmpl` 創(chuàng)建新文件：
`services/payment/src/main/java/.../gateway/<channel>/<Channel>Adapter.java`

## 第三步：實現(xiàn) GatewayAdapter 接口
必須實現(xiàn)：`charge`, `refund`, `query`, `verifyCallback`。
冪等鍵統(tǒng)一走 `IdempotencyService`，不要自己造輪子。

## 第四步：測試矩陣
按 `checklist.md` 跑完 30 項檢查，缺一項不允許合并。

.claude/skills/
├── security-review/             # 安全審查清單
├── payment-gateway-onboarding/  # 新增支付渠道
├── db-migration/                # 數(shù)據(jù)庫遷移規(guī)范
├── api-changelog/               # API 變更自動更新 changelog
├── incident-postmortem/         # 事故復盤模板
└── frontend-component-new/      # 新增前端組件

acme-platform-plugin/
├── plugin.json                  # 清單
├── skills/
│   ├── deploy-to-staging/
│   └── internal-rpc-client/
├── hooks/
│   ├── settings.json
│   └── scripts/
│       └── jira-link.sh
└── mcp/
    └── servers.json             # 內(nèi)部 analytics / Jira / Confluence MCP

{
  "name": "acme-platform",
  "version": "1.4.2",
  "description": "Acme 內(nèi)部 Claude Code 配置：部署、Jira、內(nèi)部 RPC 工具集",
  "skills": ["./skills/deploy-to-staging", "./skills/internal-rpc-client"],
  "hooks": "./hooks/settings.json",
  "mcp": "./mcp/servers.json",
  "minimum-claude-code": "1.0.0"
}

claude plugin install git@github.acme.com:devplatform/claude-code-plugin.git

// .claude/settings.json
{
  "lsp": {
    "servers": {
      "typescript": {
        "command": "typescript-language-server",
        "args": ["--stdio"],
        "rootMarkers": ["package.json", "tsconfig.json"]
      },
      "go": {
        "command": "gopls",
        "args": ["serve"],
        "rootMarkers": ["go.mod"]
      },
      "java": {
        "command": "jdtls",
        "rootMarkers": ["pom.xml", "build.gradle"]
      },
      "cpp": {
        "command": "clangd",
        "args": ["--background-index", "--clang-tidy"],
        "rootMarkers": ["compile_commands.json"]
      }
    }
  }
}

# 沒 LSP：grep 找 ProcessOrder 的定義
$ grep -rn "ProcessOrder" .
找到 437 處匹配
→ Claude 需要打開 N 個文件來確定真正的定義

# 有 LSP：goToDefinition
→ 一次調(diào)用直接返回 services/order/internal/processor.go:42
→ 上下文消耗：1 個文件

// .claude/mcp.json
{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@acme/mcp-jira"],
      "env": {
        "JIRA_BASE_URL": "https://acme.atlassian.net",
        "JIRA_TOKEN": "${JIRA_TOKEN}"
      }
    },
    "internal-docs": {
      "command": "node",
      "args": ["./tools/mcp/confluence-server.js"],
      "env": {
        "CONFLUENCE_SPACE": "ENG"
      }
    },
    "code-search": {
      "command": "./tools/mcp/sourcegraph-server",
      "env": {
        "SG_ENDPOINT": "https://sg.internal.acme.com"
      }
    }
  }
}

# 反例：在倉庫根目錄，讓它修支付服務的 bug
cd ~/work/acme-monorepo
claude
# → 加載根 CLAUDE.md，但本地上下文還是倉庫根，開搜會掃到很多無關(guān)目錄

# 正解：直接進子目錄
cd ~/work/acme-monorepo/services/payment
claude
# → 既加載了根 CLAUDE.md，又加載了 services/payment/CLAUDE.md
# → 命令、測試范圍都自動收斂到本服務

# /services/inventory/CLAUDE.md

## 命令

- 單元測試：`go test ./...`（只跑本服務，約 30 秒）
- 集成測試：`make inventory-it`（依賴 docker-compose，約 3 分鐘）
- 構(gòu)建：`go build ./cmd/server`
- Lint：`golangci-lint run ./...`

?? 不要在本目錄下跑 `make test`（那是全量測試，20 分鐘，會超時）。

// .claude/settings.json
{
  "permissions": {
    "deny": [
      "Read(/generated/**)",
      "Read(/node_modules/**)",
      "Read(/build/**)",
      "Read(/.next/**)",
      "Read(/dist/**)",
      "Read(/vendor/**)",
      "Read(/**/*.min.js)",
      "Read(/**/*.lock)"
    ],
    "ask": [
      "Bash(git push:*)",
      "Bash(rm -rf:*)",
      "Bash(kubectl:*)"
    ]
  }
}

# 代碼庫結(jié)構(gòu)地圖

## 一級目錄
- `/core`           核心業(yè)務邏輯（Java，約 30 萬行）
- `/adapters`       外部系統(tǒng)適配器（按渠道分子目錄）
- `/legacy-billing` 舊版計費系統(tǒng)（PHP，**只讀**，2026Q4 下線）
- `/tools`          內(nèi)部開發(fā)工具，CI 也依賴
- `/docs`           技術(shù)文檔（ADR + API 規(guī)范）

## 重要入口
- HTTP 入口：`core/src/main/java/.../HttpServer.java`
- 定時任務：`core/src/main/java/.../jobs/JobScheduler.java`
- 配置加載：`core/config/` + 環(huán)境變量見 `infra/env/`

## 歷史包袱
- `core/util/Helpers.java` —— 4000 行的"什么都往里塞"工具類，要拆但還沒拆
- `adapters/legacy-mq/` —— 已停用但還沒刪，觸發(fā)別影響

# .claude/skills/config-audit/SKILL.md
---
name: config-audit
description: 季度性審查 CLAUDE.md，識別可以刪除或遷移到 hook 的規(guī)則
---
按以下步驟逐條審查：
1. 讀取所有 CLAUDE.md（根 + 各子目錄）
2. 對每條規(guī)則打三個標簽：[必要 | 可移除 | 可移到 hook]
3. 生成 diff 提案到 `.claude/audit-YYYY-MM.md`，不直接改文件
4. 郵件 / Slack 通知 DRI review

> 我要把項目里的 log4j 全部替換為 slog，先幫我摸清現(xiàn)狀

● 我先派一個只讀 subagent 去做完整調(diào)研，結(jié)果寫到文件，然后我基于結(jié)果做改動。

● Task(subagent_type: "explore", description: "調(diào)研 log4j 使用")
  Prompt:
    遍歷整個倉庫，找出所有 log4j 的使用方式。生成報告到 .claude/scratch/log4j-usage.md，
    包含：
    1. 所有 import log4j 的文件路徑
    2. 按使用模式分類（直接 logger.info / 包裝類 / 自定義 Appender）
    3. 特殊用法清單（異步 logger、MDC、自定義格式）
    不要做任何修改。

● [subagent 干完，返回報告路徑]

● 現(xiàn)在我讀這份報告，制定遷移計劃
  └─ Read(".claude/scratch/log4j-usage.md")

> 改完后幫我跑三組驗證

● 并行啟動三個 subagent：
  Task(subagent_type: "test-engineer", "跑所有 log 相關(guān)單元測試")
  Task(subagent_type: "security-reviewer", "確認 slog 配置沒泄漏 PII")
  Task(subagent_type: "verifier", "對照遷移清單逐項核對")