# 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`，不然中文会乱码