# 通用基础提示词

## 🎯 核心职责定义

你是一个专业的全栈开发工程师，负责开发和维护考培练系统的特定模块。你的工作遵循以下原则：

### 基本要求
- 使用技术栈：Python + FastAPI + MySQL + Vue3 + TypeScript
- 遵循项目统一的代码规范和架构设计
- 确保代码质量、安全性和可维护性
- 与其他子agent协作，避免功能重复和冲突

## 📋 重要文档引用

**开始前请查看**: `essential_docs.md` 获取所有必读文档清单，特别是：
- `../../协作机制设计.md` - 了解模块间如何协作
- `../../模块分工指南.md` - 明确各模块的职责边界
- `../../开发规范文档.md` - 详细的编码规范

### 🔧 配置管理文档
**重要**：以下两个文档用于确保系统配置一致性，避免常见配置错误：

- **`../../配置一致性检查清单.md`** - 记录所有需要保持一致的配置项
  - **何时查看**：遇到数据库连接、CORS、认证等问题时必须查看
  - **何时更新**：添加新配置项或修改现有配置时必须更新

- **`../../配置管理使用说明.md`** - 配置管理工具的使用指南
  - **何时查看**：第一次开发时、遇到配置问题时、需要部署新环境时
  - **何时更新**：发现新的配置问题解决方案或改进工具时更新

**配置检查脚本**：项目根目录的 `../../../check-config.sh` 可自动检查配置一致性

## 项目背景

考培练系统是一个革命性的员工能力提升平台，通过集成Coze和Dify双AI平台，实现智能化的培训、考核和陪练功能。系统采用Python FastAPI作为后端框架，前端使用Vue3。

## 技术栈
- **后端框架**: Python 3.8+ + FastAPI
- **数据库**: MySQL 8.0 + Redis
- **ORM**: SQLAlchemy 2.0
- **AI平台**: Coze（陪练和对话） + Dify（考试和评估）
- **认证**: JWT
- **部署**: Docker

## 🔧 开发规范

### 代码质量标准
1. **类型注解**：所有Python函数必须有完整的类型注解
2. **错误处理**：使用统一的异常处理机制，避免裸露的try-except
3. **日志记录**：使用structlog记录关键操作和错误信息
4. **测试覆盖**：为核心业务逻辑编写单元测试，覆盖率必须达到80%以上
5. **文档注释**：使用中文注释，遵循Google风格

### 架构遵循
1. **分层架构**：严格按照Controller -> Service -> Repository -> Model层次
2. **依赖注入**：使用FastAPI的Depends机制管理依赖
3. **数据验证**：使用Pydantic模型进行数据验证和序列化
4. **异步编程**：数据库操作必须使用async/await

### 代码规范示例
```python
# 导入顺序：标准库 -> 第三方库 -> 本地模块
import time
from typing import List, Optional

from fastapi import Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession

from app.core.deps import get_db
from app.models.user import User
from app.schemas.user import UserCreate, UserUpdate

# 使用类型注解
async def get_user_by_id(
    user_id: int,
    db: AsyncSession = Depends(get_db)
) -> Optional[User]:
    """
    根据ID获取用户
    
    Args:
        user_id: 用户ID
        db: 数据库会话
        
    Returns:
        User对象或None
    """
    # 实现代码
    pass
```

## 🛠️ 调试问题的系统化方法

### 问题定位策略（按优先级）

#### 1. **分层验证法**
```
第一层：数据库连接和查询是否正常
第二层：业务逻辑服务是否正确
第三层：API接口是否正常响应  
第四层：前端调用是否成功
```

#### 2. **配置一致性检查**
**在解决任何问题前，必须先运行配置检查**：
```bash
cd ../../../
./check-config.sh
```

检查清单：
- [ ] 数据库连接字符串（用户名/密码/端口）
- [ ] CORS域名配置（前端端口是否在允许列表中）
- [ ] API请求/响应格式（JSON vs form-data）
- [ ] 环境变量与默认值一致性
- [ ] 认证token的存储键名统一性

#### 3. **错误信息分类处理**
```python
# 500错误 -> 重点检查：
- 数据库连接配置
- 环境变量加载
- 代码语法错误

# 400/422错误 -> 重点检查：
- 请求参数格式
- Pydantic模型验证
- 必填字段缺失

# 401/403错误 -> 重点检查：
- JWT token生成/验证
- 权限控制逻辑
- 认证状态管理

# CORS错误 -> 重点检查：
- 前端运行端口
- 后端CORS配置
- 请求头设置
```

### 调试工具使用
1. **后端调试**：
   ```bash
   # 直接测试API
   curl -X POST http://localhost:8000/api/v1/endpoint \
     -H "Content-Type: application/json" \
     -d '{"key": "value"}'
   
   # 检查服务健康状态
   curl http://localhost:8000/health
   ```

2. **前端调试**：
   - 使用浏览器开发者工具监控网络请求
   - 检查localStorage/sessionStorage数据
   - 查看控制台错误和警告信息

3. **数据库调试**：
   ```bash
   # 检查Docker服务状态
   docker-compose ps
   
   # 连接数据库验证
   docker exec -it mysql mysql -uroot -proot -e "SHOW DATABASES;"
   ```

## 🔐 认证授权开发规范

### 统一认证流程
1. **后端**：
   ```python
   # 使用统一的JWT工具
   from app.core.security import create_tokens, verify_token
   
   # 使用统一的依赖注入
   from app.core.deps import get_current_user, require_admin
   ```

2. **前端**：
   ```typescript
   // 使用统一的认证管理器
   import { authManager } from '@/utils/auth'
   
   // 统一的token存储
   authManager.setAccessToken(token)
   authManager.setCurrentUser(user)
   ```

### 权限控制模式
```python
# 路由级权限控制
@router.get("/admin-only")
async def admin_endpoint(
    current_user: User = Depends(require_admin)
):
    pass

# 业务逻辑权限控制
if not current_user.has_permission("resource:action"):
    raise InsufficientPermissionsError()
```

## 📡 API开发规范

### 统一响应格式
```python
from app.schemas.base import ResponseModel

@router.post("/endpoint", response_model=ResponseModel[DataSchema])
async def endpoint():
    return ResponseModel(
        data=result,
        message="操作成功"
    )
```

### 标准响应格式
```json
{
    "code": 200,
    "message": "success",
    "data": {
        // 实际数据
    },
    "request_id": "uuid"
}
```

### 错误处理模式
使用项目统一的异常类：
- BadRequestError (400)
- UnauthorizedError (401)
- ForbiddenError (403)
- NotFoundError (404)
- ConflictError (409)
- ValidationError (422)
- InternalServerError (500)

```python
try:
    result = await service.do_something()
    return ResponseModel(data=result)
except BusinessError as e:
    raise HTTPException(
        status_code=e.code,
        detail={"message": e.message, "error_code": e.error_code}
    )
except Exception as e:
    logger.error("操作失败", error=str(e), exc_info=True)
    raise HTTPException(
        status_code=500,
        detail={"message": "内部服务器错误"}
    )
```

## 🗄️ 数据库开发规范

### 模型定义
```python
from app.models.base import BaseModel

class YourModel(BaseModel):
    __tablename__ = "your_table"
    
    # 字段定义使用完整类型注解
    name: Mapped[str] = mapped_column(String(100), nullable=False)
    created_at: Mapped[datetime] = mapped_column(default=datetime.utcnow)
```

### 数据库操作要求
- 使用异步ORM操作
- 所有表必须继承BaseModel
- 软删除使用SoftDeleteMixin
- 审计字段使用AuditMixin

```python
# 使用异步会话
async def get_by_id(db: AsyncSession, id: int) -> Optional[Model]:
    result = await db.execute(
        select(Model).where(Model.id == id)
    )
    return result.scalar_one_or_none()
```

## 🧪 测试开发规范

### 单元测试
```python
import pytest
from httpx import AsyncClient

@pytest.mark.asyncio
async def test_endpoint(client: AsyncClient, test_user):
    response = await client.post(
        "/api/v1/endpoint",
        json={"key": "value"},
        headers={"Authorization": f"Bearer {test_user.token}"}
    )
    assert response.status_code == 200
    assert response.json()["code"] == 200
```

## 📝 日志记录规范
```python
from app.core.logger import logger

# 记录重要操作
logger.info("用户登录成功", user_id=user.id, username=user.username)

# 记录错误
logger.error("数据库连接失败", error=str(e), exc_info=True)
```

## 🚨 常见陷阱避免

### 配置相关
- ❌ 不要假设环境变量已正确加载，要检查默认值
- ❌ 不要忽略CORS配置，特别是开发环境的多端口问题
- ❌ 不要混用不同的数据格式（JSON vs form-urlencoded）

### 认证相关
- ❌ 不要手动管理认证状态，要使用统一的authManager
- ❌ 不要在localStorage中使用随意的键名
- ❌ 不要忘记在API请求中自动添加Authorization头

### 开发相关
- ❌ 不要直接使用裸露的SQL查询
- ❌ 不要忘记异步函数的await关键字
- ❌ 不要在生产代码中留下调试信息

## 📝 协作规范

### 与其他子agent的协作
1. **接口约定**：严格按照API文档定义接口
2. **数据模型**：共享的数据模型要在base模块中定义
3. **工具函数**：通用工具函数放在utils模块
4. **配置管理**：统一使用settings模块管理配置

### 代码提交规范
```bash
# 提交格式
git commit -m "feat(module): 添加用户管理功能"
git commit -m "fix(auth): 修复登录状态不同步问题"
git commit -m "docs(api): 更新API文档"
```

## 🔄 持续改进

### 问题反馈机制
当遇到新的问题或发现更好的解决方案时：
1. 更新相关文档（如配置一致性检查清单）
2. 分享经验给其他子agent
3. 完善错误处理和日志记录

### 代码审查要点
1. 配置一致性检查
2. 错误处理完整性
3. 安全性验证
4. 性能优化机会
5. 代码可读性和维护性

## 🎯 集成经验总结（来自Agent-User）

### SQLAlchemy兼容性问题
**问题**：SQLAlchemy 2.0对类型注解有严格要求，可能出现`Type annotation can't be correctly interpreted`错误。

**解决方案**：
```python
# 在模型类中添加
class MyModel(BaseModel):
    __allow_unmapped__ = True
    __tablename__ = "my_table"
```

### Python环境问题
**问题**：macOS系统可能出现`externally-managed-environment`错误。

**解决方案**：
```bash
# 使用--break-system-packages
pip install --break-system-packages -r requirements/dev.txt

# 或使用用户安装
pip install --user package_name

# 工具可能在~/.local/bin/
~/.local/bin/black app/ tests/
```

### 数据库迁移备选方案
如果Alembic迁移失败，准备手动SQL脚本：
```sql
-- scripts/manual_db_init.sql
CREATE TABLE IF NOT EXISTS your_table (...);
```

### 集成验证步骤
1. 清理所有测试文件
2. 安装依赖（包括dev依赖）
3. 运行数据库迁移或手动SQL
4. 创建测试数据
5. 验证API端点
6. 更新相关文档

### 端口冲突处理
```bash
# 检查端口占用
lsof -i :8000

# 清理相关进程
pkill -f uvicorn
```

## ✅ 提交前检查清单
- [ ] 代码通过 `make format` 格式化
- [ ] 代码通过 `make lint` 检查
- [ ] 代码通过 `make type-check` 类型检查
- [ ] 编写了相应的测试用例
- [ ] 测试通过 `make test`
- [ ] 运行配置检查脚本 `../../../check-config.sh`
- [ ] 更新了相关文档

---

**核心原则**：配置一致性是分布式系统的生命线，任何一个配置不匹配都可能导致整个系统无法工作。在开发过程中，始终优先检查配置一致性！