init

docs/规范与约束/开发规范.md

@@ -0,0 +1,105 @@
+# 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 字段管理