jortiz775/ai-ticket-triage-assistant

# AI 票据分级助手 AI 票据分级助手是一款由大型语言模型（LLM）驱动的内部支持工具，帮助工程和支持团队快速且一致地分析技术事件。 ## 功能 - 通过单个 API 调用分析自由格式的支持票据 - 结构化输出包括摘要、严重性、类别、根本原因假设、故障排除步骤和建议的响应 - 基于 FastAPI 的后端，具有 Pydantic 请求/响应验证 - 与 OpenAI 集成，具有严格的 JSON 提示 - 当 `OPENAI_API_KEY` 未设置时，安全的演示模式回退 - 基于 React + TypeScript 的前端，用于交互式票据分析 - 使用 Pytest 进行后端测试 - 使用 Vitest + React Testing Library 进行前端测试 - 使用 Playwright 进行端到端测试（API + 浏览器 UI，截图提交到仓库） - 使用 GitHub Actions CI 进行测试和构建验证 - Docker 和 docker-compose 设置用于本地容器化运行 ## 技术栈 - **后端:** Python 3.11+, FastAPI, Pydantic, OpenAI SDK, python-dotenv - **前端:** React, TypeScript, Vite, CSS - **测试:** Pytest, Vitest, React Testing Library, Playwright (端到端) - **CI/CD:** GitHub Actions ## 架构概述 - **前端 (`frontend/`)** 将票据文本发送到后端端点 - **后端 (`backend/`)** 验证有效负载，调用票据分析服务，并返回结构化 JSON - **服务层** 支持： - 正常模式下的 OpenAI 驱动的分析 - 演示模式下的确定性模拟分析（无 API 密钥） ## 文件结构 ``` ai-ticket-triage-assistant/ README.md .gitignore .env.example Dockerfile docker-compose.yml backend/ requirements.txt main.py app/ models/ ticket.py services/ ticket_analyzer.py routes/ analyze.py tests/ test_api.py frontend/ package.json index.html src/ App.tsx main.tsx api.ts types.ts App.css __tests__/ App.test.tsx .github/ workflows/ ci.yml ``` ## 本地设置（Windows） Python 3.11 是必需的。如果尚未安装，请使用 winget： ``` winget install Python.Python.3.11 --scope user --accept-package-agreements --accept-source-agreements ``` ### 后端设置 ``` cd backend python -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -r requirements.txt ``` 从 `backend/` 目录启动后端 — 这是为了确保 `python-dotenv` 可以在项目根目录中找到 `.env` 文件： ``` # 始终从后端/运行 — 不要从项目根目录运行 cd backend uvicorn main:app --reload --host 0.0.0.0 --port 8000 ``` 后端 API 将在 `http://localhost:8000` 上可用。 交互式 API 文档：`http://localhost:8000/docs`。 ### 前端设置 ``` cd frontend npm install npm run dev ``` 前端应用将在 `http://localhost:5173` 上可用。 ## 环境变量 将 `.env.example` 复制到项目根目录中的 `.env` 并填写您的密钥： ``` Copy-Item .env.example .env ``` ``` OPENAI_API_KEY=sk-...your-key-here... OPENAI_MODEL=gpt-4o-mini ``` ### OpenAI API 密钥 — 最小权限设置 此应用仅调用 **Chat Completions** 端点。当在 [platform.openai.com/api-keys](https://platform.openai.com/api-keys) 创建密钥时： 1. 创建一个专门的 **项目**（例如 `ai-ticket-triage`）以限制密钥的作用域。 2. 仅授予 **模型能力 → 写入**。 3. 关闭所有其他权限（文件、助手、微调等）。 `.env` 文件列在 `.gitignore` 中，永远不会被提交。 ### 演示模式（无 API 密钥） 如果 `OPENAI_API_KEY` 为空，则应用以 **演示模式** 运行：后端 返回使用关键字匹配的确定性模拟响应。不进行外部 调用。这对于开发和 UI 测试很有用。 ### 故障排除：过时的后端进程 如果即使在设置 API 密钥后 UI 仍然返回通用响应，则可能仍然有从不同目录启动的过时 后端进程在响应请求（旧进程加载时没有 `.env` 密钥）。 **修复方法：** 杀死端口 8000 上的所有进程，并从 `backend/` 重新启动： ``` # 查找并终止陈旧进程 netstat -ano | Select-String ":8000" Stop-Process -Id -Force # 重启清理 Set-Location backend & ".venv\Scripts\python.exe" -m uvicorn main:app --reload --host 0.0.0.0 --port 8000 ``` 可选： - `OPENAI_BASE_URL` 用于兼容 OpenAI 的提供商（有助于未来的 Azure OpenAI 适配） - `BACKEND_CORS_ORIGINS` 允许的源逗号分隔列表 - `VITE_API_BASE_URL` 前端 API 基础 URL（默认为 `http://localhost:8000`） ## 如何运行测试 ### 后端（Pytest） FastAPI 路由和模拟/真实分析逻辑的单元测试。 从 `backend/` 目录运行，激活虚拟环境： ``` cd backend .\.venv\Scripts\Activate.ps1 # activate the venv (Windows) pytest -q ``` 预期输出：所有测试通过，无需外部 API 调用（当 `OPENAI_API_KEY` 未设置时自动使用模拟模式）。 ### 前端（Vitest） 使用 React Testing Library 的组件测试 — 无需浏览器或服务器： ``` cd frontend npm run test -- --run # run once and exit ``` 要验证生产构建编译时没有 TypeScript 错误： ``` npm run build ``` ### 端到端（Playwright） 浏览器 + API 集成测试。Playwright **在测试运行之前自动启动两个服务器**，因此您无需手动启动它们。 #### 运行所有端到端测试（后端 API + 浏览器 UI） ``` # 从项目根目录 npm run test:e2e ``` #### 仅运行后端 API 测试（无浏览器） ``` npm run test:e2e:api ``` #### 仅运行浏览器 UI 测试 ``` npm run test:e2e:ui ``` #### 查看 HTML 报告 运行后，在您的浏览器中打开交互式报告： ``` npm run report ``` 报告在 `http://localhost:9323` 打开，包含每个测试步骤及其 内嵌的截图。 #### 提交的截图 每个测试步骤的命名截图都保存到 `screenshots/` 并提交到存储库，以便您可以在不运行它的情况下查看应用程序： | 文件 | 显示内容 | |---|---| | `01-page-load.png` | 初始页面，表单为空 | | `02-empty-validation-error.png` | 空提交时的验证错误 | | `03-all-samples-verified.png` | 所有三个样本按钮已验证 | | `04-ticket-entered.png` | 在文本区域中键入的票据文本 | | `05-analysis-results.png` | 完整的 AI 分析结果面板 | | `06-button-disabled-while-loading.png` | 在 API 调用期间按钮被禁用 | ## 示例输入 ``` { "ticket": "Users report 500 errors in the billing API after today's deployment." } ``` ## 示例输出 ``` { "summary": "Users report 500 errors in the billing API after today's deployment", "severity": "High", "category": "API", "possible_root_cause": "Likely configuration drift, dependency issue, or transient platform instability based on ticket symptoms.", "troubleshooting_steps": [ "Review recent deployments and configuration changes around the incident time.", "Check service logs, traces, and monitoring alerts for correlated errors.", "Validate dependent services, credentials, and network connectivity." ], "suggested_response": "Thank you for the detailed report. We are actively investigating this issue and have started with log analysis and dependency validation. We will share an update with findings and next actions shortly." } ``` ## 未来改进 - 添加身份验证和基于角色的访问 - 添加已分析票据的持久历史记录 - 添加置信度评分和事件趋势仪表板 - 添加一流的 Azure OpenAI 客户端适配器 - 添加外部 LLM 调用的重试/退避策略和遥测 ## 简历要点 - 使用 **FastAPI + React/TypeScript** 构建**端到端 LLM 驱动的票据分级助手**，具有严格的 JSON 结构化输出、具有演示回退的 OpenAI 集成、全面测试覆盖和通过 GitHub Actions 的 CI 自动化。

标签：API集成, AV绕过, Azure OpenAI, Docker, FastAPI, GitHub Actions, LLM, NIDS, OpenAI, Playwright, Pydantic, Pytest, React, React Testing Library, Syscalls, TypeScript, Unmanaged PE, Vitest, 严重程度评估, 云工程, 人工智能, 内存规避, 可观测性, 后端开发, 大语言模型蜜罐, 安全插件, 安全防御评估, 容器化, 开源框架, 技术分类, 持续部署, 持续集成, 支持工单, 故障排除, 测试驱动开发, 用户模式Hook绕过, 结构化数据, 自动笔记, 请求拦截, 逆向工具