init

AGENTS.md

@@ -0,0 +1,58 @@
+# AGENTS.md — doc-forge
+
+你正在参与一个外包项目，客户需要一套完整的 AI 文档模板生成系统。
+
+## 你的角色
+全栈开发 AI 助手，负责生成 Vue 3 + Ant Design Vue 前端代码和 Python FastAPI 后端代码。
+
+## 基础设施
+
+### MySQL
+- 数据库名：`doc_forge`，字符集 `utf8mb4`
+- 异步驱动：`asyncmy`
+- 连接池：pool_size=10, max_overflow=20
+- 本地开发：`docker-compose up mysql`
+- DDL 见 `init.sql`
+
+### MinIO（对象存储）
+- 三个 bucket：`doc-forge-templates`（模板）/ `doc-forge-uploads`（参考文件）/ `doc-forge-outputs`（导出文档）
+- 文件路径规则：`{bucket}/{YYYYMMDD}/{uuid}.{ext}`
+- 预签名 URL 用于前端下载，过期 1 小时
+- 本地开发：`docker-compose up minio`，Console http://localhost:9001
+- SDK：`from minio import Minio`，客户端在 `services/minio_client.py`
+
+### Docker
+- `docker-compose up -d mysql minio` 启动开发依赖
+- `docker-compose up backend web` 启动全栈
+
+## 通讯协议
+- 所有 API 响应格式：`{ code: 0, data: {...}, message: "ok" }`
+- 错误响应：`{ code: -1, message: "错误描述" }`
+- 分页响应：`{ code: 0, data: { items: [], total: N, page: 1, page_size: 20 } }`
+
+## 必须遵守的规则
+
+1. **AI 输出格式** — AI 必须返回 JSON，不得返回纯文本。前端解析 `content` 数组，按 type 分段渲染。
+2. **Word 导出** — 严禁重新生成文档。从 MinIO 拉取原始模板，只替换对应位置的文本节点。
+3. **段落边界** — 只认 Word 标题样式（Heading）。不要尝试用正则或关键词判断段落。
+4. **API Key 安全** — 所有 API Key 用 `cryptography.fernet.Fernet` 加密存储，前端只展示脱敏字符串。
+5. **并发控制** — 段落生成使用 `asyncio.gather` + `Semaphore`，单文档最大并发 5。
+6. **文件存储** — 所有用户文件存 MinIO，后端本地只做临时缓存。
+7. docs/规范与约束/开发规范.md
+8. docs/需求与设计/02-模板格式规范.md
+
+## 段落配置字段
+每个 paragraph 包含：
+- `edit_mode`: 'manual' | 'ai'
+- `model_id`: int | null（null 表示使用系统默认模型）
+- `need_prompt`: boolean + `prompt_text`: string
+- `need_file`: boolean + `file_note`: string（备注提示上传什么文件）
+- `output_format`: 'text' | 'table' | 'mixed' | 'chart'
+
+## 容易踩的坑
+- python-docx 中文字体名在 `run.fonts.eastAsia`，不是 `run.fonts.name`
+- Ant Design Vue 4.x 的 modal 使用 `v-model:open`，不是 `v-model:visible`
+- SSE 事件流要用 `sse-starlette` 的 `EventSourceResponse`
+- asyncio 中不能混用同步的 openpyxl，Excel 解析放在线程池执行 (`run_in_executor`)
+- MinIO SDK 是同步的，用 `run_in_executor` 包装，不要直接 in asyncio
+- asyncmy 连接 MySQL 需要 `charset=utf8mb4`，不然中文会乱码