database_render/upgrade.md

自定义模板系统规范 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 接口
• 不包含任何模板渲染逻辑
• 支持分页、搜索、排序参数

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

前端职责

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

渲染流程

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

配置规范

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 配置支持
• 添加模板热重载
• 实现版本管理
• 编写开发文档

开发规范

模板开发

<!-- 自定义列表模板示例 -->
{{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

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

迁移指南

从旧版本迁移

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