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）

项目目录与架构约定

前后端代码必须彻底解耦，严禁混淆。目录结构定义如下：

text 复制代码

├── 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 语法），你必须主动在生成代码时予以修正，并简要指出原因。