轻应用要真正投入使用，通常需要保存和处理数据：用户偏好、内容点赞、成绩排行、限次参与等。此前，Frontend App 已可通过 Data Form 实现表单收集等功能；需要自定义数据表和更灵活的数据查询时，通常需要使用 Backend App，编写后端接口和权限逻辑。
本次平台升级新增 Frontend Data API：为 Frontend App 提供代码定义的数据表、访问权限和数据操作。无需自建后端接口，前端轻应用即可通过 SDK 读写数据，由服务端统一执行权限和数据规则。 对于 H5、互动活动和小游戏类应用，这是一个更轻量的选择。
典型应用场景
1. 我的记录、偏好与进度
用户的选择、偏好、学习进度、浏览历史，可以保存并在下次打开时恢复。配置“仅本人”权限后，每位登录用户只能查看和管理自己的记录。
2. 公开列表、搜索与筛选
产品列表、文章列表、活动名录，支持字段筛选、条件组合、排序和分页。公开列表和榜单可直接向匿名访客展示；仅使用公开访问时，无需先配置应用 Auth。
3. 数量与数值统计
对已记录的数据进行精确计数、求和与平均值计算，例如提交总数、成绩总分与平均分。计数统计的是符合条件的记录数；参与人数等指标需结合业务的数据记录方式设计。
4. 点赞与收藏
通过新增、删除记录实现点赞、取消点赞、收藏与取消收藏，利用唯一约束防止重复，并按需查询最新总数。
5. 排行榜与我的名次
成绩榜单按分数排序，可计算“我的名次”。排名遵循配置的可见范围，并支持并列名次或连续序号两种方式。
6. 每天 / 每周限 N 次提交
每日答题、签到打卡、抽奖报名，可按日、周、月限制提交次数，由服务端校验并拦截超额提交。同时支持幂等提交：同一次提交使用相同请求标识重试，不会重复写入或消耗次数。
7. 自动判分、金额计算与随机命中
固定规则的判分、金额计算、简单抽奖的随机命中，可由服务端在数据写入时自动完成。开发时定义计算规则，运行时即可自动产生结果，无需管理员逐条录入。
数据定义：按业务需要建表
Frontend Data API 支持通过 SQL 迁移文件定义表结构，并通过配置文件声明访问权限、随机赋值和预置 Function。
| 能力 | 支持范围 |
|---|---|
| 常用字段 | 文本、整数、小数、布尔、UUID、日期和时间等 |
| 结构化数据 | JSONB，以及一维文本、整数和 UUID 数组 |
| 数据约束 | 主键（含复合主键）、唯一、非空、受限 CHECK、同一资源内的外键 |
| 默认值 | 类型匹配的常量、当前时间、当前日期、自动生成 UUID、整数自增 |
| 结构扩展 | 新增列、普通索引和唯一索引、表与列注释 |
| 自动计算 | STORED 生成列；支持通过新增迁移变更计算规则 |
| 随机赋值 | 通过 assignments.yaml 配置 random_integer 随机整数规则 |
迁移文件用于受支持的结构定义，不用于插入初始业务数据，也不开放任意 SQL、自定义触发器或存储过程。
查询与读写：覆盖常见数据交互
应用通过 Runtime SDK 的 platform.db 访问数据，可组合筛选、排序、分页等操作。
| 能力 | 说明 |
|---|---|
| 字段选择 | 按需返回可见字段 |
| 条件筛选 | 比较、集合匹配、空值与布尔判断、文本匹配，以及 AND / OR 条件组合 |
| 排序与分页 | 多字段排序、限制返回条数、按范围分页；普通列表默认 20 条，每页最多 100 条 |
| 单条读取 | 获取单条记录，支持允许结果为空的读取方式 |
| 统计与聚合 | 精确记录数，以及最小值、最大值、求和和平均值 |
| 新增 | 单条或批量新增，单次最多 100 行，整批事务执行 |
| 修改与删除 | 必须指定过滤条件，单次最多影响 100 行，超限回滚 |
| 写入返回 | 写入后可获取指定字段的结果 |
预置 Function：常用规则由服务端执行
除了基础读写，应用还可通过 platform.functions 调用预置的数据功能。
| Function | 能力 |
|---|---|
rank |
在可见数据集合中计算名次与总数 |
incrementCounter |
每用户每目标一次的加一计数，适合一次性支持或投票 |
getCounterReceipt |
查询计数请求的回执 |
submitPeriodic |
按日、周、月等周期限 N 次提交 |
getSubmissionReceipt |
查询周期提交的回执 |
一次性计数不支持取消；可取消的点赞、收藏使用记录的新增、删除与数量查询实现。请求回执可帮助应用在网络中断后确认提交结果。
权限模型：公开数据与个人数据分别控制
每张表可分别配置查询、新增、修改、删除四种操作的访问范围：
- public：匿名和登录用户均可访问，适合公开列表、榜单。
- authenticated：已登录用户可访问，不自动限定本人记录。
- own：仅本人记录，适合“我的偏好、我的进度”，通过声明归属字段确定记录所有者。
- admin：具有应用
admin角色的登录用户可操作，适合内容维护等管理功能；与租户工作台的管理身份区分。
未声明的操作默认为禁止（none）。还可配置隐藏字段与受保护字段：隐藏字段不向应用数据接口开放查询和写入，受保护字段禁止客户端直接赋值，由服务端维护。
服务端自动赋值：计算结果由规则产生
两种自动赋值能力，让应用无需另写业务接口，也能在服务端产生计算结果：
- 生成列：按定义的表达式自动计算，例如根据提交的答案计算分数。前端提交输入，不能直接改写生成结果。
- 随机数字段：由服务端生成指定范围内的随机整数，例如 1–1000 的随机号码，可结合生成列进行命中判定。
读取不会重新计算；实际新增或修改一行时，会计算生成列并重新生成该行的随机值。需要修改备注但保留原随机结果时，可将备注单独存表。
这两种能力适合固定规则判分、金额计算与随机命中。服务端保证结果按规则产生，输入数据的有效性仍需通过约束和业务设计保证；复杂题库、反作弊等逻辑可使用 Backend App 实现。
CLI 联调：方便 Agent 开发与排查
CLI 支持在当前租户权限范围内发现应用和数据表、查询表结构与业务记录，并查看 Data API 当前生效的权限、生成列、随机规则及 Functions 配置。查询不必依赖本地应用项目上下文，方便 Agent 核对数据定义、验证写入结果和定位问题。
CLI 使用管理身份，页面使用应用用户或匿名访客身份；页面的访问权限仍需按实际使用身份验证。
能力边界
- 每次基础查询针对单张表，不提供 JOIN、跨表事务、GROUP BY、upsert 等能力。
- 查询接口不支持 JSON 路径过滤；JSONB 和数组支持整体读写。
- 需要自定义服务端业务逻辑、复杂 SQL 或跨表事务时，可使用 Backend App。
如何使用
使用新版 frontend-app-vite 模板（模板能力版本 2026.10.01.1），即可在前端轻应用中接入 Frontend Data API。模板在 resources/frontend-data-api/ 下提供定义样例和 README，便于按业务需要配置数据表与规则。
使用 Agent 开发时，请为 Agent 更新平台提供的最新版 Skill 与 CLI，再描述需要的数据功能，例如“每位用户保存自己的学习进度”“每天最多答题两次，并自动计算得分”。Agent 可据此完成数据定义、页面调用和联调验证。