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