feat: update auto render

2025-08-07 20:03:53 +08:00
parent fd67864247
commit d7e8ca38f8
39 changed files with 5684 additions and 130 deletions
--- a/upgrade.md
+++ b/upgrade.md
@@ -0,0 +1,186 @@
+# 自定义模板系统规范 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. 测试自定义模板兼容性