ishenwei/nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Sync: add ses and networking notes

Browse Source
This commit is contained in:
weishen
2026-04-24 20:38:20 +08:00
parent e4f6f463cb
commit 7903d703b9
12 changed files with 925 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
Project/fonrey/DATA_MODEL/DATA_MODEL_PUBLIC.md
View File

@@ -4,7 +4,7 @@
> **版本**: v1.0
> **日期**: 2026-04-24
> **权威源**: 本文件是 `public` schema 所有表的唯一权威定义
> **设计依据**: 系统管理模块 PRD（`PRD/系统管理/系统管理模块PRD.md`）
> **设计依据**: 系统管理模块 PRD（`PRD/系统管理/系统管理模块PRD.md`）；客户端发布管理模块 PRD（`PRD/发布管理/客户端发布管理模块PRD.md`）
> **索引文档**: [`DATA_MODEL.md §三`](./DATA_MODEL.md)（仅保留摘要索引，开发以本文件为准）
---
@@ -31,7 +31,8 @@ PostgreSQL Instance
│ ├── backup_records 备份记录
│ ├── export_tasks 数据导出
│ ├── system_versions 版本历史
│ └── upgrade_events 升级记录
│ ├── upgrade_events 升级记录
│ └── client_releases 客户端版本发布
│
├── tenant_abc schema（租户业务层，见各子文档）
└── tenant_xyz schema
@@ -54,6 +55,7 @@ PostgreSQL Instance
| `public.export_tasks` | 数据导出异步任务（CSV/JSON/SQL Dump） | §2.4 |
| `public.system_versions` | 平台版本历史，唯一 current 约束 | §2.5 |
| `public.upgrade_events` | 升级/回滚事件，含灰度租户维度进度快照 | §2.5 |
| `public.client_releases` | Windows 客户端发布版本，含安装包 URL、SHA256、强制更新标记 | §2.6 |
---
@@ -376,6 +378,87 @@ CREATE TABLE public.upgrade_events (
CREATE INDEX idx_upgrade_events_status ON public.upgrade_events(status, created_at DESC);
```
### 2.6 客户端发布管理
```sql
-- ────────────────────────────────────────────────────────────
-- 6. 客户端发布管理
-- ────────────────────────────────────────────────────────────
-- 设计依据: 客户端发布管理模块 PRD §5.3
-- 说明: 本表属于 shared_apps（public schema），所有租户共享同一套客户端版本，
-- 不做多租户隔离。
-- 客户端版本发布表
CREATE TABLE public.client_releases (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-- 版本标识
version VARCHAR(20) UNIQUE NOT NULL,
-- SemVer 格式，如 '1.2.3'；由应用层校验格式，数据库层仅保证唯一性
platform VARCHAR(20) NOT NULL DEFAULT 'win32'
CHECK (platform IN ('win32')),
-- 当前仅支持 Windows；后续支持 darwin / linux 时扩展 CHECK
arch VARCHAR(10) NOT NULL DEFAULT 'x64'
CHECK (arch IN ('x64', 'arm64')),
-- 版本类型与状态
release_type VARCHAR(10) NOT NULL DEFAULT 'normal'
CHECK (release_type IN ('normal', 'force')),
-- normal = 普通更新，提示但可延后；force = 强制升级，不可跳过
status VARCHAR(10) NOT NULL DEFAULT 'draft'
CHECK (status IN ('draft', 'published', 'archived')),
-- draft = 草稿，不对外生效；published = 已发布，客户端可感知；archived = 已下线
-- 兼容性约束
min_required_version VARCHAR(20),
-- 低于该版本的客户端将被强制要求升级，NULL = 无最低版本限制
-- 由应用层在查询时比较 SemVer，数据库层不做运算
-- 安装包（EXE）
download_url TEXT NOT NULL,
-- Cloudflare R2 公开 URL，格式：
-- https://download.fonrey.com/releases/v{version}/fonrey-setup-{version}-win.exe
checksum_sha256 VARCHAR(64) NOT NULL,
-- 安装包 SHA256 十六进制字符串（64 位），客户端下载完成后校验
file_size_bytes BIGINT,
-- 安装包字节大小，用于前端展示下载大小
-- 便携版（ZIP，可选）
portable_url TEXT,
-- 无需安装的 ZIP 版本，供无管理员权限的企业环境使用
portable_checksum_sha256 VARCHAR(64),
-- 更新内容
release_notes TEXT NOT NULL,
-- 对外展示的更新日志，Markdown 格式，最多 2000 字
internal_notes TEXT,
-- 内部技术说明，不对外展示
-- 统计
download_count INTEGER NOT NULL DEFAULT 0,
-- 该版本安装包被下载次数，由应用层在每次下载时原子递增
-- 时间与操作人
published_at TIMESTAMPTZ,
-- 首次设为 published 时记录，后续状态变更不更新此字段
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
created_by UUID REFERENCES public.platform_admins(id) ON DELETE SET NULL,
published_by UUID REFERENCES public.platform_admins(id) ON DELETE SET NULL
);
-- 只允许一条 published 记录（同平台+架构下的当前生效版本）
CREATE UNIQUE INDEX idx_client_releases_published
ON public.client_releases(platform, arch)
WHERE status = 'published';
-- 快速查找草稿/已发布版本（管理后台列表查询）
CREATE INDEX idx_client_releases_status ON public.client_releases(status, created_at DESC);
-- 按版本号快速定位（客户端更新检测时传入 current_version 查询）
CREATE INDEX idx_client_releases_version ON public.client_releases(version);
```
---
## 三、关键约束与禁止操作
@@ -391,6 +474,9 @@ CREATE INDEX idx_upgrade_events_status ON public.upgrade_events(status, created_
| `platform_admins` 与 `staff` 完全独立 | 不共享表、不共享 auth 系统 |
| MFA 强制 | `platform_admins.mfa_enabled` 在首次 TOTP 确认后才变 TRUE；登录流必须检查 |
| `admin_sessions` 30 分钟滚动超时 | 应用层每次活跃请求更新 `expires_at = NOW() + 30min` |
| `client_releases` 唯一 published | `idx_client_releases_published` 部分唯一索引保证同平台+架构下只有一条 `status='published'` |
| `client_releases` 不可跨租户隔离 | 本表属于 public schema，所有租户共享；禁止在租户 schema 中创建副本 |
| `client_releases.download_count` 原子递增 | 必须使用 `UPDATE ... SET download_count = download_count + 1`，禁止先读后写 |
---
@@ -468,6 +554,27 @@ FROM public.backup_records br
JOIN public.tenants t ON t.id = br.tenant_id
WHERE br.status IN ('pending', 'in_progress')
ORDER BY br.created_at DESC;
-- 客户端更新检测：查询当前生效版本（platform=win32, arch=x64）
SELECT version, release_type, download_url, portable_url,
checksum_sha256, file_size_bytes, release_notes, published_at
FROM public.client_releases
WHERE platform = 'win32'
AND arch = 'x64'
AND status = 'published'
LIMIT 1;
-- 客户端版本管理列表（管理后台，含各状态版本）
SELECT version, platform, arch, release_type, status,
download_count, published_at, created_at
FROM public.client_releases
ORDER BY created_at DESC;
-- 统计各版本活跃客户端数（需结合客户端上报心跳表，当前仅记录下载量）
SELECT version, download_count
FROM public.client_releases
WHERE status IN ('published', 'archived')
ORDER BY published_at DESC;
```
### 5.2 禁止查询
@@ -478,6 +585,8 @@ ORDER BY br.created_at DESC;
| `DELETE FROM public.platform_audit_logs` | append-only 审计表 |
| `UPDATE public.tenants SET schema_name = ...` | schema 名绑定 PG 物理 schema |
| `UPDATE public.domains SET domain = ...` | 域名路由不可变 |
| `UPDATE public.client_releases SET version = ...` | 版本号创建后不可修改，变更须新建记录 |
| 在租户 schema 中创建 `client_releases` 副本 | 本表属于 public schema，多租户共享，禁止下沉到租户层 |
---
@@ -486,3 +595,4 @@ ORDER BY br.created_at DESC;
| 版本 | 日期 | 变更 |
|------|------|------|
| v1.0 | 2026-04-24 | 从 `DATA_MODEL.md §三` 独立拆分；内容等价于 v1.2 DATA_MODEL.md §三 |
| v1.1 | 2026-04-24 | 新增 §2.6 `client_releases` 表（客户端发布管理）；同步更新表清单、约束规则、查询模式 |