# AGENTS.md — AI 编码助手指引

> 本文档供 Claude Code / Copilot / Cursor 等 AI 编码助手读取，确保生成的代码符合项目约定。

---

## 项目概述

AI 文档模板生成系统（第一阶段 MVP），定位是一个 **Word 模板标注器**。

核心流程：上传 Word → 解析标题/段落/表格 → 生成 HTML 预览（含 data-block-id）→ 用户点击区域 → 配置提示词 → 保存配置。

---

## 技术栈

- **前端**：Vue 3 + TypeScript + Vite + Ant Design Vue + 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
```