# 广播系统软件架构文档

## 1. 架构目标

构建一个基于 Tauri v2 的桌面广播显示系统，满足以下架构目标：
- 支持固定窗口行为（无边框、左上角定位、启动即开）
- 支持 5000px 标尺在任意屏宽下的稳定分段显示
- 支持子元素跨段连续渲染
- 保持模块边界清晰，便于后续扩展（动态数据、渲染升级）

## 2. 总体架构

采用“宿主层 + 前端应用层 + 渲染域层”的分层结构：

- 宿主层（Tauri Runtime）
  - 负责窗口生命周期、屏幕信息读取、系统能力接入
- 前端应用层（Vue Application）
  - 负责状态管理、分段计算、组件编排
- 渲染域层（Ruler Rendering Domain）
  - 负责刻度绘制、切片映射、子元素裁剪与连续性

架构原则：
- 计算与渲染分离：算法在 `composables/services`，界面在 `components/views`
- 数据驱动：通过状态变化触发渲染，不在组件中写复杂业务判断
- 可替换渲染：先 DOM，后续可平滑迁移到 Canvas

## 3. 逻辑视图（模块划分）

建议目录结构：

```text
broadcast-client/
  src/
    main.ts
    App.vue
    views/
      BroadcastView.vue
    components/
      RulerCanvas.vue
      RulerSegment.vue
      RulerTicks.vue
      SegmentChildren.vue
    composables/
      useScreenInfo.ts
      useSegmentLayout.ts
      useRulerTicks.ts
    services/
      segmentService.ts
      childSliceService.ts
    models/
      ruler.ts
      segment.ts
      child.ts
    utils/
      math.ts
  src-tauri/
    tauri.conf.json
    src/
      lib.rs
```

模块职责：
- `useScreenInfo`：读取并维护当前主屏宽度、DPI 信息
- `segmentService`：计算段数量、每段映射关系
- `useRulerTicks`：生成 10/100 刻度数据
- `childSliceService`：计算子元素在每段的可见切片
- `RulerSegment`：单段渲染容器（裁剪窗口）
- `SegmentChildren`：渲染跨段子元素切片

## 4. 关键数据模型

```ts
type TickType = "minor" | "major";

interface Tick {
  x: number;
  type: TickType;
  label?: string;
}

interface Segment {
  index: number;
  sourceX: number;
  sliceWidth: number;
  top: number;
  height: number; // 固定 64
}

interface ChildElement {
  id: string;
  left: number;
  width: number;
  top: number;
  height: number;
  zIndex?: number;
  className?: string;
}

interface ChildSlice {
  childId: string;
  segmentIndex: number;
  renderLeft: number;
  renderTop: number;
  renderWidth: number;
  renderHeight: number;
  clipOffset: number;
}
```

设计说明：
- `Segment` 只描述“段映射”，不关心具体 UI。
- `ChildSlice` 是“子元素在某段中的投影结果”，用于直接渲染。
- 所有坐标统一使用同一逻辑坐标系（以 5000px 主轴为基准）。

## 5. 运行时流程（时序）

启动流程：
1. Tauri 启动并创建窗口（无边框，位置 `(0,0)`）。
2. 前端初始化，读取屏幕宽度 `screenWidth`。
3. 计算 `segments = ceil(5000 / screenWidth)`。
4. 生成刻度数据 `ticks`，构建段列表 `segmentList`。
5. 渲染每段：段容器裁剪 + 虚拟标尺偏移显示。
6. 若存在子元素，计算 `ChildSlice[]` 并叠加渲染。

更新流程（屏宽变化）：
1. 监听窗口尺寸/屏幕变化事件。
2. 重新计算 `segmentList` 与 `ChildSlice[]`。
3. 增量更新视图（避免全量销毁重建）。

## 6. 关键算法设计

### 6.1 分段算法

- 输入：`TOTAL_WIDTH=5000`, `screenWidth`, `SEGMENT_HEIGHT=64`
- 输出：`Segment[]`
- 复杂度：`O(n)`，`n = segmentCount`

核心规则：
- `segmentCount = ceil(5000 / screenWidth)`
- 每段 `sourceX = i * screenWidth`
- `sliceWidth = min(screenWidth, 5000 - sourceX)`

### 6.2 子元素切片算法

- 输入：`ChildElement[]`, `Segment[]`
- 输出：`ChildSlice[]`
- 复杂度：`O(m * n)`（可按区间优化）

相交判定：
- 仅当子元素区间与段区间重叠时生成切片
- 切片宽度为区间交集长度
- 渲染左偏移为交集起点相对段起点

## 7. 部署视图

单机本地部署：
- 可执行文件（Tauri 打包产物）
- 前端静态资源内嵌
- 无外部服务依赖

跨平台建议：
- Windows 为主目标平台
- 后续可扩展到 Linux/macOS（保持 API 使用跨平台）

## 8. 非功能架构设计

### 8.1 性能
- 预计算与缓存刻度数据
- 分段与切片计算函数纯函数化，便于 memoization
- 控制组件重渲染范围（按段粒度更新）

### 8.2 可维护性
- 算法层独立文件，配套单元测试
- 组件职责单一，避免“巨型组件”
- 使用 TypeScript 类型约束输入输出

### 8.3 兼容性
- 适配不同分辨率，屏宽变化自动重算
- 高 DPI 场景下进行像素对齐优化

## 9. 异常与容错架构

- 屏幕宽度读取失败：降级默认值（如 1920）
- 输入数据异常（负宽度、越界坐标）：统一在 service 层校正/裁剪
- 渲染失败保护：关键计算异常时记录日志并回退最小可用视图

## 10. 安全与边界

当前系统以本地渲染为主，安全关注点较轻，建议：
- 最小化 Tauri 权限配置
- 不暴露不必要的系统 API
- 对未来外部输入（若接入）进行 schema 校验

## 11. 测试架构

测试分层：
- 单元测试：`segmentService`、`childSliceService`
- 组件测试：`RulerSegment`、`SegmentChildren`
- 集成测试：启动后窗口行为与全链路渲染

关键断言：
- 分段数量与位置正确
- 末段宽度裁剪正确
- 子元素跨段连续且无视觉跳变
- 大小刻度在每段中对齐正确

## 12. 可扩展路线

- 渲染升级：DOM -> Canvas/WebGL
- 数据升级：静态子元素 -> 实时广播内容流
- 交互升级：缩放、定位、标记线、主题切换
- 多屏支持：副屏渲染与窗口同步控制

## 13. 架构决策记录（ADR 简版）

- ADR-001：采用 Tauri v2 作为宿主框架（轻量、跨平台）
- ADR-002：采用 Vue3 + TS 作为前端基础（可维护、类型安全）
- ADR-003：先采用 DOM 裁剪方案（交付快、调试友好），保留 Canvas 替换能力
- ADR-004：分段按屏宽计算并纵向堆叠（严格满足需求中的显示规则）