feat: 作业纸

2026-10-23 16:52:47 +08:00
parent 83a90407b0
commit c090675255
14 changed files with 532 additions and 3 deletions
@@ -137,3 +137,37 @@ worksheet.is_new 暂保留兼容：新接口以时间派生为准，旧接口仅
 ## 发布可见性补充（2026-10-16）

 沿用 worksheets 与 worksheet_resources 的 draft/active/hidden，不新增布尔上线字段。categories 增加同名 status，新建默认草稿；上级未上线会阻止下级公开读取，不覆盖下级状态。管理预览、上下架、首发时间及快照失效已实现，资源公开读取/生成/下载仍待后续接口接入相同策略。详见 [内容发布与可见性](./内容发布与可见性.md)。
+
+## 独立纸张条目补充（2026-10-23）
+
+worksheet 表示可以独立展示、分享、收藏、上下架和统计的业务条目，并不要求与绘制页面或绘制实现一一对应。田字格、米字格等需要独立运营时，各自占一条 worksheet，继续使用字符串业务 ID；不新增自增主键或含义重复的 type 字段。
+
+| 条目 ID                | 标题          | renderer_key | render_config                    |
+| ---------------------- | ------------- | ------------ | -------------------------------- |
+| paper-tian             | 田字格        | paper-sheet  | {"paperType":"tian"}             |
+| paper-mi               | 米字格        | paper-sheet  | {"paperType":"mi"}               |
+| paper-square           | 方格          | paper-sheet  | {"paperType":"square"}           |
+| paper-four-line        | 四线三格      | paper-sheet  | {"paperType":"four-line"}        |
+| paper-letter           | 信纸          | paper-sheet  | {"paperType":"letter"}           |
+| paper-horizontal       | 横线          | paper-sheet  | {"paperType":"horizontal"}       |
+| paper-vertical         | 竖线          | paper-sheet  | {"paperType":"vertical"}         |
+| paper-dictation-hanzi  | 汉字听写      | paper-sheet  | {"paperType":"dictation-hanzi"}  |
+| paper-dictation-pinyin | 拼音/英语听写 | paper-sheet  | {"paperType":"dictation-pinyin"} |
+| paper-homework-log     | 作业登记表    | paper-sheet  | {"paperType":"homework-log"}     |
+
+小程序纸张选项和本地条目元数据统一维护于 `config/worksheets/papers.ts`。服务端在 `paper-sheet-presets.ts` 显式登记支持的 ID、路由和参数；发布与旧格式导入复用此映射，不开放任意渲染配置写入。公开接口仅对已匹配的独立条目增加 `rendering: {rendererKey: "paper-sheet", paperType: "mi"}` 等白名单摘要，不透传原始 render_config。客户端同时校验条目 ID 和纸张类型，不认识的条目或错配配置不能默认生成田字格。
+
+独立条目初始化使用工作区根目录命令：
+
+```sh
+pnpm paper-sheets:seed
+pnpm paper-sheets:seed --apply
+```
+
+第一条仅预演；第二条只允许本机 `doodle_dev`，事务创建缺少的十种纸张草稿并记录审计、撤销展示快照。已有相同配置条目不修改，ID 被其他配置占用时整批回滚。初始化需要原 `paper-sheet` 已存在，用它的分类和封面建立草稿，年龄和标题来自独立条目定义；仅复制明确配置过的年级关系，不从年龄推断。
+
+草稿暂借综合入口预览，不能把该封面当作各纸张真实预览。开发版进入相应独立 ID 后，直接使用客户端已注册配置进行本地预览，不请求公开详情或通过 404 判断草稿；可通过调试发布工具导出当前纸张封面并发布。体验版和正式版必须读取到 active 详情及匹配绘制摘要才允许生成，404 或网络失败均不能降级为本地预览。新增条目首次发布时间为空，计数及 seed 从零开始，发布流程负责首次发布时间。不存在原综合入口时可直接通过开发版逐张创建条目。
+
+旧 `paper-sheet` 的 ID、记录、收藏、计数和发布时间保留，不向新条目分摊。旧链接的 `type` 参数继续生效，综合入口的新分享通过 `mode` 保留纸张选择；进入综合入口时仍以综合条目为收藏和下载目标，主动切换纸张则转为对应独立条目，之后分享、发布、收藏和下载都指向它。颜色变化继续作为用户参数，不改变业务身份。
+
+本次复用既有字段，不需要 DDL 迁移。worksheet_resources 仍管理“小猫涂色”等功能下面的具体内容，不将这十种独立纸张重复建为资源。
@@ -125,3 +125,7 @@ page 默认 1，范围 1～1000000；pageSize 默认 20，范围 1～100。超
 ## 年龄段匹配调整（2026-10-16）

 用户确认将普通题型查询从“最小年龄等于年龄段下限”改为“适用范围完整覆盖所选年龄段”。本次仅修改 ageBand 匹配语义，不修改 grade/grades、age/ageBand 参数格式，不改数据库或小程序云函数。旧分龄推荐接口尚未迁移，其匹配和榜单规则不属于本次普通列表变更。
+
+### 独立作业纸绘制摘要（2026-10-23）
+
+已登记的 `paper-tian`、`paper-mi` 等十个独立条目在配置匹配时额外返回可选 `rendering`，例如 `{"rendererKey":"paper-sheet","paperType":"mi"}`。这是服务端校验后的公开参数摘要，不包含原始 `renderConfig` 或其他生成器内部字段。未知 renderer、未登记条目或错配配置不返回摘要；新客户端遇到独立纸张摘要缺失或不匹配时提示不可用，不回退生成其他纸张。旧综合入口 `paper-sheet` 的响应保持兼容。