From 110a16b19f33630a5b6a59b75c0721aa535df5ec Mon Sep 17 00:00:00 2001
From: Your Name <your.email@example.com>
Date: Wed, 6 May 2026 12:42:45 +0800
Subject: [PATCH] docs(repo): align local verification with shared test db

---
 CONTRIBUTING.md | 10 ++++++++--
 README.md       | 12 +++++++-----
 2 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ec0e529..33be0c7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -7,11 +7,17 @@
 在提交 PR 前，至少完成以下验证：
 
 ```bash
-go test ./... -count=1
-go test -race ./...
+go test ./... -count=1 -p 1
+go test -race ./... -p 1
 go vet ./...
 ```
 
+说明：
+
+- 当前默认本地测试库是共享的 PostgreSQL `localhost:5434/ai_customer_service`
+- 为避免跨包并发测试互相污染测试表，默认使用 `-p 1` 串行执行 Go 测试
+- 如果后续切到隔离测试库或每包独立数据库，再考虑恢复并发
+
 如果改动涉及生产门禁、回滚、平台适配或配置契约，还要补跑对应脚本或最小验证：
 
 ```bash
diff --git a/README.md b/README.md
index 0a6f24a..aaca3d8 100644
--- a/README.md
+++ b/README.md
@@ -54,8 +54,8 @@ cp .env.platform-adapters.example .env.platform-adapters.local
 ```bash
 make test
 make run
-go test ./... -count=1
-go test -race ./...
+go test ./... -count=1 -p 1
+go test -race ./... -p 1
 go vet ./...
 ```
 
@@ -110,8 +110,8 @@ go vet ./...
 
 当前推荐的验证顺序：
 
-1. `go test ./... -count=1`
-2. `go test -race ./...`
+1. `go test ./... -count=1 -p 1`
+2. `go test -race ./... -p 1`
 3. `go vet ./...`
 4. `bash -n scripts/verify_preprod_gate_b.sh`
 5. `bash -n scripts/verify_gate_c_rollback.sh`
@@ -127,8 +127,10 @@ go vet ./...
 - 提交使用 Conventional Commits
 - 仓库审阅归属见 [.github/CODEOWNERS](.github/CODEOWNERS)
 - PR 会自动执行基础 CI：
-  `go test ./... -count=1`、`go test -race ./...`、`go vet ./...`、Gate 脚本语法检查
+  GitHub 执行 `go test ./... -count=1`、`go test -race ./...`、`go vet ./...`、Gate 脚本语法检查；
+  Gitea/TKSea 因共享测试库约束，执行 `go test ./... -count=1 -p 1`、`go test -race ./... -p 1`、`go vet ./...`、Gate 脚本语法检查
 - GitHub 使用 [`.github/workflows/ci.yml`](.github/workflows/ci.yml)，Gitea/TKSea 使用 [`.gitea/workflows/ci.yml`](.gitea/workflows/ci.yml)
+- 本地默认共享 PostgreSQL 测试库，所以本地验证命令统一使用 `-p 1` 串行执行，避免跨包并发污染测试表
 - 变更配置契约时，必须同步更新：
   - `docs/CONFIG_CONTRACT_BASELINE.md`
   - `test/QA_GATE_STATUS.md`