From 1e4e9dc34267e009709b6e08dcca31ba5fafb475 Mon Sep 17 00:00:00 2001
From: Developer <developer@rwadurian.com>
Date: Tue, 2 Dec 2025 18:23:18 -0800
Subject: [PATCH] =?UTF-8?q?docs(admin-service):=20=E6=B7=BB=E5=8A=A0?=
 =?UTF-8?q?=E5=AE=8C=E6=95=B4=E6=B5=8B=E8=AF=95=E6=89=A7=E8=A1=8C=E6=8C=87?=
 =?UTF-8?q?=E5=8D=97=E5=92=8C=E6=95=B0=E6=8D=AE=E5=BA=93=E6=B5=8B=E8=AF=95?=
 =?UTF-8?q?=E8=84=9A=E6=9C=AC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增文件:
- TEST_EXECUTION_GUIDE.md: 完整的测试执行指南
  - 三层测试说明（单元/集成/E2E）
  - 数据库依赖说明
  - 多种测试执行方法（本地/WSL2/Docker）
  - 常见问题排查
  - CI/CD 配置示例

- scripts/test-with-docker-db.sh: WSL2完整测试脚本
  - 自动启动PostgreSQL容器
  - 运行所有测试层级
  - 生成覆盖率报告
  - 自动清理

测试层级说明:
✅ 单元测试: 不需要数据库（Value Objects/Entities/Mappers）
✅ 集成测试: 需要数据库（Repository/Handlers）
✅ E2E测试: 需要数据库（Controllers/API）

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../admin-service/TEST_EXECUTION_GUIDE.md     | 357 ++++++++++++++++++
 .../scripts/test-with-docker-db.sh            |  78 ++++
 2 files changed, 435 insertions(+)
 create mode 100644 backend/services/admin-service/TEST_EXECUTION_GUIDE.md
 create mode 100644 backend/services/admin-service/scripts/test-with-docker-db.sh

diff --git a/backend/services/admin-service/TEST_EXECUTION_GUIDE.md b/backend/services/admin-service/TEST_EXECUTION_GUIDE.md
new file mode 100644
index 00000000..90ee9c09
--- /dev/null
+++ b/backend/services/admin-service/TEST_EXECUTION_GUIDE.md
@@ -0,0 +1,357 @@
+# Admin Service 测试执行指南
+
+## 测试层级说明
+
+admin-service 包含三个层级的测试，每个层级有不同的依赖要求：
+
+### 1. 单元测试（Unit Tests）
+**位置**: `test/unit/`
+**依赖**: ❌ 不需要数据库
+**测试内容**:
+- Value Objects (值对象验证逻辑)
+- Entities (实体业务方法)
+- Mappers (数据转换)
+
+**运行命令**:
+```bash
+npm run test:unit
+```
+
+### 2. 集成测试（Integration Tests）
+**位置**: `test/integration/`
+**依赖**: ✅ 需要 PostgreSQL 数据库
+**测试内容**:
+- Repository (数据库CRUD操作)
+- Handlers (命令/查询处理器)
+
+**运行命令**:
+```bash
+# 需要先设置 DATABASE_URL 环境变量
+DATABASE_URL="postgresql://postgres:password@localhost:5433/admin_service_test" \
+  npm run test:integration
+```
+
+### 3. E2E 测试（End-to-End Tests）
+**位置**: `test/e2e/`
+**依赖**: ✅ 需要 PostgreSQL 数据库
+**测试内容**:
+- Controller (API端点、验证、错误处理)
+
+**运行命令**:
+```bash
+# 需要先设置 DATABASE_URL 环境变量
+DATABASE_URL="postgresql://postgres:password@localhost:5433/admin_service_test" \
+  npm run test:e2e
+```
+
+## 完整测试执行流程
+
+### 方法1: 使用本地 PostgreSQL
+
+#### 步骤1: 安装 PostgreSQL
+```bash
+# Ubuntu/Debian
+sudo apt install postgresql
+
+# macOS
+brew install postgresql
+
+# 或使用 Docker
+docker run -d \
+  --name admin-test-db \
+  -e POSTGRES_USER=postgres \
+  -e POSTGRES_PASSWORD=password \
+  -e POSTGRES_DB=admin_service_test \
+  -p 5433:5432 \
+  postgres:16-alpine
+```
+
+#### 步骤2: 创建测试数据库
+```bash
+# 如果使用本地 PostgreSQL
+createdb admin_service_test
+
+# 如果使用 Docker，数据库已自动创建
+```
+
+#### 步骤3: 运行 Prisma 迁移
+```bash
+cd backend/services/admin-service
+
+DATABASE_URL="postgresql://postgres:password@localhost:5433/admin_service_test" \
+  npx prisma migrate deploy
+```
+
+#### 步骤4: 运行所有测试
+```bash
+DATABASE_URL="postgresql://postgres:password@localhost:5433/admin_service_test" \
+  npm test
+```
+
+### 方法2: 使用 WSL2 + Docker（推荐）
+
+#### 一键脚本
+```bash
+# 在 WSL2 中
+cd /mnt/c/Users/dong/Desktop/rwadurian/backend/services/admin-service
+chmod +x scripts/test-with-docker-db.sh
+./scripts/test-with-docker-db.sh
+```
+
+该脚本会自动：
+1. 启动 Docker PostgreSQL 容器
+2. 等待数据库就绪
+3. 运行数据库迁移
+4. 执行所有测试（单元 + 集成 + E2E）
+5. 生成覆盖率报告
+6. 清理数据库容器
+
+#### 手动步骤
+```bash
+# 1. 启动数据库
+docker run -d --name admin-test-db --rm \
+  -e POSTGRES_USER=postgres \
+  -e POSTGRES_PASSWORD=password \
+  -e POSTGRES_DB=admin_service_test \
+  -p 5433:5432 \
+  postgres:16-alpine
+
+# 2. 等待数据库就绪
+sleep 5
+
+# 3. 运行迁移
+DATABASE_URL="postgresql://postgres:password@localhost:5433/admin_service_test" \
+  npx prisma migrate deploy
+
+# 4. 运行测试
+DATABASE_URL="postgresql://postgres:password@localhost:5433/admin_service_test" \
+  npm test
+
+# 5. 清理
+docker stop admin-test-db
+```
+
+### 方法3: 使用 Docker Compose
+
+```bash
+cd backend/services/admin-service
+
+# 启动并运行测试
+docker-compose -f docker-compose.test.yml up --build
+
+# 清理
+docker-compose -f docker-compose.test.yml down -v
+```
+
+## 分类测试执行
+
+### 只运行单元测试（无需数据库）
+```bash
+npm run test:unit
+```
+**预期输出**: 所有 Value Object, Entity, Mapper 测试通过
+
+### 只运行集成测试（需要数据库）
+```bash
+# 1. 确保数据库运行中
+docker ps | grep admin-test-db
+
+# 2. 运行集成测试
+DATABASE_URL="postgresql://postgres:password@localhost:5433/admin_service_test" \
+  npm run test:integration
+```
+**预期输出**: Repository 和 Handler 测试通过
+
+### 只运行 E2E 测试（需要数据库）
+```bash
+# 1. 确保数据库运行中
+docker ps | grep admin-test-db
+
+# 2. 运行 E2E 测试
+DATABASE_URL="postgresql://postgres:password@localhost:5433/admin_service_test" \
+  npm run test:e2e
+```
+**预期输出**: Controller API 端点测试通过
+
+## 覆盖率报告
+
+### 生成覆盖率报告
+```bash
+DATABASE_URL="postgresql://postgres:password@localhost:5433/admin_service_test" \
+  npm run test:cov
+```
+
+### 查看覆盖率
+```bash
+# HTML 报告
+open coverage/lcov-report/index.html
+
+# 或在 WSL 中
+explorer.exe coverage/lcov-report/index.html
+```
+
+## 常见问题排查
+
+### Q1: 集成/E2E 测试失败 - "Can't reach database server"
+
+**原因**: 数据库未运行或连接信息错误
+
+**解决**:
+```bash
+# 检查数据库是否运行
+docker ps | grep admin-test-db
+
+# 如果没有运行，启动数据库
+docker run -d --name admin-test-db --rm \
+  -e POSTGRES_USER=postgres \
+  -e POSTGRES_PASSWORD=password \
+  -e POSTGRES_DB=admin_service_test \
+  -p 5433:5432 \
+  postgres:16-alpine
+
+# 验证连接
+docker exec admin-test-db psql -U postgres -d admin_service_test -c "SELECT 1;"
+```
+
+### Q2: Prisma 迁移失败
+
+**原因**: 数据库schema不匹配
+
+**解决**:
+```bash
+# 重置数据库
+docker stop admin-test-db
+docker run -d --name admin-test-db --rm \
+  -e POSTGRES_USER=postgres \
+  -e POSTGRES_PASSWORD=password \
+  -e POSTGRES_DB=admin_service_test \
+  -p 5433:5432 \
+  postgres:16-alpine
+
+# 重新运行迁移
+DATABASE_URL="postgresql://postgres:password@localhost:5433/admin_service_test" \
+  npx prisma migrate deploy
+```
+
+### Q3: 端口冲突
+
+**原因**: 5433 端口已被占用
+
+**解决**:
+```bash
+# 查找占用端口的进程
+lsof -i :5433
+
+# 或更改数据库端口
+docker run -d --name admin-test-db --rm \
+  -e POSTGRES_USER=postgres \
+  -e POSTGRES_PASSWORD=password \
+  -e POSTGRES_DB=admin_service_test \
+  -p 5434:5432 \
+  postgres:16-alpine
+
+# 更新 DATABASE_URL
+DATABASE_URL="postgresql://postgres:password@localhost:5434/admin_service_test" \
+  npm test
+```
+
+### Q4: WSL2 中 Docker 不可用
+
+**原因**: Docker Desktop 未启动或 WSL2 集成未配置
+
+**解决**:
+1. 启动 Docker Desktop
+2. 在 Docker Desktop 设置中启用 WSL2 集成
+3. 在 WSL2 中验证: `docker --version`
+
+## 测试结果示例
+
+### 成功的测试运行
+```
+PASS test/unit/domain/value-objects/version-code.vo.spec.ts
+PASS test/unit/domain/value-objects/version-name.vo.spec.ts
+PASS test/unit/domain/value-objects/file-size.vo.spec.ts
+PASS test/unit/domain/value-objects/file-sha256.vo.spec.ts
+PASS test/unit/domain/entities/app-version.entity.spec.ts
+PASS test/unit/infrastructure/mappers/app-version.mapper.spec.ts
+PASS test/integration/repositories/app-version.repository.spec.ts
+PASS test/integration/handlers/create-version.handler.spec.ts
+PASS test/e2e/version.controller.spec.ts
+
+Test Suites: 9 passed, 9 total
+Tests:       ~100 passed, ~100 total
+Coverage:    85%+ (varies by component)
+Time:        ~30s
+```
+
+## 持续集成（CI）配置
+
+### GitHub Actions 示例
+```yaml
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: password
+          POSTGRES_DB: admin_service_test
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate Prisma client
+        run: npm run prisma:generate
+
+      - name: Run migrations
+        run: npx prisma migrate deploy
+        env:
+          DATABASE_URL: postgresql://postgres:password@localhost:5432/admin_service_test
+
+      - name: Run tests
+        run: npm test
+        env:
+          DATABASE_URL: postgresql://postgres:password@localhost:5432/admin_service_test
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v3
+        with:
+          files: ./coverage/lcov.info
+```
+
+## 总结
+
+| 测试类型 | 需要数据库 | 命令 | 测试文件数 |
+|---------|----------|------|-----------|
+| 单元测试 | ❌ | `npm run test:unit` | 6 |
+| 集成测试 | ✅ | `npm run test:integration` | 2 |
+| E2E测试 | ✅ | `npm run test:e2e` | 1 |
+| 全部测试 | ✅ | `npm test` | 9 |
+| 覆盖率 | ✅ | `npm run test:cov` | 9 |
+
+**推荐执行流程**:
+1. 快速验证: `npm run test:unit` (无需数据库，~5秒)
+2. 完整测试: 启动数据库 → `npm test` (~30秒)
+3. 查看覆盖率: `open coverage/lcov-report/index.html`
diff --git a/backend/services/admin-service/scripts/test-with-docker-db.sh b/backend/services/admin-service/scripts/test-with-docker-db.sh
new file mode 100644
index 00000000..5883a13f
--- /dev/null
+++ b/backend/services/admin-service/scripts/test-with-docker-db.sh
@@ -0,0 +1,78 @@
+#!/bin/bash
+
+# 在 WSL2 中运行完整测试（使用 Docker 提供的测试数据库）
+
+set -e
+
+BLUE='\033[0;34m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}=== Admin Service Complete Test Suite ===${NC}"
+
+# 1. 启动 PostgreSQL 测试数据库容器
+echo -e "${YELLOW}1. Starting PostgreSQL test database...${NC}"
+docker run -d \
+  --name admin-test-db \
+  --rm \
+  -e POSTGRES_USER=postgres \
+  -e POSTGRES_PASSWORD=password \
+  -e POSTGRES_DB=admin_service_test \
+  -p 5433:5432 \
+  postgres:16-alpine
+
+echo -e "${YELLOW}Waiting for database to be ready...${NC}"
+sleep 5
+
+# 2. 检查数据库连接
+echo -e "${YELLOW}2. Checking database connection...${NC}"
+until docker exec admin-test-db pg_isready -U postgres; do
+  echo "Waiting for database..."
+  sleep 2
+done
+echo -e "${GREEN}✓ Database is ready${NC}"
+
+# 3. 设置环境变量
+export DATABASE_URL="postgresql://postgres:password@localhost:5433/admin_service_test?schema=public"
+export NODE_ENV=test
+
+# 4. 安装依赖（如果需要）
+if [ ! -d "node_modules" ]; then
+  echo -e "${YELLOW}3. Installing dependencies...${NC}"
+  npm ci
+fi
+
+# 5. 生成 Prisma 客户端
+echo -e "${YELLOW}4. Generating Prisma client...${NC}"
+npm run prisma:generate
+
+# 6. 运行数据库迁移
+echo -e "${YELLOW}5. Running database migrations...${NC}"
+npx prisma migrate deploy
+
+# 7. 运行单元测试
+echo -e "${BLUE}=== Running Unit Tests ===${NC}"
+npm run test:unit
+
+# 8. 运行集成测试
+echo -e "${BLUE}=== Running Integration Tests ===${NC}"
+npm run test:integration
+
+# 9. 运行 E2E 测试
+echo -e "${BLUE}=== Running E2E Tests ===${NC}"
+npm run test:e2e
+
+# 10. 生成覆盖率报告
+echo -e "${BLUE}=== Generating Coverage Report ===${NC}"
+npm run test:cov
+
+echo -e "${GREEN}=== All tests completed successfully! ===${NC}"
+
+# 11. 清理
+echo -e "${YELLOW}Cleaning up test database...${NC}"
+docker stop admin-test-db
+
+echo -e "${GREEN}✓ Test suite finished${NC}"
+echo -e "${BLUE}Coverage report: ./coverage/lcov-report/index.html${NC}"