zwt13703
161 lines
3.9 KiB
Markdown
161 lines
3.9 KiB
Markdown
# AGENTS.md — AI 编码助手指引
|
||
|
||
> 本文档供 Claude Code / Copilot / Cursor 等 AI 编码助手读取，确保生成的代码符合项目约定。
|
||
|
||
---
|
||
|
||
## 项目概述
|
||
|
||
AI 文档模板生成系统（第一阶段 MVP），定位是一个 **Word 模板标注器**。
|
||
|
||
核心流程：上传 Word → 解析标题/段落/表格 → 生成 HTML 预览（含 data-block-id）→ 用户点击区域 → 配置提示词 → 保存配置。
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
- **前端**：Vue 3 + TypeScript + Vite + Element Plus + Pinia + Vue Router 4
|
||
- **后端**：Python 3.11+ + FastAPI + SQLAlchemy + Alembic + MySQL 8.0
|
||
- **存储**：MinIO（文件）/ MySQL（结构化数据）
|
||
- **关键词**：block_id, template, region_type, upsert
|
||
|
||
---
|
||
|
||
## 代码约定
|
||
|
||
### 后端
|
||
|
||
- 路由文件在 `app/api/`，服务逻辑在 `app/services/`，Model 在 `app/models/`
|
||
- 所有接口返回 JSON，统一格式 `{"data": ..., "message": "ok"}`
|
||
- 错误返回 `{"detail": "错误信息"}`
|
||
- 使用 Python类型注解
|
||
- 数据库 session 通过依赖注入 `get_db` 获取
|
||
- Model 使用 `sqlalchemy.orm.DeclarativeBase`
|
||
|
||
### 前端
|
||
|
||
- 组件使用 Composition API + `<script setup lang="ts">`
|
||
- 全局状态走 Pinia，不滥用 props/emit 跨多层传递
|
||
- API 请求走 `src/api/base.ts` 的 axios 实例
|
||
- 样式优先使用全局 CSS 变量（`var(--c-primary)`），避免硬编码色值
|
||
- 组件文件命名：`PascalCase.vue`
|
||
|
||
### 数据库
|
||
|
||
- 表名：snake_case（如 `template_block`）
|
||
- 字段名：snake_case（Model 中用 `__tablename__` 映射）
|
||
- 迁移使用 Alembic auto-generation
|
||
|
||
---
|
||
|
||
## 核心数据模型
|
||
|
||
### template
|
||
|
||
```python
|
||
class Template(Base):
|
||
__tablename__ = "template"
|
||
id: int # PK, auto
|
||
name: str # 模板名称
|
||
type: str # 报告类/公文类
|
||
version: str # v1.0.0
|
||
original_file_path: str # 文件存储路径
|
||
status: int # 1=启用 0=停用
|
||
created_by: str
|
||
created_at: datetime
|
||
updated_at: datetime
|
||
```
|
||
|
||
### template_block
|
||
|
||
```python
|
||
class TemplateBlock(Base):
|
||
__tablename__ = "template_block"
|
||
id: int # PK
|
||
template_id: int # FK → template.id
|
||
block_id: str # "block_001"
|
||
parent_block_id: str | None
|
||
block_type: str # "title" | "heading" | "paragraph" | "table"
|
||
block_name: str | None
|
||
text_preview: str | None
|
||
level: int
|
||
sort_order: int
|
||
table_rows: int | None
|
||
table_cols: int | None
|
||
```
|
||
|
||
### block_config
|
||
|
||
```python
|
||
class BlockConfig(Base):
|
||
__tablename__ = "block_config"
|
||
id: int # PK
|
||
template_id: int # FK
|
||
block_id: str # "block_003"
|
||
region_name: str | None
|
||
region_type: str # "ai_generate" | "manual" | "fixed" | "table"
|
||
data_sources: str | None # JSON 数组字符串
|
||
prompt: str | None
|
||
output_format: str # "formal_paragraph" | ...
|
||
need_review: int # 0/1
|
||
remark: str | None
|
||
enabled: int # 0/1
|
||
# UNIQUE(template_id, block_id)
|
||
```
|
||
|
||
---
|
||
|
||
## 关键接口
|
||
|
||
### 上传模板
|
||
```
|
||
POST /api/templates/upload
|
||
multipart/form-data: file + name + type
|
||
→ {"template_id": 1, "name": "...", "status": "uploaded"}
|
||
```
|
||
|
||
### 模板详情（核心接口）
|
||
```
|
||
GET /api/templates/{id}
|
||
→ {
|
||
template: {...},
|
||
preview_html: "<div ...>",
|
||
blocks: [...],
|
||
tree: [...],
|
||
configs: {"block_003": {...}}
|
||
}
|
||
```
|
||
|
||
### 保存区域配置
|
||
```
|
||
POST /api/templates/{id}/blocks/{blockId}/config
|
||
{region_name, region_type, data_sources, prompt, output_format, need_review, remark, enabled}
|
||
→ {"message": "saved"}
|
||
```
|
||
|
||
---
|
||
|
||
## 第一阶段不做
|
||
|
||
- ❌ 完整在线 Word 编辑
|
||
- ❌ 多人协同
|
||
- ❌ 权限审批
|
||
- ❌ 复杂表格智能填充
|
||
- ❌ 移动端适配
|
||
- ❌ 提示词历史版本（后续阶段）
|
||
|
||
---
|
||
|
||
## 项目启动
|
||
|
||
```bash
|
||
# 后端
|
||
docker compose up -d mysql minio
|
||
cd backend && pip install -r requirements.txt
|
||
alembic upgrade head
|
||
uvicorn app.main:app --reload
|
||
|
||
# 前端
|
||
cd frontend && npm install && npm run dev
|
||
```
|