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

55 lines
3.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 项目发布时间编辑与排序对接说明
依据:用户提供的 `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;排序与空值规则在多页数据上成立;再次发布保留已有手工时间。