Spaces:
Sleeping
Sleeping
| # 服务层规格说明 — Services Specification | |
| ## 概述 | |
| 服务层采用薄包装（Thin Wrapper）设计模式，主要负责输入验证、错误处理和委托调用。核心业务逻辑集中在LLM服务层。 | |
| ## 1. 分析服务 (`src/services/analyse_service.py`) | |
| ### 1.1 功能职责 | |
| - 工作描述和用户信息的分析请求处理 | |
| - 基于反馈的分析结果优化 | |
| - 输入参数验证和错误处理 | |
| ### 1.2 主要接口 | |
| #### `analyse(jd: str, user_info: str) -> Dict[str, Any]` | |
| **功能**: 分析职位描述和用户背景，生成匹配度分析报告 | |
| **参数**: | |
| - `jd`: 职位描述文本，不能为空 | |
| - `user_info`: 用户简历/背景信息，不能为空 | |
| **返回值**: 结构化分析结果字典，包含： | |
| - key_skills: 提取的关键技能列表 | |
| - match_points: 匹配的优势点列表 | |
| - gap_points: 不足或差距点列表 | |
| - suggestions: 改进建议列表 | |
| - pitch: 简短自我推销文本 | |
| **异常处理**: 当输入参数为空时抛出 ValueError | |
| **处理流程**: | |
| 1. 验证输入参数非空 | |
| 2. 委托给 llm_service.analyse_llm() | |
| 3. 返回结构化分析结果 | |
| #### `refine(summary: Dict[str, Any], feedback: str) -> Dict[str, Any]` | |
| **功能**: 基于用户反馈优化分析结果 | |
| **参数**: | |
| - `summary`: 之前的分析结果，不能为空 | |
| - `feedback`: 用户反馈和优化要求，不能为空 | |
| **返回值**: 优化后的分析结果（与analyse函数格式相同） | |
| **异常处理**: 当输入参数为空时抛出 ValueError | |
| **处理流程**: | |
| 1. 验证输入参数非空 | |
| 2. 委托给 llm_service.refine_llm() | |
| 3. 返回更新的分析结果 | |
| ## 2. 生成服务 (`src/services/generation_service.py`) | |
| ### 2.1 功能职责 | |
| - 编排简历和求职信的并行生成 | |
| - 确保生成内容的一致性和质量 | |
| - 统一的错误处理和验证 | |
| ### 2.2 主要接口 | |
| #### `generate_both(summary: Dict[str, Any], user_info: str) -> Tuple[str, str]` | |
| **功能**: 基于分析结果和用户信息生成简历和求职信 | |
| **参数**: | |
| - `summary`: 分析服务返回的结构化分析结果 | |
| - `user_info`: 用户原始简历/背景信息 | |
| **返回值**: 元组 (resume_markdown, cover_letter_text) | |
| - resume_markdown: Markdown格式的简历内容 | |
| - cover_letter_text: 纯文本格式的求职信内容 | |
| **异常处理**: 当输入参数为空时抛出 ValueError，传递LLM服务层的所有异常 | |
| **处理流程**: | |
| 1. 验证输入参数非空 | |
| 2. 并行调用LLM服务生成简历和求职信 | |
| 3. 返回生成结果元组 | |
| ## 3. LLM服务 (`src/services/llm_service.py`) | |
| ### 3.1 功能职责 | |
| - 核心LLM交互逻辑 | |
| - JSON响应解析和错误处理 | |
| - 提示词模板管理和调用 | |
| - 与LiteLLM客户端的集成 | |
| ### 3.2 核心接口 | |
| #### 分析相关 | |
| - `analyse_llm()`: 调用LLM进行职位匹配度分析 | |
| - `refine_llm()`: 基于反馈优化分析结果 | |
| #### 生成相关 | |
| - `generate_resume_llm()`: 生成Markdown格式简历 | |
| - `generate_cover_letter_llm()`: 生成纯文本求职信 | |
| #### 工具函数 | |
| - `_parse_json_response()`: 解析LLM返回的JSON响应，处理代码块包装 | |
| ### 3.3 处理流程 | |
| **标准分析流程**: | |
| 1. 获取分析提示词模板 | |
| 2. 格式化提示词（插入参数） | |
| 3. 调用LLM API | |
| 4. 解析JSON响应 | |
| 5. 返回结构化结果 | |
| **JSON解析逻辑**: | |
| - 检测并处理 ```json 代码块包装 | |
| - 提取纯JSON内容 | |
| - 解析为Python字典 | |
| - 异常处理和错误消息 | |
| ## 4. 服务层交互流程 | |
| ### 4.1 标准工作流 | |
| 用户输入 → analyse_service.analyse() → llm_service.analyse_llm() → 分析结果 | |
| ↓ | |
| 分析结果 → generation_service.generate_both() → llm_service.generate_*() → 简历+求职信 | |
| ### 4.2 优化迭代流程 | |
| 用户反馈 → analyse_service.refine() → llm_service.refine_llm() → 更新分析 | |
| ↓ | |
| 更新分析 → generation_service.generate_both() → llm_service.generate_*() → 更新文档 | |
| ## 5. 错误处理策略 | |
| ### 5.1 输入验证 | |
| - 服务层边界进行输入验证 | |
| - 空值检查和类型验证 | |
| - 统一异常格式 ValueError | |
| ### 5.2 LLM调用异常 | |
| - 网络超时和连接错误 | |
| - API密钥验证失败 | |
| - 模型不可用或限额超限 | |
| - JSON解析失败处理 | |
| ### 5.3 业务逻辑异常 | |
| - 模板参数缺失 | |
| - 响应格式不符合预期 | |
| - 用户友好错误消息 | |
| ## 6. 扩展和优化 | |
| ### 6.1 性能优化 | |
| - 生成请求并行化（当前为串行） | |
| - 响应结果缓存 | |
| - 超时设置和资源管理 | |
| ### 6.2 功能扩展 | |
| - 添加数据验证（使用Pydantic） | |
| - 重试机制（使用tenacity） | |
| - 异步处理支持 | |
| - 缓存层集成 | |
| ### 6.3 测试策略 | |
| - 单元测试覆盖输入验证 | |
| - 模拟LLM服务集成测试 | |
| - 使用mock_data端到端测试 | |
| - 性能基准测试 |