# 项目发布时间编辑与排序对接说明 依据:用户提供的 `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`: ```json { "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`,但管理页面不再提供这两种排序。首次加载、查询、重置和翻页都显式指定发布时间排序,避免省略参数后回退到创建时间排序。现有后端已支持所需枚举,无需修改接口。 ```text 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;排序与空值规则在多页数据上成立;再次发布保留已有手工时间。