Files
vibemake-admin/docs/project-dates-backend-requirements.md
T
2026-11-03 15:50:13 +08:00

3.8 KiB
Raw Blame History

项目发布时间编辑与排序对接说明

依据:用户提供的 admin-api(8).md 第 2.2、5.3、5.4、5.5 节。更新日期:2026-11-02。

本说明替代此前关于手动修改 updatedAt 及 sortBy / sortDirection 的拟定需求。按当前接口文档,后端已提供发布时间编辑和排序能力,本功能无需再新增接口或字段;真实部署环境仍需联调确认。

编辑字段:publishedAt

使用既有 PATCH /admin-api/projects/{projectCode},平铺提交当前完整基础信息及可选 publishedAt:

{
  "name": "microduck",
  "description": "A Tiny biped duck robot",
  "projectType": "GENERAL",
  "coverUrl": "",
  "publishedAt": "2026-11-02T10:30:00.000"
}
  • publishedAt 是现有发布时间字段新增了后台编辑能力,并非新的 updatedAt 替代字段。
  • 不修改日期时省略该字段,由后端保留原值;修改时传上海时间字符串;清空时显式提交 "publishedAt": null。未设置时间的项目可以留空。
  • 仅指定发布时间,不提交 updatedAt,系统更新时间仍由后端维护;不改变发布状态或已发布 Commit。
  • 发布时只有 publishedAt 为空才自动填入当前上海时间;已有的手工时间会保留。清空后下次发布会重新填充。
  • 响应仍为 ProjectView。前端核对返回的 publishedAt 是否与修改/清空一致,异常时保留表单并提示确认结果。

时间约定

  • createdAt、updatedAt、publishedAt 等无时区后缀的服务端日期按 Asia/Shanghai(UTC+8)解析,不能补 Z。
  • 带 Z 或明确偏移的时间直接解析,以兼容 STEP 签名等接口。
  • 界面转换到浏览器本地时区显示;编辑提交则转换为上海时间、保留毫秒且不带时区后缀,不依赖浏览器默认时区。
  • 例如上海本地 2026-10-28 12:34:56 提交为 2026-10-28T12:34:56.000;纽约冬季本地 2026-01-01 23:45:00 提交为 2026-01-02T12:45:00.000。

列表排序:sort

项目管理列表仅按发布时间倒序,始终向 GET /admin-api/projects 显式发送 sort=PUBLISHED_AT_DESC。空值排最后,同值时的固定顺序由服务端负责,并在分页之前完成。前端直接展示响应,不额外对当前页排序。

接口文档仍列出 CREATED_AT_DESC(服务端默认)和 RESOURCES_FIRST,但管理页面不再提供这两种排序。首次加载、查询、重置和翻页都显式指定发布时间排序,避免省略参数后回退到创建时间排序。现有后端已支持所需枚举,无需修改接口。

GET /admin-api/projects?page=1&size=20&sort=PUBLISHED_AT_DESC
GET /admin-api/projects?page=2&size=20&ownerUserCode=owner-1&keyword=robot&sort=PUBLISHED_AT_DESC
  • 只发送 PUBLISHED_AT_DESC,不发送 sortBy、sortDirection,不提供升序。
  • 项目表格显示「创建时间」「发布时间」;创建时间仅展示,发布时间表头标记倒序,移除多模式「排序方式」选择器。
  • 点击发布时间表头回第一页并保留已提交筛选;查询、翻页和页大小切换保留发布时间倒序;重置清空筛选并回到第一页,仍按发布时间倒序。
  • 用户详情「名下项目」复用表格展示发布时间,但原有用户项目接口本次不增加排序参数或入口。

验证与联调

前端回归:npx playwright test tests/project-dates.spec.ts。覆盖上海时间、带时区值、毫秒原值保留、其他浏览器时区跨日转换、空值/清空、保存失败、取消编辑、响应核对、排序枚举及筛选分页联动。

这些测试拦截全部管理 API,不代表已验证真实后端。联调时应确认:修改时间在刷新后持久保留;清空后返回 null;排序与空值规则在多页数据上成立;再次发布保留已有手工时间。