ai-service/
├── app/                          # 应用主目录
│   ├── main.py                   # FastAPI 应用入口
│   ├── config.py                 # 配置管理
│   ├── database.py               # 数据库连接和会话管理
│   ├── redis_op.py               # Redis 连接池管理
│   ├── logger.py                 # 日志配置
│   ├── dependencies/             # 依赖注入模块
│   │   ├── __init__.py          # 通用依赖
│   │   └── points.py            # 积分相关依赖
│   ├── models/                   # 数据模型
│   │   ├── __init__.py
│   │   └── point.py             # 积分相关模型
│   ├── schemas/                  # Pydantic 数据模式
│   │   ├── chat.py              # 聊天接口模式
│   │   ├── ocr.py               # OCR 接口模式
│   │   └── jfbym.py             # 验证码接口模式
│   ├── routers/                  # API 路由
│   │   ├── ocr.py               # OCR 路由
│   │   ├── jfbym.py             # 验证码路由
│   │   └── v1/
│   │       ├── chat.py          # 聊天路由
│   │       └── models.py        # 模型管理路由
│   ├── services/                 # 业务逻辑服务
│   │   └── point.py             # 积分管理服务
│   ├── utils/                    # 工具函数
│   │   ├── ocr.py               # OCR 工具
│   │   └── jfbym.py             # 验证码工具
│   ├── middlewares/              # 中间件
│   │   └── tracing.py           # 请求追踪中间件
│   └── internal/                 # 内部管理接口
│       └── admin.py             # 管理员接口
├── tests/                        # 测试代码
│   ├── conftest.py              # 测试配置
│   ├── test_main.py             # 主应用测试
│   └── routers/                 # 路由测试
├── logs/                         # 日志目录（如 app.log）
├── docker-compose.yml            # 生产环境 Docker Compose
├── docker-compose.test.yaml      # 测试环境 Docker Compose
├── Dockerfile                    # Docker 镜像构建
├── pyproject.toml                # 项目依赖配置
├── uv.lock                       # uv 依赖锁定文件
└── README.md                     # 项目说明文档

git clone <repository-url>
cd ai-service

# 使用 pip 安装
pip install -e .

# 或使用 uv (推荐)
uv sync

# 数据库配置
DATABASE_URL=mysql+aiomysql://username:password@localhost:3306/ai_service
DATABASE_USERNAME=your_db_username
DATABASE_PASSWORD=your_db_password

# Redis 配置
REDIS_URL=redis://localhost:6379/0

# AI 聊天服务配置
AICHAT_BASE_URL=https://api.deepseek.com/v1/
AICHAT_API_KEY=your_deepseek_api_key

# 讯飞 OCR 配置
XFYUN_APP_ID=your_xfyun_app_id
XFYUN_API_SECRET=your_xfyun_api_secret
XFYUN_API_KEY=your_xfyun_api_key

# 云码验证码配置
JFBYM_API_TOKEN=your_jfbym_token

# 积分策略配置，这个也可以不配置，使用默认的 .env.default
MONTHLY_GRANT_AMOUNT=100000
AICHAT_POINTS_COST=100
OCR_GENERAL_POINTS_COST=50
JFBYM_POINTS_COST=10

uv run python run.py dev

X-User-Id: 123
# 或
user_id: 123

{
  "model": "deepseek-chat",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "stream": false,
  "temperature": 0.7,
  "max_tokens": 4096
}

{
  "image": "base64_encoded_image_string",
  "encoding": "jpg",
  "status": 3
}

{
  "type": "验证码类型",
  "image": "base64_encoded_image_string"
}

{
  "code": 10000,
  "message": "success",
  "data": {
    "code": 0,
    "data": "识别结果"
  }
}

{
  "code": 400,
  "message": "云码验证码处理失败: 具体错误信息",
  "data": null
}

# 启动测试数据库
docker-compose -f docker-compose.test.yaml up -d

# 运行所有测试
pytest

# 运行特定测试文件
pytest tests/routers/test_chat.py

# 运行测试并显示覆盖率
pytest --cov=app

# 格式化代码
ruff format

# 检查代码质量
ruff check

# 修复可自动修复的问题
ruff check --fix

# 实时查看应用日志
tail -f logs/app.log

2025-06-03 10:30:15 - app.main - [abc-123-def] - INFO - Root endpoint accessed!

# 1. 查询用户当前积分
curl -X GET "http://localhost:8010/admin/user/points?user_id=123"

# 2. 扣除所有积分
curl -X POST "http://localhost:8010/admin/user/points/deduct?user_id=123&amount=当前积分数"

# 3. 添加新的积分
curl -X POST "http://localhost:8010/admin/user/points?user_id=123&amount=新积分数"

# 备份 MySQL 数据
docker exec mysql_container mysqldump -u root -p ai_service > backup.sql

# 备份 Redis 数据
docker exec redis_container redis-cli BGSAVE

# 恢复 MySQL 数据
docker exec -i mysql_container mysql -u root -p ai_service < backup.sql