data-page重构评审后两项修补:①自定义页面护栏回填——重构砍掉的旧版最佳实践恰是手写页最需要的底线(骨架三件套/用户数据必转义优先textContent、innerHTML先过esc/SQL参数化+查error字段+加载错误态/大表LIMIT超2000行服务端报error),模板自带这层保护、AI自由发挥的custom.html没有,SKILL.md补为硬要求5-8并把检查清单扩成四项联动;②dashboard count模式去重复卡——metric为count时与固定「总条数」卡同值,只渲两张且省一条冗余COUNT(*) SQL,metric查询按isCount短路为null(渲染分支同守卫);另评审确认:模板/config/base.css三层职责切分成立,类覆盖无悬空,kanban-card改名接线一致,config缺失静默回退DEFAULT属可接受降级
This commit is contained in:
+75
-120
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: data-page
|
||||
description: 数据页面脚手架:把 table/dashboard/kanban 模板复制到任务目录 .app/templates/,配合 db 工具产出 /app/{task_id}/ 可访问、经 /api/db/{task_id}/query 读写 data.db 的查看/管理页
|
||||
description: 数据页面脚手架:把 table/dashboard/kanban 模板复制到任务目录 .app/,配合 db 工具产出 /app/{task_id}/ 可访问、经 /api/db/{task_id}/query 读写 data.db 的查看/管理页
|
||||
visit_url: /app/{task_id}/
|
||||
---
|
||||
|
||||
@@ -24,14 +24,20 @@ visit_url: /app/{task_id}/
|
||||
- 数据库:任务目录下的 `data.db`
|
||||
- 页面目录:任务目录下的 `.app/`(带点目录,任务文件面板默认隐藏;URL 路径与目录名在路由层解耦)
|
||||
- 页面入口:`.app/index.html`
|
||||
- 访问地址:`/app/{task_id}/`(注意:URL 无点、目录有点,别写错路径;完整 URL = 站点地址 + 该路径,run 输出末尾的「访问地址」已拼好,直接转发)
|
||||
- 访问地址:`/app/{task_id}/`(URL 无点、目录有点,别写错;完整 URL = 站点地址 + 该路径,run 输出末尾的「访问地址」已拼好,直接转发)
|
||||
- 数据 API:`/api/db/{task_id}/query`
|
||||
|
||||
`{task_id}` 是任务目录的名称。页面通过 URL 动态解析,不要硬编码。
|
||||
|
||||
## 初始化
|
||||
|
||||
生成页面前,调用 `skill(name="data-page", op="run")`(无需参数,模板固定复制到 `.app/templates/`)。已存在则跳过,不会覆盖修改过的文件(重跑幂等)。
|
||||
调用 `skill(name="data-page", op="run")`,无需参数。它会把以下文件复制到 `.app/`:
|
||||
|
||||
- `table.html` / `dashboard.html` / `kanban.html` —— 三个页面模板
|
||||
- `base.css` —— 共用样式
|
||||
- `config-table.js` / `config-dashboard.js` / `config-kanban.js` —— 配置骨架
|
||||
|
||||
已存在则跳过,不会覆盖(重跑幂等)。
|
||||
|
||||
## 数据 API
|
||||
|
||||
@@ -73,130 +79,77 @@ const taskId = location.pathname.split('/').filter(Boolean)[1];
|
||||
|
||||
1. **明确数据结构**:与用户确认字段。如果描述模糊,可以建议合理的结构。
|
||||
2. **创建表并录入数据**:用 `db` 工具完成。
|
||||
3. **初始化模板**:调用 `skill(name="data-page", op="run")`(无参数)。
|
||||
4. **生成页面**:从 `.app/templates/` 选合适的模板,根据表结构调整字段和 SQL,写入 `.app/index.html`。
|
||||
5. **告知用户**:把 run 输出末尾「访问地址」那行的**完整 URL**(含域名)发给用户——只给 `/app/...` 相对路径用户打不开;再简要说明页面功能。
|
||||
3. **初始化**:调用 `skill(name="data-page", op="run")`。
|
||||
4. **为每个要生成的页面写 config 文件**(见下一节)。**不要读也不要改模板本身**。
|
||||
5. **选定入口页**:把要作为首页的模板复制为 `.app/index.html`(同目录复制,引用路径不变),或直接保留多个页面并在 index.html 里做导航。
|
||||
6. **告知用户**:把 run 输出末尾「访问地址」那行的完整 URL 发给用户,再简要说明页面功能。
|
||||
|
||||
页面必须包含:
|
||||
默认只写 config 就够。模板无法覆盖需求时,才走自定义路径(见「自定义页面」一节)。
|
||||
|
||||
- HTML 骨架(`<!DOCTYPE html>`、`<meta viewport>`、UTF-8)
|
||||
- 桌面优先、移动兼容的样式:容器宽度按页面类型给足(表格类 1200px、看板类 1400px 或不设、统计类 1080px),不要照搬 800px 级别的移动端尺寸
|
||||
- 通过 `fetch` 调用数据 API
|
||||
- 错误处理和加载状态
|
||||
- **返回应用入口**:右下角 FAB(房子图标),`backToApp()` 跳主界面深链 `/?s=<task_id>`——数据页面的 task_id 就是会话 id,一点直达发起本页的对话;若未来 APK 提供 JS 桥,只需替换 `backToApp()` 一处。**每一个 `.app/*.html` 页面(含 index.html)都要带**——用户可能从任意子页直入,缺出口即被困住
|
||||
## 页面配置
|
||||
|
||||
## 模板
|
||||
三个模板对应三份 config:
|
||||
|
||||
模板位于 `.app/templates/`。
|
||||
| 模板 | config 文件 | 用途 |
|
||||
|---|---|---|
|
||||
| `table.html` | `config-table.js` | 清单、列表、增删改 |
|
||||
| `dashboard.html` | `config-dashboard.js` | 统计、汇总、明细 |
|
||||
| `kanban.html` | `config-kanban.js` | 按字段分列,状态流转 |
|
||||
|
||||
- **table.html**:标准表格,适合清单、列表。含排序、搜索、分页。
|
||||
- **dashboard.html**:统计看板,顶部卡片 + 简单图表 + 明细表。
|
||||
- **kanban.html**:分组看板,按字段分列展示。
|
||||
每份 config 的结构:
|
||||
|
||||
优先使用模板。模板都不合适时才从零写。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>采购清单</title>
|
||||
<style>
|
||||
body { font-family: system-ui, sans-serif; margin: 0; padding: 16px; background: #f5f5f5; }
|
||||
h1 { font-size: 20px; margin: 0 0 16px; }
|
||||
.card { background: white; border-radius: 12px; padding: 16px; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
|
||||
table { width: 100%; border-collapse: collapse; }
|
||||
th, td { padding: 8px; text-align: left; border-bottom: 1px solid #eee; font-size: 14px; }
|
||||
th { color: #666; font-weight: 500; }
|
||||
.empty { text-align: center; color: #999; padding: 32px; }
|
||||
.error { color: #d33; padding: 12px; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>采购清单</h1>
|
||||
<div class="card" id="content">加载中…</div>
|
||||
|
||||
<script>
|
||||
const taskId = location.pathname.split('/').filter(Boolean)[1];
|
||||
const API = `/api/db/${taskId}/query`;
|
||||
|
||||
async function query(sql, params = []) {
|
||||
const res = await fetch(API, {
|
||||
method: 'POST',
|
||||
headers: {'Content-Type': 'application/json'},
|
||||
body: JSON.stringify({sql, params})
|
||||
});
|
||||
const data = await res.json();
|
||||
if (data.error) throw new Error(data.error);
|
||||
return data;
|
||||
}
|
||||
|
||||
function escapeHtml(s) {
|
||||
return String(s ?? '').replace(/[&<>"']/g, c => ({
|
||||
'&':'&','<':'<','>':'>','"':'"',"'":'''
|
||||
}[c]));
|
||||
}
|
||||
|
||||
async function render() {
|
||||
const el = document.getElementById('content');
|
||||
try {
|
||||
const rows = await query('SELECT * FROM parts ORDER BY id');
|
||||
if (!rows.length) {
|
||||
el.innerHTML = '<div class="empty">暂无数据</div>';
|
||||
return;
|
||||
}
|
||||
el.innerHTML = `<table>
|
||||
<thead><tr><th>名称</th><th>规格</th><th>类别</th><th>数量</th><th>单位</th><th>备注</th></tr></thead>
|
||||
<tbody>${rows.map(r => `<tr>
|
||||
<td>${escapeHtml(r.name)}</td>
|
||||
<td>${escapeHtml(r.spec)}</td>
|
||||
<td>${escapeHtml(r.category)}</td>
|
||||
<td>${escapeHtml(r.qty)}</td>
|
||||
<td>${escapeHtml(r.unit)}</td>
|
||||
<td>${escapeHtml(r.note)}</td>
|
||||
</tr>`).join('')}</tbody>
|
||||
</table>`;
|
||||
} catch (e) {
|
||||
el.innerHTML = `<div class="error">加载失败:${escapeHtml(e.message)}</div>`;
|
||||
}
|
||||
}
|
||||
|
||||
render();
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
```javascript
|
||||
window.PAGE_CONFIG = {
|
||||
table: '表名',
|
||||
pk: 'id',
|
||||
title: '页面标题',
|
||||
// ...字段见下
|
||||
};
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
只写实际需要的字段,其余用模板默认值。
|
||||
|
||||
**前端**
|
||||
### config-table.js 字段
|
||||
|
||||
- 用原生 JS + fetch,不引入框架
|
||||
- 样式用内联 `<style>` 或独立 CSS,不依赖外部 CSS 库
|
||||
- 图表用纯 SVG 或 CSS 绘制
|
||||
- 桌面优先、移动兼容:数据页面主要在电脑上看,窄屏靠横向滚动兑底
|
||||
- 所有可能横向溢出的内容(表格、长文本、代码)包一层 `overflow-x: auto` 容器;卡片内滚动可配合负 margin 贴边
|
||||
- flex 居中用 `width: fit-content; margin: 0 auto`,不用 `justify-content: center`(内容超出滚动容器时居中会裁掉首屏左侧)
|
||||
- 显示加载状态和错误提示
|
||||
- 提交类按钮加禁用状态,避免重复点击
|
||||
- `table`、`pk`、`title`、`pageSize`、`editable`
|
||||
- `labels`:`{ 列名: '中文标签' }`,未列出的列用原名
|
||||
- `numCols`:`['数值列名', ...]`,数字列右对齐
|
||||
- `options`:`{ 列名: ['枚举值1', '枚举值2'] }`,编辑时用下拉
|
||||
- `pills`:`{ 列名: { '值': 'ok|ship|pay|refund' } }`,状态着色
|
||||
|
||||
**数据库**
|
||||
### config-dashboard.js 字段
|
||||
|
||||
- 使用参数化查询
|
||||
- 大表查询加 `LIMIT`
|
||||
- `table`、`pk`、`title`、`groupBy`、`detailColumns`、`detailLimit`
|
||||
- `metric`:`{ type: 'count' }` 或 `{ type: 'sum', column: '列名', label: '标签' }`
|
||||
|
||||
**安全**
|
||||
### config-kanban.js 字段
|
||||
|
||||
- 用户输入渲染到 HTML 时用 `textContent`,或用 `escapeHtml` 转义后再用 `innerHTML`
|
||||
- `table`、`pk`、`title`
|
||||
- `groupField`:分列字段
|
||||
- `groups`:`['列1', '列2', ...]`,列的显示顺序
|
||||
- `titleField`:卡片主标题字段
|
||||
- `metaFields`:`['字段1', '字段2']`,卡片上显示的次要信息
|
||||
|
||||
**用户体验**
|
||||
## 自定义页面
|
||||
|
||||
- 页面标题反映数据内容
|
||||
- 空数据时显示友好提示
|
||||
- 操作有反馈(保存成功、删除确认)
|
||||
只有当模板无法覆盖需求时(特殊图表、多表关联、自定义交互等)才使用。
|
||||
|
||||
自定义页面必须满足:
|
||||
|
||||
1. 使用独立文件名(如 `.app/custom.html`)
|
||||
2. 引用 `./base.css` 继承统一视觉
|
||||
3. 提供返回会话入口(FAB,跳 `/?s=<task_id>`)
|
||||
4. 在回复中说明为什么没用模板
|
||||
5. HTML 骨架完整:`<!DOCTYPE html>`、`<meta charset="UTF-8">`、`<meta name="viewport" content="width=device-width, initial-scale=1">`
|
||||
6. 用户数据渲染必转义:优先 `textContent`;用 `innerHTML` 先过 `esc()`(照抄模板里的实现),绝不把 API 查询结果裸拼进 HTML——模板自带转义,手写页面没有这层保护
|
||||
7. 所有 SQL 参数化(`?`);fetch 结果检查 `error` 字段(失败仍是 HTTP 200),并有加载态/错误提示
|
||||
8. 大表查询加 `LIMIT`:服务端单次超 2000 行直接报 error
|
||||
|
||||
`.app/` 下每个 HTML 页面(含 index.html)都要有返回会话入口——用户可能从任意子页直入,缺出口即被困住。
|
||||
|
||||
## 视觉规范
|
||||
|
||||
配色、圆角、字体、阴影、容器宽度、FAB、看板卡片等基础样式由 `base.css` 统一提供,模板和自定义页面都引用它。自定义页面不要重写这些基础样式。
|
||||
|
||||
## 常见错误
|
||||
|
||||
@@ -205,16 +158,18 @@ const taskId = location.pathname.split('/').filter(Boolean)[1];
|
||||
3. 没检查 `error` 字段 —— API 错误时仍返回 200
|
||||
4. 表名或字段名拼错
|
||||
5. 引入 CDN 外部库 —— 容器可能无网络,优先纯原生
|
||||
6. 页面文件不在 `.app/` 下 —— 无法通过 `/app/{task_id}/` 访问(目录带点、URL 不带点,两者别写反)
|
||||
7. SQL 占位符与参数数量不匹配 —— 优先用结构化 insert,避免手写
|
||||
6. 页面文件不在 `.app/` 下 —— 无法通过 `/app/{task_id}/` 访问(目录带点、URL 不带点)
|
||||
7. SQL 占位符与参数数量不匹配 —— 优先用结构化 insert
|
||||
8. 读或改模板文件 —— 应只写 config
|
||||
9. 自定义页面没引用 `base.css` —— 视觉会和其它页面割裂
|
||||
|
||||
## 检查清单
|
||||
|
||||
- [ ] 数据库表已创建
|
||||
- [ ] 数据已录入
|
||||
- [ ] `.app/index.html` 已写入
|
||||
- [ ] 数据库表已创建、数据已录入
|
||||
- [ ] 调用了 `skill run`
|
||||
- [ ] 写好了对应的 `config-*.js`
|
||||
- [ ] 选定入口页(复制为 `.app/index.html` 或保留多页 + 导航)
|
||||
- [ ] 页面动态解析 task_id
|
||||
- [ ] 包含错误处理和加载状态
|
||||
- [ ] 用户输入渲染时已转义
|
||||
- [ ] 每个 `.app/*.html` 页面右下角都有「返回会话」FAB(backToApp → `/?s=<task_id>` 深链)
|
||||
- [ ] 已告知用户完整访问 URL(run 输出「访问地址」那行,含域名,非相对路径)
|
||||
- [ ] 每个 `.app/*.html` 都有返回会话入口
|
||||
- [ ] 自定义页面:引用了 `base.css`、数据渲染已转义、SQL 参数化、大表加 LIMIT
|
||||
- [ ] 已告知用户完整访问 URL(含域名)
|
||||
|
||||
Reference in New Issue
Block a user