企业级医疗信息系统自动化测试解决方案
特性 • 快速开始 • 安装 • 使用 • 配置 • 结构 • 贡献
--- ## 📋 目录 - [项目概述](#项目概述) - [功能特性](#功能特性) - [技术架构](#技术架构) - [快速开始](#快速开始) - [安装指南](#安装指南) - [环境要求](#环境要求) - [一键安装](#一键安装) - [手动安装](#手动安装) - [使用方法](#使用方法) - [启动服务](#启动服务) - [访问系统](#访问系统) - [执行测试](#执行测试) - [配置说明](#配置说明) - [主配置文件](#主配置文件) - [数据库配置](#数据库配置) - [AI服务配置](#ai服务配置) - [安全配置](#安全配置) - [项目结构](#项目结构) - [测试指南](#测试指南) - [运行所有测试](#运行所有测试) - [按类型运行](#按类型运行) - [独立测试套件](#独立测试套件) - [API文档](#api文档) - [开发指南](#开发指南) - [代码规范](#代码规范) - [调试模式](#调试模式) - [日志系统](#日志系统) - [部署指南](#部署指南) - [常见问题](#常见问题) - [更新日志](#更新日志) - [贡献指南](#贡献指南) - [许可证](#许可证) - [联系方式](#联系方式) --- ## 📖 项目概述 **HIS 自动化测试平台** 是一个专为企业级医疗信息系统（Hospital Information System, HIS）设计的自动化测试平台。该平台集成了先进的 AI 技术、多浏览器支持、全面的测试管理功能，旨在提供高效、可靠、智能的自动化测试解决方案。 ### 核心价值 - **🤖 AI 驱动**: 集成多种大语言模型（讯飞星火、阿里云百练、DeepSeek 等），实现智能测试用例生成、UI 元素识别、错误诊断等功能 - **🔄 Playwright 引擎**: 基于 Playwright 1.59+ 的现代浏览器自动化引擎，支持 Chromium、Firefox、WebKit - **📊 全流程覆盖**: 从需求分析、测试用例生成、脚本录制、执行监控到报告生成，提供完整的测试生命周期管理 - **🔒 企业级安全**: 采用 AES-256-GCM 加密、HMAC 签名验证、JWT 认证等多层安全机制，保障数据安全 - **⚡ 高性能**: 基于内存预加载、热更新、异步处理等技术，确保系统响应迅速、运行稳定 - **🎯 易于使用**: 提供直观的 Web 界面、树形配置管理、实时日志监控等，降低使用门槛 - **📚 智能知识库**: 基于向量数据库的文档智能问答系统，支持语义搜索和 RAG 增强 ### 版本信息 | 组件 | 版本 | 更新日期 | |------|------|----------| | 后端 | v2.7.0 | 2026-05-11 | | 前端 | v2.6.4 | 2026-01-25 | | Python | >=3.9 | - | | Node.js | >=16.0.0 | - | --- ## ✨ 功能特性 ### 🔧 核心功能 #### 1. 智能测试引擎 - **Playwright 引擎**: Playwright 1.59+ 现代浏览器自动化引擎 - **多浏览器兼容**: Chrome、Firefox、WebKit 全平台支持 - **智能元素定位**: 支持 XPath、CSS 选择器、AI 视觉识别等多种定位方式 - **自动等待机制**: 智能、显式、隐式等待策略，提升脚本稳定性 #### 2. AI 智能化模块 - **测试用例生成**: 基于 LLM 的需求分析和测试用例自动生成 - **UI 自动化测试**: AI 驱动的页面元素识别和操作序列生成 - **智能错误诊断**: 自动分析失败原因并提供修复建议 - **代码优化建议**: AI 辅助的脚本性能优化和最佳实践推荐 - **多模型支持**: 讯飞星火、阿里云百练、DeepSeek、公司 Dify 等多种 AI 提供商 #### 3. 配置管理中心 - **统一配置存储**: SystemConfigManager (数据库) 优先 + YAML 降级的双轨配置机制 - **可视化编辑器**: 树形结构的配置浏览和编辑界面 - **实时同步**: WebSocket 推送配置变更，毫秒级生效 - **版本控制**: 配置变更历史记录和回滚能力 - **加密存储**: 敏感配置项采用 AES-256-GCM 加密存储 - **智能加载**: 启动时自动检测最优配置源，支持端口范围验证和格式兼容 #### 4. 测试管理与执行 - **项目管理**: 多项目、多环境的测试组织方式 - **用例管理**: YAML 格式的测试用例编写和管理 - **批量执行**: 支持并发执行、定时任务、CI/CD 集成 - **实时监控**: WebSocket 实时推送执行进度和结果 - **报告生成**: Allure HTML 报告、PDF/Excel 导出 #### 5. 用户与权限系统 - **角色权限**: 管理员、测试员、普通用户三级权限体系 - **JWT 认证**: 安全的用户认证和会话管理 - **操作审计**: 完整的操作日志记录和追溯能力 #### 6. 文档智能问答系统 (新增) - **知识库管理**: 支持 `documents/` 目录下的子文件夹作为独立知识库 - **文档向量化**: 自动将文档转换为向量表示，支持批量处理 - **智能检索**: 基于嵌入模型的语义搜索，支持自然语言查询 - **RAG 增强**: 检索增强生成，提升 AI 回答质量和准确性 - **Qdrant 集成**: 高性能向量数据库用于文档存储和检索 - **并发控制**: 支持多文档同时处理，防止重复操作 #### 7. 高级录制器 (新增) - **可视化录制**: 无需编码的测试脚本录制界面 - **WebSocket 通信**: 实时双向通信，低延迟操作反馈 - **元素智能识别**: 自动识别页面元素并生成操作步骤 - **脚本导出**: 支持导出为多种测试框架格式 ### 🛠️ 高级特性 #### 性能优化 - ✅ 内存预加载：配置数据预加载到内存，响应时间 < 10ms - ✅ 热更新机制：配置变更即时生效，无需重启服务 - ✅ 异步处理：基于 asyncio 的全异步架构 - ✅ 连接池管理：数据库连接池优化，支持高并发 - ✅ 配置缓存：SystemConfigManager 缓存机制，减少数据库查询 #### 安全防护 - ✅ 加密传输：HTTPS + AES-256-GCM 端到端加密 - ✅ 签名验证：HMAC-SHA256 请求签名防篡改 - ✅ 密钥轮换：自动化的加密密钥轮换机制 - ✅ SQL 注入防护：参数化查询 + ORM 安全层 - ✅ XSS 防护：输入过滤 + 输出编码 - ✅ 路由级鉴权：细粒度的 API 访问控制 #### 可观测性 - ✅ 结构化日志：分级日志系统，支持敏感信息脱敏 - ✅ 性能监控：API 响应时间、资源使用率实时监控 - ✅ 错误追踪：完整的异常堆栈和上下文信息 - ✅ 审计日志：用户操作记录和安全事件追踪 - ✅ 启动性能指标：配置加载耗时统计和性能优化建议 --- ## 🏗️ 技术架构 ### 系统架构图 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 前端展示层 │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ React 18 │ │ Ant Design 5 │ │ CodeMirror │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ API 网关层 │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ FastAPI │ │ JWT Auth │ │ Rate Limit │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 业务逻辑层 │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │测试引擎 │ │AI 服务 │ │配置管理 │ │用户管理 │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │文档问答 │ │向量化服务 │ │高级录制 │ │ │ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 数据持久层 │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ SQLite │ │SQL Server│ │ Qdrant │ │ YAML │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 技术栈详情 | 层级 | 技术 | 说明 | |------|------|------| | **前端框架** | React 18.3 | 基于 Hooks 的函数式组件开发 | | **UI 库** | Ant Design 5.29 | 企业级 UI 组件库 | | **状态管理** | React Context + Hooks | 轻量级状态管理方案 | | **路由** | React Router DOM 7.12 | 客户端路由 | | **代码编辑** | CodeMirror 5.65 / Tiptap 3.22 | YAML/富文本编辑 | | **后端框架** | FastAPI 0.115 | 高性能异步 Web 框架 | | **ORM** | SQLAlchemy 2.0 | Python SQL 工具包 | | **ASGI 服务器** | Uvicorn 0.34 | 高性能 ASGI 实现 | | **测试引擎** | Playwright 1.59 | 浏览器自动化引擎 | | **数据库** | SQLite / SQL Server | 本地 + 业务数据库 | | **向量库** | Qdrant 1.7+ (可选) | 文档向量和语义搜索 | | **AI 集成** | OpenAI SDK / LangChain | 多模型统一调用接口 | | **加密** | cryptography 42.0 | AES-256-GCM + PBKDF2 | | **配置管理** | SystemConfigManager | 数据库优先的配置管理系统 | --- ## 🚀 快速开始 ### 最简启动（3 步上手） ```bash # 1. 克隆项目 git clone https://github.com/your-org/his-automated-testing.git cd his-automated-testing # 2. 安装依赖 python setup.py all # 3. 启动服务 python start_dev.py ``` 启动成功后： - **前端地址**: http://localhost:3000 - **后端 API**: http://localhost:8000 - **默认账号**: `admin` / `admin123` - **API 文档**: http://localhost:8000/docs --- ## 📦 安装指南 ### 环境要求 #### 必需环境 | 环境 | 最低版本 | 推荐版本 | 用途 | |------|----------|----------|------| | Python | 3.9+ | 3.11+ | 后端运行时 | | Node.js | 16.0+ | 18 LTS | 前端构建工具 | | npm | 8.0+ | 10+ | 包管理器 | | Chrome | 最新版 | 最新版 | 浏览器自动化 | | Git | 2.0+ | 最新版 | 版本控制 | #### 可选环境 | 环境 | 用途 | 安装说明 | |------|------|----------| | Docker | 容器化部署 | 可选，用于生产环境 | | Redis | 缓存/消息队列 | 可选，用于大规模部署 | | PostgreSQL | 替代 SQLite | 可选，用于生产环境 | | Qdrant | 向量数据库 | 用于文档智能问答功能 | #### 操作系统支持 - ✅ **macOS** 10.15+ (完全支持) - ✅ **Ubuntu** 20.04+ (完全支持) - ✅ **Windows** 10/11 (基本支持，部分功能受限) - ✅ **CentOS** 7+ (服务器部署) ### 一键安装 ```bash # 方式一：下载并安装所有依赖（需要联网） python setup.py all # 方式二：仅下载依赖包（离线准备） python setup.py download # 方式三：离线安装（从本地依赖目录安装） python setup.py install --offline # 方式四：自动确认所有提示 python setup.py all --yes ``` ### 手动安装 #### 1. Python 环境 ```bash # 创建虚拟环境（推荐） python -m venv .venv source .venv/bin/activate # Linux/macOS # 或 .venv\Scripts\activate # Windows # 升级 pip pip install --upgrade pip # 安装 Python 依赖 pip install -r requirements.txt # 如果使用 UV 包管理器（更快） uv pip install -r requirements.txt ``` #### 2. Node.js 环境 ```bash # 进入前端目录 cd his_platform/frontend # 安装依赖 npm install # 或使用 pnpm（更快） pnpm install # 返回项目根目录 cd ../.. ``` #### 3. ChromeDriver 同步 ```bash # 自动检测并下载对应版本的 ChromeDriver python browser_driver/sync_chromedriver.py ``` #### 4. 初始化数据库 ```bash # 执行数据库初始化脚本（首次启动会自动执行） python his_platform/backend/scripts/init_database.py ``` #### 5. 可选：安装 Qdrant 向量数据库 ```bash # 启动 Qdrant 服务（可选，用于 AI 知识库功能） python start_qdrant.py ``` ### 验证安装 ```bash # 检查 Python 依赖 python -c "import fastapi; print(f'FastAPI: {fastapi.__version__}')" python -c "import playwright; print('Playwright: OK')" # 检查 Node.js 依赖 cd his_platform/frontend && npm list --depth=0 # 运行健康检查测试 pytest specialized_tests/test_types/unit/ -v --tb=short ``` --- ## 💻 使用方法 ### 启动服务 #### 开发模式（推荐） ```bash # 启动完整服务（前端 + 后端） python start_dev.py # 仅启动后端 python start_dev.py --backend-only # Debug 模式（详细日志 + SQL 日志） python start_dev.py --debug ``` **启动选项说明**： | 参数 | 说明 | 示例 | |------|------|------| | `--debug` | 启用详细日志和 SQL 查询日志 | `python start_dev.py --debug` | | `--backend-only` | 仅启动后端服务 | `python start_dev.py --backend-only` | **启动输出示例**： ``` [INFO] 🔍 环境检测完成: development | 配置来源: system_config_table | 后端:8000 前端:3000 | 耗时: 15.23ms [INFO] ✅ 后端服务启动成功: http://localhost:8000 [INFO] ✅ 前端服务启动成功: http://localhost:3000 [INFO] 🎉 所有服务已就绪！ ``` #### 生产模式 ```bash # 后台运行后端 nohup uvicorn his_platform.backend.app.main:app \ --host 0.0.0.0 --port 8000 \ --workers 4 \ > logs/backend.log 2>&1 & # 构建并启动前端 cd his_platform/frontend npm run build npm start -- -p 3000 -s build ``` ### 访问系统 启动成功后，通过浏览器访问： | 服务 | 地址 | 说明 | |------|------|------| | **前端界面** | http://localhost:3000 | Web 管理界面 | | **API 文档** | http://localhost:8000/docs | Swagger UI 交互式文档 | | **ReDoc 文档** | http://localhost:8000/redoc | ReDoc 格式 API 文档 | | **健康检查** | http://localhost:8000/api/health | 服务健康状态 | ### 默认登录 - **用户名**: `admin` - **密码**: `admin123` - **角色**: 系统管理员 ⚠️ **安全提示**: 请在生产环境中立即修改默认密码！ ### 主要功能模块 #### 1. 🎯 Dashboard（仪表盘） 访问路径：`/dashboard` - 系统概览和关键指标 - 最近测试执行情况 - 待办任务和通知 #### 2. 🧪 测试管理 - **场景测试**: `/scenario-test` - 场景化测试用例管理 - **API 测试**: `/api-test` - 接口测试和调试 - **AI 智能测试**: `/ai-smart-test` - AI 驱动的智能测试 - **AI 测试中心**: `/ai-ui-test-center` - AI UI 自动化测试中心 - **高级录制器**: `/advanced-recorder` - 可视化脚本录制（无需认证即可使用） #### 3. 📄 文档中心 - **文档库**: `/document-library` - 测试文档管理 - **文档智能问答**: `/document-qa-workbench` - 基于知识库的 AI 问答系统（新增） - **文档分析**: `/doc-analysis` - AI 文档分析 - **知识库**: `/test-knowledge` - 测试知识积累 #### 4. ⚙️ 系统配置 - **全局配置**: `/global-config` - 系统参数配置（树形编辑器） - **项目管理**: `/project-config` - 多项目环境管理 - **菜单管理**: `/menu-management` - 自定义菜单 - **AI 配置管理**: `/ai-config-management` - AI 提供商和模型配置 #### 5. 👥 用户管理 - **用户管理**: `/user-management` - 用户账号管理 - **权限管理**: `/permission-manage` - 角色和权限分配 #### 6. 📊 报告中心 - **Allure 报告**: `/allure-reports` - 可视化测试报告 - **API 报告**: `/api-reports` - 接口测试统计 - **截图管理**: `/screenshots` - 失败截图查看 ### 执行测试 #### 通过 Web 界面 1. 登录系统 2. 进入"场景测试"或"API 测试"模块 3. 选择或创建测试用例 4. 点击"执行"按钮 5. 实时查看执行进度和结果 #### 通过命令行 ```bash # 运行所有测试 python specialized_tests/run_all_tests.py # 运行特定类型的测试 pytest specialized_tests/test_types/unit/ -v # 单元测试 pytest specialized_tests/test_types/api/ -v # API 测试 pytest specialized_tests/test_types/e2e/ -v # E2E 测试 pytest specialized_tests/test_types/integration/ -v # 集成测试 # 运行独立测试套件 python specialized_tests/interface/interface_test_suite.py # 运行带覆盖率报告的测试 pytest --cov=his_platform --cov-report=html ``` --- ## ⚙️ 配置说明 ### 主配置文件 **位置**: `config/settings.yaml` 这是系统的**唯一配置来源**（禁止使用环境变量配置），但实际加载时会遵循以下优先级： **配置加载优先级（严格模式，无硬编码默认值）**： 1️⃣ **SystemConfigManager** (system_config 表，AES-256 加密) - 最高优先级 2️⃣ **settings.yaml 明文文件** - 降级方案 3️⃣ ❌ **失败** - 记录日志，抛出异常 **设计原则**： - 所有配置必须来自外部源（DB 或 YAML 文件） - 禁止使用硬编码默认值，避免配置漂移 - 配置缺失时必须明确报错，便于快速定位问题 - 端口必须通过范围验证 (1-65535) #### 配置文件结构 ```yaml # ==================== 服务接口配置 ==================== Service_interface: backend_interface: 'localhost:8000' # 后端服务地址（支持格式：host:port 或纯 port） frontend_interface: 'localhost:3000' # 前端服务地址 # ==================== 测试环境配置 ==================== testServer: description: 测试环境配置 extranet_url: http://your-server:9090 # 外网地址 hospital_url: http://192.168.0.217:8180/webhis/ # HIS 地址 intranet_url: http://192.168.0.106:8180/webhis/ # 内网地址 test_account: your_account # 测试账号 test_password: your_password # 测试密码 test_role: 门诊收费处 # 测试角色 test_jg_name: 金渠卫生院 # 机构名称 test_jgid: "247" # 机构ID # ==================== AI 服务配置 ==================== ai_server: default_AI_service_provider: Company_Internal_dify # 默认 AI 提供商 default_model: Qwen3-32B-A6000 # 默认模型 providers: # 多提供商配置 Company_Internal_dify: provider_name: 公司Dify base_url: http://192.168.0.8:9001/v1/chat-messages models: Qwen3-32B-A6000: api_key: your-api-key is_default: true xunfei: provider_name: 讯飞星火 base_url: https://spark-api-open.xf-yun.com/x2 # ... 更多配置 aliyun: provider_name: 阿里云百练 base_url: https://dashscope.aliyuncs.com/compatible-mode/v1 # ... 更多配置 # ==================== 数据库配置 ==================== database_config: db_type: sqlserver # 数据库类型 database: YDHIS # 数据库名称 host: 192.168.0.100 # 数据库主机 port: 1433 # 端口 user: sa # 用户名 password: your_password # 密码 pool_size: 10 # 连接池大小 max_overflow: 5 # 最大溢出连接数 # ==================== 引擎配置 ==================== engineType: default_engine: playwright # 默认引擎: playwright # ==================== 安全配置 ==================== security_config: encryption_password: your_secure_password encryption_salt: your_secure_salt key_management: enabled: true rotation: auto_rotate: true encryption_key_ttl_days: 30 # 密钥轮换周期（天） # ==================== 日志配置 ==================== logging: level: INFO # 日志级别: DEBUG/INFO/WARNING/ERROR file: max_size_mb: 50 # 单个日志文件最大大小 backup_count: 5 # 保留备份数量 retention_days: 30 # 日志保留天数 sensitive_filter: enabled: true # 启用敏感信息过滤 ``` #### 配置格式兼容性 系统支持多种端口配置格式： | 格式 | 示例 | 说明 | |------|------|------| | 标准 `host:port` | `localhost:8000` | 推荐格式 | | 纯数字 | `8000` | 仅端口号 | | 带空格 | ` localhost : 8000 ` | 自动去除空格 | **错误处理示例**： ``` ❌ 配置加载失败！所有数据源均无法获取有效端口配置。 尝试的数据源: 1. SystemConfigManager (system_config表): ✅ 已尝试 2. settings.yaml文件 (config/settings.yaml): ✅ 已尝试 错误详情 (2个): 1. SCM配置项为空: backend_interface 或 frontend_interface 缺失 2. YAML后端配置项为空 解决方案: 1. 确保 config/settings.yaml 存在且包含 Service_interface 节点 示例: Service_interface: backend_interface: 'localhost:8000' frontend_interface: 'localhost:3000' 2. 或启动一次完整初始化: python start_dev.py 3. 检查数据库是否损坏: sqlite3 his_platform.db 'PRAGMA integrity_check;' ``` ### 数据库配置 平台使用**双数据库架构**： #### 1. 平台本地数据库 (SQLite) **用途**: 存储用户、权限、配置、测试元数据等 **位置**: `his_platform/backend/data_storage/his_platform.db`（由 SQLiteDatabase 类自动计算） **配置**: ```yaml user_database_config: db_type: sqlite database_path: his_platform/backend/data_storage/his_platform.db journal_mode: WAL # WAL 模式提升并发性能 synchronous: NORMAL # 同步模式 auto_vacuum: true # 自动清理 ``` **主要表**: | 表名 | 用途 | |------|------| | `users` | 用户账号信息 | | `roles` | 角色定义 | | `permissions` | 权限项 | | `secure_config_keys` | 加密配置项 | | `system_config` | 系统配置（AES-256 加密） | | `test_projects` | 测试项目 | | `test_cases` | 测试用例 | | `conversations` | AI 对话记录 | | `conversation_messages` | 对话消息详情 | #### 2. 业务数据库 (SQL Server) **用途**: 存储 HIS 业务数据、测试数据等 **配置**: ```yaml database_config: db_type: sqlserver host: 192.168.0.100 port: 1433 database: YDHIS user: sa password: your_password ``` ### AI 服务配置 平台支持**多 AI 提供商**，可灵活切换： #### 支持的提供商 | 提供商 | 模型 | 适用场景 | 特点 | |--------|------|----------|------| | **公司 Dify** | Qwen3-32B-A6000 | 通用场景（默认） | 内网访问，低延迟 | | **讯飞星火** | x1 (高级) / lite (轻量) | 中文场景 | 中文理解能力强 | | **阿里云百练** | qwen3.5 系列 | 长文本/复杂推理 | 上下文窗口大 | | **DeepSeek** | DeepSeek-V3.2 | 代码生成 | 编程能力强 | | **scent 超算** | Qwen3-30B | 高性能计算 | 算力强大 | #### 配置示例 ```yaml ai_server: default_AI_service_provider: xunfei # 切换默认提供商 providers: xunfei: provider_name: 讯飞星火 auth_type: mixed # 认证类型: api_key/mixed base_url: https://spark-api-open.xf-yun.com/x2 websocket_config: APPID: your_app_id APISecret: your_api_secret APIKey: your_api_key models: x1: model_id: x1 description: 高级版模型 is_default: true ``` ### 安全配置 #### 加密机制 平台采用**多层加密体系**： ``` 请求流程: 客户端 → HMAC签名 → AES加密 → HTTPS传输 → 服务端验证解密 加密算法: - 对称加密: AES-256-GCM (数据加密) - 密钥派生: PBKDF2-HMAC-SHA256 (密钥 derivation) - 签名验证: HMAC-SHA256 (防篡改) - 密码哈希: bcrypt (密码存储) ``` #### 密钥管理 ```yaml security_config: encryption_password: your_master_password # 主密码 encryption_salt: your_unique_salt # 盐值 key_management: enabled: true rotation: auto_rotate: true # 自动轮换 encryption_key_ttl_days: 30 # 密钥有效期 max_key_versions: 3 # 保留历史密钥数 key_info: algorithm: AES-256-GCM # 加密算法 signature_algorithm: HMAC-SHA256 # 签名算法 storage: encrypted # 存储方式: encrypted key_file_permissions: "0600" # 文件权限 ``` #### 环境变量（可选） 虽然主要配置在 YAML 中，但以下环境变量可用于特殊场景： | 变量名 | 用途 | 示例 | |--------|------|------| | `APP_MASTER_KEY` | 应用主密钥（最高优先级） | `base64 encoded key` | | `PYTHONPATH` | Python 模块搜索路径 | `/path/to/project` | | `NODE_ENV` | Node.js 运行环境 | `development/production` | --- ## 📁 项目结构 ``` automated_testing/ ├── 📋 项目根目录文件 │ ├── AGENTS.md # AI Agent 开发指南 │ ├── main.py # Python 入口文件 │ ├── launcher.py # 应用启动器 │ ├── start_dev.py # 开发环境启动脚本（含端口验证和配置解析） │ ├── start_qdrant.py # Qdrant 向量数据库启动脚本 │ ├── setup.py # 一键安装脚本 │ ├── requirements.txt # Python 依赖 │ └── README.md # 项目文档（本文件） │ ├── ⚙️ config/ # 配置文件目录 │ ├── settings.yaml # 主配置文件（唯一配置来源） │ ├── environments/ # 环境配置 │ │ ├── development.yaml # 开发环境 │ │ ├── production.yaml # 生产环境 │ │ └── test.yaml # 测试环境 │ └── security/ # 安全相关配置 │ └── key_management_service.py │ ├── 🎨 his_platform/ # 主应用目录 │ ├── backend/ # 后端服务 (FastAPI) │ │ ├── app/ │ │ │ ├── main.py # FastAPI 应用入口 │ │ │ ├── routes/ # API 路由 │ │ │ │ ├── ai_services/ # AI 服务接口（含公共路由和私有路由） │ │ │ │ ├── knowledge/ # 知识库接口 │ │ │ │ ├── config_service/ # 配置管理接口 │ │ │ │ ├── storage_service/documents/ # 文档服务和向量化路由 │ │ │ │ │ ├── interfaces/routes/document_routes.py # 含向量化路由集成 │ │ │ │ │ └── config.py # 文档存储路径配置 │ │ │ │ └── recording/ # 录制器路由（WebSocket 无需认证） │ │ │ ├── services/ # 业务逻辑服务 │ │ │ ├── utils/ # 工具类 │ │ │ │ ├── logging/ # 日志系统（优化后的配置表驱动日志） │ │ │ │ │ └── logger.py # 日志配置和实现 │ │ │ │ ├── security/ # 安全工具 │ │ │ │ ├── ai_providers/ # AI 提供商适配 │ │ │ │ ├── structured_config.py # SystemConfigManager 配置管理 │ │ │ │ └── config_accessor.py # 配置访问器 │ │ │ └── models/ # 数据模型 │ │ ├── tests/ # 后端测试 │ │ ├── scripts/ # 维护脚本 │ │ │ └── init_database.py # 数据库初始化（单入口，幂等性） │ │ └── data_storage/ # 数据存储目录 │ │ └── his_platform.db # SQLite 数据库 │ │ │ └── frontend/ # 前端应用 (React) │ ├── src/ │ │ ├── pages/ # 页面组件 │ │ │ ├── GlobalConfig/ # 全局配置页面 │ │ │ ├── AITestCenter/ # AI 测试中心 │ │ │ ├── DocumentQaWorkbench.js # 文档智能问答（新增） │ │ │ ├── AIConfigManagement.js # AI 配置管理 │ │ │ └── ... │ │ ├── components/ # 公共组件 │ │ ├── services/ # API 服务层 │ │ │ └── vectorization-api.js # 向量化 API 服务 │ │ ├── hooks/ # 自定义 Hooks │ │ └── App.js # 应用入口 │ ├── package.json # 前端依赖 │ └── public/ # 静态资源 │ ├── 🧪 specialized_tests/ # 专业测试套件 │ ├── run_all_tests.py # 测试运行器 │ └── test_types/ │ ├── unit/ # 单元测试 │ ├── api/ # API 测试 │ ├── e2e/ # E2E 测试 │ └── integration/ # 集成测试 │ ├── 🔧 tools/ # 工具脚本 │ ├── cleanup/ # 环境清理工具 │ │ ├── cleanup_environment.py │ │ └── cleanup_metadata.py │ ├── qdrant/ # Qdrant 管理 │ │ ├── start_qdrant.py │ │ └── stop_qdrant.py │ └── setup/ # 安装工具 │ └── download_embedding_model.py │ ├── 🧪 tests/ # 手动测试脚本 │ └── manual/ │ ├── test_ai_integration_e2e.py │ └── test_ai_security_fixes.py │ ├── 📚 docs/ # 项目文档 │ ├── API_DOCUMENTATION.md │ ├── SECURE_CONFIG_DESIGN.md │ └── TOOLS_CLASSIFICATION.md │ ├── 📚 Tutorial_document/ # 教程文档 ├── 📚 ModelPrompts/ # AI Prompt 模板 ├── 📚 ModelSkils/ # AI Skill 定义 │ ├── 🗄️ V2/ # V2 版本遗留代码（已弃用 Selenium 框架） │ ├── 🌐 documents/ # 文档存储目录（知识库根目录） │ ├── knowledge_base_1/ # 知识库 1 │ ├── knowledge_base_2/ # 知识库 2 │ └── ... │ ├── 🌐 browser_driver/ # 浏览器驱动管理 ├── 🌐 cicd/ # CI/CD 配置 │ └── 📊 logs/ # 日志目录 ├── backend_YYYYMMDD.log # 后端日志 └── frontend_YYYYMMDD.log # 前端日志 ``` --- ## 🧪 测试指南 ### 运行所有测试（推荐） ```bash python specialized_tests/run_all_tests.py ``` 这将运行完整的测试套件，包括： - 单元测试 - API 接口测试 - E2E 端到端测试 - 集成测试 ### 后端系统测试（新增） ```bash # 运行所有后端系统测试 pytest his_platform/backend/tests/ -v --tb=short # 按模块运行 pytest his_platform/backend/tests/test_system_config.py -v # 系统配置 pytest his_platform/backend/tests/test_system_health.py -v # 健康检查 pytest his_platform/backend/tests/test_system_data.py -v # 数据层 pytest his_platform/backend/tests/test_system_auth.py -v # 认证授权 pytest his_platform/backend/tests/test_system_api.py -v # API 接口 pytest his_platform/backend/tests/test_system_security.py -v # 安全防护 ``` ### 性能与并发测试（新增） ```bash # 性能基准测试 pytest his_platform/backend/tests/test_benchmark_suite.py -v # 并发场景测试 pytest his_platform/backend/tests/test_concurrency_scenarios.py -v # WebSocket 扩展测试 pytest his_platform/backend/tests/test_websocket_extended.py -v ``` ### 前端测试（新增） ```bash # 组件测试 (Vitest) cd his_platform/frontend && npx vitest run # E2E 测试 (Cypress) cd his_platform/frontend && npx cypress run ``` ### 按类型运行 #### 单元测试 ```bash # 运行所有单元测试 pytest specialized_tests/test_types/unit/ -v # 运行特定测试文件 pytest specialized_tests/test_types/unit/test_config_adapter.py -v # 运行带详细输出的测试 pytest specialized_tests/test_types/unit/ -v -s # CI 命令（排除特定测试） pytest specialized_tests/test_types/unit/ specialized_tests/test_types/integration/ \ --ignore=test_types/unit/backend/test_llm_document_processor.py \ --ignore=test_types/unit/test_file_validation.py -x ``` #### API 测试 ```bash # 运行 API 测试 pytest specialized_tests/test_types/api/ -v # 运行特定 API 测试 pytest specialized_tests/test_types/api/test_health_check.py -v ``` #### E2E 测试 ```bash # 运行 E2E 测试（需要启动服务） pytest specialized_tests/test_types/e2e/ -v # 运行特定的 E2E 测试 pytest specialized_tests/test_types/e2e/test_login_flow.py -v ``` #### 集成测试 ```bash # 运行集成测试 pytest specialized_tests/test_types/integration/ -v ``` ### 独立测试套件 ```bash # 接口测试套件 python specialized_tests/interface/interface_test_suite.py # CRUD 功能测试 python his_platform/backend/test_service_interface_crud.py # 安全修复验证 python his_platform/backend/tests/test_security_fixes.py ``` ### 测试选项 ```bash # 显示进度条 pytest -v # 只运行失败的测试 pytest --lf # 并行运行（需要 pytest-xdist） pytest -n auto # 生成覆盖率报告 pytest --cov=his_platform --cov-report=html --cov-report=term # 生成 Allure 报告 pytest --alluredir=allure-results allure serve allure-results # 运行特定标记的测试 pytest -m "slow" # 运行标记为 slow 的测试 pytest -m "not slow" # 排除 slow 测试 ``` ### 测试数据管理 测试完成后清理环境： ```bash # 清理测试环境 python tools/cleanup/cleanup_test_environment.py # 清理元数据和向量数据 python tools/cleanup/cleanup_metadata.py # 全面清理（慎用！） python tools/cleanup/cleanup_environment.py ``` --- ## 📚 API 文档 ### 在线文档 启动服务后访问： - **Swagger UI**: http://localhost:8000/docs - **ReDoc**: http://localhost:8000/redoc ### 核心 API 端点 #### 认证接口 | 方法 | 端点 | 说明 | 认证 | |------|------|------|------| | POST | `/api/auth/login` | 用户登录 | 无需 | | POST | `/api/auth/logout` | 用户登出 | 需要 | | POST | `/api/auth/refresh` | 刷新 Token | 无需 | | GET | `/api/auth/me` | 获取当前用户信息 | 需要 | #### 配置管理接口 | 方法 | 端点 | 说明 | 认证 | |------|------|------|------| | GET | `/api/settings/global-config` | 获取全局配置 | 需要 | | PUT | `/api/settings/global-config` | 更新全局配置 | 需要 | | POST | `/api/settings/sync` | 同步配置到 YAML | 需要 | | GET | `/api/settings/config-tree` | 获取配置树结构 | 需要 | #### 测试执行接口 | 方法 | 端点 | 说明 | 认证 | |------|------|------|------| | POST | `/api/tests/execute` | 执行测试 | 需要 | | GET | `/api/tests/{id}/result` | 获取测试结果 | 需要 | | GET | `/api/tests/history` | 获取执行历史 | 需要 | | WebSocket | `/ws/tests/execution` | 实时执行进度 | 需要 | #### AI 服务接口 | 方法 | 端点 | 说明 | 认证 | |------|------|------|------| | GET | `/ai/providers` | 获取可用 AI 提供商列表 | **无需** | | POST | `/ai/chat` | AI 对话 | 需要 | | POST | `/ai/generate-testcase` | 生成测试用例 | 需要 | | POST | `/ai/analyze-ui` | 分析 UI 元素 | 需要 | #### 文档和向量化接口（新增） | 方法 | 端点 | 说明 | 认证 | |------|------|------|------| | GET | `/documents` | 获取文档列表 | 需要 | | GET | `/documents/stats` | 获取文档统计信息 | 需要 | | POST | `/documents/{doc_id}/build-index` | 触发文档向量化 | 需要 | | GET | `/documents/{doc_id}/index-status` | 获取向量化状态 | 需要 | | GET | `/knowledge-bases` | 获取知识库列表 | 需要 | #### 高级录制器接口 | 方法 | 端点 | 说明 | 认证 | |------|------|------|------| | WebSocket | `/ws/recording/advanced` | 高级录制器 WebSocket 连接 | **无需** | ### 使用示例 #### 登录获取 Token ```bash curl -X POST http://localhost:8000/api/auth/login \ -H "Content-Type: application/json" \ -d '{"username": "admin", "password": "admin123"}' ``` 响应： ```json { "access_token": "eyJhbGciOiJIUzI1NiIs...", "token_type": "bearer", "expires_in": 28800, "user": { "username": "admin", "role": "admin" } } ``` #### 使用 Token 访问受保护接口 ```bash curl -X GET http://localhost:8000/api/settings/global-config \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." ``` #### 调用 AI 接口（无需认证） ```bash curl -X GET http://localhost:8000/ai/providers ``` 响应： ```json { "providers": ["openai", "xunfei", "aliyun"] } ``` --- ## 👨💻 开发指南 ### 代码规范 #### Python 代码规范 ```bash # 代码格式化 black his_platform/ tools/ specialized_tests/ # 导入排序 isort his_platform/ tools/ specialized_tests/ # 代码检查 flake8 his_platform/ --max-line-length=120 # 类型检查 mypy his_platform/ ``` #### JavaScript 代码规范 ```bash cd his_platform/frontend # ESLint 检查 npm run lint # 自动修复 npm run lint:fix # Prettier 格式化 npm run format # 检查格式 npm run format:check ``` ### 调试模式 #### 启动 Debug 模式 ```bash python start_dev.py --debug ``` Debug 模式将启用： - 详细 DEBUG 级别日志 - SQL 查询日志 - 请求/响应完整日志 - 热重载（如果可用） #### VSCode 调试配置 创建 `.vscode/launch.json`： ```json { "version": "0.2.0", "configurations": [ { "name": "FastAPI Debug", "type": "python", "request": "launch", "module": "uvicorn", "args": [ "his_platform.backend.app.main:app", "--host", "localhost", "--port", "8000", "--reload" ], "cwd": "${workspaceFolder}", "env": { "PYTHONPATH": "${workspaceFolder}" } }, { "name": "Start Dev Server Debug", "type": "python", "request": "launch", "program": "start_dev.py", "args": ["--debug"], "console": "integratedTerminal", "cwd": "${workspaceFolder}" } ] } ``` ### 日志系统 #### 日志配置（优化后） 日志系统采用**配置表驱动**设计，不再依赖外部文件进行初始配置： **核心特性**： - ✅ 启动时无冗余配置文件查找操作 - ✅ 配置表设置与日志需求自动协调 - ✅ 日志配置正确初始化（使用配置表值） - ✅ 清晰的配置分离（日志配置 vs 应用设置） - ✅ 性能指标：启动时间和资源利用率测量 - ✅ 向后兼容现有日志实践 #### 日志配置示例 ```yaml logging: level: INFO # 全局日志级别 console_level: INFO # 控制台输出级别 file_level: INFO # 文件输出级别 format: "[%(asctime)s] %(levelname)s - %(name)s - %(message)s" file: max_size_mb: 50 # 单个文件最大 50MB backup_count: 5 # 保留 5 个备份 retention_days: 30 # 保留 30 天 ``` #### 日志文件位置 ``` logs/ ├── backend_YYYYMMDD.log # 后端日志 ├── frontend_YYYYMMDD.log # 前端日志 └── test_YYYYMMDD.log # 测试日志 ``` #### 敏感信息过滤 系统自动过滤以下敏感字段： - `password`, `password_hash` - `api_key`, `api_secret` - `token`, `secret` - `private_key` 示例日志输出： ``` [2026-05-11 10:30:45] INFO - app.routes.authentication - User admin logged in successfully [2026-05-11 10:30:46] WARNING - app.utils.security - Invalid token provided [2026-05-11 10:30:47] INFO - 🔍 环境检测完成: development | 配置来源: system_config_table | 后端:8000 前端:3000 | 耗时: 15.23ms ``` #### 启动性能指标 启动时会输出配置加载性能指标： ``` [INFO] 🔍 环境检测完成: development | 配置来源: system_config_table | 后端:8000 前端:3000 | 耗时: 15.23ms ``` 字段说明： - `environment`: 当前运行环境（development/production） - `config_source`: 配置来源（system_config_table/settings_yaml/mixed_scm_yaml） - `backend_port`: 后端服务端口 - `frontend_port`: 前端服务端口 - `elapsed_ms`: 配置加载耗时（毫秒） --- ## 🚢 部署指南 ### 开发环境部署 参考 [快速开始](#快速开始) 部分。 ### 生产环境部署 #### 1. 系统要求 - **CPU**: 4 核+ - **内存**: 8 GB+ - **磁盘**: 50 GB SSD - **网络**: 稳定的内网连接 #### 2. 环境准备 ```bash # 创建专用用户 sudo useradd -m -s /bin/bash his_tester sudo su - his_tester # 克隆代码 git clone