# AI 文档模板生成系统 · 开发规范

## 一、代码规范

### 1.1 Python 后端
- Python 3.11+，使用类型注解
- 文件命名：snake_case.py
- 类命名：PascalCase
- 函数/变量：snake_case
- 数据库表：小写复数（templates, paragraphs）
- 异步优先：async/await 贯穿全栈

### 1.2 TypeScript 前端
- TypeScript 5.x，strict 模式
- 文件命名：PascalCase.vue（组件），camelCase.ts（工具/API）
- 组件命名：多单词 PascalCase
- 变量/函数：camelCase
- 接口命名：I 开头或 PascalCase
- 使用 `<script setup lang="ts">` 组合式 API
- 禁止使用 `any`

### 1.3 API 规范
- 基础路径：`/api/v1`
- RESTful 风格
- 请求体：JSON
- 响应格式：`{ code: 0, data: {...}, message: "ok" }`
- 分页：`{ code: 0, data: { items: [], total: N, page: 1, page_size: 20 } }`

## 二、数据库规范

### 2.1 命名
- 表名：小写复数
- 主键：id (INTEGER PRIMARY KEY AUTOINCREMENT)
- 时间戳：created_at, updated_at (DATETIME)
- 外键：{table}_id (INTEGER, REFERENCES {table}(id))

### 2.2 约束
- 所有表必须有 created_at 和 updated_at
- 软删除不实现，用 DELETE 物理删除
- 开发环境用 SQLite，生产环境可切换 PostgreSQL

## 三、安全规范

### 3.1 API Key 加密
- 使用 cryptography.fernet.Fernet 加密
- 加密密钥从环境变量 ENCRYPTION_KEY 读取
- 数据库仅存储密文
- 前端展示脱敏：前 3 位 + **** + 后 4 位

### 3.2 文件上传
- 允许类型：.docx, .xlsx, .xls, .csv, .pdf, .txt, .md
- 大小限制：单文件 ≤ 50MB
- 存储路径：uploads/{YYYYMMDD}/{uuid}.{ext}
- MIME type + 扩展名双重校验

## 四、AI 模型调用规范

### 4.1 超时
- 单次 AI 请求超时：60 秒
- 重试策略：最多 3 次，指数退避（2s → 4s → 8s）

### 4.2 并发
- 单文档最大并发：5 个段落同时请求
- 全局最大并发：10 个段落同时请求（跨文档）
- 使用 asyncio.Semaphore 控制

### 4.3 错误处理
- 400 错误：重试
- 401/403 错误：标记模型不可用，停止生成
- 429 错误：等待 30 秒后重试
- 500 错误：重试，3 次后标记段落失败
- 超时错误：重试，3 次后标记段落失败

## 五、Word 导出规范

### 5.1 导出流程
1. 复制原始模板文件（作为样式骨架）
2. 获取 template 的 file_path
3. 用 python-docx 打开副本
4. 遍历段落 → 找到对应位置 → 替换内容
5. 保存为新文件

### 5.2 段落定位策略
按优先级：
1. 段落 ID 精确匹配（解析时记录的 paragraph_id）
2. 段落标题文本完全匹配
3. 段落序号匹配（一、二、三 / 1.1 / 1.2）
4. 段落索引匹配（第 N 个位置）

### 5.3 表格处理
- 导出时保留原模板中的表格占位（空的带样式表格或占位标记）
- 用 python-docx 找到表格节点，逐格填充数据
- 如需新增表格，在段落最后插入

## 六、前端组件规范

### 6.1 Ant Design Vue 使用规范
- 使用 composition API + `<script setup>`
- 组件样式使用 `<style scoped>`
- 全局覆盖 Ant Design 主题色在 App.vue 中通过 ConfigProvider 设置

### 6.2 状态管理
- 使用 Pinia，每个模块独立 store
- API 请求在 store 的 action 中调用，组件只 dispatch action
- 加载状态由 store 内部的 loading 字段管理