// AI 经常写出来的三种"吞错误"
data, _ := json.Marshal(req)        // 忽略 err
resp, err := http.Get(url)
defer resp.Body.Close()             // resp 可能是 nil，err 没判先 defer
if err != nil { panic(err) }        // 在库代码里 panic，等于埋雷

// 典型翻车：闭包里并发写同一个 map
results := map[string]int{}
for _, id := range ids {
    go func(id string) {
        results[id] = fetch(id)   // data race！map 并发写直接 panic 或脏数据
    }(id)
}
// 还少了 WaitGroup，主协程根本没等它们完成

# 列出所有未按 gofmt 格式化的文件；非空就让 CI 失败
test -z "$(gofmt -l .)"

go test -race ./...

go test -race -coverprofile=cover.out ./...
go tool cover -func=cover.out | tail -1   # 看 total 覆盖率

.PHONY: verify
verify:
    test -z "$$(gofmt -l .)"     # 格式
    go vet ./...                  # 基础静态
    go build ./...                # 幻觉 API/依赖必死
    go test -race -cover ./...    # 竞态 + 覆盖率

# AGENTS.md — order-service (Go)

## 系统地图
- cmd/server      程序入口，只做装配，不写业务
- internal/order  订单域：下单、查询
- internal/refund 退款域：本次要改的就是这块
- internal/platform  基础设施：db、kafka、http client 封装

## 必须遵守的约定（踩过坑的）
1. 错误一律 fmt.Errorf("...: %w", err) 往上包，禁止吞错（不许 _ = err）。
2. 库代码禁止 panic；panic 只允许出现在 main/初始化的"起不来就该死"场景。
3. 所有对外调用（DB/HTTP/Kafka）第一个参数必须是 context.Context，并真正传下去。
4. 并发写共享状态必须加锁或用 channel；每个 goroutine 必须有明确的退出路径。
5. 金额用 int64 以"分"为单位，禁止 float64。
6. 能用标准库就别加依赖；加任何第三方包要在 PR 里说明理由。
7. 跨域只能 import 对方的接口包，禁止 import 对方的 internal 实现。

## 标准样板
改写链路前先读 internal/refund/service.go 的 Refund()，照这个结构来：
入参带 ctx → 校验 → 业务 → 落库 → 发消息，每步错误都 %w 包好。

order-service/
├── cmd/server/         # 入口
└── internal/
    ├── order/          # 订单域
    ├── refund/         # 退款域（本次要改）
    │   ├── api/        # HTTP handler
    │   ├── service/    # 业务
    │   └── store/      # DB 访问
    └── fulfillment/    # 履约域：退款只能通过接口通知它

# .golangci.yml 片段（depguard 配置在不同版本语法略有差异，按你的版本微调）
linters-settings:
  depguard:
    rules:
      refund-domain:
        files:
          - "**/internal/refund/**"
        deny:
          - pkg: "order-service/internal/fulfillment/store"
            desc: "退款域不许直连履约实现，只能走 fulfillment 的接口"
      service-layer:
        files:
          - "**/internal/*/service/**"
        deny:
          - pkg: "net/http"
            desc: "service 层不许碰 http，HTTP 细节留在 api 层"

# .go-arch-lint.yml（示意，按工具版本调整）
version: 3
workdir: internal
components:
  api:     { in: "*/api" }
  service: { in: "*/service" }
  store:   { in: "*/store" }
deps:
  api:     { mayDependOn: [service] }
  service: { mayDependOn: [store] }
  store:   { mayDependOn: [] }          # store 不许反向依赖

func TestRefund(t *testing.T) {
    tests := []struct {
        name    string
        order   Order
        amount  int64
        wantErr error
    }{
        {"全额退款成功", paidOrder(100_00), 100_00, nil},
        {"未支付订单不可退", unpaidOrder(), 100_00, ErrNotRefundable},
        {"退款额超过可退额", paidOrder(100_00), 200_00, ErrAmountExceeded},
        {"重复退款应幂等", refundedOrder(100_00), 100_00, ErrAlreadyRefunded},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            svc := newRefundService(tt.order)
            err := svc.Refund(context.Background(), tt.amount)
            if !errors.Is(err, tt.wantErr) { // 注意 errors.Is，配合 %w 才管用
                t.Fatalf("Refund() err = %v, want %v", err, tt.wantErr)
            }
        })
    }
}

func TestRefundHandler(t *testing.T) {
    body := strings.NewReader(`{"amount":10000}`)
    req := httptest.NewRequest(http.MethodPost, "/orders/1001/refund", body)
    rec := httptest.NewRecorder()

    newRouter(stubRefundService{}).ServeHTTP(rec, req)

    if rec.Code != http.StatusOK {
        t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
    }
}

# refund.feature
场景: 重复收到退款消息时不能退两次
  假如 订单 1001 已经退款成功
  当 系统再次收到订单 1001 的退款消息
  那么 不应再发起一次退款
  并且 账户余额保持不变

# .golangci.yml（最小可用版，linter 名称按你的版本核对）
run:
  timeout: 5m
linters:
  enable:
    - errcheck       # 没处理的 error 直接报错 —— 治"吞错误"
    - errorlint      # 强制正确用 %w / errors.Is
    - govet          # 基础静态
    - staticcheck    # 强大的静态分析
    - gosec          # 安全扫描
    - bodyclose      # http resp.Body 忘了 Close
    - sqlclosecheck  # sql.Rows 忘了 Close
    - noctx          # 发请求没带 context
    - contextcheck   # context 没一路传下去
    - depguard       # 依赖 / 分层约束（见上）
    - revive         # 风格 / 命名约定

# Makefile —— 把前面的方法串成可执行的闸门
COVER_MIN ?= 70          # 覆盖率阈值
NEW_FROM  ?= origin/main  # 老项目增量 lint 的基线

.DEFAULT_GOAL := verify

# ---- 第一步：拧紧白送的那半套 ----
fmt:                       ## 检查 gofmt，有未格式化文件就失败
    @u="$$(gofmt -l .)"; [ -z "$$u" ] || { echo "未格式化: $$u"; exit 1; }

vet:                       ## 基础静态检查
    go vet ./...

build:                     ## 全量编译，幻觉 API/缺失依赖必死
    go build ./...

tidy-check:                ## go.mod/go.sum 不许被偷偷改，揪出多余依赖
    go mod tidy
    @git diff --exit-code go.mod go.sum

test:                      ## 竞态检测 + 生成覆盖率
    go test -race -coverprofile=cover.out -covermode=atomic ./...

cover: test                ## 覆盖率低于阈值就失败
    @t=$$(go tool cover -func=cover.out | awk '/^total:/{gsub(/%/,"",$$3);print $$3}'); \
    echo "coverage: $$t%"; \
    awk -v t="$$t" -v m="$(COVER_MIN)" 'BEGIN{exit (t+0<m+0)}' || \
        { echo "覆盖率 $$t% 低于 $(COVER_MIN)%"; exit 1; }

# ---- 第二步：补缺的那半套 ----
lint:                      ## golangci-lint 总闸门
    golangci-lint run

lint-new:                  ## 老项目只拦新增违规
    golangci-lint run --new-from-rev=$(NEW_FROM)

arch:                      ## 架构/分层边界校验
    go run github.com/fe3dback/go-arch-lint@latest check

# ---- 聚合闸门：CI 直接调它 ----
verify: fmt vet build tidy-check lint arch cover  ## 合并前过一遍
    @echo "all checks passed"

verify-new: fmt vet build tidy-check lint-new arch cover  ## 老项目专用

.PHONY: fmt vet build tidy-check test cover lint lint-new arch verify verify-new

# .github/workflows/verify.yml
name: verify
on: [push, pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with: { go-version: '1.22' }
      - run: go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
      - run: make verify

# .github/workflows/verify.yml
name: verify
on: [push, pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with: { go-version: '1.22' }

      - name: 格式
        run: test -z "$(gofmt -l .)"

      - name: 依赖没被偷偷改
        run: go mod tidy && git diff --exit-code go.mod go.sum

      - name: 编译（幻觉 API 必死）
        run: go build ./...

      - name: 静态 + 安全 + 依赖约束
        uses: golangci/golangci-lint-action@v6

      - name: 竞态 + 覆盖率
        run: go test -race -cover ./...

      - name: 架构边界
        run: go run github.com/fe3dback/go-arch-lint@latest check

@startmindmap
* Go 服务的 AI harness
** 为什么好伺候
*** 工具链白送半套
*** gofmt/vet/race/cover 开箱即用
*** 白送≠拧紧
** AI 爱翻的三块
*** 吞错误/丢错误链
*** 并发竞态/goroutine 泄漏
*** 幻觉依赖/幻觉 API
*** (顺带) 破坏 internal 边界
** 第一步 拧紧白送的
*** gofmt -l 格式
*** go vet 静态
*** go build 治幻觉API
*** go test -race 竞态
*** go test -cover 覆盖率
** 第二步 补缺的半套
*** AGENTS.md 上下文
*** internal + depguard 边界
*** SDD + 表驱动测试
*** godog 行为契约
*** golangci-lint 总闸门
** 落地顺序
*** 1 拧紧白送
*** 2 golangci-lint
*** 3 AGENTS.md
*** 4 internal 边界
*** 5 SDD+表驱动
*** 6 godog 补业务
@endmindmap

# AGENTS.md — order-service

Go 后端服务，负责订单与退款。人看的总览在 README.md；
深层架构与 runbook 在 man/ 和 docs/adr/，本文件不复述，只给链接。

## Context Map
- `cmd/server/` — 程序入口，只做装配，禁止写业务逻辑
- `internal/order/` — 订单域：下单、查询
- `internal/refund/` — 退款域：`api/`（HTTP）、`service/`（业务）、`store/`（DB）
- `internal/fulfillment/` — 履约域：退款只能通过其接口通知，禁止直连实现
- `internal/platform/` — 基础设施：db、kafka、http client 封装
- 深入阅读：架构见 `man/index.md`，关键决策见 `docs/adr/`

## Commands
- 拉依赖：`go mod download`
- 构建：`make build`（= `go build ./...`，幻觉 API/缺依赖必死）
- 测试：`make test`（= `go test -race -cover ./...`）
- 静态/安全/依赖闸门：`make lint`（= `golangci-lint run`）
- 提交前全量闸门：`make verify`
- 跑单个测试：`go test -race -run TestRefund ./internal/refund/...`

## Harness Rules
- 不许编造：不臆造包、函数、文件、命令或运行结果；不确定就说不确定。
- 重大歧义先问：当某个选择会改变行为/接口/数据时，先问再写。
- 先想后写：多步改动先说清假设和简短计划。
- 简单优先：用解决问题的最小代码，不做没要求的抽象与配置项。
- 外科手术式改动：只动任务需要的地方，沿用现有风格，不顺手重构无关代码。
- 完工先自证：跑 `make verify` 并报告结果；没绿不许声称"做完了"。

## Project Rules（Go 专属，踩过坑的）
- 错误：一律 `fmt.Errorf("...: %w", err)` 往上包；禁止 `_ = err`。库代码禁止 `panic`（只允许 main/init）。
- context：所有 DB/HTTP/Kafka 调用第一参数必须是 `ctx context.Context`，且真正传下去。
- 并发：共享状态必须加锁或走 channel；每个 goroutine 必须有退出路径。测试一律 `-race` 跑。
- 金额：`int64` 以"分"为单位，禁止 `float64`。
- 依赖：能用标准库就别加第三方；新增依赖需在 PR 说明理由。改完跑 `go mod tidy`，`go.mod`/`go.sum` 的 diff 必须是有意的。
- 边界：跨域只走接口，禁止 import 别的域的 `store`/内部实现；由 depguard 强制。
- 分层：HTTP 细节留在 `api`，业务在 `service`，DB 在 `store`；`service` 不许 import `net/http`。
- 日志：用结构化日志；禁止打手机号/身份证/卡号等 PII。

## 标准样板
改写链路前先读 `internal/refund/service.go` 的 `Refund()`，照它的结构来：
入参带 `ctx` → 校验 → 业务 → 落库 → 发消息，每步错误都 `%w` 包好。

## AI Tooling
- 主要面向：Codex / Claude Code / Cursor。
- Cursor 规则放在 `.cursor/rules/`。
- 可选：把 `CLAUDE.md`、`GEMINI.md` 软链到本文件（`ln -s AGENTS.md CLAUDE.md`）。

## Keeping Current
- 触发更新：新增域/包、命令变化、或出现需要新护栏的 AI 反复犯错时。
- 学习闭环：同一个问题纠正 AI 两次以上，就在这里加一条规则；同时删掉过时规则，保持文件短到能读完。

# .golangci.yml — order-service
run:
  timeout: 5m
  tests: true            # 测试文件也检查

linters:
  # 不用默认集，显式开启，避免版本升级时行为漂移
  disable-all: true
  enable:
    - errcheck       # 没处理的 error 直接报错 —— 治"吞错误"
    - errorlint      # 强制正确用 %w / errors.Is / errors.As
    - govet          # 基础静态检查
    - staticcheck    # 强大的静态分析
    - ineffassign    # 无效赋值
    - unused         # 未使用的代码
    - gosec          # 安全扫描
    - bodyclose      # http resp.Body 忘了 Close
    - sqlclosecheck  # sql.Rows/Stmt 忘了 Close
    - rowserrcheck   # 忘了检查 rows.Err()
    - noctx          # 发 HTTP 请求没带 context
    - contextcheck   # context 没一路传下去
    - depguard       # 依赖 / 分层约束
    - gocritic       # 一批有用的代码风格/性能检查
    - revive         # 可配置的风格 / 命名约定
    - misspell       # 拼写错误

linters-settings:
  errcheck:
    check-type-assertions: true   # v, ok := x.(T) 也要检查
    check-blank: true             # 禁止用 _ 吞掉 error

  govet:
    enable-all: true
    disable:
      - fieldalignment            # 结构体字段对齐太吵，关掉

  gosec:
    excludes:
      - G104                      # 和 errcheck 重复，避免双重报错

  revive:
    rules:
      - name: error-return        # error 必须是最后一个返回值
      - name: error-naming        # error 变量命名规范
      - name: context-as-argument # context 必须是第一个参数
      - name: unreachable-code

  depguard:
    rules:
      # 退款域不许直连履约实现，只能走接口
      refund-domain:
        files:
          - "**/internal/refund/**"
        deny:
          - pkg: "order-service/internal/fulfillment/store"
            desc: "退款域不许直连履约实现，只能走 fulfillment 的对外接口"
      # service 层不许碰 HTTP，HTTP 细节留在 api 层
      service-layer:
        files:
          - "**/internal/*/service/**"
        deny:
          - pkg: "net/http"
            desc: "service 层不许依赖 net/http，HTTP 处理留在 api 层"
      # 全局禁用项：金额禁用浮点、日期统一用 time
      global:
        deny:
          - pkg: "math/big"
            desc: "金额请用 int64（分），不要引入 big 计算"

issues:
  max-issues-per-linter: 0        # 不限制，全部暴露
  max-same-issues: 0
  exclude-rules:
    # 测试文件放宽：允许忽略错误、允许 gosec 的部分告警
    - path: _test\.go
      linters:
        - errcheck
        - gosec
        - bodyclose
  # 老项目落地用：只拦相对基线的新增违规，老债先冻住
  # 命令行用 golangci-lint run --new-from-rev=origin/main 也可，二选一
  # new-from-rev: origin/main