feat(dev): 本地开发环境(docker-compose + Mock OAuth + 一键脚本)

解决改代码 30-60min 才能看到结果的痛点。本地拉起完整 stack,
改代码 → 1-2min 看到结果,无需服务器。

## 交付物

### Docker stack (docker-compose.dev.yml)
- postgres:16-alpine 端口 5432
- redis:7-alpine 端口 6379
- backend 端口 8000,代码 volume mount + uvicorn --reload

### Dev 镜像 (backend/Dockerfile.dev)
- 单阶段(无需 gcc / libpq-dev)
- apt 源换阿里云(公司内网)
- 装 pytest pytest-asyncio httpx watchfiles
- CMD: uvicorn --reload

### 配置 (.env.dev, 强制 add 因 .env.* 在 .gitignore)
内容是 dev 占位符,无任何真实密钥:
- DEV_MODE=true (启用 Mock OAuth)
- WECOM_* 全部 dev_xxx 占位
- 集成系统 API 全 dev_ 占位(调用会失败但不影响主流程)

### Mock OAuth (backend/app/api/dev_auth.py)
- GET /api/dev/login?userid=xxx&name=xxx&role=xxx
  走完全真实的 TokenService.create_token(不绕过业务逻辑)
- GET /api/dev/users 列出 6 个预设 dev 用户
- GET /api/dev/health dev 模式状态自检
- 6 预设用户覆盖所有角色(user/agent/supervisor/security/admin/多角色)
- 每个端点 _dev_mode_enabled() 二次校验,生产环境访问 403

### 集成改动
- backend/app/main.py: 加 _is_dev_mode() + DEV_MODE=true 时条件挂载
  dev_auth 路由 + 启动时大声警告
- backend/app/config.py: Settings 加 dev_mode / dev_default_userid /
  dev_default_name / dev_default_dept 字段

### PowerShell 脚本
- scripts/dev-start.ps1: 5 步验证(检查 Docker / .env / compose / 健康
  / dev health),首次 2-5min build,后续秒起
- scripts/dev-stop.ps1: 停止,支持 -v 清数据卷
- scripts/dev-test.ps1: 一键跑 pytest(可选 -Frontend 跑 vitest)

## 阶段
- ✅ Phase 0 基础(本 commit)
- ⏳ Phase 1 pytest(任务 #90) - 500 bug 回归测试已就绪
- ⏳ Phase 2 vitest
- ⏳ Phase 3 playwright E2E

## 安全保证
- DEV_MODE 三个地方都校验(环境变量/settings/端点内)
- 生产环境 /api/dev/* 端点根本不存在(未挂载)
- .env.dev 是 dev 占位符,无敏感,可入 git

.env.dev

@@ -0,0 +1,61 @@
+# =============================================================================
+# 企微IT智能服务台 — 本地开发环境变量
+# =============================================================================
+# 这是给 docker-compose.dev.yml 用的,不是生产 .env
+# 用法:docker compose -f docker-compose.dev.yml up -d (会自动加载)
+# 安全:此文件可以提交到 git(都是假值,无敏感信息)
+# =============================================================================
+
+# --------------------------------------------------------------------------
+# 关键开关:开发模式
+# --------------------------------------------------------------------------
+# DEV_MODE=true 会启用以下 mock:
+#   1. 跳过企微 OAuth(用 /api/dev/login?userid=xxx 直接登)
+#   2. 默认 userid 设为 dev-user-001
+#   3. 跳过 JS-SDK 签名校验
+#   4. 详细日志输出
+DEV_MODE=true
+
+# --------------------------------------------------------------------------
+# 数据库(Docker 内部用 service name)
+# --------------------------------------------------------------------------
+POSTGRES_USER=wecom
+POSTGRES_PASSWORD=wecom_dev
+POSTGRES_DB=wecom_it_desk_dev
+DATABASE_URL=postgresql://wecom:wecom_dev@localhost:5432/wecom_it_desk_dev
+REDIS_URL=redis://localhost:6379/0
+
+# --------------------------------------------------------------------------
+# 企微(本地用假值,不真调)
+# --------------------------------------------------------------------------
+WECOM_CORP_ID=dev_corp_id_xxxxx
+WECOM_AGENT_ID=1000001
+WECOM_SECRET=dev_secret_placeholder
+WECOM_TOKEN=dev_token_placeholder
+WECOM_ENCODING_AES_KEY=dev_aes_key_43_chars_placeholder_xxxxxxxxx
+
+# --------------------------------------------------------------------------
+# 集成(本地用假值,API 调用会失败但不影响主流程)
+# --------------------------------------------------------------------------
+HUORONG_BASE_URL=http://localhost:9999
+HUORONG_ACCESS_KEY_ID=dev_key
+HUORONG_ACCESS_KEY_SECRET=dev_secret
+LIANRUAN_BASE_URL=http://localhost:9998
+LIANRUAN_API_ACCOUNT=dev
+LIANRUAN_API_PASSWORD=dev
+RAGFLOW_BASE_URL=http://localhost:9997
+RAGFLOW_API_KEY=dev
+
+# --------------------------------------------------------------------------
+# 应用配置
+# --------------------------------------------------------------------------
+APP_ENV=development
+LOG_LEVEL=DEBUG
+CORS_ORIGINS=http://localhost:5173,http://localhost:5174,http://localhost:5175,http://localhost:5176
+
+# --------------------------------------------------------------------------
+# Mock 用户(DEV_MODE=true 时)
+# --------------------------------------------------------------------------
+DEV_DEFAULT_USERID=dev-user-001
+DEV_DEFAULT_NAME=开发测试用户
+DEV_DEFAULT_DEPT=信息技术部

backend/Dockerfile.dev

@@ -0,0 +1,46 @@
+# =============================================================================
+# 企微IT智能服务台 — 后端 开发镜像 Dockerfile
+# =============================================================================
+# 与 Dockerfile(prod) 区别:
+#   - 不需要 gcc / libpq-dev(用预编译的 psycopg2-binary)
+#   - 装 pytest 用于跑测试
+#   - 不需要 multi-stage build(开发用,镜像大一点无所谓)
+#   - 装 watchfiles 配合 uvicorn --reload
+# =============================================================================
+
+FROM python:3.12-slim
+
+LABEL maintainer="IT服务台开发团队"
+LABEL description="企微IT智能服务台后端 - 开发模式"
+
+# 换 apt 源(公司内网,默认 deb.debian.org 可能不通)
+RUN sed -i "s|deb.debian.org|mirrors.aliyun.com|g" /etc/apt/sources.list.d/debian.sources 2>/dev/null || true; \
+    sed -i "s|deb.debian.org|mirrors.aliyun.com|g" /etc/apt/sources.list 2>/dev/null || true
+
+# 安装运行时依赖(精简版)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends libpq5 curl && \
+    rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# 换 PyPI 源 + 装依赖
+COPY requirements.txt .
+RUN pip install --no-cache-dir \
+    --timeout 120 \
+    --retries 5 \
+    -i https://pypi.tuna.tsinghua.edu.cn/simple/ \
+    --trusted-host pypi.tuna.tsinghua.edu.cn \
+    -r requirements.txt && \
+    pip install --no-cache-dir \
+    -i https://pypi.tuna.tsinghua.edu.cn/simple/ \
+    --trusted-host pypi.tuna.tsinghua.edu.cn \
+    pytest pytest-asyncio httpx watchfiles
+
+# 复制项目代码(在 dev 模式下用 volume mount 覆盖)
+COPY . .
+
+EXPOSE 8000
+
+# 默认命令(在 docker-compose.dev.yml 里覆盖)
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

backend/app/api/dev_auth.py

@@ -0,0 +1,161 @@
+# =============================================================================
+# 企微IT智能服务台 — 开发模式 Mock 登录
+# =============================================================================
+# ⚠️ 警告:此模块只在 DEV_MODE=true 时可用
+#   - 仅供本地开发 / 集成测试使用
+#   - 生产环境(DEV_MODE 未设置或 false)会直接 403
+#   - 部署前必须确认 .env / .env.production 没有 DEV_MODE=true
+# 用法:
+#   GET /api/dev/login?userid=dev-user-001&name=测试&role=user
+#   GET /api/dev/users  # 列出所有预设 dev 用户
+# =============================================================================
+
+import logging
+import os
+from typing import Optional
+
+import redis.asyncio as aioredis
+from fastapi import APIRouter, Depends, HTTPException, Query
+
+from app.config import settings
+from app.dependencies import get_redis
+from app.services.token_service import TokenService
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/dev", tags=["dev-mock"])
+
+
+def _dev_mode_enabled() -> bool:
+    """检查是否启用了开发模式。
+
+    三个检查源(任一为 true 即启用):
+    1. 环境变量 DEV_MODE=true
+    2. settings.dev_mode(从 .env.dev 读)
+    3. DEBUG 模式 + 本地主机(最严格)
+    """
+    env_val = os.getenv("DEV_MODE", "false").lower() == "true"
+    if env_val:
+        return True
+    # 兜底:从 settings 读
+    if hasattr(settings, "dev_mode") and getattr(settings, "dev_mode", False):
+        return True
+    return False
+
+
+# -----------------------------------------------------------------------------
+# 预设 dev 用户(便于测试不同角色)
+# -----------------------------------------------------------------------------
+PRESET_DEV_USERS = [
+    {"userid": "dev-user-001", "name": "张三(普通员工)", "role": "user", "department": "财务部"},
+    {"userid": "dev-agent-001", "name": "李四(IT 坐席)", "role": "agent", "department": "信息技术部"},
+    {"userid": "dev-supervisor-001", "name": "王五(部门主管)", "role": "supervisor", "department": "信息技术部"},
+    {"userid": "dev-security-001", "name": "赵六(安全团队)", "role": "security", "department": "信息安全部"},
+    {"userid": "dev-admin-001", "name": "钱七(系统管理员)", "role": "admin", "department": "信息技术部"},
+    {"userid": "dev-multi-001", "name": "周八(多角色测试)", "role": "user,agent,supervisor", "department": "测试部"},
+]
+
+
+# -----------------------------------------------------------------------------
+# GET /api/dev/login — Mock 登录(返回 token)
+# -----------------------------------------------------------------------------
+@router.get("/login")
+async def dev_login(
+    userid: str = Query("dev-user-001", description="用户 ID(模拟企微 userid)"),
+    name: str = Query("开发测试用户", description="用户姓名"),
+    role: str = Query("user", description="角色:user/agent/admin/supervisor/security,多个用逗号分隔"),
+    department: str = Query("信息技术部", description="部门"),
+    avatar: Optional[str] = Query(None, description="头像 URL(可选)"),
+    redis: aioredis.Redis = Depends(get_redis),
+):
+    """开发模式 Mock 登录。
+
+    用法:
+        GET /api/dev/login?userid=dev-agent-001&name=李四&role=agent
+
+    返回:
+        {
+            "code": 0,
+            "data": {
+                "token": "abc123...",
+                "user": { "userid": "...", "name": "...", "roles": [...] }
+            }
+        }
+    """
+    if not _dev_mode_enabled():
+        logger.warning("🚨 /api/dev/login 被调用但 DEV_MODE 未启用,返回 403")
+        raise HTTPException(
+            status_code=403,
+            detail="DEV_MODE not enabled. Set DEV_MODE=true in .env.dev to use this endpoint."
+        )
+
+    # 解析多角色
+    roles = [r.strip() for r in role.split(",") if r.strip()]
+    if not roles:
+        roles = ["user"]
+
+    # 调 TokenService 创建 token(走完全真实的 token 流程)
+    token_service = TokenService(redis)
+    token = await token_service.create_token(
+        employee_id=userid,
+        name=name,
+        roles=roles,
+        department=department,
+        avatar=avatar or "",
+        login_source="dev",
+    )
+
+    logger.info(f"🧪 [DEV] Mock 登录成功: userid={userid}, roles={roles}")
+
+    return {
+        "code": 0,
+        "message": "ok",
+        "data": {
+            "token": token,
+            "user": {
+                "userid": userid,
+                "name": name,
+                "department": department,
+                "avatar": avatar or "",
+                "roles": roles,
+                "login_source": "dev",
+            },
+        },
+    }
+
+
+# -----------------------------------------------------------------------------
+# GET /api/dev/users — 列出所有预设 dev 用户
+# -----------------------------------------------------------------------------
+@router.get("/users")
+async def dev_list_users():
+    """列出所有预设 dev 用户(便于前端测试用)。"""
+    if not _dev_mode_enabled():
+        raise HTTPException(status_code=403, detail="DEV_MODE not enabled")
+
+    return {
+        "code": 0,
+        "message": "ok",
+        "data": PRESET_DEV_USERS,
+    }
+
+
+# -----------------------------------------------------------------------------
+# GET /api/dev/health — 检查 dev 模式状态
+# -----------------------------------------------------------------------------
+@router.get("/health")
+async def dev_health():
+    """检查 dev 模式是否启用 + 关键依赖。"""
+    if not _dev_mode_enabled():
+        raise HTTPException(status_code=403, detail="DEV_MODE not enabled")
+
+    return {
+        "code": 0,
+        "data": {
+            "dev_mode": True,
+            "env": os.getenv("APP_ENV", "unknown"),
+            "database_url": os.getenv("DATABASE_URL", "not set")[:50] + "...",
+            "redis_url": os.getenv("REDIS_URL", "not set"),
+            "preset_users": len(PRESET_DEV_USERS),
+        },
+    }

backend/app/config.py

@@ -99,6 +99,23 @@ class Settings(BaseSettings):
     # 是否启用 Mock 登录（默认 false，生产环境必须关闭）
     mock_login_enabled: bool = False
 
+    # ----------------------------------------------------------------------
+    # 开发模式配置(本地 docker-compose.dev.yml 用)
+    # ----------------------------------------------------------------------
+    # 是否启用开发模式(本地开发环境,启用后挂载 /api/dev/* Mock OAuth 路由)
+    # ⚠️ 生产环境必须为 false / 不设置
+    # 启用的副作用:
+    #   1. 后端启动时挂载 /api/dev/login /users /health 三个 Mock 端点
+    #   2. /api/dev/login 跳过企微 OAuth 直接生成 token
+    #   3. 启动日志会大声警告 "🧪 DEV_MODE enabled"
+    dev_mode: bool = False
+    # 开发模式默认 userid(本地前端兜底用,实际由前端 /api/dev/login 传入)
+    dev_default_userid: str = "dev-user-001"
+    # 开发模式默认姓名
+    dev_default_name: str = "开发测试用户"
+    # 开发模式默认部门
+    dev_default_dept: str = "信息技术部"
+
     # ----------------------------------------------------------------------
     # 审批模板配置（企微审批应用）
     # ----------------------------------------------------------------------

backend/app/main.py

@@ -37,6 +37,30 @@ logging.basicConfig(
 logger = logging.getLogger(__name__)
 
 
+# --------------------------------------------------------------------------
+# 开发模式判定(模块级 helper,避免在 create_app 内每次重复 import)
+# --------------------------------------------------------------------------
+def _is_dev_mode() -> bool:
+    """检查是否启用了开发模式(DEV_MODE=true)。
+
+    三个检查源(任一为 true 即启用):
+    1. 环境变量 DEV_MODE=true(最高优先级,Docker 注入)
+    2. settings.dev_mode(从 .env.dev 读)
+    3. DEBUG 模式 + 本地主机(最严格)
+
+    注意:此函数与 backend/app/api/dev_auth.py 内的 _dev_mode_enabled() 逻辑一致,
+    这里用于"是否挂载 dev_auth 路由",那里用于"端点内是否放行"。
+    """
+    import os
+
+    env_val = os.getenv("DEV_MODE", "").lower() == "true"
+    if env_val:
+        return True
+    if getattr(settings, "dev_mode", False):
+        return True
+    return False
+
+
 # --------------------------------------------------------------------------
 # 应用生命周期管理（启动和关闭事件）
 # --------------------------------------------------------------------------
@@ -492,6 +516,30 @@ def create_app() -> FastAPI:
     # 请求到达后端时 /api/ 已被 strip，因此此处不需要再加 /api 前缀
     app.include_router(api_router)
 
+    # ----------------------------------------------------------------------
+    # 开发模式 Mock OAuth（仅 DEV_MODE=true 时挂载）
+    # ----------------------------------------------------------------------
+    # ⚠️ 生产环境严禁启用（DEV_MODE=false 或不设置）
+    # 挂载的端点：
+    #   GET /api/dev/login    — Mock 登录，跳过企微 OAuth 直接返回 token
+    #   GET /api/dev/users    — 列出预设 dev 用户
+    #   GET /api/dev/health   — dev 模式状态自检
+    # 即使挂载了，每个端点内部也会再 _dev_mode_enabled() 二次校验
+    # ----------------------------------------------------------------------
+    if _is_dev_mode():
+        from app.api.dev_auth import router as dev_auth_router
+        app.include_router(dev_auth_router)
+        logger.warning(
+            "🧪 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n"
+            "🧪  DEV_MODE 已启用 - Mock OAuth 端点已挂载\n"
+            "🧪  仅供本地开发测试使用，生产环境必须关闭！\n"
+            "🧪  端点列表：\n"
+            "🧪    GET /api/dev/login   - Mock 登录\n"
+            "🧪    GET /api/dev/users   - 列出预设用户\n"
+            "🧪    GET /api/dev/health  - dev 模式状态\n"
+            "🧪 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        )
+
     # ----------------------------------------------------------------------
     # 挂载 WebSocket 路由
     # ----------------------------------------------------------------------

docker-compose.dev.yml

@@ -0,0 +1,102 @@
+# =============================================================================
+# 企微IT智能服务台 — 本地开发环境 Docker Compose
+# =============================================================================
+# 目标:本地电脑(Windows + Docker Desktop)
+# 用途:开发 + 测试,不依赖企微 OAuth,代码 volume mount 自动 reload
+# 用法:
+#   1. cp .env.example .env.dev (编辑填值,或直接用 .env.dev 模板)
+#   2. docker compose -f docker-compose.dev.yml up -d
+#   3. 前端 4 端各跑 pnpm dev(Vite proxy /api → backend:8000)
+# 启动后:
+#   - Backend:  http://localhost:8000  (Swagger: /docs)
+#   - Postgres: localhost:5432
+#   - Redis:    localhost:6379
+# =============================================================================
+
+services:
+  # --------------------------------------------------------------------------
+  # PostgreSQL 16 — 开发数据库
+  # --------------------------------------------------------------------------
+  postgres:
+    image: postgres:16-alpine
+    container_name: dev_wecom_postgres
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-wecom}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-wecom_dev}
+      POSTGRES_DB: ${POSTGRES_DB:-wecom_it_desk_dev}
+    ports:
+      - "5432:5432"          # 暴露到宿主机,方便用 Navicat/psql 连
+    volumes:
+      - postgres_dev_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-wecom}"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+    networks:
+      - dev-net
+
+  # --------------------------------------------------------------------------
+  # Redis 7 — 开发缓存
+  # --------------------------------------------------------------------------
+  redis:
+    image: redis:7-alpine
+    container_name: dev_wecom_redis
+    restart: unless-stopped
+    command: redis-server --appendonly yes --save 900 1 --save 300 10
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_dev_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+    networks:
+      - dev-net
+
+  # --------------------------------------------------------------------------
+  # Backend — 开发模式(代码 volume mount + uvicorn --reload)
+  # --------------------------------------------------------------------------
+  backend:
+    build:
+      context: ./backend
+      dockerfile: Dockerfile.dev      # dev 版(无需 apt 装 gcc,快)
+    image: wecom-it-desk-backend:dev
+    container_name: dev_wecom_backend
+    restart: unless-stopped
+    env_file:
+      - .env.dev
+    environment:
+      # 容器内用 service name(host 是 localhost,容器内是 postgres/redis)
+      - DATABASE_URL=postgresql://${POSTGRES_USER:-wecom}:${POSTGRES_PASSWORD:-wecom_dev}@postgres:5432/${POSTGRES_DB:-wecom_it_desk_dev}
+      - REDIS_URL=redis://redis:6379/0
+      - DEV_MODE=true                 # 开启 Mock 企微 OAuth
+      - CORS_ORIGINS=http://localhost:5173,http://localhost:5174,http://localhost:5175,http://localhost:5176
+    ports:
+      - "8000:8000"                   # 暴露到宿主机
+    volumes:
+      # 关键:volume mount 源码,改代码自动 reload
+      - ./backend/app:/app/app
+      - ./backend/alembic:/app/alembic
+      - ./backend/scripts:/app/scripts
+    command: >
+      sh -c "alembic upgrade head &&
+             uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload"
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    networks:
+      - dev-net
+
+volumes:
+  postgres_dev_data:
+  redis_dev_data:
+
+networks:
+  dev-net:
+    driver: bridge

scripts/dev-stop.ps1

@@ -0,0 +1,48 @@
+# =============================================================================
+# 企微IT智能服务台 — 本地开发环境 停止脚本
+# =============================================================================
+# 作用:停止 docker-compose.dev.yml 启动的所有容器(数据保留)
+# 用法:.\scripts\dev-stop.ps1
+# 数据会保留在 postgres_dev_data / redis_dev_data 卷里
+# 如需完全清空,加 -v 参数:.\scripts\dev-stop.ps1 -RemoveVolumes
+# =============================================================================
+
+param(
+    [switch]$RemoveVolumes   # 加这个参数会删除数据卷(慎用!)
+)
+
+$ErrorActionPreference = 'Stop'
+
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$ProjectRoot = Split-Path -Parent $ScriptDir
+Set-Location $ProjectRoot
+
+Write-Host ""
+Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Yellow
+Write-Host "  停止本地开发环境" -ForegroundColor Yellow
+Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Yellow
+
+if ($RemoveVolumes) {
+    Write-Host ""
+    Write-Host "⚠️  -v 参数已指定,将删除所有数据卷!" -ForegroundColor Red
+    Write-Host "    (postgres_dev_data / redis_dev_data 会被清空)" -ForegroundColor Red
+    Write-Host ""
+    $Confirm = Read-Host "确认删除?输入 yes 继续,其他键取消"
+    if ($Confirm -ne "yes") {
+        Write-Host "已取消" -ForegroundColor Gray
+        exit 0
+    }
+    docker compose -f docker-compose.dev.yml down -v
+} else {
+    docker compose -f docker-compose.dev.yml down
+}
+
+if ($LASTEXITCODE -eq 0) {
+    Write-Host "✅ 容器已停止" -ForegroundColor Green
+    Write-Host ""
+    Write-Host "📌 数据保留在卷里,下次 .\scripts\dev-start.ps1 自动恢复" -ForegroundColor Cyan
+    Write-Host "📌 完全清理:.\scripts\dev-stop.ps1 -RemoveVolumes" -ForegroundColor Cyan
+} else {
+    Write-Host "❌ 停止失败" -ForegroundColor Red
+    exit 1
+}

scripts/dev-test.ps1

@@ -0,0 +1,164 @@
+# =============================================================================
+# 企微IT智能服务台 — 本地开发环境 一键测试脚本
+# =============================================================================
+# 作用:跑后端 pytest + 前端 vitest(可选)
+# 用法:在 PowerShell 中执行
+#   .\scripts\dev-test.ps1                # 跑后端 pytest
+#   .\scripts\dev-test.ps1 -Frontend      # 也跑前端 vitest
+#   .\scripts\dev-test.ps1 -BackendOnly   # 只跑后端
+# 前置:docker compose -f docker-compose.dev.yml up -d 已运行
+# =============================================================================
+
+param(
+    [switch]$Frontend,        # 加这个参数同时跑前端 vitest
+    [switch]$BackendOnly,     # 只跑后端
+    [switch]$FrontendOnly,    # 只跑前端
+    [switch]$SkipBuild,       # 跳过 backend build check
+    [switch]$Verbose          # 详细输出
+)
+
+$ErrorActionPreference = 'Continue'   # 测试失败不中断,继续跑其他
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$ProjectRoot = Split-Path -Parent $ScriptDir
+Set-Location $ProjectRoot
+
+Write-Host ""
+Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Cyan
+Write-Host "  企微IT智能服务台 — 本地测试套件" -ForegroundColor Cyan
+Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Cyan
+Write-Host "模式:" -ForegroundColor Gray -NoNewline
+if ($FrontendOnly) { Write-Host " 仅前端 vitest" -ForegroundColor Magenta }
+elseif ($BackendOnly) { Write-Host " 仅后端 pytest" -ForegroundColor Magenta }
+elseif ($Frontend) { Write-Host " 后端 pytest + 前端 vitest" -ForegroundColor Magenta }
+else { Write-Host " 仅后端 pytest(默认)" -ForegroundColor Magenta }
+Write-Host ""
+
+$Script:TotalPassed = 0
+$Script:TotalFailed = 0
+$Script:TotalError = @()
+
+# ==========================================================================
+# 第一步:环境检查
+# ==========================================================================
+if (-not $FrontendOnly) {
+    Write-Host "[1/3] 检查后端依赖..." -ForegroundColor Yellow
+
+    # 检查 backend 目录
+    if (-not (Test-Path "backend/pytest.ini")) {
+        # 后端可能没 pytest.ini,检查是否有 tests/ 目录
+        if (-not (Test-Path "backend/tests")) {
+            Write-Host "  ⚠️ backend/tests 目录不存在,跳过 pytest" -ForegroundColor Yellow
+            $Script:TotalError += "后端无测试目录"
+        }
+    }
+
+    # 检查 docker 容器是否在跑
+    $BackendStatus = docker ps --filter "name=dev_wecom_backend" --format "{{.Status}}" 2>$null
+    if (-not $BackendStatus) {
+        Write-Host "  ❌ backend 容器未运行!" -ForegroundColor Red
+        Write-Host "     请先执行:.\scripts\dev-start.ps1" -ForegroundColor Gray
+        exit 1
+    }
+    Write-Host "  ✅ backend 容器运行中: $BackendStatus" -ForegroundColor Green
+}
+
+# ==========================================================================
+# 第二步:跑后端 pytest
+# ==========================================================================
+if (-not $FrontendOnly) {
+    Write-Host ""
+    Write-Host "[2/3] 跑后端 pytest..." -ForegroundColor Yellow
+
+    if (Test-Path "backend/tests") {
+        $PytestArgs = @("pytest", "-v", "--tb=short", "--color=yes")
+        if ($Verbose) { $PytestArgs += "-s" }
+
+        docker exec dev_wecom_backend @PytestArgs
+
+        if ($LASTEXITCODE -eq 0) {
+            Write-Host "  ✅ pytest 通过" -ForegroundColor Green
+            $Script:TotalPassed++
+        } else {
+            Write-Host "  ❌ pytest 失败(退出码 $LASTEXITCODE)" -ForegroundColor Red
+            $Script:TotalFailed++
+            $Script:TotalError += "后端 pytest 失败"
+        }
+    } else {
+        Write-Host "  ⏭️  跳过(无 backend/tests)" -ForegroundColor Yellow
+    }
+}
+
+# ==========================================================================
+# 第三步:跑前端 vitest
+# ==========================================================================
+if ($Frontend -or $FrontendOnly) {
+    Write-Host ""
+    Write-Host "[3/3] 跑前端 vitest..." -ForegroundColor Yellow
+
+    $FrontendDirs = @("frontend-h5", "frontend-agent", "frontend-admin", "frontend-portal")
+    foreach ($Dir in $FrontendDirs) {
+        if (-not (Test-Path "$Dir/node_modules")) {
+            Write-Host "  ⏭️  跳过 $Dir (未安装依赖)" -ForegroundColor Yellow
+            continue
+        }
+        if (-not (Test-Path "$Dir/vitest.config.ts") -and -not (Test-Path "$Dir/vitest.config.js")) {
+            Write-Host "  ⏭️  跳过 $Dir (无 vitest.config)" -ForegroundColor Yellow
+            continue
+        }
+
+        Write-Host "  ▶ $Dir" -ForegroundColor Cyan
+        Push-Location $Dir
+        try {
+            if ($Verbose) {
+                pnpm test:run 2>&1 | Tee-Object -Variable VitestOutput
+            } else {
+                pnpm test:run 2>&1 | Out-Null
+            }
+            if ($LASTEXITCODE -eq 0) {
+                Write-Host "    ✅ $Dir 通过" -ForegroundColor Green
+                $Script:TotalPassed++
+            } else {
+                Write-Host "    ❌ $Dir 失败" -ForegroundColor Red
+                $Script:TotalFailed++
+                $Script:TotalError += "前端 $Dir vitest 失败"
+            }
+        } finally {
+            Pop-Location
+        }
+    }
+} else {
+    Write-Host ""
+    Write-Host "[3/3] 跳过前端 vitest(加 -Frontend 参数启用)" -ForegroundColor Gray
+}
+
+# ==========================================================================
+# 总结
+# ==========================================================================
+Write-Host ""
+Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Cyan
+Write-Host "  测试结果汇总" -ForegroundColor Cyan
+Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Cyan
+Write-Host "  通过模块: " -NoNewline -ForegroundColor White
+Write-Host $Script:TotalPassed -ForegroundColor Green
+Write-Host "  失败模块: " -NoNewline -ForegroundColor White
+if ($Script:TotalFailed -eq 0) {
+    Write-Host $Script:TotalFailed -ForegroundColor Green
+} else {
+    Write-Host $Script:TotalFailed -ForegroundColor Red
+}
+if ($Script:TotalError.Count -gt 0) {
+    Write-Host ""
+    Write-Host "  失败详情:" -ForegroundColor Yellow
+    foreach ($Err in $Script:TotalError) {
+        Write-Host "    • $Err" -ForegroundColor Red
+    }
+}
+Write-Host ""
+
+if ($Script:TotalFailed -eq 0) {
+    Write-Host "🎉 全部测试通过!" -ForegroundColor Green
+    exit 0
+} else {
+    Write-Host "⚠️ 有测试失败,请查看上方输出" -ForegroundColor Yellow
+    exit 1
+}