From 44fa5a3830f9bd24ba601130997473b41a3c6101 Mon Sep 17 00:00:00 2001 From: bujinyuan Date: Sat, 28 Feb 2026 09:47:42 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=BB=9F=E4=B8=80=E6=97=B6=E9=97=B4?= =?UTF-8?q?=E6=A0=BC=E5=BC=8F=E4=B8=BA=E4=BA=9A=E6=B4=B2=E5=8F=8B=E5=A5=BD?= =?UTF-8?q?=E7=9A=84=E6=97=A5=E6=9C=9F=E6=97=B6=E9=97=B4=E5=AD=97=E7=AC=A6?= =?UTF-8?q?=E4=B8=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 所有文档中的时间字段统一为 yyyy-MM-dd HH:mm:ss 格式（Asia/Shanghai）： - 移除 ISO 8601 格式（2026-02-27T10:00:00Z） - 移除 Unix 时间戳（1740700000） - 响应字段从 timestamp(int64) 改为 time(string) - API README 新增「时间格式规范」章节 - 涉及 10 个文档文件 Made-with: Cursor --- docs/api/README.md | 19 +++++++++++++++++-- docs/api/admin.md | 4 ++-- docs/api/auth.md | 2 +- docs/api/im.md | 10 +++++----- docs/api/meeting.md | 10 +++++----- docs/api/notify.md | 4 ++-- docs/api/websocket.md | 8 ++++---- docs/architecture/system-architecture.md | 2 +- .../2026-02-27-echochat-system-design.md | 4 ++-- .../2026-02-27-phase1-foundation-and-auth.md | 6 +++--- 10 files changed, 42 insertions(+), 27 deletions(-) diff --git a/docs/api/README.md b/docs/api/README.md index 593ad1a..8d76c15 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -37,6 +37,21 @@ Authorization: Bearer ``` +### 时间格式规范 + +系统所有时间字段统一使用 **亚洲友好的日期时间字符串格式**： + +``` +yyyy-MM-dd HH:mm:ss +``` + +示例：`"2026-03-01 14:12:12"` + +- 所有 API 响应中的时间字段（`created_at`、`updated_at`、`last_login_at`、`started_at` 等）均使用此格式 +- 所有 API 请求中的时间参数（如预约会议时间）也使用此格式 +- WebSocket 消息中的时间字段同样遵循此格式 +- 时区统一采用 **Asia/Shanghai (UTC+8)** + ### 统一响应格式 **成功响应：** @@ -45,7 +60,7 @@ Authorization: Bearer "code": 0, "message": "ok", "data": { ... }, - "timestamp": 1740700000 + "time": "2026-02-27 18:00:00" } ``` @@ -55,7 +70,7 @@ Authorization: Bearer "code": 1001, "message": "参数错误：邮箱格式不正确", "data": null, - "timestamp": 1740700000 + "time": "2026-02-27 18:00:00" } ``` diff --git a/docs/api/admin.md b/docs/api/admin.md index 88f57d8..9919358 100644 --- a/docs/api/admin.md +++ b/docs/api/admin.md @@ -99,9 +99,9 @@ "phone": "13800138000", "status": 1, "roles": ["user"], - "last_login_at": "2026-02-27T10:00:00Z", + "last_login_at": "2026-02-27 10:00:00", "last_login_ip": "192.168.1.100", - "created_at": "2026-02-20T08:00:00Z" + "created_at": "2026-02-20 08:00:00" } } ``` diff --git a/docs/api/auth.md b/docs/api/auth.md index c8c52a7..dc743ca 100644 --- a/docs/api/auth.md +++ b/docs/api/auth.md @@ -163,7 +163,7 @@ "gender": 1, "phone": "13800138000", "roles": ["user"], - "created_at": "2026-02-27T10:00:00Z" + "created_at": "2026-02-27 10:00:00" } } ``` diff --git a/docs/api/im.md b/docs/api/im.md index 0aa4c48..b6373ec 100644 --- a/docs/api/im.md +++ b/docs/api/im.md @@ -49,7 +49,7 @@ "type": 1, "content": "你好", "sender_id": 2, - "created_at": "2026-02-27T10:30:00Z" + "created_at": "2026-02-27 10:30:00" }, "unread_count": 3, "is_pinned": false @@ -65,7 +65,7 @@ "type": 1, "content": "明天开会", "sender_id": 3, - "created_at": "2026-02-27T11:00:00Z" + "created_at": "2026-02-27 11:00:00" }, "unread_count": 0, "is_pinned": true, @@ -117,7 +117,7 @@ { "user_id": 1, "nickname": "张三", "role": 2, "online": true }, { "user_id": 2, "nickname": "李四", "role": 0, "online": false } ], - "created_at": "2026-02-20T09:00:00Z" + "created_at": "2026-02-20 09:00:00" } } ``` @@ -153,7 +153,7 @@ "content": "明天几点开会？", "extra": {}, "status": 1, - "created_at": "2026-02-27T10:28:00Z" + "created_at": "2026-02-27 10:28:00" }, { "id": 99, @@ -169,7 +169,7 @@ "thumbnail": "https://cdn.echochat.com/img/xxx_thumb.jpg" }, "status": 1, - "created_at": "2026-02-27T10:29:00Z" + "created_at": "2026-02-27 10:29:00" } ], "has_more": true diff --git a/docs/api/meeting.md b/docs/api/meeting.md index 8907248..51d6051 100644 --- a/docs/api/meeting.md +++ b/docs/api/meeting.md @@ -55,7 +55,7 @@ "status": 1, "host_id": 1, "max_members": 50, - "created_at": "2026-02-27T10:00:00Z" + "created_at": "2026-02-27 10:00:00" } } ``` @@ -73,7 +73,7 @@ | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | title | string | 是 | 会议标题 | -| scheduled_at | string | 是 | 预约时间（ISO 8601，如 "2026-03-01T14:00:00Z"） | +| scheduled_at | string | 是 | 预约时间，格式：`yyyy-MM-dd HH:mm:ss`，如 `"2026-03-01 14:00:00"` | | password | string | 否 | 会议密码 | | max_members | int | 否 | 最大人数 | | invite_user_ids | int[] | 否 | 预先邀请的用户 ID 列表 | @@ -110,10 +110,10 @@ "has_password": true, "max_members": 50, "current_members": 5, - "started_at": "2026-02-27T10:00:00Z", + "started_at": "2026-02-27 10:00:00", "participants": [ - { "user_id": 1, "nickname": "张三", "role": 1, "joined_at": "2026-02-27T10:00:00Z" }, - { "user_id": 2, "nickname": "李四", "role": 0, "joined_at": "2026-02-27T10:01:00Z" } + { "user_id": 1, "nickname": "张三", "role": 1, "joined_at": "2026-02-27 10:00:00" }, + { "user_id": 2, "nickname": "李四", "role": 0, "joined_at": "2026-02-27 10:01:00" } ] } } diff --git a/docs/api/notify.md b/docs/api/notify.md index c45e183..d6b82cc 100644 --- a/docs/api/notify.md +++ b/docs/api/notify.md @@ -49,7 +49,7 @@ "from_username": "zhangsan" }, "is_read": false, - "created_at": "2026-02-27T10:00:00Z" + "created_at": "2026-02-27 10:00:00" }, { "id": 2, @@ -62,7 +62,7 @@ "message": "我是你的同事" }, "is_read": false, - "created_at": "2026-02-27T09:30:00Z" + "created_at": "2026-02-27 09:30:00" } ], "total": 15, diff --git a/docs/api/websocket.md b/docs/api/websocket.md index 4917ae1..4c29499 100644 --- a/docs/api/websocket.md +++ b/docs/api/websocket.md @@ -41,7 +41,7 @@ "event": "im.message.send", "seq": 1001, "data": { ... }, - "timestamp": 1740700000 + "time": "2026-02-27 18:06:40" } ``` @@ -50,7 +50,7 @@ | event | string | 事件名称，格式：`{模块}.{对象}.{动作}` | | seq | int | 消息序列号，客户端自增，用于匹配请求和响应 | | data | object | 事件数据 | -| timestamp | int | 发送时间戳（秒） | +| time | string | 发送时间，格式：`yyyy-MM-dd HH:mm:ss`，时区 Asia/Shanghai | ### 服务端响应格式（ACK） @@ -70,7 +70,7 @@ { "event": "im.message.new", "data": { ... }, - "timestamp": 1740700000 + "time": "2026-02-27 18:06:40" } ``` @@ -117,7 +117,7 @@ "type": 1, "content": "你好", "extra": {}, - "created_at": "2026-02-27T10:30:00Z" + "created_at": "2026-02-27 10:30:00" } ``` diff --git a/docs/architecture/system-architecture.md b/docs/architecture/system-architecture.md index 12187cd..09d7562 100644 --- a/docs/architecture/system-architecture.md +++ b/docs/architecture/system-architecture.md @@ -435,7 +435,7 @@ POST /api/v1/client/log # 前端错误上报接口 "stack": "Error: ICE connection failed...", "page": "/meeting/room", "user_agent": "...", - "timestamp": 1740700000 + "time": "2026-02-27 18:06:40" } ``` diff --git a/docs/plans/2026-02-27-echochat-system-design.md b/docs/plans/2026-02-27-echochat-system-design.md index 8d5b988..99359b6 100644 --- a/docs/plans/2026-02-27-echochat-system-design.md +++ b/docs/plans/2026-02-27-echochat-system-design.md @@ -587,7 +587,7 @@ echo:ws:conn:{conn_id} → 连接信息 JSON (STRING) "event": "im.message.send", "seq": 1001, "data": {}, - "timestamp": 1740700000 + "time": "2026-02-27 18:06:40" } ``` @@ -720,7 +720,7 @@ DELETE /media/room/:id "code": 0, "message": "ok", "data": {}, - "timestamp": 1740700000 + "time": "2026-02-27 18:00:00" } ``` diff --git a/docs/plans/2026-02-27-phase1-foundation-and-auth.md b/docs/plans/2026-02-27-phase1-foundation-and-auth.md index 1d9789c..26e72f2 100644 --- a/docs/plans/2026-02-27-phase1-foundation-and-auth.md +++ b/docs/plans/2026-02-27-phase1-foundation-and-auth.md @@ -224,9 +224,9 @@ type LogConfig struct { type Response struct { Code int `json:"code"` Message string `json:"message"` - Data interface{} `json:"data,omitempty"` - TraceID string `json:"trace_id,omitempty"` - Timestamp int64 `json:"timestamp"` + Data interface{} `json:"data,omitempty"` + TraceID string `json:"trace_id,omitempty"` + Time string `json:"time"` } ```