已将业务时间生成入口统一为 Asia/Shanghai,不依赖服务器默认时区

This commit is contained in:
lxp
2026-10-29 16:42:10 +08:00
parent 0dd39eb23d
commit bec48bb3ea
22 changed files with 357 additions and 69 deletions
+13 -13
View File
@@ -87,7 +87,7 @@
### 2.2 时间和公共类型
```ts
type UtcDateTime = string;
type ShanghaiDateTime = string;
interface ApiResponse<T> {
code: string;
@@ -104,11 +104,11 @@ interface PageResponse<T> {
}
```
`createdAt`、`updatedAt`、`publishedAt`、`expiresAt`、`startedAt`、`finishedAt` 为 UTC 时间字符串,例如 `2026-10-20T02:30:00.123`,当前没有时区后缀。前端按 UTC 解析后再格式化为本地时间,不能直接当作北京时间。提交历史的 `authorDate` 沿用 Git 日期,可能自带 `Z` 或时区偏移。
`createdAt`、`updatedAt`、`publishedAt`、`expiresAt`、`startedAt`、`finishedAt` 为上海时间(`Asia/Shanghai`,UTC+8)字符串,例如 `2026-10-20T10:30:00.123`,当前没有时区后缀。前端应补充 `+08:00` 后解析,再格式化为用户本地时间;不能继续补 `Z`,也不能依赖浏览器默认时区。前后端需同时切换时间约定,避免多显示 8 小时。提交历史的 `authorDate` 沿用 Git 日期,可能自带 `Z` 或时区偏移。
```ts
function parseServerTime(value: string): Date {
return new Date(/(?:Z|[+-]\d{2}:?\d{2})$/i.test(value) ? value : `${value}Z`);
return new Date(/(?:Z|[+-]\d{2}:?\d{2})$/i.test(value) ? value : `${value}+08:00`);
}
```
@@ -281,7 +281,7 @@ interface UserView {
status: UserStatus;
role: UserRole;
projectCount: number; // 名下未删除项目数
createdAt: UtcDateTime;
createdAt: ShanghaiDateTime;
}
```
@@ -349,7 +349,7 @@ interface ProjectView {
repoStatus: RepoStatus;
publishStatus: PublishStatus;
publishedCommitSha: string | null;
publishedAt: UtcDateTime | null;
publishedAt: ShanghaiDateTime | null;
sourceProjectCode: string | null;
sourceCommitSha: string | null;
likeCount: number;
@@ -357,8 +357,8 @@ interface ProjectView {
liked: boolean;
sourceRepositoryUrl: string | null;
sourceLicense: string | null;
createdAt: UtcDateTime;
updatedAt: UtcDateTime;
createdAt: ShanghaiDateTime;
updatedAt: ShanghaiDateTime;
}
interface ManagedProjectView {
@@ -711,7 +711,7 @@ interface CoverUploadSignature {
uploadUrl: string;
objectKey: string;
coverUrl: string;
expiresAt: UtcDateTime;
expiresAt: ShanghaiDateTime;
formFields: Record<string, string>;
}
```
@@ -771,7 +771,7 @@ interface UrdfUploadSignature {
batchCode: string;
mainRelativePath: string;
uploadUrl: string;
expiresAt: UtcDateTime;
expiresAt: ShanghaiDateTime;
files: UrdfFileSignature[];
}
```
@@ -849,7 +849,7 @@ interface ResourceFile { relativePath: string; sizeBytes: number }
interface ResourceUploadSignature {
batchCode: string;
uploadUrl: string;
expiresAt: UtcDateTime;
expiresAt: ShanghaiDateTime;
files: { relativePath: string; objectKey: string; formFields: Record<string, string> }[];
}
@@ -1026,9 +1026,9 @@ interface TaskView {
canRetry: boolean;
retryMessage: string | null;
warnings: string[];
createdAt: UtcDateTime;
startedAt: UtcDateTime | null;
finishedAt: UtcDateTime | null;
createdAt: ShanghaiDateTime;
startedAt: ShanghaiDateTime | null;
finishedAt: ShanghaiDateTime | null;
}
```
+84 -9
View File
@@ -2,7 +2,7 @@
以下 SQL 由维护人员手工执行,应用不会自动迁库。已有数据库执行下面的增量 SQL;新建数据库先执行 database.md 中的四表 SQL,然后只创建本文件的任务表,不重复执行 ALTER。
执行前暂停社区端、后台和导入工具的写入并备份数据库。不要对已有列重复执行。所有时间字段由应用写入 UTC。项目来源改为从任务表读取,因此社区端、后台和导入工具升级前都应创建任务表,即使暂不启动后台也需要执行。
执行前暂停社区端、后台和导入工具的写入并备份数据库。不要对已有列重复执行。所有时间字段由应用写入上海时间(Asia/Shanghai,UTC+8)。项目来源改为从任务表读取,因此社区端、后台和导入工具升级前都应创建任务表,即使暂不启动后台也需要执行。
## 项目字段收敛
@@ -69,10 +69,10 @@ CREATE TABLE project_import_task (
target_sha VARCHAR(64) NULL COMMENT '迁移后冻结的目标提交SHA',
error_code VARCHAR(64) NULL COMMENT '最近失败错误码',
warnings_json TEXT NOT NULL COMMENT '兼容性提醒JSON数组',
started_at DATETIME(3) NULL COMMENT '最近开始时间UTC',
finished_at DATETIME(3) NULL COMMENT '最近结束时间UTC',
created_at DATETIME(3) NOT NULL COMMENT '创建时间UTC',
updated_at DATETIME(3) NOT NULL COMMENT '更新时间UTC',
started_at DATETIME(3) NULL COMMENT '最近开始时间(Asia/Shanghai)',
finished_at DATETIME(3) NULL COMMENT '最近结束时间(Asia/Shanghai)',
created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)',
PRIMARY KEY (id),
UNIQUE KEY uk_import_task_code (task_code),
UNIQUE KEY uk_import_project (project_code),
@@ -120,7 +120,7 @@ ALTER TABLE project MODIFY COLUMN publish_status VARCHAR(16) NOT NULL DEFAULT 'U
## 新建普通文件写入操作记录表(本次上线前执行)
只新增此表,不需要修改项目表。由运维手工执行;应用不自动迁库。时间全部为 UTC。
只新增此表,不需要修改项目表。由运维手工执行;应用不自动迁库。时间全部为上海时间(Asia/Shanghai,UTC+8)。
```sql
CREATE TABLE repository_write_operation (
@@ -137,9 +137,9 @@ CREATE TABLE repository_write_operation (
failure_status INT NULL COMMENT '明确失败时原HTTP状态码',
last_error_code VARCHAR(64) NULL COMMENT '最近核对错误编码,不保存异常正文或凭证',
check_count INT NOT NULL DEFAULT 0 COMMENT '后台已执行核对次数',
next_check_at DATETIME(3) NOT NULL COMMENT '下次只读核对时间UTC',
created_at DATETIME(3) NOT NULL COMMENT '创建时间UTC',
updated_at DATETIME(3) NOT NULL COMMENT '最近更新时间UTC',
next_check_at DATETIME(3) NOT NULL COMMENT '下次只读核对时间(Asia/Shanghai)',
created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
updated_at DATETIME(3) NOT NULL COMMENT '最近更新时间(Asia/Shanghai)',
PRIMARY KEY (operation_code),
KEY idx_write_project_status (project_code, status, created_at),
KEY idx_write_next_check (status, next_check_at)
@@ -147,3 +147,78 @@ CREATE TABLE repository_write_operation (
```
已完成的操作记录仍用于幂等重放,不要在客户端可能重试期间删除。历史 REVIEW 没有操作记录,不会凭最新 SHA 自动判成功;需核对实际结果后按原维护流程处理。迁移、Fork 继续使用原流程。
## 业务时间由 UTC 迁移到上海时间
新版统一通过 `ProjectSupport` 生成上海时间(`Asia/Shanghai`),字段类型保持 `DATETIME(3)`。以下 SQL 由维护人员手工执行,应用不会执行迁移,也不会自动修改已有数据库。
执行顺序:暂停社区端、管理端和导入工具,备份业务数据库及导入状态目录;确认以下六张表中的历史时间仍全部为 UTC 后执行一次转换;核对结果后同时部署新版各模块,并同步前端的 `+08:00` 解析方式,再恢复服务。新建空库无需执行数据转换。若已经写入上海时间或存在混合时区数据,必须先按切换记录确定待转换数据范围,不能直接执行以下全表更新;本脚本不能重复执行。
```sql
USE vibemake;
START TRANSACTION;
UPDATE sys_user
SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR),
updated_at = DATE_ADD(updated_at, INTERVAL 8 HOUR);
UPDATE project
SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR),
updated_at = DATE_ADD(updated_at, INTERVAL 8 HOUR),
published_at = DATE_ADD(published_at, INTERVAL 8 HOUR);
UPDATE project_comment
SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR),
updated_at = DATE_ADD(updated_at, INTERVAL 8 HOUR);
UPDATE project_like
SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR);
UPDATE project_import_task
SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR),
updated_at = DATE_ADD(updated_at, INTERVAL 8 HOUR),
started_at = DATE_ADD(started_at, INTERVAL 8 HOUR),
finished_at = DATE_ADD(finished_at, INTERVAL 8 HOUR);
UPDATE repository_write_operation
SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR),
updated_at = DATE_ADD(updated_at, INTERVAL 8 HOUR),
next_check_at = DATE_ADD(next_check_at, INTERVAL 8 HOUR);
COMMIT;
```
空值保持为空,毫秒精度保持不变。`next_check_at` 等调度时间也需要转换,避免切换后提前或延后核对任务。Git 提交日期、OSS 签名内容和 Gitea 内部数据库不参与转换。
已有数据库的时间字段注释可单独按以下 SQL 更新;DDL 会隐式提交,不要放入上面的数据转换事务。
```sql
ALTER TABLE sys_user
MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
MODIFY COLUMN updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)';
ALTER TABLE project
MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
MODIFY COLUMN updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)',
MODIFY COLUMN published_at DATETIME(3) NULL COMMENT '最近发布时间(Asia/Shanghai)';
ALTER TABLE project_comment
MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
MODIFY COLUMN updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)';
ALTER TABLE project_like
MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '点赞时间(Asia/Shanghai)';
ALTER TABLE project_import_task
MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
MODIFY COLUMN updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)',
MODIFY COLUMN started_at DATETIME(3) NULL COMMENT '最近开始时间(Asia/Shanghai)',
MODIFY COLUMN finished_at DATETIME(3) NULL COMMENT '最近结束时间(Asia/Shanghai)';
ALTER TABLE repository_write_operation
MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
MODIFY COLUMN updated_at DATETIME(3) NOT NULL COMMENT '最近更新时间(Asia/Shanghai)',
MODIFY COLUMN next_check_at DATETIME(3) NOT NULL COMMENT '下次只读核对时间(Asia/Shanghai)';
```
旧导入状态首次由新版读取时,将未声明时区的 `reservedAt` 从 UTC 转为上海时间,原子保存并标记 `timeZone=Asia/Shanghai`,后续不会再次转换。应在业务库完成转换后再续跑;未迁移的数据库时间与清单不一致时,现有归属校验会阻止接管项目。回滚应用前需要同时恢复数据库和导入状态备份,并恢复前端的旧时间解析约定。
+9 -9
View File
@@ -15,8 +15,8 @@ CREATE TABLE sys_user (
role VARCHAR(16) NOT NULL DEFAULT 'USER' COMMENT '用户角色 USER普通用户 ADMIN管理员 OFFICIAL官方托管账号',
password_hash VARCHAR(100) NULL COMMENT '管理员BCrypt密码哈希,普通用户为空',
session_version BIGINT NOT NULL DEFAULT 0 COMMENT '登录会话版本,禁用或修改密码时递增',
created_at DATETIME(3) NOT NULL COMMENT '创建时间 UTC',
updated_at DATETIME(3) NOT NULL COMMENT '更新时间 UTC',
created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)',
PRIMARY KEY (id),
UNIQUE KEY uk_user_code (user_code),
UNIQUE KEY uk_user_email (email)
@@ -47,14 +47,14 @@ CREATE TABLE project (
repo_status VARCHAR(16) NOT NULL DEFAULT 'CREATING' COMMENT '仓库状态 CREATING READY FAILED',
publish_status VARCHAR(16) NOT NULL DEFAULT 'UNPUBLISHED' COMMENT '发布状态 UNPUBLISHED未发布 PUBLISHED已发布 BLOCKED管理员下架',
published_commit_sha VARCHAR(64) NULL COMMENT '社区已发布 Commit SHA',
published_at DATETIME(3) NULL COMMENT '最近发布时间 UTC',
published_at DATETIME(3) NULL COMMENT '最近发布时间(Asia/Shanghai)',
moderation_reason VARCHAR(500) NULL COMMENT '管理员下架原因',
repo_write_status VARCHAR(16) NOT NULL DEFAULT 'IDLE' COMMENT '仓库写入状态 IDLE空闲 WRITING写入中 REVIEW待核对',
source_project_id BIGINT NULL COMMENT 'Fork 来源项目',
source_commit_sha VARCHAR(64) NULL COMMENT 'Fork 来源已发布 Commit SHA',
deleted TINYINT(1) NOT NULL DEFAULT 0 COMMENT '逻辑删除标识',
created_at DATETIME(3) NOT NULL COMMENT '创建时间 UTC',
updated_at DATETIME(3) NOT NULL COMMENT '更新时间 UTC',
created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)',
PRIMARY KEY (id),
UNIQUE KEY uk_project_code (project_code),
UNIQUE KEY uk_project_repo (gitea_owner, gitea_repo_name),
@@ -73,8 +73,8 @@ CREATE TABLE project_comment (
user_id BIGINT NOT NULL COMMENT '评论用户',
content TEXT NOT NULL COMMENT '纯文本评论内容',
deleted TINYINT(1) NOT NULL DEFAULT 0 COMMENT '逻辑删除标识',
created_at DATETIME(3) NOT NULL COMMENT '创建时间 UTC',
updated_at DATETIME(3) NOT NULL COMMENT '更新时间 UTC',
created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)',
updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)',
PRIMARY KEY (id),
UNIQUE KEY uk_comment_code (comment_code),
KEY idx_comment_project (project_id, deleted, created_at),
@@ -86,7 +86,7 @@ CREATE TABLE project_like (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部点赞主键',
project_id BIGINT NOT NULL COMMENT '所属项目',
user_id BIGINT NOT NULL COMMENT '点赞用户',
created_at DATETIME(3) NOT NULL COMMENT '点赞时间 UTC',
created_at DATETIME(3) NOT NULL COMMENT '点赞时间(Asia/Shanghai)',
PRIMARY KEY (id),
UNIQUE KEY uk_like_project_user (project_id, user_id),
CONSTRAINT fk_like_project FOREIGN KEY (project_id) REFERENCES project(id),
@@ -94,7 +94,7 @@ CREATE TABLE project_like (
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='项目点赞';
```
内部 ID 仅用于数据库关联,对外使用业务编码。时间均由后端写入 UTC。`CREATING` 项目表示仓库初始化未完成,不代表编辑草稿。Gitea 数据库与业务库分离,不修改 Gitea 内部表。
内部 ID 仅用于数据库关联,对外使用业务编码。时间均由后端写入上海时间(Asia/Shanghai,UTC+8)。`CREATING` 项目表示仓库初始化未完成,不代表编辑草稿。Gitea 数据库与业务库分离,不修改 Gitea 内部表。
新增项目和用户使用 12 位小写字母和数字编码,历史 32 位编码继续保留。现有 `project_code CHAR(32)` 和 `user_code CHAR(32)` 可容纳两者,不需要修改表结构或历史记录;仓库名称仍为 `p_{projectCode}`。用户编码由安全随机数生成,唯一索引兜底,冲突时最多尝试 5 次;同一邮箱并发注册复用已有用户。评论编码保持 32 位。GitHub 运维导入的来源和进度保存于批次状态目录,GitHub 来源不占用社区内部 Fork 来源字段。
+14 -14
View File
@@ -90,7 +90,7 @@
### 时间和版本
项目和评论的时间字段按 UTC 保存,JSON 格式为 `2026-10-13T08:30:00`,可能带小数秒,**没有时区后缀**。前端解析这些字段时应按 UTC 处理,再转换成用户时区;不要直接当成本地时间。历史提交的 `authorDate` 来自仓库服务,可带 `Z` 或时区偏移。
项目、评论及上传过期时间统一使用上海时间(`Asia/Shanghai`,UTC+8),JSON 格式为 `2026-10-13T08:30:00`,可能带小数秒,**没有时区后缀**。前端解析这些字段时应补充 `+08:00`,再转换成用户时区;不能继续补 `Z` 或依赖浏览器本地时区。历史提交的 `authorDate` 来自仓库服务,可带 `Z` 或时区偏移。
Git SHA 使用完整的 40 或 64 位十六进制字符串,不使用缩写。几个版本字段的用途不同:
@@ -149,8 +149,8 @@ Git SHA 使用完整的 40 或 64 位十六进制字符串,不使用缩写。
以下 TypeScript 类型与当前 JSON 字段对应。项目列表、工作区详情、社区详情、创建、修改、发布和 Fork 共用 Project 结构。
```typescript
/** 无时区后缀,按 UTC 解释。 */
export type UtcDateTime = string;
/** 无时区后缀,按 Asia/Shanghai(UTC+8)解释。 */
export type ShanghaiDateTime = string;
export interface ApiResponse<T> {
code: string;
@@ -219,7 +219,7 @@ export interface Project {
repoStatus: 'CREATING' | 'READY' | 'FAILED';
publishStatus: 'UNPUBLISHED' | 'PUBLISHED' | 'BLOCKED';
publishedCommitSha: string | null;
publishedAt: UtcDateTime | null;
publishedAt: ShanghaiDateTime | null;
sourceProjectCode: string | null;
sourceCommitSha: string | null;
sourceRepositoryUrl: string | null; // 在线迁移任务记录的原仓库地址
@@ -227,15 +227,15 @@ export interface Project {
likeCount: number;
commentCount: number;
liked: boolean;
createdAt: UtcDateTime;
updatedAt: UtcDateTime;
createdAt: ShanghaiDateTime;
updatedAt: ShanghaiDateTime;
}
export interface CoverUploadSignature {
uploadUrl: string;
objectKey: string;
coverUrl: string;
expiresAt: UtcDateTime; // 无时区后缀,按 UTC 解释
expiresAt: ShanghaiDateTime; // 无时区后缀,按 Asia/Shanghai(UTC+8)解释
formFields: Record<string, string>;
}
@@ -248,7 +248,7 @@ export interface UrdfUploadSignature {
batchCode: string;
mainRelativePath: string;
uploadUrl: string;
expiresAt: UtcDateTime; // 无时区后缀,按 UTC 解释
expiresAt: ShanghaiDateTime; // 无时区后缀,按 Asia/Shanghai(UTC+8)解释
files: Array<{
relativePath: string;
objectKey: string;
@@ -296,7 +296,7 @@ export interface Comment {
commentCode: string;
author: PublicUser;
content: string;
createdAt: UtcDateTime;
createdAt: ShanghaiDateTime;
}
```
@@ -543,7 +543,7 @@ data 示例中 image 仅展示格式前缀,实际值为完整图片:
}
```
签名有效期为 5 分钟;策略绑定 Bucket、完整对象 key、Content-Type、1 字节~5 MiB 的大小范围和成功状态码 200。文件类型按声明的 MIME 约束,后端不读取或解码图片。对象路径由后端生成,日期使用 UTC:test 为 `vibemake_dev/project-covers/{userCode}/{yyyyMMdd}/{随机编码}.{扩展名}`,prod 为 `vibemake/project-covers/...`。不要修改 formFields、对象路径或上传类型。
签名有效期为 5 分钟;策略绑定 Bucket、完整对象 key、Content-Type、1 字节~5 MiB 的大小范围和成功状态码 200。文件类型按声明的 MIME 约束,后端不读取或解码图片。对象路径由后端生成,日期使用 Asia/Shanghai:test 为 `vibemake_dev/project-covers/{userCode}/{yyyyMMdd}/{随机编码}.{扩展名}`,prod 为 `vibemake/project-covers/...`。不要修改 formFields、对象路径或上传类型。
### 浏览器直传与保存项目
@@ -1471,14 +1471,14 @@ async function downloadWorkspaceFile(projectCode: string, path: string, token: s
}
```
### UTC 时间解析
### 上海时间解析
只对项目、评论中不带时区的 UTC 字段使用这个函数;历史 authorDate 已带时区时按其原值解析。
对项目、评论、上传过期时间等不带时区的上海时间字段使用这个函数;历史 authorDate 已带时区时按其原值解析。前端与后端需同时切换,旧版补 `Z` 的解析方式会多显示 8 小时。
```typescript
function parseUtcTime(value: UtcDateTime): Date {
function parseShanghaiTime(value: ShanghaiDateTime): Date {
const hasTimezone = /(?:Z|[+-]\d{2}:\d{2})$/i.test(value);
return new Date(hasTimezone ? value : `${value}Z`);
return new Date(hasTimezone ? value : `${value}+08:00`);
}
```