feat: 完成分类、worksheet 接口开发，资源迁移到七牛

2026-10-16 17:32:23 +08:00
parent e6ded00a4c
commit 8827110f2f
107 changed files with 12775 additions and 125 deletions
@@ -0,0 +1,58 @@
+# 内容发布与可见性
+
+2026-10-16。三张表统一使用 `status = draft / active / hidden`，不增加重复的 isPublished 布尔字段。draft 用于开发、编辑及测试，active 为上线，hidden 为下架。新增分类、题型、资源默认 draft。
+
+## 公开规则
+
+- 分类：自身及所有祖先均为 active。公开列表只返回从 active 根节点可达的分类；不存在、未公开、祖先未公开的详情统一 404。
+- 题型：自身为 active，所属分类及全部祖先可见。全部、分类、年级、年龄、Tag、最新、热门、计数、分页和详情使用同一服务端规则。公开路由不能用 status、preview 或测试模式参数读取草稿；即使调用者是管理员，公开接口也不放宽。
+- 资源：自身为 active，所属题型及其分类链均可见。管理预览提供派生 visible；资源公开读取/生成/下载接口尚未实现，后续必须复用相同规则再开放。
+
+上级下架只改变有效可见性，不批量改写下级 status。恢复上级不会使原有草稿或下架内容自动上线。分类目录不根据题型数量自动隐藏；允许已上线的空分类。
+
+## 管理接口
+
+统一前缀 `/api/v1`，均要求有效本站 JWT 和服务端当前 active + admin 账户。体验版、客户端开关或自报角色不能替代鉴权。
+
+| 方法  | 路径                                  | 用途                                                  |
+| ----- | ------------------------------------- | ----------------------------------------------------- |
+| GET   | /admin/categories                     | 全部状态的扁平分类列表                                |
+| GET   | /admin/categories/:id                 | 分类管理详情                                          |
+| POST  | /admin/categories                     | 创建分类，省略 status 为 draft                        |
+| PATCH | /admin/categories/:id                 | 原有字段及 status 的局部修改                          |
+| GET   | /admin/worksheets                     | 原有组合筛选及分页，额外支持 status；省略查询全部状态 |
+| GET   | /admin/worksheets/:id                 | 题型卡片数据预览，含 status 和 visible                |
+| PATCH | /admin/worksheets/:id/status          | 题型状态修改                                          |
+| GET   | /admin/worksheet-resources            | 支持 worksheetId/status/page/pageSize                 |
+| GET   | /admin/worksheet-resources/:id        | 资源卡片数据预览，含 status 和 visible                |
+| PATCH | /admin/worksheet-resources/:id/status | 资源状态修改                                          |
+
+状态修改请求示例：`{"status":"hidden"}`。不接受其他字段或测试专用状态；非法值 400，不存在 404，题型/资源发布时上级未上线返回 409。管理预览沿用公开字段白名单，不返回任意渲染配置、私有文件、源文件地址或签名 URL；尚未提供服务端绘制测试图的接口。
+
+所有写事务重新锁定、检查管理员账户，再按分类 → 父题型 → 资源顺序加锁；状态、首次发布时间、快照失效与审计同事务提交。相同状态重复提交不刷新时间、重复审计或增加快照版本。下架不清零统计，不删除收藏/下载历史，不重写内容更新时间。
+
+第一次从未发布草稿转 active 登记 firstPublishedAt；重新上架保留首次发布时间。旧 active/hidden 的未知首次发布时间保持 NULL，历史审计用于防止改回草稿后伪装新品。上线内容直接编辑不提供旧版与草稿版并存的保证；版本管理或独立测试环境另行实施。
+
+## 快照与小程序切换边界
+
+分类状态/父级变化、分类删除、分类上线创建，以及题型/资源状态变化，会在同一事务清空服务端 `page_configs` 的 home/category/age，递增 version，清空 publishedVersion/publishedAt。重新构建页面配置时必须按上述可见性过滤；空配置不得降级返回旧快照。
+
+这只撤销新后端数据库中的展示快照。当前新后端还没有首页构建、静态配置分发或 CDN 清理接口，不能据此声称微信云端/七牛已分发的旧 JSON 被撤回。已下载或缓存的公开文件也不具备内容保密能力。
+
+`doodle-mini` 分类页已在 2026-10-16 接入新后端：通过全局环境配置读取公开分类及完整题型分页，已移除写死目录和静态题型兜底；失败展示重试，点击时重新读取公开详情，404 阻止跳转并刷新。开发入口使用 http://127.0.0.1:8800/api/v1，体验版/正式版仅使用待填写的 HTTPS 线上地址。
+
+首页预拉取、登录、收藏、下载及其他页面仍使用旧云服务。新后端状态不会自动改写旧云数据或撤回旧静态文件；首页快照重建、缓存版本验证、其他入口/分享直达生成页的可用性检查尚待迁移。分类页接入不能视为全站上下架切换已完成。联调方式见 [小程序本地后端接口联调](../../../doodle-mini/docs/v3.5/本地后端接口联调.md)。
+
+## 数据库升级及现有数据
+
+新增 Prisma 迁移 `20261016000000_category_publication`；已有已登记基线的库执行 `pnpm --filter @doodle/server db:deploy`。已应用的 `0_v35_baseline` 不变。手工 SQL 升级使用 009，不能与同一 Prisma 增量重复执行；新空库可通过完整 Prisma 历史或最新 002/003 初始化。
+
+增量迁移给既有分类设为 active，保留此前公开行为；新建默认 draft。分类旧导出省略 status 时，新导入记录为 draft，已有记录保留当前状态；显式 status 才修改，防止旧导出重新上架内容。题型旧导出与当前数据冲突时仍拒绝覆盖。
+
+本地 doodle_dev 已升级：6 个分类维持 active，51 个题型及全部其他业务数据指纹与升级前一致，未写入测试用户或测试内容。哪些旧条目仍在开发由维护者确认后通过管理接口设为 draft/hidden，不按名称自动判断。
+
+## 验证
+
+`pnpm check` 检查格式、静态检查、类型与普通测试；`pnpm test:db` 使用独立临时 PostgreSQL 数据库并在完成后删除。发布回归覆盖：默认草稿、管理员与普通用户隔离、多层祖先下架、全部查询路径与详情防绕过、资源所属关系、发布前置检查、首次/重复发布、未知历史时间、并发幂等、同事务缓存失效、旧导出状态保留、审计失败回滚及事务内账户复核。
+
+验证结果：`pnpm check` 通过（28 项普通测试，数据库测试由单独命令执行）；`pnpm test:db` 共 39 项通过，临时数据库已清理。本地运行服务公开分类 6 条、题型 51 条，新增管理查询匿名均返回 401，Swagger 已注册全部新路由。