docs/spec.md

# 📑 技术规格说明（SPR） — AI-powered Resume & Cover Letter Generator

## 1. 项目结构

```
apply-helper/
├── pyproject.toml           # 项目依赖与配置
├── uv.lock                  # UV 依赖锁定文件
├── .env.example             # 环境变量配置模板
├── src/                     # 源代码根目录
│   ├── streamlit_app.py     # Streamlit 前端主入口
│   ├── mock_data.py         # 测试用模拟数据
│   ├── services/            # 业务逻辑层
│   │   ├── __init__.py
│   │   ├── analyse_service.py   # JD/用户信息分析与总结
│   │   ├── generation_service.py # 简历与求职信生成
│   │   └── llm_service.py       # LLM/LiteLLM 统一封装与调用
│   └── llm/                     # LLM集成层
│       ├── __init__.py
│       ├── litellm_client.py    # LiteLLM API 封装
│       └── prompt_templates.py  # LLM Prompt 模板管理
├── docs/                    # 文档目录
│   ├── prd.md              # 产品需求文档
│   ├── spec.md             # 技术规格说明（本文件）
│   ├── services.spec.md    # 服务层规格说明
│   └── llm.spec.md         # LLM集成规格说明
└── tests/                  # 单元测试（待实现）
```

## 2. 主要 Python 文件与函数

### 2.1 `src/streamlit_app.py` — Streamlit 前端主入口

- **页面布局**: 侧边栏输入控制，主区域双列预览（简历 + 求职信）
- **会话状态管理**: 使用 `st.session_state` 持久化分析结果、生成文档和错误状态
- **主要函数**：
	- `main()`：应用入口，负责页面配置、UI渲染与交互逻辑
	- `initialize_session_state()`：初始化会话状态变量
	- `handle_analyse(jd: str, user_info: str)`：分析按钮回调，包含输入验证、调用服务、异常处理
	- `handle_refine(feedback: str)`：优化按钮回调，基于反馈更新分析
	- `handle_mock_analyse()`：模拟分析按钮回调，加载预设测试数据
- **模拟数据功能**: 三个按钮支持加载模拟JD、简历和完整分析结果
- **错误处理**: 集中化错误显示，用户友好提示信息



### 2.2 LLM 集成层

#### `src/services/llm_service.py` — LLM服务包装层
- **核心功能**: 提供LLM调用的统一接口，负责提示词模板格式化和LiteLLM调用
- **主要函数**:
  - `analyse_llm(jd: str, user_info: str) -> str`: 工作分析，返回原始LLM响应字符串
  - `refine_llm(summary_json: str, feedback: str) -> str`: 基于反馈优化分析，返回原始LLM响应
  - `generate_resume_llm(summary_json: str, user_info: str) -> str`: 生成Markdown格式简历
  - `generate_cover_letter_llm(job_description: str, user_info: str) -> str`: 生成德语求职信

#### `src/llm/litellm_client.py` — LiteLLM客户端集成
- **多Provider支持**: 优先支持Azure OpenAI，备用支持标准OpenAI
- **自动配置**: 基于环境变量自动检测和配置最优客户端
- **主要函数**:
  - `call_llm(prompt: str, model: str = None, max_tokens: int = 800, temperature: float = 1.0) -> str`
  - `get_azure_client() -> dict`: 配置Azure OpenAI客户端
  - `get_openai_client() -> dict`: 配置标准OpenAI客户端
  - 包含连接测试和调试模式，支持litellm debug

#### `src/llm/prompt_templates.py` — 提示词模板管理
- **模板类型**: analyse, refine, generate_resume, generate_cover_letter
- **函数**: `get_template(name: str) -> str`
- **特点**: 
  - 字典存储，包含详细的JSON输出格式要求
  - ANALYSE_PROMPT: 德国科技市场专家角色，8-12个技能提取，4-6个匹配点分析
  - GENERATE_COVER_LETTER_PROMPT: 德语商务求职信生成，符合德国商务信函规范
  - 所有模板包含明确的输出格式要求和角色设定

#### 核心处理逻辑
- **提示词管理**: 从模板获取提示词，使用Python字符串format动态替换参数
- **LLM调用**: 通过LiteLLM统一接口调用不同provider的模型
- **错误处理**: LiteLLM层处理API调用异常，服务层处理业务逻辑异常
- **响应处理**: 返回原始字符串响应，由上层服务负责结构化解析


### 2.3 业务服务层

#### `src/services/analyse_service.py` — 分析服务
- **功能**: 职位描述与用户背景的匹配分析，使用Pydantic数据模型
- **数据模型**: `AnalysisResult(BaseModel)` - 结构化分析结果
  - key_skills: List[str] - 关键技能列表
  - match_points: List[str] - 匹配优势点
  - gap_points: List[str] - 技能差距点
  - suggestions: List[str] - 改进建议
  - pitch: str - 价值主张
- **主要逻辑**: 
  - 验证输入参数非空
  - 委托LLM服务进行分析
  - `_parse_analysis_response()` - 复杂JSON解析逻辑，处理代码块包装
  - `analyse()` - 初始分析，返回AnalysisResult对象
  - `refine()` - 基于反馈优化分析，使用model_dump_json()序列化

#### `src/services/generation_service.py` — 文档生成服务
- **功能**: 编排简历和求职信的生成
- **主要接口**:
  - `generate_resume(summary: AnalysisResult, user_info: str) -> str` - 生成简历
  - `generate_cover_letter(job_description: str, user_info: str) -> str` - 生成求职信
  - `generate_both(summary: AnalysisResult, user_info: str, job_description: str) -> Tuple[str, str]` - 生成完整文档对
- **主要逻辑**:
  - 使用AnalysisResult对象和原始文本作为输入
  - 调用LLM服务生成简历(Markdown)和求职信(德语文本)
  - 支持动态导入处理，兼容模块和独立运行
  - 返回生成的文档元组

### 2.4 模拟数据系统

#### `src/mock_data.py` — 测试数据管理
- **MOCK_JD**: 完整的高级软件工程师职位描述
- **MOCK_RESUME**: John Smith 的详细简历信息
- **Analysis_Summary**: 结构化分析结果（Dict格式）
  - key_skills, match_points, gap_points, suggestions, pitch
- **Resume**: 生成的Markdown格式简历
- **Cover_Letter**: 生成的纯文本求职信
- **用途**: 支持无需LLM调用的完整工作流测试

## 3. Streamlit UI 实现

### 3.1 页面布局

- **侧边栏（Sidebar）**：
	- **模拟数据按钮**: 三列布局 - "Load Mock JD", "Load Mock Resume", "Mock Analyse"
	- **输入区域**: 
		- Job Description 文本区域（高度150px）
		- User Resume/Info 文本区域（高度200px）
	- **控制按钮**: "Analyse" 按钮（全宽）
	- **优化区域**: 
		- Feedback 文本区域（高度100px）
		- "Refine" 按钮（全宽）

- **主区域（Main Area）**：
	- **错误显示**: 使用 `st.error()` 显示异常信息
	- **分析摘要**: 使用 `st.json()` 展示结构化分析结果
	- **双列预览**: 
		- 左列: Resume 预览（Markdown 渲染）
		- 右列: Cover Letter 预览（纯文本显示）

### 3.2 会话状态管理

**状态变量**:
- `summary` - 分析摘要结果
- `resume_md` - 生成的简历Markdown
- `cover_letter_txt` - 生成的求职信文本  
- `error` - 错误信息显示
- `user_info_input` - 用户输入缓存

### 3.3 交互流程

1. **标准工作流**:
   - 输入JD和用户信息 → 点击"Analyse" → 显示分析和生成结果
   - 输入反馈 → 点击"Refine" → 更新分析和重新生成

2. **模拟数据工作流**:
   - 点击"Load Mock JD" → 自动填充职位描述
   - 点击"Load Mock Resume" → 自动填充简历信息  
   - 点击"Mock Analyse" → 直接加载完整分析结果

3. **错误处理**:
   - 输入验证: 检查空值，显示友好错误信息
   - 异常捕获: 包装在try-catch中，显示具体错误消息
   - 状态清理: 成功时清除error状态


## 4. 技术实现详情

### 4.1 依赖管理

**核心依赖**: streamlit (UI), litellm (LLM调用), python-dotenv (环境变量), weasyprint (PDF，未使用), pydantic (验证，未使用)

**安装和运行**:
1. `pip install uv` - 安装包管理器
2. `uv sync` - 同步依赖
3. `cp .env.example .env` - 配置环境变量
4. `uv run streamlit run src/streamlit_app.py` - 启动应用

### 4.2 LLM集成配置

**多Provider支持**: 优先Azure OpenAI，备用标准OpenAI

**Azure OpenAI配置**: AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_MODEL, AZURE_OPENAI_API_VERSION(默认2024-12-01-preview)

**OpenAI配置**: OPENAI_API_KEY（使用gpt-3.5-turbo模型）

**配置逻辑**: 
- 优先检测Azure配置，如果完整则使用Azure
- Azure不可用时回退到标准OpenAI
- 支持模型参数覆盖，但仅支持azure/前缀的模型
- 包含详细的配置验证和错误提示

### 4.3 开发和测试

**模拟数据测试**:
- 无需配置LLM即可测试完整UI流程
- `src/mock_data.py` 包含完整测试数据集
- 点击"Mock Analyse"按钮即可加载预设结果

**调试和测试模式**:
- `python src/llm/litellm_client.py` - 测试LLM连接和配置验证
- `python src/services/analyse_service.py` - 测试分析服务完整流程
- `python src/services/generation_service.py` - 测试文档生成流程
- 包含litellm._turn_on_debug()调试支持

### 4.4 架构特点

**模块化设计**:
- 业务逻辑与UI分离
- LLM集成层独立封装
- 服务层薄包装，便于替换实现

**扩展点**:
- 添加新的LLM provider: 扩展 `litellm_client.py` 中的客户端配置函数
- 添加PDF导出: 实现 `pdf_service.py` 集成WeasyPrint
- 添加新的生成模板: 在 `prompt_templates.py` 中添加新模板常量
- 数据验证增强: 当前使用Pydantic AnalysisResult模型，可扩展更多验证模型
- 多语言支持: 扩展prompt_templates支持不同语言的求职信生成