database_render/docs/template_system.md

# 模板系统开发文档

## 概述

本项目实现了一个可扩展的三层模板系统，支持动态模板渲染、热重载、版本管理和YAML配置。

## 架构设计

### 三层模板架构

1. **布局模板 (Layout Template)**
   - 基础布局结构，固定不变
   - 提供响应式设计框架
   - 包含核心CSS和JS引用

2. **列表模板 (List Template)**
   - 可扩展的列表/表格/卡片视图模板
   - 支持多种展示模式：table、card、timeline
   - 模板继承自布局模板

3. **字段模板 (Field Template)**
   - 独立的字段渲染器
   - 支持多种数据类型：string、time、tag、markdown等
   - 可插拔式设计

### 核心组件

#### 1. TemplateLoader (模板加载器)
- 负责模板加载和缓存管理
- 支持三层模板架构
- 提供模板验证和错误处理

#### 2. VersionManager (版本管理器)
- 模板版本控制
- 自动备份和回滚
- 版本历史记录

#### 3. HotReloadWatcher (热重载监听器)
- 文件变更自动检测
- 实时模板更新
- 开发模式优化

#### 4. ConfigLoader (配置加载器)
- YAML配置文件解析
- 模板类型定义
- 字段渲染器配置

## 使用指南

### 快速开始

1. **启动服务**
```bash
cd cmd/template_system
go run main.go
```

2. **访问示例**
- 模板管理界面: http://localhost:8080
- API文档: http://localhost:8080/api/templates/health

### 模板定义

#### 创建自定义模板

1. **基础模板结构**
```yaml
# config/templates.yaml
templates:
  my_table:
    name: "我的表"
    type: "list"
    description: "自定义表视图"
    fields:
      id: "number"
      name: "string"
      created_at: "time"
    config:
      page_size: 10
      show_search: true
```

2. **模板文件位置**
```
web/templates/
├── builtin/           # 内置模板
│   ├── layout.html    # 基础布局
│   ├── list.html      # 列表模板
│   └── field/         # 字段模板
├── custom/            # 自定义模板
│   ├── _default/      # 默认模板
│   └── {table_name}/  # 特定表模板
└── config/templates.yaml # 模板配置
```

### API接口

#### 模板管理API

1. **获取可用模板**
```http
GET /api/templates/available?table=users
```

2. **获取模板配置**
```http
GET /api/templates/config
```

3. **版本历史**
```http
GET /api/templates/versions/{template_name}
```

4. **创建新版本**
```http
POST /api/templates/versions/{template_name}
Content-Type: application/json

{
  "description": "添加搜索功能",
  "author": "developer"
}
```

5. **回滚版本**
```http
POST /api/templates/versions/{template_name}/rollback/{version}
```

#### 前端渲染API

1. **动态渲染**
```javascript
// 使用前端渲染引擎
const templateEngine = new TemplateEngine();
const result = await templateEngine.render('list', 'users', data);
```

2. **模板切换**
```javascript
// 切换模板类型
const uiController = new UIController();
await uiController.switchTemplate('card', 'users');
```

### 开发特性

#### 热重载

在开发模式下，模板文件变更会自动检测并重载：

1. **启用热重载**
```go
config := template.TemplateConfig{
    HotReload: true,
    // ... 其他配置
}
```

2. **手动重载**
```http
POST /api/templates/hotreload/reload
```

#### 版本管理

1. **自动版本控制**
- 每次模板修改自动创建版本
- 支持版本回滚
- 版本历史追踪

2. **版本命令**
```bash
# 查看版本历史
curl http://localhost:8080/api/templates/versions/{template_name}

# 回滚到指定版本
curl -X POST http://localhost:8080/api/templates/versions/{template_name}/rollback/{version}
```

### 性能优化

#### 缓存策略

1. **模板缓存**
- LRU缓存机制
- 可配置缓存大小
- 支持缓存清除

2. **前端缓存**
- 模板结果缓存5分钟
- 智能缓存失效
- 内存优化

#### 预加载

1. **模板预加载**
- 常用模板预加载
- 延迟加载策略
- 按需加载

2. **性能监控**
```javascript
// 启用性能监控
const monitor = new PerformanceMonitor();
monitor.enableTracking();
```

### 配置说明

#### 模板类型配置

```yaml
template_types:
  list:
    layout: "table"
    fields:
      default: "raw"
      time: "time"
      tag: "tag"
    options:
      striped: true
      hover: true
```

#### 字段类型配置

```yaml
field_types:
  string:
    type: "text"
    renderer: "text"
    validation:
      max_length: 100
  
  time:
    type: "datetime"
    renderer: "time"
    formatting:
      format: "2006-01-02 15:04:05"
```

### 最佳实践

1. **模板组织**
   - 保持模板简单，专注单一功能
   - 使用语义化的模板名称
   - 合理利用模板继承

2. **性能优化**
   - 启用模板缓存
   - 使用CDN加载静态资源
   - 压缩模板文件

3. **版本管理**
   - 定期清理旧版本
   - 使用有意义的版本描述
   - 测试版本回滚功能

### 故障排除

#### 常见问题

1. **模板加载失败**
   - 检查文件路径权限
   - 验证模板语法
   - 查看错误日志

2. **热重载不工作**
   - 确认文件权限
   - 检查文件监听限制
   - 查看系统日志

3. **版本回滚失败**
   - 检查版本文件是否存在
   - 确认版本标识符正确
   - 验证文件权限

### 扩展开发

#### 添加新的字段渲染器

1. **创建字段模板**
```html
<!-- web/templates/builtin/field/new_type.html -->
{{define "field_new_type"}}
<div class="field-new-type">
  {{.Value}}
</div>
{{end}}
```

2. **注册字段类型**
```yaml
field_types:
  new_type:
    type: "custom"
    renderer: "new_type"
```

#### 添加新的模板类型

1. **创建模板文件**
```html
<!-- web/templates/builtin/new_type.html -->
{{template "layout" .}}
```

2. **注册模板类型**
```yaml
template_types:
  new_type:
    layout: "new_layout"
    fields: {}
```

### 贡献指南

欢迎提交PR和Issue！

1. Fork项目
2. 创建特性分支
3. 添加测试
4. 提交PR

## 许可证

MIT License