---
name: data-page
description: 数据页面脚手架:把 table/dashboard/kanban 模板复制到任务目录 app/templates/,配合 db 工具产出 /app/{task_id}/ 可访问、经 /api/db/{task_id}/query 读写 data.db 的查看/管理页
visit_url: /app/{task_id}/
---
# data-page
## 何时使用
当用户提出以下需求时使用本技能:
- 把数据整理到数据库
- 生成数据查看页面
- 生成数据管理页面
- 数据统计展示
不适用:纯粹的文件读写、代码编写、信息检索。
## 环境约定
每个会话有独立的任务目录:
- 数据库:任务目录下的 `data.db`
- 页面目录:任务目录下的 `app/`
- 页面入口:`app/index.html`
- 访问地址:`/app/{task_id}/`(完整 URL = 站点地址 + 该路径;run 输出末尾的「访问地址」已拼好,直接转发)
- 数据 API:`/api/db/{task_id}/query`
`{task_id}` 是任务目录的名称。页面通过 URL 动态解析,不要硬编码。
## 初始化
生成页面前,调用 `skill(name="data-page", op="run")`(无需参数,模板固定复制到 `app/templates/`)。已存在则跳过,不会覆盖修改过的文件(重跑幂等)。
## 数据 API
页面通过此接口读写数据。
### 请求
```
POST /api/db/{task_id}/query
Content-Type: application/json
{
"sql": "SELECT * FROM parts WHERE qty > ?",
"params": [0]
}
```
- `sql`:任意 SQLite 语句
- `params`:参数化绑定的值数组,可省略
- 必须使用参数化,不要把用户输入拼进 SQL
### 响应
成功时返回 JSON:
- SELECT:行数组 `[{"id": 1, "name": "螺丝"}, ...]`
- 写操作:`{"rowsAffected": 1, "lastInsertRowid": 3}`
- 建表等 DDL:`{"ok": true}`
失败时返回 `{"error": "错误信息"}`,HTTP 状态码仍为 200。前端需要检查 `error` 字段。
### task_id 获取
```javascript
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/...` 相对路径用户打不开;再简要说明页面功能。
页面必须包含:
- HTML 骨架(``、``、UTF-8)
- 桌面优先、移动兼容的样式:容器宽度按页面类型给足(表格类 1200px、看板类 1400px 或不设、统计类 1080px),不要照搬 800px 级别的移动端尺寸
- 通过 `fetch` 调用数据 API
- 错误处理和加载状态
- **返回应用入口**:右下角 FAB(房子图标),`backToApp()` 跳主界面深链 `/?s=`——数据页面的 task_id 就是会话 id,一点直达发起本页的对话;若未来 APK 提供 JS 桥,只需替换 `backToApp()` 一处。**每一个 `app/*.html` 页面(含 index.html)都要带**——用户可能从任意子页直入,缺出口即被困住
## 模板
模板位于 `app/templates/`。
- **table.html**:标准表格,适合清单、列表。含排序、搜索、分页。
- **dashboard.html**:统计看板,顶部卡片 + 简单图表 + 明细表。
- **kanban.html**:分组看板,按字段分列展示。
优先使用模板。模板都不合适时才从零写。
## 最小示例
```html
采购清单
采购清单
加载中…
```
## 最佳实践
**前端**
- 用原生 JS + fetch,不引入框架
- 样式用内联 `