# 广播系统技术方案

## 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 广播客户端
- 本技术方案文档
- 软件架构文档
- 基础测试用例与验收记录