test(integration): reorganize test structure and add runner script

- Move integration tests and mock upstream resources from `integration/` to `test/` directory.
- Add `test/integration.sh` script to orchestrate environment setup and test execution.
- Update build context in `docker-compose.integration.yml` to match new structure.
- Add documentation for local development and integration testing workflows in README.

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。

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"

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 ./...