557 lines
15 KiB
Plaintext
557 lines
15 KiB
Plaintext
# Finyx Data AI - Cursor 开发规则
|
||
|
||
## 📋 项目概述
|
||
|
||
本项目是数据资产盘点系统的后端 API 服务，使用 FastAPI 框架开发，提供数据资产盘点、场景挖掘和报告生成等功能。
|
||
|
||
## 🏗️ 技术栈
|
||
|
||
- **Web 框架**: FastAPI 0.104+
|
||
- **数据验证**: Pydantic 2.0+
|
||
- **异步支持**: asyncio, httpx
|
||
- **大模型**: 通义千问 (DashScope)、OpenAI
|
||
- **日志**: Loguru
|
||
- **文档处理**: pandas, openpyxl, python-docx, pdfplumber
|
||
- **Python 版本**: 3.10+
|
||
|
||
## 📁 项目结构规范
|
||
|
||
```
|
||
app/
|
||
├── api/ # API 路由（按模块组织）
|
||
│ ├── v1/ # API v1 版本
|
||
│ │ ├── inventory/ # 数据盘点模块
|
||
│ │ ├── value/ # 场景挖掘模块
|
||
│ │ └── delivery/ # 报告生成模块
|
||
│ └── common/ # 通用路由
|
||
├── core/ # 核心模块（配置、异常、响应格式）
|
||
├── models/ # 数据模型层（ORM，如需要）
|
||
├── schemas/ # 数据模式层（Pydantic 模型）
|
||
├── services/ # 业务逻辑层
|
||
├── utils/ # 工具函数
|
||
└── main.py # 应用入口
|
||
```
|
||
|
||
### 目录使用规范
|
||
|
||
- **`api/`**: 只包含路由定义和请求处理，不包含业务逻辑
|
||
- **`schemas/`**: 定义所有 Pydantic 模型（请求、响应）
|
||
- **`services/`**: 包含业务逻辑实现（可选的，复杂逻辑建议放这里）
|
||
- **`utils/`**: 通用工具函数，应该是无状态的
|
||
- **`core/`**: 核心配置和基础类，不应该频繁修改
|
||
|
||
## 💻 代码风格规范
|
||
|
||
### 1. 导入顺序
|
||
|
||
```python
|
||
# 标准库
|
||
import os
|
||
from typing import Optional, List
|
||
from pathlib import Path
|
||
|
||
# 第三方库
|
||
from fastapi import FastAPI, UploadFile, File
|
||
from pydantic import BaseModel, Field
|
||
import pandas as pd
|
||
|
||
# 本地模块
|
||
from app.core.config import settings
|
||
from app.core.response import success_response, error_response
|
||
from app.utils.logger import logger
|
||
```
|
||
|
||
### 2. 类型注解
|
||
|
||
- **必须使用类型注解**：所有函数参数和返回值
|
||
- 使用 `Optional[T]` 表示可选类型
|
||
- 使用 `List[T]`, `Dict[K, V]` 等明确容器类型
|
||
|
||
```python
|
||
async def process_file(
|
||
file: UploadFile,
|
||
project_id: str,
|
||
file_type: Optional[str] = None
|
||
) -> dict:
|
||
"""处理文件"""
|
||
pass
|
||
```
|
||
|
||
### 3. 文档字符串（Docstring）
|
||
|
||
- 所有公共函数和类必须有文档字符串
|
||
- 使用 Google 风格或 NumPy 风格
|
||
- 说明参数、返回值和可能的异常
|
||
|
||
```python
|
||
async def parse_document(file_path: str, file_type: str) -> List[TableInfo]:
|
||
"""
|
||
解析文档文件，提取表结构信息
|
||
|
||
Args:
|
||
file_path: 文件路径
|
||
file_type: 文件类型（excel/word/pdf）
|
||
|
||
Returns:
|
||
表信息列表
|
||
|
||
Raises:
|
||
FileParseException: 文件解析失败时抛出
|
||
"""
|
||
pass
|
||
```
|
||
|
||
## 🔌 API 开发规范
|
||
|
||
### 1. 路由定义
|
||
|
||
- 使用路由装饰器定义路径和 HTTP 方法
|
||
- 使用 `response_model` 指定响应模型
|
||
- 添加标签（tags）用于 API 文档分类
|
||
|
||
```python
|
||
from app.core.response import APIResponse
|
||
|
||
@router.post(
|
||
"/parse-document",
|
||
response_model=APIResponse[ParseDocumentResponse],
|
||
tags=["数据盘点"],
|
||
summary="文档解析接口",
|
||
description="解析上传的数据字典文档，提取表结构信息"
|
||
)
|
||
async def parse_document(request: ParseDocumentRequest):
|
||
"""文档解析接口"""
|
||
pass
|
||
```
|
||
|
||
### 2. 请求和响应模型
|
||
|
||
- **所有请求和响应必须使用 Pydantic 模型**
|
||
- 模型定义在 `app/schemas/` 目录下
|
||
- 使用 `Field` 添加字段描述和验证
|
||
|
||
```python
|
||
from pydantic import BaseModel, Field
|
||
from typing import Optional, List
|
||
|
||
class ParseDocumentRequest(BaseModel):
|
||
"""文档解析请求模型"""
|
||
project_id: str = Field(..., description="项目ID")
|
||
file_type: Optional[str] = Field(None, description="文件类型，可选，自动识别")
|
||
|
||
class ParseDocumentResponse(BaseModel):
|
||
"""文档解析响应模型"""
|
||
tables: List[TableInfo] = Field(..., description="表列表")
|
||
total_tables: int = Field(..., description="总表数")
|
||
```
|
||
|
||
### 3. 响应格式
|
||
|
||
- **统一使用 `success_response()` 和 `error_response()`**
|
||
- 不要直接返回字典或 JSONResponse（特殊情况除外）
|
||
|
||
```python
|
||
from app.core.response import success_response, error_response
|
||
|
||
# ✅ 正确
|
||
return success_response(
|
||
data={"result": "..."},
|
||
message="操作成功"
|
||
)
|
||
|
||
# ❌ 错误
|
||
return {"success": True, "data": {...}}
|
||
```
|
||
|
||
### 4. 异常处理
|
||
|
||
- **使用自定义异常类**（在 `app/core/exceptions.py` 中定义）
|
||
- 让全局异常处理器捕获，不要手动返回错误响应
|
||
- 记录异常日志
|
||
|
||
```python
|
||
from app.core.exceptions import FileUploadException, FileParseException
|
||
from app.utils.logger import logger
|
||
|
||
# ✅ 正确
|
||
if not validate_file(file):
|
||
raise FileUploadException("文件验证失败", error_detail="文件格式不支持")
|
||
|
||
try:
|
||
result = parse_file(file_path)
|
||
except Exception as e:
|
||
logger.exception(f"文件解析失败: {str(e)}")
|
||
raise FileParseException("文件解析失败", error_detail=str(e))
|
||
```
|
||
|
||
## 🤖 大模型接口开发规范
|
||
|
||
### 1. 使用 LLM 客户端
|
||
|
||
- **统一使用 `app/utils/llm_client.py` 中的 `llm_client`**
|
||
- 不要直接调用大模型 API
|
||
- 处理超时和重试（已在客户端中实现）
|
||
|
||
```python
|
||
from app.utils.llm_client import llm_client
|
||
|
||
# ✅ 正确
|
||
response = await llm_client.call(
|
||
prompt=user_prompt,
|
||
system_prompt=system_prompt,
|
||
temperature=0.3,
|
||
model="qwen-max"
|
||
)
|
||
|
||
result = llm_client.parse_json_response(response)
|
||
|
||
# ❌ 错误
|
||
# 直接调用 httpx 或 requests
|
||
```
|
||
|
||
### 2. 提示词构建
|
||
|
||
- 提示词应该清晰、结构化
|
||
- 使用模板字符串或格式化函数
|
||
- 明确输出格式要求（JSON Schema）
|
||
|
||
```python
|
||
SYSTEM_PROMPT = """你是数据资产管理专家..."""
|
||
|
||
def build_prompt(tables: List[TableInfo], context: str) -> str:
|
||
"""构建提示词"""
|
||
tables_info = format_tables_info(tables)
|
||
return f"""
|
||
请分析以下数据资产：
|
||
|
||
{tables_info}
|
||
|
||
业务背景：{context}
|
||
|
||
请以 JSON 格式输出结果。
|
||
"""
|
||
```
|
||
|
||
### 3. 响应解析和验证
|
||
|
||
- 使用 `llm_client.parse_json_response()` 解析 JSON
|
||
- 验证返回数据的完整性和正确性
|
||
- 处理解析错误
|
||
|
||
```python
|
||
try:
|
||
response_text = await llm_client.call(prompt)
|
||
result = llm_client.parse_json_response(response_text)
|
||
|
||
# 验证数据
|
||
validate_result(result)
|
||
|
||
except json.JSONDecodeError as e:
|
||
logger.error(f"JSON 解析失败: {e}")
|
||
raise LLMAPIException("大模型返回格式错误")
|
||
```
|
||
|
||
## 📄 文件处理规范
|
||
|
||
### 1. 文件上传
|
||
|
||
- **使用 `app/utils/file_handler.py` 中的工具函数**
|
||
- 验证文件类型和大小
|
||
- 保存到指定目录并返回路径
|
||
- 清理临时文件
|
||
|
||
```python
|
||
from app.utils.file_handler import save_upload_file, cleanup_temp_file
|
||
|
||
# ✅ 正确
|
||
file_path = await save_upload_file(file, project_id)
|
||
try:
|
||
# 处理文件
|
||
result = process_file(file_path)
|
||
finally:
|
||
# 清理临时文件
|
||
cleanup_temp_file(file_path)
|
||
```
|
||
|
||
### 2. 文件类型检测
|
||
|
||
- 使用 `detect_file_type()` 函数
|
||
- 支持的文件类型：excel, word, pdf, csv
|
||
|
||
```python
|
||
from app.utils.file_handler import detect_file_type
|
||
|
||
file_type = detect_file_type(file.filename)
|
||
```
|
||
|
||
## 📝 日志使用规范
|
||
|
||
### 1. 使用日志记录器
|
||
|
||
- **统一使用 `app/utils/logger.py` 中的 `logger`**
|
||
- 不同级别的日志：
|
||
- `logger.info()` - 信息日志（正常流程）
|
||
- `logger.warning()` - 警告日志（异常但不影响功能）
|
||
- `logger.error()` - 错误日志（需要关注）
|
||
- `logger.exception()` - 异常日志（带堆栈信息）
|
||
|
||
```python
|
||
from app.utils.logger import logger
|
||
|
||
logger.info(f"开始处理文件: {file_path}")
|
||
logger.warning(f"文件格式可能不标准: {file_type}")
|
||
logger.error(f"文件解析失败: {error}")
|
||
logger.exception("未处理的异常") # 自动包含堆栈信息
|
||
```
|
||
|
||
### 2. 日志内容
|
||
|
||
- 包含关键信息（文件路径、项目ID、错误详情等）
|
||
- 不要记录敏感信息（API Key、密码等）
|
||
- 使用 f-string 格式化
|
||
|
||
## ⚙️ 配置管理规范
|
||
|
||
### 1. 使用配置对象
|
||
|
||
- **统一使用 `app/core/config.py` 中的 `settings`**
|
||
- 不要直接使用 `os.getenv()`
|
||
- 配置值通过环境变量设置
|
||
|
||
```python
|
||
from app.core.config import settings
|
||
|
||
# ✅ 正确
|
||
api_key = settings.DASHSCOPE_API_KEY
|
||
max_size = settings.MAX_UPLOAD_SIZE
|
||
|
||
# ❌ 错误
|
||
api_key = os.getenv("DASHSCOPE_API_KEY")
|
||
```
|
||
|
||
## 🧪 测试规范
|
||
|
||
### 1. 测试文件位置
|
||
|
||
- 测试文件放在 `tests/` 目录
|
||
- 测试文件名以 `test_` 开头
|
||
- 测试函数名以 `test_` 开头
|
||
|
||
### 2. 测试用例
|
||
|
||
- 覆盖正常情况和异常情况
|
||
- 使用 pytest 和 pytest-asyncio
|
||
- Mock 外部依赖（大模型 API、文件系统等）
|
||
|
||
```python
|
||
import pytest
|
||
from fastapi.testclient import TestClient
|
||
from unittest.mock import patch, AsyncMock
|
||
|
||
@pytest.mark.asyncio
|
||
async def test_parse_document_success():
|
||
"""测试文档解析成功"""
|
||
with patch('app.services.document_parser.parse_excel') as mock_parse:
|
||
mock_parse.return_value = [table1, table2]
|
||
# 测试代码
|
||
pass
|
||
```
|
||
|
||
## 📚 文档规范
|
||
|
||
### 1. 代码注释
|
||
|
||
- 复杂逻辑必须有注释说明
|
||
- 函数参数和返回值说明在 docstring 中
|
||
- 使用中文注释（项目使用中文）
|
||
|
||
### 2. API 文档
|
||
|
||
- 使用 FastAPI 自动生成的文档
|
||
- 通过路由装饰器添加描述
|
||
- 使用 `summary` 和 `description` 参数
|
||
|
||
```python
|
||
@router.post(
|
||
"/api/v1/inventory/parse-document",
|
||
summary="文档解析",
|
||
description="解析上传的数据字典文档（Excel/Word/PDF），提取表结构信息",
|
||
response_description="解析结果，包含表列表和统计信息"
|
||
)
|
||
```
|
||
|
||
### 3. 文档文件管理规范
|
||
|
||
**⚠️ 重要规则：所有生成的文档文件必须统一放到 `docs/` 文件夹中**
|
||
|
||
#### 文档分类
|
||
|
||
- **项目文档**（README、开发指南等）：放在项目根目录（允许例外）
|
||
- `README.md` - 项目说明
|
||
- `DEVELOPMENT.md` - 开发指南
|
||
- `QUICK_START.md` - 快速开始
|
||
- `API_OVERVIEW.md` - API 总览
|
||
|
||
- **接口开发文档**：**必须放在 `docs/` 文件夹中**
|
||
- `docs/01-parse-document.md` - 文档解析接口说明
|
||
- `docs/02-parse-sql-result.md` - SQL 结果解析接口说明
|
||
- `docs/03-parse-business-tables.md` - 业务表解析接口说明
|
||
- `docs/04-ai-analyze.md` - AI 分析接口说明
|
||
- `docs/05-scenario-recommendation.md` - 场景推荐接口说明
|
||
- `docs/06-scenario-optimization.md` - 场景优化接口说明
|
||
- `docs/07-generate-report.md` - 报告生成接口说明
|
||
|
||
- **项目进度和状态文档**：**必须放在 `docs/` 文件夹中**
|
||
- `docs/研发进度说明.md` - 研发进度汇总
|
||
- `docs/测试结果.md` - 测试结果报告
|
||
- `docs/技术架构.md` - 技术架构文档
|
||
- `docs/配置说明.md` - 配置说明文档
|
||
|
||
- **设计文档和技术文档**：**必须放在 `docs/` 文件夹中**
|
||
- `docs/数据资产盘点报告-大模型接口设计文档.md`
|
||
- `docs/数据库设计.md`
|
||
- `docs/API设计规范.md`
|
||
|
||
#### 规则要求
|
||
|
||
1. **所有新生成的文档（除项目根目录的必要文档外）都必须放在 `docs/` 文件夹中**
|
||
2. **不要直接在项目根目录创建文档文件**（如 `研发进度说明.md`、`测试结果.md` 等）
|
||
3. **如果需要在根目录放置文档，必须先评估是否应该放在 `docs/` 中**
|
||
4. **文档命名规范**：
|
||
- 使用小写字母和连字符：`kebab-case.md`
|
||
- 中文文档可以使用中文名称：`研发进度说明.md`
|
||
- 技术文档建议使用英文：`api-design.md`
|
||
5. **文档组织**：
|
||
- 相关文档放在同一目录
|
||
- 使用 `docs/README.md` 作为文档索引
|
||
- 大型文档可以创建子目录，如 `docs/api/`、`docs/architecture/`
|
||
|
||
#### 文档目录结构
|
||
|
||
```
|
||
docs/
|
||
├── README.md # 文档索引
|
||
├── 01-parse-document.md # 接口开发文档
|
||
├── 02-parse-sql-result.md
|
||
├── 03-parse-business-tables.md
|
||
├── 04-ai-analyze.md
|
||
├── 05-scenario-recommendation.md
|
||
├── 06-scenario-optimization.md
|
||
├── 07-generate-report.md
|
||
├── 研发进度说明.md # 项目状态文档
|
||
├── 数据资产盘点报告-大模型接口设计文档.md # 设计文档
|
||
└── [其他文档...]
|
||
```
|
||
|
||
#### 违反规则的后果
|
||
|
||
- ❌ **错误示例**：在项目根目录创建 `研发进度说明.md`
|
||
- ✅ **正确示例**：在 `docs/` 目录创建 `docs/研发进度说明.md`
|
||
|
||
**AI 助手在生成文档时必须遵守此规则，除非用户明确指定其他位置。**
|
||
|
||
## 🔒 安全规范
|
||
|
||
### 1. 输入验证
|
||
|
||
- 所有用户输入必须验证
|
||
- 使用 Pydantic 模型进行数据验证
|
||
- 验证文件类型、大小、路径等
|
||
|
||
### 2. 敏感信息
|
||
|
||
- 不要在代码中硬编码 API Key、密码等
|
||
- 使用环境变量存储敏感信息
|
||
- 不要在日志中记录敏感信息
|
||
|
||
### 3. 文件安全
|
||
|
||
- 验证文件扩展名（使用白名单）
|
||
- 限制文件大小
|
||
- 防止路径遍历攻击
|
||
- 及时清理临时文件
|
||
|
||
## 🚀 性能优化规范
|
||
|
||
### 1. 异步处理
|
||
|
||
- **文件 I/O 和网络请求必须使用 async/await**
|
||
- 批量操作考虑并发处理
|
||
- 耗时操作考虑异步任务队列
|
||
|
||
### 2. 错误重试
|
||
|
||
- 大模型 API 调用失败时自动重试（已在客户端实现）
|
||
- 其他网络请求考虑重试机制
|
||
- 使用指数退避策略
|
||
|
||
## 📦 依赖管理
|
||
|
||
### 1. 添加依赖
|
||
|
||
- 在 `requirements.txt` 中添加依赖
|
||
- 指定版本号（使用 `>=` 允许小版本更新）
|
||
- 更新后运行 `pip install -r requirements.txt`
|
||
|
||
### 2. 导入检查
|
||
|
||
- 确保所有导入的模块都在 `requirements.txt` 中
|
||
- 不要使用未声明的依赖
|
||
|
||
## ✅ 开发检查清单
|
||
|
||
开发新接口时，请确保：
|
||
|
||
- [ ] 请求和响应使用 Pydantic 模型定义
|
||
- [ ] 使用 `success_response()` 返回成功响应
|
||
- [ ] 使用自定义异常类抛出错误
|
||
- [ ] 添加日志记录（关键步骤）
|
||
- [ ] 验证输入数据（文件类型、大小等）
|
||
- [ ] 处理异常情况（try-except）
|
||
- [ ] 清理临时资源（文件、连接等）
|
||
- [ ] 添加 API 文档描述（summary、description）
|
||
- [ ] 编写单元测试（至少覆盖主要流程）
|
||
- [ ] 代码通过 lint 检查（无错误）
|
||
|
||
## 🎯 接口开发优先级
|
||
|
||
按照以下顺序开发接口：
|
||
|
||
1. **高优先级**（核心功能）:
|
||
- `/api/v1/inventory/ai-analyze` - 数据资产智能识别
|
||
- `/api/v1/delivery/generate-report` - 完整报告生成
|
||
- `/api/v1/value/scenario-recommendation` - 潜在场景推荐
|
||
|
||
2. **中优先级**:
|
||
- `/api/v1/inventory/parse-document` - 文档解析
|
||
- `/api/v1/inventory/parse-business-tables` - 业务表解析
|
||
- `/api/v1/value/scenario-optimization` - 场景优化
|
||
|
||
3. **低优先级**:
|
||
- `/api/v1/inventory/parse-sql-result` - SQL 结果解析
|
||
|
||
## 📖 参考文档
|
||
|
||
- **开发文档**: `docs/` 目录下的各接口详细开发说明
|
||
- **开发指南**: `DEVELOPMENT.md`
|
||
- **API 总览**: `API_OVERVIEW.md`
|
||
- **框架总结**: `FRAMEWORK_SUMMARY.md`
|
||
|
||
## 🔄 代码审查重点
|
||
|
||
审查代码时关注：
|
||
|
||
1. **是否遵循项目结构规范**
|
||
2. **是否使用统一的响应格式和异常处理**
|
||
3. **是否添加了必要的日志记录**
|
||
4. **是否验证了输入数据**
|
||
5. **是否处理了异常情况**
|
||
6. **是否清理了临时资源**
|
||
7. **是否有适当的文档字符串**
|
||
8. **是否使用了类型注解**
|
||
|
||
---
|
||
|
||
**最后更新**: 2025-01-XX
|
||
**维护者**: Finyx AI Team
|