# Meteor Fullstack - Distributed Monitoring Network

## Overview
Meteor Fullstack 是一个覆盖边缘设备、云端 API、数据处理和 Web 前端的完整流星监测网络。仓库采用 npm workspace 管理前后端，并通过 Go、Rust 等多语言组件连接实时观测、事件验证和观测结果展示。

## System Topology
- `meteor-edge-client/`：Rust 编写的边缘客户端 CLI（命令在 `src/main.rs`），负责摄像头采集、事件检测与上传，核心运行循环位于 `src/app.rs::Application::run`。
- `meteor-web-backend/`：NestJS Web API，入口 `src/main.ts` 启动 `AppModule`，聚合认证、设备注册、事件存取、支付与指标等子模块，持久化通过 TypeORM/PostgreSQL。
- `meteor-frontend/`：Next.js 15 应用（App Router），入口 `src/app/layout.tsx`，主要页面位于 `src/app/dashboard|gallery|analysis` 等目录，使用 React Query 与自建服务交互。
- `meteor-compute-service/`：Go 处理服务，入口 `cmd/meteor-compute-service/main.go`，从 SQS 拉取事件、执行校验并写入数据库，辅以 CloudWatch 指标与健康检查。
- `infrastructure/`：Terraform 定义 S3、SQS、CloudWatch、RDS/VPC 等资源，为各服务提供统一云端环境。

## Execution Entry Points
- **边缘采集**：`meteor-edge-client/src/main.rs` 解析 CLI（`Run` 子命令），构造 `Application`，根据 `camera` 参数（例如 `sim:pattern:meteor`）覆盖配置并启动摄像头、检测、存储、心跳等控制器。
- **Web API**：`meteor-web-backend/src/main.ts` 通过 `NestFactory` 启动服务，`AppModule` 汇集 `devices`, `events`, `metrics` 等模块；Socket 网关与定时任务由 `ScheduleModule` 提供。
- **前端应用**：`meteor-frontend/src/app/page.tsx` 定义默认仪表盘；路由由 `app/` 目录自动生成，`services/` 封装 API 调用，`contexts/` 提供跨页面状态。
- **计算服务**：`meteor-compute-service/internal/processor` 中的 `Processor.Start` 协程消费 SQS 消息，配合 `internal/validation` 动态加载检测策略。

## Data Flow Summary
1. 边缘设备通过 `meteor-edge-client run --camera …` 捕获帧，`storage` 模块归档事件，`communication` 模块将打包结果上传后端。
2. NestJS 后端在 `events` 与 `devices` 模块中接收上传，写入事件表并向 SQS 推送需要进一步分析的数据。
3. Go 计算服务从 SQS 获取消息，调用验证提供者生成分析结果，再回写数据库并发送 CloudWatch 指标。
4. 前端通过 React Query 请求 NestJS API，展示仪表盘、图库与分析视图，实现实时监控闭环。

## Development Workflow
```bash
npm run install:all   # 初始化依赖
npm run dev           # 并行启动前端(3001)与后端(3000)
npm run test:fullstack
./test-setup.sh       # 启动 LocalStack + 测试数据库
```
Rust 与 Go 组件分别使用 `cargo run`, `cargo test`, `go run`, `go test ./...`；详细测试矩阵参见 `TESTING.md`。

## Testing & Verification
- 前端：Jest + Testing Library (`npm run test:frontend`)，Playwright E2E (`npm run test:e2e`).
- 后端：Jest 单元与集成测试 (`npm run test:backend`, `npm run test:integration`).
- 边缘客户端：`cargo check`、`cargo test`；模拟摄像机脚本位于 `meteor-edge-client/scripts/`。
- 组合流程：`npm run test:fullstack` 调用前后端及集成测试，配合 `docker-compose.test.yml`。

## Infrastructure & Operations
- Terraform 输出的 S3/SQS/CloudWatch 资源需同步到 `.env` 与部署配置，细节参见 `infrastructure/README.md`。
- Pino + CloudWatch 提供日志链路，`metrics` 模块和 Go `metrics` 包推送业务指标。
- CI/CD 可利用 `meteor-edge-client/.github/workflows/` 示例以及 repo 根目录的 npm scripts。

## Additional Documentation
- 贡献者指南：`AGENTS.md`
- 测试细节：`TESTING.md`
- 边缘摄像模拟：`meteor-edge-client/CAMERA_SIMULATION_USAGE.md`
- 基础设施：`infrastructure/README.md`