init project

2026-07-01 19:50:29 +08:00
commit 685d69ebdc
21 changed files with 1002 additions and 0 deletions
@@ -0,0 +1,160 @@
+# 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
+```