# 自定义模板系统规范 v2.0

## 系统架构（三层分离）

### 1. 布局模板（固定层）

- **作用**：提供页面基础框架，包括头部、导航、底部等
- **特性**：系统内置，不可修改，所有页面共享
- **路径**：`web/templates/builtin/layout.html`
- **职责**：确保品牌一致性和基础用户体验

### 2. 列表模板（可扩展层）

- **作用**：定义数据列表的展示方式
- **支持类型**：
  - `list`：传统表格视图
  - `card`：卡片式网格视图
  - `timeline`：时间轴视图
- **自定义路径**：`web/templates/custom/{table_name}/`
- **后备机制**：未找到自定义模板时使用系统默认

### 3. 字段模板（可扩展层）

- **作用**：控制单个字段的渲染方式
- **内置渲染器**：
  - `raw`：原始文本
  - `markdown`：Markdown 渲染
  - `time`：时间格式化
  - `tag`：标签样式
  - `category`：分类显示
- **自定义路径**：`web/templates/custom/{table_name}/field/`

## 数据流与渲染机制

### 后端职责

- 提供标准化 JSON API 接口
- 不包含任何模板渲染逻辑
- 支持分页、搜索、排序参数

```http
GET /api/data/{table_alias}?page=1&per_page=20&search=keyword&sort=created_at&order=desc
```

### 前端职责

- 纯前端模板渲染（无服务端渲染）
- AJAX 获取数据后动态渲染
- 支持模板缓存和热重载

### 渲染流程

```
用户请求 → 加载布局模板 → 加载列表模板 → 加载字段模板 → AJAX获取数据 → 前端渲染
```

## 配置规范

### YAML 配置扩展

```yaml
templates:
  custom_path: "./web/templates/custom"
  cache_enabled: true
  hot_reload: false # 开发环境可开启

tables:
  - name: "articles"
    template: "card" # 可选：指定默认模板
    custom_templates:
      list: "custom/articles/list.html"
      fields:
        content: "custom/articles/field/markdown.html"
```

### 文件结构规范

```
web/templates/
├── builtin/              # 系统内置（只读）
│   ├── layout.html       # 基础布局
│   ├── list.html         # 默认列表
│   └── field/            # 默认字段渲染器
├── custom/               # 用户自定义
│   └── {table_name}/
│       ├── list.html     # 列表模板
│       ├── card.html     # 卡片模板
│       └── field/
│           ├── markdown.html
│           └── tag.html
```

## 约束条件

### 技术约束

- 模板必须继承基础布局
- 仅支持前端渲染，无服务端逻辑
- 模板文件名必须符合规范
- 不支持动态模板编译（安全考虑）

### 兼容性约束

- 自定义模板需兼容系统 CSS 框架（TailwindCSS）
- 必须保持响应式设计
- 支持 JavaScript API 接口规范

## 功能变更说明

### 已移除功能

- ❌ 表格/卡片模式切换功能
- ❌ 数据导出功能
- ❌ 服务端模板渲染
- ❌ 动态表格模式切换

### 新增功能

- ✅ 自定义列表模板支持
- ✅ 自定义字段渲染器
- ✅ 模板热重载（开发环境）
- ✅ 模板版本管理
- ✅ 多级模板继承

## 实施里程碑

### Phase 1：基础架构（Week 1-2）

- [ ] 建立三层模板架构
- [ ] 实现基础布局模板
- [ ] 创建文件结构规范
- [ ] 添加模板验证机制

### Phase 2：模板引擎（Week 3-4）

- [ ] 实现模板加载系统
- [ ] 建立模板继承机制
- [ ] 添加错误处理和回退
- [ ] 实现模板缓存

### Phase 3：前端集成（Week 5-6）

- [ ] 完成 AJAX 数据获取
- [ ] 实现动态模板渲染
- [ ] 添加模板切换 UI
- [ ] 优化加载性能

### Phase 4：配置系统（Week 7-8）

- [ ] 扩展 YAML 配置支持
- [ ] 添加模板热重载
- [ ] 实现版本管理
- [ ] 编写开发文档

## 开发规范

### 模板开发

```html
<!-- 自定义列表模板示例 -->
{{template "layout" .}} {{define "content"}}
<div class="custom-list">
  {{range .Data}}
  <div class="item">{{template "field" dict "Value" .Title "Type" "raw"}}</div>
  {{end}}
</div>
{{end}}
```

### JavaScript API

```javascript
// 模板系统API
TemplateSystem.load(tableName, templateType);
TemplateSystem.render(data, template);
TemplateSystem.reloadCache();
```

## 迁移指南

### 从旧版本迁移

1. 移除所有服务端模板渲染代码
2. 将现有模板迁移到新文件结构
3. 更新配置文件格式
4. 测试自定义模板兼容性