docs/services.spec.md

服务层规格说明 — 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端到端测试
• 性能基准测试