meteor_detection_system/meteor-edge-client/prd.md

边缘计算端：功能与职责定义

1. 核心定位与目标

边缘计算端是整个分布式网络的“眼睛”和“前线哨兵”。它是一个部署在用户现场（例如，安装在树莓派上）的、高度自动化的智能观测站。

其核心目标是：在无需人工干预的情况下，自主完成从天空监控、事件识别、数据归档到云端上报的全过程，同时保证高可靠性和低资源消耗。

2. 系统架构：模块化与事件驱动

为了实现高度的可扩展性和可维护性，边缘端应用采用模块化、事件驱动的架构。所有模块作为独立的专家运行，通过一个中央的 事件总线 (Event Bus) 进行通信，实现了最大限度的解耦。

graph TD
    subgraph "应用核心 (Core)"
        App("app<br>(应用协调器)")
        EventBus("events<br>(事件总线)")
    end

    subgraph "数据源 (Data Sources)"
        Camera("camera<br>(摄像头控制器)")
        GPS("gps<br>(GPS模块)")
        Sensors("sensors<br>(环境传感器)")
    end

    subgraph "数据处理流水线 (Processing Pipeline)"
        Detection("detection<br>(检测流水线)")
        Overlay("overlay<br>(信息叠加)")
    end

    subgraph "数据输出 (Outputs)"
        Storage("storage<br>(存储管理器)")
        Communication("communication<br>(通信管理器)")
        Streaming("streaming<br>(视频流)")
    end

    subgraph "外部接口 (External Interfaces)"
        HW["硬件<br>(摄像头, GPS, 传感器)"]
        FS["文件系统<br>(磁盘)"]
        Network["网络<br>(HTTP API, MQTT, RTSP)"]
    end

    %% 控制流
    App -- 初始化 --> Camera
    App -- 初始化 --> Detection
    App -- 初始化 --> GPS
    App -- 初始化 --> Sensors
    App -- 初始化 --> Overlay
    App -- 初始化 --> Storage
    App -- 初始化 --> Communication
    App -- 初始化 --> Streaming

    %% 数据流
    HW -- 原始数据 --> Camera
    HW -- 原始数据 --> GPS
    HW -- 原始数据 --> Sensors

    Camera -- 发布 FrameCapturedEvent --> EventBus
    GPS -- 发布 GpsStatusEvent --> EventBus
    Sensors -- 发布 EnvironmentEvent --> EventBus

    EventBus -- 订阅 FrameCapturedEvent --> Detection
    EventBus -- 订阅 FrameCapturedEvent --> Overlay
    EventBus -- 订阅 FrameCapturedEvent --> Storage
    EventBus -- 订阅 GpsStatusEvent --> Overlay
    EventBus -- 订阅 EnvironmentEvent --> Overlay

    Detection -- 发布 MeteorDetectedEvent --> EventBus

    EventBus -- 订阅 MeteorDetectedEvent --> Storage
    EventBus -- 订阅 MeteorDetectedEvent --> Communication

    Overlay -- 叠加信息到帧 --> Streaming
    Camera -- 原始帧 --> Streaming

    Storage -- 写入文件 --> FS
    Communication -- 发送数据 --> Network
    Streaming -- 推送RTSP流 --> Network

3. 各模块功能与职责详解

3.1 app (应用协调器)

• [cite_start]职责: 作为系统的“大脑”，负责初始化、协调和管理所有其他模块的生命周期 [cite: 1442]。它确保所有后台任务都能正常启动，并在应用关闭时能够优雅地退出。

3.2 events (事件总线)

• [cite_start]职责: 提供一个中央消息传递系统 [cite: 1442][cite_start]。它是整个应用的神经中枢，允许所有模块在不直接相互依赖的情况下进行通信，从而实现高度的解耦和灵活性 [cite: 1442]。

3.3 camera (摄像头控制器)

• 职责:
  • [cite_start]实时视频采集: 负责与摄像头硬件交互，以可配置的帧率（例如30 FPS）持续捕获视频帧 [cite: 1442]。
  • [cite_start]原始数据发布: 将每一帧捕获到的画面，连同一个自增的 帧号 (frame_id) 和 高精度时间戳 (timestamp)，封装成一个 FrameCapturedEvent 并立即发布到事件总线 [cite: 1442]。
  • [cite_start]环境适应性: 仅在当地日落之后和日出之前的时间段内激活摄像头进行捕捉，以节省资源并避免无效数据 [cite: 1442]。

3.4 detection (检测流水线)

• 职责:
  • [cite_start]智能分析: 这是应用的“智能”核心。它订阅事件总线上的 FrameCapturedEvent [cite: 1442]。
  • [cite_start]上下文缓冲: 在其内部维护一个环形缓冲区（Ring Buffer），用于存储最近的N帧视频以供分析 [cite: 1442]。
  • [cite_start]事件决策: 在帧缓冲区上运行一个可插拔的检测算法（MVP阶段为基于帧间亮度差异的算法），通过对比多帧的连续变化来识别潜在的流星事件 [cite: 1442]。
  • [cite_start]信号发布: 当识别出事件时，它会向事件总线发布一个全新的 MeteorDetectedEvent 事件，其中包含触发检测的关键帧号和时间戳 [cite: 1442]。

3.5 storage (存储管理器)

• 职责:
  • [cite_start]数据归档: 负责将瞬时的事件永久化存储。它同时订阅 FrameCapturedEvent 和 MeteorDetectedEvent [cite: 1442]。
  • [cite_start]录制缓冲: 通过消费 FrameCapturedEvent，在内部维护一个独立的环形缓冲区，用于“准备录制” [cite: 1442]。
  • [cite_start]事件包创建: 当监听到 MeteorDetectedEvent 时，它会根据信号中的帧号，从自己的缓冲区中提取出事件发生前后一段时间的视频帧，并将其与所有相关的元数据（GPS、传感器数据、算法中间数据等）打包成一个专属的事件目录 [cite: 1442]。
  • [cite_start]完成通知: 在成功将事件包写入本地磁盘后，它会发布一个 EventPackageArchivedEvent，通知其他模块归档已完成 [cite: 1442]。
  • [cite_start]数据清理: 实现一个基于时间的清理策略，自动删除过旧的本地事件包以管理磁盘空间 [cite: 1442]。

3.6 communication (通信管理器)

• 职责:
  • [cite_start]云端连接: 负责所有与云平台的外部通信 [cite: 1442]。
  • [cite_start]事件上传: 它订阅 EventPackageArchivedEvent。当收到这个“归档完成”的信号后，它会将本地的事件包压缩并安全地上传到云端的API端点 [cite: 1442]。
  • [cite_start]状态报告: 定期向云端发送“心跳”信号，以报告设备的在线状态 [cite: 1442]。
  • [cite_start]设备注册: 在首次启动时，执行一次性的设备注册流程，将设备的硬件ID与用户账户绑定 [cite: 1442]。

(未来扩展模块)

• [cite_start]gps & sensors: 负责从GPS模块和环境传感器（如温湿度）读取数据，并将其作为事件发布到总线 [cite: 1442]。
• [cite_start]overlay: 负责在视频帧上实时叠加时间戳、GPS坐标等信息 [cite: 1442]。
• [cite_start]streaming: 负责提供一个RTSP服务器，用于实时视频流的远程查看 [cite: 1442]。