feat: release contextual omnichannel customer platform

Add Telegram, WhatsApp and email account management, realtime messaging, contextual multilingual AI, customer intelligence, knowledge workflows, enterprise controls, a unified design system and complete repository documentation.
2026-07-30 02:29:53 +08:00
parent 9804341463
commit af49d22ca7
66 changed files with 3181 additions and 554 deletions
@@ -0,0 +1,81 @@
+# API 目录
+
+API 统一位于 `/api`，内部渠道回调位于 `/internal/webhooks`。除注册、登录、健康检查和签名 Webhook 外，业务接口均要求 `Authorization: Bearer <token>`。
+
+成功响应采用统一数据包装；错误响应包含可展示消息和 HTTP 状态。调用方必须处理 `401`、`403`、`404`、`409`、`429` 和 `5xx`。
+
+## 认证与安全
+
+- `POST /api/auth/register`、`POST /api/auth/login`
+- `GET /api/auth/me`
+- `POST /api/auth/ws-ticket`：生成短期 WebSocket 票据
+- `POST /api/auth/change-password`
+- `POST /api/auth/logout-all`
+- `GET|POST|DELETE /api/api-keys`
+
+## 消息与会话
+
+- `GET /api/conversations`
+- `GET /api/conversations/:id`
+- `GET /api/conversations/:id/messages/page`：游标分页
+- `POST /api/conversations/:id/messages`：发送文本/回复
+- `POST /api/conversations/:id/media`
+- `POST /api/conversations/:id/album`
+- `POST /api/conversations/:id/read`
+- `POST /api/conversations/:id/presence`
+- `POST /api/conversations/:id/messages/action`
+- `PATCH /api/conversations/:id/messages/:messageId`
+- `GET /api/conversations/:id/messages/:messageId/attachment`
+- `POST /api/conversations/:id/actions`：归档、静音、清空、删除等会话动作
+
+## 渠道
+
+- `GET /api/channels`
+- Telegram：`/api/channels/telegram/start` 以及 `phone`、`code`、`password`、`state`
+- WhatsApp：`/api/channels/whatsapp/start`、状态、联系人、代理、设备、资料、指标和备份
+- 邮箱：`POST /api/channels/email/connect`
+- 通用：设为默认、状态、日志、删除和渠道测试
+- 可靠投递：Webhook 投递记录/重放、出站任务/重试
+
+## WhatsApp 群组
+
+- `GET /api/conversations/:id/whatsapp/group`
+- `POST /api/conversations/:id/whatsapp/group/action`
+
+动作由服务端白名单控制，包括成员、管理员、名称、描述和邀请链接管理。
+
+## AI
+
+- `POST /api/ai/translate`
+- `POST /api/ai/analyze`
+- `POST /api/ai/replies`
+- `POST /api/ai/summarize`
+- `POST /api/ai/text-action`
+- `POST /api/ai/adoptions`
+- `GET|PATCH /api/ai/translations`
+- `GET /api/conversations/:id/ai-status`
+- `POST /api/conversations/:id/messages/:messageId/analyze`
+
+AI 接口是业务增强能力。模型超时或限流不应阻断原始消息收发。
+
+## 客户经营与管理
+
+- 客户：列表、详情、导入、导出、查重、合并和基础 CRUD。
+- 商机、任务等资源：统一 CRUD 路由。
+- 团队：成员、邀请、角色、操作日志和登录记录。
+- 设置、通知、知识库、计费、仪表盘、分析与全局搜索。
+
+## Webhook
+
+- `POST /internal/webhooks/telegram/:tenantId/:channelId`
+- `POST /internal/webhooks/whatsapp/:tenantId/:channelId`
+
+生产调用必须携带对应签名。处理器同时校验 URL 中租户/渠道与数据库归属，事件应携带稳定 ID 以实现幂等。
+
+## 健康检查
+
+- `GET /health/live`：进程存活。
+- `GET /health/ready`：依赖就绪。
+- Nginx 暴露 `/health` 供容器健康检查。
+
+接口的请求/响应类型以 `src/services/`、`src/types/` 和 `server/src/index.js` 为当前实现准则。正式对外开放 API 前，应从路由生成 OpenAPI 3 文档并进行契约测试。
@@ -0,0 +1,79 @@
+# 系统架构
+
+## 1. 架构目标
+
+灵犀跨境以“租户隔离、渠道可扩展、消息实时、AI 异步化”为核心。浏览器只访问统一 Web/API 入口；Telegram、WhatsApp、邮箱和模型凭据只保存在服务端环境与加密存储中。
+
+```text
+Browser
+  │ HTTPS / WebSocket
+  ▼
+Nginx (web:80)
+  ├── React SPA
+  └── /api, /internal, /health ──► Node.js API (:3100)
+                                     ├── PostgreSQL 16
+                                     ├── DeepSeek Anthropic API
+                                     ├── Telegram Gateway / TDLib
+                                     ├── WhatsApp Gateway / Baileys
+                                     ├── IMAP + SMTP
+                                     └── Stripe
+```
+
+## 2. 仓库结构
+
+| 路径 | 职责 |
+| --- | --- |
+| `src/` | React 页面、组件、状态、API 客户端、国际化与类型 |
+| `server/src/index.js` | 认证、租户业务、消息、AI、渠道、Webhook、WebSocket 与数据初始化 |
+| `whatsapp-gateway/` | 普通 WhatsApp 多账号连接、消息/媒体/群组/联系人操作 |
+| `tests/e2e/` | Playwright 桌面与移动端验收 |
+| `docker/` | Nginx 与邮件协议测试辅助镜像 |
+| `docs/` | 架构、部署、接口、测试与运维文档 |
+
+## 3. 核心数据流
+
+### 入站消息
+
+1. Telegram/WhatsApp 网关向带租户和渠道标识的内部 Webhook 投递事件；邮箱轮询器从 IMAP 拉取邮件。
+2. API 校验签名、渠道归属与事件幂等标识。
+3. 消息、会话、联系人和状态写入 PostgreSQL。
+4. API 向当前租户的 WebSocket 客户端广播增量事件。
+5. 文本消息进入 AI 高优先级队列；较早历史进入低优先级补齐队列。
+6. 翻译、意图、情感、风险和会话记忆完成后再次广播更新。
+
+### 出站消息
+
+1. 前端提交渠道、会话、正文、媒体、回复目标和客户端幂等标识。
+2. API 验证 RBAC、租户归属、渠道状态与限流。
+3. 先落库发送任务，再调用对应网关或 SMTP。
+4. 网关状态事件持续对账已发送、已送达、已读和失败状态。
+5. 可恢复错误进入持久化重试；超过阈值进入死信等待人工重放。
+
+### 上下文 AI
+
+- 最近消息优先处理，以保证实时聊天速度。
+- 每个会话维护独立上下文；超过长度阈值后压缩为结构化记忆。
+- 历史消息按游标后台补齐，避免首次打开阻塞。
+- 翻译目标可自动识别，也可由坐席指定；智能回复保持人工确认发送。
+
+## 4. 隔离与权限
+
+- JWT 含用户、租户和角色信息；业务查询必须带 `tenant_id`。
+- 渠道、会话、消息、客户、任务与管理资源均在服务端校验租户归属。
+- WebSocket 使用短期票据，不把长期 JWT 放入 URL。
+- API Key 仅在创建时返回明文，持久化摘要并支持撤销。
+- 邮箱密码使用 `EMAIL_CREDENTIAL_KEY` 加密；网关登录态位于独立持久卷。
+
+## 5. 可靠性边界
+
+- PostgreSQL 是平台业务数据的事实来源。
+- Telegram/WhatsApp 平台状态由异步事件最终一致对账。
+- WebSocket 只用于加速展示；断线后客户端必须通过 REST 游标补齐。
+- Webhook 接收快速确认，耗时处理异步化；失败投递可查询和重放。
+- AI 失败不能阻断原始消息收发，任务可独立重试。
+
+## 6. 当前约束
+
+- Telegram Gateway 为独立仓库和独立部署，本仓库只保存适配与配置。
+- 普通 WhatsApp 接入依赖非官方 Web 多设备协议，生产使用前必须评估账号风控和平台条款。
+- API 目前集中在单入口文件，业务增长后应按领域拆分路由、服务、仓储和迁移文件。
@@ -0,0 +1,60 @@
+# 备份与恢复
+
+## 备份范围
+
+1. PostgreSQL：租户、用户、客户、消息、任务、审计和持久队列。
+2. `lingxi_whatsapp_data`：WhatsApp 多设备登录态与网关缓存。
+3. Telegram Gateway：由其独立部署执行 TDLib 数据和配置备份。
+4. 环境密钥：存入公司 Secret 管理系统，不与数据备份打包。
+5. 对象存储或上传目录：若生产启用，按独立生命周期备份。
+
+## PostgreSQL
+
+```bash
+docker compose exec -T postgres pg_dump \
+  -U "${LX_DB_USER:-lingxi}" \
+  -d "${LX_DB_NAME:-lingxi_crossborder}" \
+  -Fc > "lingxi-postgres-$(date +%Y%m%d-%H%M%S).dump"
+```
+
+恢复必须在隔离环境先演练：
+
+```bash
+createdb lingxi_restore_test
+pg_restore --clean --if-exists --no-owner \
+  --dbname lingxi_restore_test lingxi-postgres-YYYYMMDD-HHMMSS.dump
+```
+
+## WhatsApp 持久卷
+
+备份前短暂停止网关写入，避免文件不一致：
+
+```bash
+docker compose stop whatsapp-gateway
+docker run --rm \
+  -v lingxi-crossborder_lingxi_whatsapp_data:/source:ro \
+  -v "$PWD/backups:/backup" \
+  alpine tar -czf /backup/whatsapp-data.tar.gz -C /source .
+docker compose start whatsapp-gateway
+```
+
+恢复前保留现有卷副本，在测试环境验证账号能重连；登录态过期时应走重新授权，不能把旧凭据强行用于其他账号。
+
+## 策略
+
+- PostgreSQL：每日全量，生产规模扩大后增加连续归档或托管 PITR。
+- 网关登录态：每日加密备份，账号变更后额外备份。
+- 至少保留 7 个日备、4 个周备、6 个月备，按法规和客户合同调整。
+- 备份使用独立凭据、服务端加密和异地存储。
+
+## 恢复演练
+
+每月至少一次：
+
+1. 在隔离网络创建全新环境。
+2. 恢复数据库、网关数据和必要配置。
+3. 验证租户数、关键表行数和最近消息时间。
+4. 验证登录、会话读取、渠道重连、收发和媒体下载。
+5. 记录 RPO、RTO、失败点和改进项。
+
+仅“备份成功”不等于可恢复；没有完成验收的备份不得视为合格。
@@ -0,0 +1,63 @@
+# 配置说明
+
+以 `.env.example` 为唯一模板。开发、测试、生产分别保存自己的 `.env`，不得提交 Git。
+
+## 基础配置
+
+| 变量 | 必填 | 说明 |
+| --- | --- | --- |
+| `LX_DB_USER` | 否 | PostgreSQL 用户，默认 `lingxi` |
+| `LX_DB_PASSWORD` | 是 | 数据库强密码 |
+| `LX_DB_NAME` | 否 | 数据库名，默认 `lingxi_crossborder` |
+| `LX_JWT_SECRET` | 是 | 至少 32 字节随机值 |
+| `LX_WEB_PORT` | 否 | Web 暴露端口，默认 `8088` |
+| `APP_PUBLIC_URL` | 是 | 用户访问的 HTTPS 根地址 |
+| `PUBLIC_WEBHOOK_BASE_URL` | 是 | 外部网关可访问的 Webhook 根地址 |
+
+## AI
+
+| 变量 | 必填 | 说明 |
+| --- | --- | --- |
+| `DEEPSEEK_API_KEY` | 是 | 服务端模型密钥 |
+| `DEEPSEEK_MODEL` | 是 | 当前默认 `deepseek-v4-flash` |
+
+API 基础地址在 Compose 中设置为 `https://api.deepseek.com/anthropic`。切换模型前应验证 Anthropic 兼容接口、JSON 输出稳定性、延迟和成本。
+
+## Telegram
+
+| 变量 | 说明 |
+| --- | --- |
+| `TELEGRAM_GATEWAY_URL` | 独立 Telegram Gateway API 地址 |
+| `TELEGRAM_GATEWAY_TOKEN` | 网关服务令牌 |
+| `TELEGRAM_GATEWAY_TENANT_ID` | 网关租户 |
+| `TELEGRAM_GATEWAY_SERVICE_EMAIL` / `PASSWORD` | 服务账号 |
+| `TELEGRAM_GATEWAY_ACCOUNT_ID` | 可选默认账号 |
+| `TELEGRAM_WEBHOOK_SECRET` | Telegram Webhook 独立签名密钥 |
+
+## WhatsApp
+
+| 变量 | 说明 |
+| --- | --- |
+| `WHATSAPP_GATEWAY_TOKEN` | API 与网关间认证，至少 32 位 |
+| `WHATSAPP_WEBHOOK_SECRET` | Webhook 签名密钥，不能与 Token 相同 |
+| `WHATSAPP_LOG_LEVEL` | `info`、`warn` 或 `error` |
+
+WhatsApp 登录态保存在 `lingxi_whatsapp_data` 卷，不得复制到源码目录或提交 Git。
+
+## 邮箱与支付
+
+- 团队邀请：`SMTP_HOST`、`SMTP_PORT`、`SMTP_SECURE`、`SMTP_USER`、`SMTP_PASSWORD`、`SMTP_FROM`。
+- 企业邮箱渠道使用用户提供的 IMAP/SMTP 信息；`EMAIL_CREDENTIAL_KEY` 用于加密凭据。
+- Stripe：`STRIPE_SECRET_KEY`、`STRIPE_WEBHOOK_SECRET` 和各套餐 `STRIPE_PRICE_*`。
+
+## 生成随机密钥
+
+PowerShell 示例：
+
+```powershell
+$bytes = New-Object byte[] 48
+[Security.Cryptography.RandomNumberGenerator]::Fill($bytes)
+[Convert]::ToBase64String($bytes)
+```
+
+每个变量单独生成，不复用。生产密钥应放入部署平台的 Secret 管理，不写入 Compose、镜像或 CI 日志。
@@ -0,0 +1,73 @@
+# 部署与回滚
+
+## 1. 前置条件
+
+- Linux x86_64 主机，建议 4 核、8 GB 内存、50 GB 可扩展磁盘。
+- Docker Engine 24+、Compose v2。
+- 域名、HTTPS 证书和可访问的 Telegram Gateway。
+- 出站可访问 Telegram、WhatsApp、DeepSeek、邮箱服务和 Stripe。
+
+## 2. 首次部署
+
+```bash
+git clone ssh://git@git.ohkeji.cn:23/wmq/lingxi-web.git
+cd lingxi-web
+cp .env.example .env
+# 编辑 .env 并替换全部占位值
+docker compose --env-file .env build
+docker compose --env-file .env up -d
+docker compose ps
+```
+
+检查：
+
+```bash
+curl -fsS http://127.0.0.1:8088/health
+docker compose exec api node -e "fetch('http://127.0.0.1:3100/health/ready').then(async r=>{console.log(await r.text());process.exit(r.ok?0:1)})"
+docker compose logs --tail=100 api whatsapp-gateway web
+```
+
+## 3. 生产入口
+
+在 Compose 外层部署 Caddy、Nginx 或云负载均衡：
+
+- 只对公网开放 80/443。
+- 将 HTTPS 请求转发到 `127.0.0.1:8088`。
+- 保留 `Host`、`X-Forwarded-For`、`X-Forwarded-Proto`。
+- WebSocket 路径启用 Upgrade/Connection 头并提高空闲超时。
+- PostgreSQL、API、WhatsApp Gateway 不映射公网端口。
+
+将 `APP_PUBLIC_URL` 和 `PUBLIC_WEBHOOK_BASE_URL` 改为正式 HTTPS 地址，随后重建 API。
+
+## 4. 更新
+
+```bash
+git fetch --tags
+git checkout main
+git pull --ff-only
+docker compose --env-file .env build
+docker compose --env-file .env up -d
+docker compose ps
+```
+
+更新前先执行数据库和 WhatsApp 登录态备份。更新后验证登录、渠道状态、收发、WebSocket、AI、媒体和健康检查。
+
+## 5. 回滚
+
+1. 记录当前版本：`git describe --tags --always`。
+2. 恢复与目标版本兼容的数据库备份。
+3. 检出稳定标签，例如 `git checkout v1.0.0`。
+4. 重新构建并启动：`docker compose up -d --build`。
+5. 执行健康和关键业务检查。
+
+`snapshot-*` 是历史源码归档，不保证数据库向后兼容，不应直接作为生产回滚点。
+
+## 6. 零停机演进
+
+当前 Compose 是单实例，会有短暂重启窗口。需要零停机时应：
+
+- 将 PostgreSQL 迁移到托管或高可用实例。
+- 将 Web/API 部署为至少两个实例并使用外部负载均衡。
+- WebSocket 使用共享事件总线或粘性会话。
+- 将持久任务改用共享队列并确保幂等。
+- 数据库变更采用“先兼容、再切换、后清理”的多阶段迁移。
@@ -0,0 +1,58 @@
+# 运维手册
+
+## 日常检查
+
+```powershell
+docker compose ps
+docker compose logs --since=30m api
+docker compose logs --since=30m whatsapp-gateway
+Invoke-RestMethod http://127.0.0.1:8088/health
+docker compose exec api node -e "fetch('http://127.0.0.1:3100/health/ready').then(async r=>{console.log(await r.text());process.exit(r.ok?0:1)})"
+```
+
+重点关注：API 错误率、Webhook 延迟与死信数、出站队列深度、WebSocket 在线数、AI 延迟/限流、数据库连接与磁盘、渠道断线数。
+
+## 常见故障
+
+### 页面“加载失败”
+
+1. 检查 `web` 与 `api` 健康状态。
+2. 检查浏览器请求的 HTTP 状态和 API 日志。
+3. `401` 重新登录；`403` 检查角色；`5xx` 检查数据库和外部依赖。
+4. 不要通过清库或删除持久卷解决普通错误。
+
+### 渠道显示已连接但无消息
+
+1. 验证渠道最近心跳、Webhook 状态和投递日志。
+2. 检查 Webhook 地址是否能从网关容器访问。
+3. 检查签名密钥是否一致、渠道 ID 是否属于当前租户。
+4. 触发安全的状态对账；不要反复解绑账号。
+
+### WebSocket 不实时
+
+1. 确认反向代理允许 Upgrade。
+2. 检查短期票据是否过期以及客户端是否自动重连。
+3. 断线期间通过 REST 游标补齐，不依赖丢失的内存事件。
+
+### AI 变慢或失败
+
+1. 查看模型响应状态、超时和限流。
+2. 确认高优先级实时队列未被历史补齐占满。
+3. 暂停历史补齐而不是暂停消息接收。
+4. 原始消息应照常展示，待模型恢复后重试增强任务。
+
+## 变更与事件处理
+
+- 配置、密钥、数据库和网关升级都先备份并记录操作人。
+- 重大故障先止损：暂停高风险发送、保留日志、不要破坏现场。
+- 恢复后补做根因、影响租户、时间线、数据一致性和预防措施记录。
+
+## 告警建议
+
+- 健康检查连续 3 次失败。
+- 5 分钟 API 5xx 比例超过 2%。
+- Webhook 最老未处理任务超过 60 秒或死信新增。
+- WhatsApp/Telegram 渠道离线超过 2 分钟。
+- PostgreSQL 磁盘超过 75%、连接超过 80%。
+- AI P95 超过目标或 `429` 持续出现。
+- 备份任务失败或超过 24 小时未成功。
@@ -0,0 +1,56 @@
+# 技术选型
+
+## Web
+
+| 技术 | 版本范围 | 选择原因 |
+| --- | --- | --- |
+| React | 18.3 | 组件生态成熟，适合高交互消息工作台 |
+| TypeScript | 5.7 | 为接口、消息事件和页面状态提供静态约束 |
+| Vite | 5.4 | 本地启动和生产构建快速 |
+| React Router | 7.x | 页面路由和错误边界 |
+| TanStack Query | 5.x | 服务端状态缓存、刷新和失败重试 |
+| Zustand | 4.x | 轻量跨组件客户端状态 |
+| Tailwind CSS | 3.4 | 设计令牌与响应式界面 |
+| Recharts | 2.15 | 仪表盘趋势和客户画像雷达图 |
+| Zod + React Hook Form | 3.x / 7.x | 表单校验与可维护的输入状态 |
+| Lucide React | 0.462 | 一致的线性图标系统 |
+
+## API 与数据
+
+| 技术 | 作用 |
+| --- | --- |
+| Node.js 20 | 前后端统一运行时，适合 I/O 密集的消息网关 |
+| Express 5 | REST、Webhook 与中间件 |
+| PostgreSQL 16 | 多租户业务数据、队列和审计的持久化 |
+| `pg` | 直接、透明的 SQL 访问 |
+| `ws` | 实时消息与状态广播 |
+| JWT + bcryptjs | 身份令牌与密码哈希 |
+| Helmet + CORS | 基础 HTTP 安全头和来源约束 |
+| IMAPFlow + Nodemailer | 企业邮箱收取与发送 |
+| Mailparser | MIME 邮件解析 |
+| Mammoth + pdf-parse | DOCX/PDF 知识文件抽取 |
+
+## 渠道与 AI
+
+| 组件 | 作用 |
+| --- | --- |
+| Telegram Gateway + TDLib | 普通 Telegram 账号登录、同步和操作 |
+| Baileys 7 | WhatsApp 多设备连接、消息和群组能力 |
+| DeepSeek Anthropic-compatible API | 翻译、意图、情感、风险、摘要和回复建议 |
+| Stripe | 套餐结算与 Webhook 对账 |
+
+## 交付与质量
+
+| 技术 | 作用 |
+| --- | --- |
+| Docker Compose | 本地、测试和单机生产编排 |
+| Nginx | 静态站点、SPA fallback、API/WebSocket 反向代理 |
+| Node Test Runner | API 与网关单元/协议测试 |
+| Playwright | Chromium 桌面与移动端视觉/交互 E2E |
+
+## 取舍
+
+- 当前采用模块化单体 API，部署简单、事务边界清晰；代码量继续增长时应优先拆文件而不是立即拆微服务。
+- PostgreSQL 同时承载业务和持久任务，减少早期基础设施；高吞吐阶段可引入 Redis 与专用队列。
+- WhatsApp 普通账号接入覆盖面高，但稳定性和合规性弱于官方 Business Platform，应为企业客户预留官方适配器。
+- AI 采用异步增强而非消息主链路依赖，模型故障时仍可正常沟通。
@@ -0,0 +1,45 @@
+# 测试策略
+
+## 测试层次
+
+| 层次 | 命令 | 覆盖 |
+| --- | --- | --- |
+| 类型检查 | `npm run typecheck` | 前端 TypeScript |
+| 生产构建 | `npm run build` | 类型、打包、资源引用 |
+| API 单元/业务 | `npm test --prefix server` | 业务函数、权限与数据逻辑 |
+| 邮件协议 | `npm run test:email-protocol --prefix server` | IMAP/SMTP 协议 |
+| 邮件 API E2E | `npm run test:email-api --prefix server` | 真实测试邮件服务链路 |
+| WhatsApp 网关 | `npm test --prefix whatsapp-gateway` | 路由、状态、消息与可靠性 |
+| 浏览器 E2E | `npm run test:e2e` | 桌面/移动端主要用户路径 |
+
+## 提交前最低要求
+
+- 文档或纯样式：类型检查、构建、相关页面 E2E。
+- 前端业务：类型检查、构建、完整 Playwright。
+- API：语法检查、API 测试、相关 E2E。
+- 网关：网关测试、容器健康、真实测试账号冒烟。
+- 认证、租户、支付、备份：完整回归并人工复核安全边界。
+
+## 真实链路验收
+
+Mock 测试不能证明渠道真实可用。发布前使用无重要数据的测试账号逐项验证：
+
+1. Telegram 手机号、验证码、二步密码登录。
+2. WhatsApp QR/配对、断开、重连和多账号切换。
+3. 邮箱 IMAP 首次同步、SMTP 发信和附件。
+4. 双向文本、引用、图片、文档、语音、贴纸、相册。
+5. 已发送、送达、已读、编辑、撤回、输入状态。
+6. 历史分页、断网恢复、WebSocket 重连和增量补齐。
+7. 多语言翻译、意图开关、会话记忆压缩和 AI 失败降级。
+8. Webhook 失败重试、死信、人工重放和幂等。
+9. RBAC 越权请求、租户交叉资源 ID 和登录限流。
+
+## 测试数据
+
+- 只使用专用测试租户和测试账号。
+- 不把手机号、验证码、会话凭据、邮件密码和生产消息写入测试代码或报告。
+- Playwright 失败产物可能包含页面数据；归档前脱敏，且不得提交 Git。
+
+## 发布记录
+
+每次版本标签应记录执行日期、提交 SHA、环境、测试命令、通过/跳过/失败数量和已知限制。跳过项必须说明原因，不能等同于通过。