tauri-client/broadcast-client/技术方案.md

广播系统技术方案

1. 文档目的

基于《广播系统需求文档》，输出可直接指导开发与联调的技术落地方案，覆盖：

• Tauri v2 窗口与生命周期实现
• 5000px 标尺分段渲染策略
• 子元素切段一致性处理
• 性能、兼容性与验收测试方案

2. 目标与范围

2.1 目标

• 程序启动后自动创建无边框窗口，并固定在 (0, 0)。
• 在任意屏幕宽度下，正确展示宽 5000px、高 64px 的标尺内容。
• 当屏幕宽度小于 5000px 时，按“横向切片、纵向堆叠”方式渲染。
• 标尺满足 10px 小格、100px 大格。
• 主容器内子元素在切断位置保持视觉连续。

2.2 范围

• 包含：桌面端单窗口显示、标尺渲染、分段映射、子元素切段、基础性能优化。
• 不包含：网络同步、多用户协作、云端配置、复杂拖拽编辑器。

3. 技术选型

• 桌面容器：Tauri v2
• 前端框架：Vue 3 + TypeScript
• 构建工具：Vite
• 样式：CSS（必要时搭配 CSS 变量）
• 渲染策略：DOM + CSS（优先），保留 Canvas 升级路径

选择理由：

• Tauri 体积小、启动快，适合常驻轻量显示工具。
• Vue 3 组件化能力可清晰拆分“窗口层 / 标尺层 / 分段层”。
• 5000px*64px 属于中低复杂度场景，DOM 足以支撑且便于调试与维护。

4. 核心实现方案

4.1 窗口管理实现

在 Tauri v2 配置中设置：

• 无边框：decorations: false
• 启动即显示：默认窗口自动创建
• 初始位置：x: 0, y: 0
• 可选增强：置顶 alwaysOnTop（按产品决策开关）

建议窗口配置（示意）：

• 初始宽度：屏幕宽度（或合理默认值）
• 初始高度：由分段数量计算（见 4.2）

4.2 分段显示算法

定义：

• TOTAL_WIDTH = 5000
• SEGMENT_HEIGHT = 64
• screenWidth = 当前主屏宽度
• segmentCount = ceil(TOTAL_WIDTH / screenWidth)

每段 i（从 0 开始）映射：

• 源区域横向起点：sourceX = i * screenWidth
• 当前段有效宽度：sliceWidth = min(screenWidth, TOTAL_WIDTH - sourceX)
• 目标位置：x = 0, y = i * SEGMENT_HEIGHT
• 目标尺寸：sliceWidth x SEGMENT_HEIGHT

渲染方式：

• 外层容器高度：segmentCount * 64px
• 每一段都渲染同一条“5000px 虚拟标尺”，但通过 transform: translateX(-sourceX) 显示对应片段
• 段容器设置 overflow: hidden，实现“切片窗口”效果

4.3 标尺刻度绘制策略

总宽范围 [0, 5000)：

• 每 10px 一个小刻度
• 每 100px 一个大刻度（并可带数值标签）

实现建议：

• 通过循环生成刻度数据结构，交由 Vue 渲染
• 大刻度与小刻度使用不同高度和样式类
• 统一使用绝对定位，避免复杂流式布局导致抖动

数据模型示例：

• ticks: Array<{ x: number; type: "minor" | "major"; label?: string }>

4.4 子元素切断与连续性

子元素抽象：

• child = { id, left, width, top, height, style }

对第 i 段，子元素可见区间计算：

• segmentStart = i * screenWidth
• segmentEnd = segmentStart + screenWidth
• childStart = child.left
• childEnd = child.left + child.width
• 相交宽度：visibleWidth = max(0, min(childEnd, segmentEnd) - max(childStart, segmentStart))

若 visibleWidth > 0，则在该段渲染一个“切片子元素”：

• 本段左偏移：renderLeft = max(childStart, segmentStart) - segmentStart
• 源内容偏移：clipOffset = max(0, segmentStart - childStart)

连续性保证：

• 同一子元素跨段时复用同一视觉样式与层级
• 文本类子元素建议使用 white-space: nowrap 并通过裁剪窗口显示，避免换行错位

4.5 分辨率适配

• 启动时读取主屏宽度
• 监听窗口尺寸变化（可选）
• 变化后重新计算 segmentCount 与各段 sourceX
• 对高 DPI 环境，使用 CSS 像素布局，必要时读取缩放比做微调

5. 性能优化策略

• 刻度数据缓存：ticks 在 TOTAL_WIDTH 不变时仅初始化一次
• 分段列表缓存：仅在屏宽变化时重算
• 避免深层响应式：大数组使用浅响应或只读数据
• 降低重排：段内使用绝对定位，减少文档流参与
• 控制重绘：样式变化优先 transform / opacity

目标性能指标：

• 冷启动到首屏可见 < 1.5s（常规办公设备）
• resize 重算后 100ms 内完成主要布局更新
• 无明显掉帧和视觉撕裂

6. 错误处理与边界条件

• screenWidth <= 0：回退默认宽度（如 1920）
• 极窄屏幕（如 800）：保证 segmentCount 正确增长
• 最后一段不足整宽：必须按 sliceWidth 渲染，禁止越界
• 子元素超出 [0, 5000]：按相交逻辑自动裁剪

7. 开发实施计划

阶段 1：工程初始化

• 初始化 Tauri v2 + Vue3 + TS 项目
• 完成基础窗口配置（无边框、坐标）

阶段 2：核心渲染

• 实现标尺刻度生成
• 实现分段容器与映射逻辑
• 验证不同屏宽下显示正确

阶段 3：子元素切段

• 定义子元素数据结构
• 完成相交裁剪与跨段显示
• 增加典型跨段用例

阶段 4：优化与验收

• 性能优化与边界处理
• 执行验收用例并修复问题

8. 测试与验收方案

对照需求验收项设计测试用例：

• 启动后窗口：无边框、位于 (0, 0)
• 主容器：逻辑宽 5000px、高 64px
• 分段：segmentCount = ceil(5000 / screenWidth)，每段高度 64px
• 刻度：10px 小格、100px 大格位置准确
• 子元素：跨段后位置连续、无错位/跳变

建议增加自动化：

• 单元测试：分段计算函数、子元素相交函数
• 组件测试：段渲染快照
• 手工测试：多分辨率与 DPI 场景

9. 风险与应对

• 风险：高 DPI 下 1px 线条发虚
  应对：使用整数像素对齐与样式微调。

• 风险：窗口尺寸变化频繁触发抖动
  应对：对 resize 处理加入节流（如 100ms）。

• 风险：后续需求扩展（动画、动态数据）导致 DOM 压力上升
  应对：预留 Canvas 渲染替换层接口。

10. 交付物

• 可运行的 Tauri 广播客户端
• 本技术方案文档
• 软件架构文档
• 基础测试用例与验收记录