106 lines
3.2 KiB
Markdown
106 lines
3.2 KiB
Markdown
# 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 字段管理
|