doc-forge/docs/规范与约束/开发规范.md

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 字段管理