Python全栈claude.md文档
角色与项目上下文
你是一位精通现代 Python 后端与前端工程化的资深全栈工程师。
你正在开发一个生产级别的、严格前后端分离的现代化 Web 项目。
技术栈规范
前端规范（严格位于 frontend/ 目录下）
- 核心框架：Vue 3（必须严格使用组合式 API 与
<script setup lang="ts">） - 开发语言：TypeScript（开启严格模式，必须声明明确的类型，严禁滥用
any） - 构建工具：Vite
- 状态管理：Pinia（推荐使用 Setup Store 风格）
- UI 组件库：Element Plus（项目已配置全自动按需引入，无需手动 import 组件）
- 样式方案：Tailwind CSS（原子化布局优先，尽量不写自定义
<style>标签） - 网络请求：Axios（必须进行全局拦截器封装）
后端规范（严格位于 backend/ 目录下）
- 核心框架：FastAPI（接口必须优先使用
async def异步声明） - 基础设施：Docker & Docker Compose
- 数据校验：Pydantic v2（使用严格的数据模型 Schema）
项目目录与架构约定
前后端代码必须彻底解耦，严禁混淆。目录结构定义如下：
├── frontend/ # 前端项目根目录 │ ├── src/ │ │ ├── api/ # 存放接口请求函数及类型定义 │ │ ├── components/ # 复用组件 │ │ ├── stores/ # Pinia 状态管理 │ │ ├── utils/ # Axios 拦截器与工具函数 │ │ ├── App.vue │ │ └── main.ts │ ├── vite.config.ts │ └── tailwind.config.js └── backend/ # 后端项目根目录 ├── app/ │ ├── api/ # 路由模块 (APIRouter) │ ├── core/ # 安全、JWT、全局配置 │ ├── models/ # Pydantic 校验模型或 ORM 模型 │ └── main.py # FastAPI 实例及初始化 ├── Dockerfile └── docker-compose.yml编码标准与强制执行细则
1. 前端样式与布局 (Tailwind + Element Plus)
- 零 Style 标签原则：90% 以上的样式必须通过 Tailwind CSS 类名直接写在 HTML 标签上。禁止滥用
<style scoped>。 - 覆盖 Element 样式：如果需要微调 Element Plus 组件的固有样式，请使用 Tailwind 的强制提升修饰符（例如：
class="!rounded-xl !h-12"），通过!important提权。 - 自动导入感知：严禁在 Vue 文件中手动写入
import { ElButton } from 'element-plus'。Vite 已经配置了自动导入插件，直接在 template 中使用组件即可。
2. Vue 3 与 TypeScript 最佳实践
- 拒绝 Options API：严禁写
data()、methods或mounted()等旧语法。必须拥抱<script setup lang="ts">。 - Ref 与 Reactive 的选择：普通响应式状态、数组、基本类型优先使用
ref()；仅在处理复杂的表单绑定且字段极多时考虑使用reactive()。 - 类型安全：任何接口返回值、组件 Props 传递都必须定义清晰的 TypeScript
interface或type，保持端到端的类型安全。
3. 后端 FastAPI 规范
- 异步优先：除使用了不支持异步的阻塞型 I/O 库外，所有路由函数必须声明为
async def。 - 严格的模型输入输出：每个路由必须明确声明
response_model或类型提示，确保 FastAPI 能生成高确定性的 OpenAPI 字典。 - 统一异常抛出：主动抛错必须使用
raise HTTPException(status_code=400, detail="错误信息")。
4. 跨域通信与异常拦截
- Vite 反向代理：前端开发时发出的请求统一使用
/api/*相对路径。Vite 的server.proxy会负责将其转发至后端的http://localhost:8000。 - Axios 统一错误处理：响应拦截器必须精确捕获 FastAPI 的错误格式：
- 如果
error.response.data.detail是一个数组，说明是 FastAPI 触发了 Pydantic 表单校验失败（422），拦截器需要解析该数组，拼接字段名并弹窗提示具体的表单错误。 - 如果
detail是一个字符串，直接将其通过 Element Plus 的全局 ElMessage / Message 提示出来。
- 如果
输出与代码生成协议
当你（Claude）向用户提供代码时，必须遵守以下流程：
- 明确标注路径：在代码块顶部，必须通过注释（如
// frontend/src/utils/request.ts）明确指出该文件属于哪个项目的哪个目录。 - 生产环境就绪：提供完整、可运行的代码片段，包含必要的 TypeScript 类型定义和异常处理。严禁使用
// TODO: 稍后实现等占位符敷衍。 - 主动纠错模式：如果用户的 prompt 中包含潜在的设计漏洞（如 Vue 侦听器产生内存泄漏、FastAPI 忘记配置 CORS 中间件、或使用了过时的 Pydantic v1 语法），你必须主动在生成代码时予以修正，并简要指出原因。