diff --git a/README.md b/README.md
index 69dc81b..ba50268 100644
--- a/README.md
+++ b/README.md
@@ -55,6 +55,26 @@ docker build -t ez-api .
 docker run -p 8080:8080 --env-file .env ez-api
 ```
 
+### 本地联合开发（配合 balancer）
+
+- 目录结构建议：`/workspace/` 下并列放置 `ez-api` 与 `balancer`。
+- 初始化/更新 Go 工作区（Go 1.20+）：在 `/workspace` 执行
+  ```bash
+  go work use ./ez-api ./ez-api/test ./balancer
+  ```
+  仓库已附带 `go.work`，若路径一致可直接复用；若放在其他位置请按上面命令重建。
+
+### 集成测试
+
+依赖 Docker 与 docker compose，且默认在工作区里与 `balancer` 仓库并列（用于构建镜像）。在仓库内运行：
+
+```bash
+cd ez-api
+./test/integration.sh
+```
+
+脚本会拉起 `docker-compose.integration.yml` 中的服务，运行带 `integration` tag 的 Go 测试，并在完成后清理容器和卷。
+
 ## 设计决策
 
 - **异步日志**: 日志不会立即写入 DB。它们被缓冲在内存中，并分批刷新，以减少 DB IOPS。
diff --git a/docker-compose.integration.yml b/docker-compose.integration.yml
index add61b7..215bb06 100644
--- a/docker-compose.integration.yml
+++ b/docker-compose.integration.yml
@@ -31,7 +31,7 @@ services:
 
   mock-upstream:
     build:
-      context: ./integration/mock-upstream
+      context: ./test/mock-upstream
       dockerfile: Dockerfile
     ports:
       - "8082:8082"
diff --git a/integration/go.mod b/test/go.mod
similarity index 100%
rename from integration/go.mod
rename to test/go.mod
diff --git a/test/integration.sh b/test/integration.sh
new file mode 100755
index 0000000..fafc205
--- /dev/null
+++ b/test/integration.sh
@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Runs integration tests inside the ez-api repo (builds docker-compose + go test).
+
+REPO_ROOT=$(cd -- "$(dirname -- "$0")"/.. && pwd)
+compose_file="$REPO_ROOT/docker-compose.integration.yml"
+
+echo "[integration] bringing up services..."
+docker compose -f "$compose_file" up --build -d --wait
+
+cleanup() {
+  echo "[integration] tearing down services..."
+  docker compose -f "$compose_file" down -v
+}
+trap cleanup EXIT
+
+echo "[integration] running go test with integration tag..."
+cd "$REPO_ROOT/test"
+go test -tags=integration ./...
diff --git a/integration/integration_test.go b/test/integration_test.go
similarity index 100%
rename from integration/integration_test.go
rename to test/integration_test.go
diff --git a/integration_test.sh b/test/integration_test.sh
similarity index 100%
rename from integration_test.sh
rename to test/integration_test.sh
diff --git a/integration/mock-upstream/Dockerfile b/test/mock-upstream/Dockerfile
similarity index 100%
rename from integration/mock-upstream/Dockerfile
rename to test/mock-upstream/Dockerfile
diff --git a/integration/mock-upstream/main.go b/test/mock-upstream/main.go
similarity index 100%
rename from integration/mock-upstream/main.go
rename to test/mock-upstream/main.go