ai-doc-template-system/AGENTS.md

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

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

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

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 编辑
• ❌ 多人协同
• ❌ 权限审批
• ❌ 复杂表格智能填充
• ❌ 移动端适配
• ❌ 提示词历史版本（后续阶段）

---

项目启动

# 后端
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