doc-forge/CLAUDE.md

doc-forge — AI 文档模板生成系统

项目概述

上传 Word 模板 → AI 自动解析段落（按标题样式切割）→ 用户标注段落配置 → 上传参考文件 → AI 多段落并行生成 → 预览编辑 → 导出 Word（保留原始样式）。

技术栈

层	技术	说明
前端	Vue 3.4 + TypeScript + Ant Design Vue 4.x + Pinia + Vite 5	web/
后端	Python 3.11+ + FastAPI + SQLAlchemy 2.0 async	backend/app/
数据库	MySQL 8.0（asyncmy 驱动）	docker-compose mysql
对象存储	MinIO	存模板文件、参考文件、生成文档
Word 处理	python-docx	解析/导出
Excel 处理	openpyxl	解析参考文件

目录结构

doc-forge/
├── web/                 前端
│   └── src/
│       ├── views/       TemplateList, TemplateEditor, ModelManage, GeneratePage, HistoryPage, PreviewEdit
│       ├── components/  ParagraphList, ParagraphConfig, DocPreview, FileUploader, ModelModal, TestModal
│       ├── api/         Axios（template, model, generate）
│       ├── stores/      Pinia（template, model, document）
│       └── router/      6 条路由
├── backend/
│   ├── app/
│   │   ├── models/      ORM（template, paragraph, ai_model, document, generation_log）
│   │   ├── routers/     API（templates, models, generate, export）
│   │   ├── schemas/     Pydantic 校验
│   │   ├── services/    业务逻辑（parser, ai_service, generator, exporter, minio_client）
│   │   └── main.py
│   ├── config.py        配置（MySQL + MinIO + AI）
│   └── database.py      异步引擎
├── docs/                项目文档
├── docker-compose.yml   MySQL + MinIO + backend + web
├── init.sql             数据库建表 DDL
├── CLAUDE.md
└── AGENTS.md

关键约定

段落解析规则

• 段落边界由 Word 标题样式（Heading 1~6）确定
• 标题与下一标题之间的正文、表格归属到该标题段落
• 表格独立存储为 is_table=True，归属于前一个标题

AI 输出格式

AI 必须返回结构化 JSON：

{"content": [{"type": "text", "text": "..."}, {"type": "table", "headers": [], "rows": []}]}

文件存储

• 所有文件存 MinIO，不存本地磁盘
• bucket 分三类：templates / uploads / outputs
• MinIO 开发环境在 docker-compose 中启动

AI 模型调用

• OpenAI 格式：GPT-4o, DeepSeek-V3, 通义千问
• Anthropic 格式：Claude 3.5 Sonnet
• 超时 60s，最多重试 3 次，单文档最大并发 5

Word 导出

• 从 MinIO 拉取原始模板 → 在内存中修改 → 上传回 MinIO
• 样式完全保留（字体/颜色/行距/页边距/页眉页脚）