---
name: 模板系统代码设计
overview: 基于现有代码结构和前端原型，设计并实现完整的模板系统，包括模板CRUD、占位符解析、数据源绑定、模板渲染、复制/替换模式等核心功能。
todos:
  - id: create-dtos
    content: 创建模板相关的 DTO 类（CreateTemplateRequest、UpdateTemplateRequest、CopyTemplateRequest、ReplaceDataSourceRequest、TemplateRenderRequest、TemplateRenderResult、PlaceholderInfo、PlaceholderMapping）
    status: pending
  - id: create-parser
    content: 创建 PlaceholderParser 占位符解析工具类
    status: pending
  - id: create-template-service
    content: 创建 TemplateService 实现模板 CRUD、复制、占位符管理、数据源替换等业务逻辑
    status: pending
  - id: create-render-service
    content: 创建 TemplateRenderService 实现模板渲染（支持 HTML/Markdown/纯文本输出）
    status: pending
  - id: create-controller
    content: 创建 TemplateController 暴露 RESTful API 接口
    status: pending
  - id: update-repository
    content: 扩展 TemplateRepository 添加必要的查询方法
    status: pending
  - id: integration-test
    content: 编写集成测试验证模板系统功能
    status: pending
---

# 模板系统代码设计

## 一、系统架构

```mermaid
flowchart TB
    subgraph Frontend[前端]
        TemplateList[模板列表]
        TemplateEditor[模板编辑器]
        TemplatePreview[模板预览]
    end
    
    subgraph Backend[后端 graph-service]
        Controller[TemplateController]
        Service[TemplateService]
        Renderer[TemplateRenderService]
        Parser[PlaceholderParser]
        Repository[TemplateRepository]
    end
    
    subgraph Dependencies[依赖服务]
        DataSourceService[DataSourceService]
        DocumentService[DocumentService]
    end
    
    TemplateList --> Controller
    TemplateEditor --> Controller
    TemplatePreview --> Controller
    Controller --> Service
    Controller --> Renderer
    Service --> Repository
    Renderer --> Parser
    Renderer --> DataSourceService
    Service --> DataSourceService
```

## 二、核心数据模型

### 2.1 占位符映射结构（PlaceholderMapping）

```json
{
  "{{项目名称}}": {
    "dataSourceId": "ds_001",
    "type": "text",
    "defaultValue": "未设置"
  },
  "{{投资金额}}": {
    "dataSourceId": "ds_002", 
    "type": "text",
    "format": "currency"
  },
  "{{市场数据表}}": {
    "dataSourceId": "ds_003",
    "type": "table"
  },
  "{{项目图片}}": {
    "dataSourceId": "ds_004",
    "type": "image"
  }
}
```

### 2.2 模板内容示例

```text
# {{项目名称}}可行性研究报告

## 一、项目概述
本项目预计总投资{{投资金额}}，位于{{项目地点}}。

## 二、市场分析
{{市场数据表}}

## 三、项目效果
{{项目图片}}
```

## 三、代码结构设计

### 3.1 新增文件清单

```
graph-service/src/main/java/com/lingyue/graph/
├── controller/
│   └── TemplateController.java         # 模板API接口
├── service/
│   ├── TemplateService.java            # 模板业务逻辑
│   └── TemplateRenderService.java      # 模板渲染服务
├── dto/
│   ├── CreateTemplateRequest.java      # 创建模板请求
│   ├── UpdateTemplateRequest.java      # 更新模板请求
│   ├── CopyTemplateRequest.java        # 复制模板请求
│   ├── ReplaceDataSourceRequest.java   # 替换数据源请求
│   ├── TemplateRenderRequest.java      # 渲染请求
│   ├── TemplateRenderResult.java       # 渲染结果
│   ├── PlaceholderInfo.java            # 占位符信息
│   └── PlaceholderMapping.java         # 占位符映射
└── util/
    └── PlaceholderParser.java          # 占位符解析工具
```

## 四、核心接口设计

### 4.1 TemplateController API

| 方法 | 路径 | 描述 |

|-----|------|-----|

| POST | `/api/templates` | 创建模板 |

| GET | `/api/templates/{id}` | 获取模板详情 |

| GET | `/api/templates` | 查询模板列表 |

| PUT | `/api/templates/{id}` | 更新模板 |

| DELETE | `/api/templates/{id}` | 删除模板 |

| POST | `/api/templates/{id}/copy` | 复制模板 |

| PUT | `/api/templates/{id}/placeholders` | 更新占位符映射 |

| POST | `/api/templates/{id}/replace-datasources` | 批量替换数据源 |

| POST | `/api/templates/{id}/render` | 渲染模板 |

| GET | `/api/templates/{id}/placeholders` | 获取占位符列表 |

### 4.2 TemplateService 核心方法

```java
public interface TemplateService {
    // CRUD
    Template create(String userId, CreateTemplateRequest request);
    Template getById(String id);
    List<Template> getByUserId(String userId);
    Template update(String id, UpdateTemplateRequest request);
    void delete(String id);
    
    // 复制模式
    Template copy(String sourceTemplateId, CopyTemplateRequest request);
    
    // 占位符管理
    List<PlaceholderInfo> extractPlaceholders(String content);
    Template updatePlaceholderMapping(String id, Map<String, PlaceholderMapping> mapping);
    
    // 批量替换数据源
    Template replaceDataSources(String id, ReplaceDataSourceRequest request);
}
```

### 4.3 TemplateRenderService 核心方法

```java
public interface TemplateRenderService {
    // 渲染模板
    TemplateRenderResult render(String templateId);
    TemplateRenderResult render(Template template);
    
    // 预览渲染（不保存）
    TemplateRenderResult preview(String templateId);
    
    // 渲染单个占位符
    String renderPlaceholder(String placeholder, PlaceholderMapping mapping);
}
```

## 五、核心流程

### 5.1 模板渲染流程

```mermaid
sequenceDiagram
    participant Client
    participant Controller as TemplateController
    participant RenderService as TemplateRenderService
    participant Parser as PlaceholderParser
    participant DataSourceService
    
    Client->>Controller: POST /templates/{id}/render
    Controller->>RenderService: render(templateId)
    RenderService->>RenderService: getTemplate(id)
    RenderService->>Parser: extractPlaceholders(content)
    Parser-->>RenderService: List<PlaceholderInfo>
    
    loop 每个占位符
        RenderService->>RenderService: getMapping(placeholder)
        RenderService->>DataSourceService: getValue(dataSourceId)
        DataSourceService-->>RenderService: DataSourceValue
        RenderService->>RenderService: formatValue(value, type)
    end
    
    RenderService->>RenderService: replacePlaceholders()
    RenderService-->>Controller: TemplateRenderResult
    Controller-->>Client: 渲染结果
```

### 5.2 模板复制流程

```mermaid
sequenceDiagram
    participant Client
    participant Controller as TemplateController
    participant Service as TemplateService
    participant Repository as TemplateRepository
    
    Client->>Controller: POST /templates/{id}/copy
    Controller->>Service: copy(sourceId, request)
    Service->>Repository: selectById(sourceId)
    Repository-->>Service: 源模板
    Service->>Service: 复制模板内容和占位符映射
    Service->>Service: 设置sourceTemplateId
    Service->>Repository: insert(newTemplate)
    Repository-->>Service: 新模板
    Service-->>Controller: Template
    Controller-->>Client: 新模板信息
```

## 六、关键实现细节

### 6.1 占位符解析（PlaceholderParser）

- 支持格式：`{{占位符名称}}`
- 正则表达式：`\{\{([^}]+)\}\}`
- 提取信息：占位符名称、位置（行号、列号）、上下文

### 6.2 数据源替换模式

支持两种替换方式：

1. **ID映射替换**：`{"oldDataSourceId": "newDataSourceId"}`
2. **名称匹配替换**：按数据源名称自动匹配

### 6.3 渲染结果结构

```java
public class TemplateRenderResult {
    private String templateId;
    private String renderedContent;      // HTML格式
    private String renderedMarkdown;     // Markdown格式
    private String renderedPlainText;    // 纯文本格式
    private List<RenderDetail> details;  // 每个占位符的渲染详情
    private List<String> warnings;       // 警告信息（如数据源缺失）
    private Map<String, Object> metadata;
}
```

### 6.4 占位符类型处理

| 类型 | 处理方式 |

|-----|---------|

| text | 直接替换为文本值 |

| image | 生成 `<img>` 标签或 Markdown 图片语法 |

| table | 生成 HTML 表格或 Markdown 表格 |

| mixed | 根据实际数据类型自动处理 |

## 七、依赖现有代码

- [DataSourceService](backend/graph-service/src/main/java/com/lingyue/graph/service/DataSourceService.java)：获取数据源值
- [DataSourceValue](backend/graph-service/src/main/java/com/lingyue/graph/dto/DataSourceValue.java)：数据源值结构
- [Template](backend/graph-service/src/main/java/com/lingyue/graph/entity/Template.java)：模板实体
- [TemplateRepository](backend/graph-service/src/main/java/com/lingyue/graph/repository/TemplateRepository.java)：模板数据访问