---
name: project-structure
description: 工程目录与构建规范。用于本仓库跨模块改动时，保证边缘端与云端目录职责清晰、构建产物结构一致、部署方式一致。
---

# 工程结构规范

## 顶层职责

- `collector/`：边缘采集进程
- `configurator/`：边缘配置服务
- `cloud_server/`：云端服务
- `frontend/config_app/`：边缘前端
- `frontend/cloud_app/`：云端前端
- `foundation/`：共享 C++ 基础库
- `docs/`：通用技术文档

## 构建与产物

- 各后端模块使用 `build/` 作为构建目录
- 打包输出到 `runtime/`
- 原则：`build/` 与对应 `runtime/` 目录结构保持一致，避免运行时路径偏差

## 脚本职责

- `build.sh`：编译 + 前端构建 + 资源同步
- `run.sh`：构建后启动（必要时先停旧进程）
- `package.sh`：整体打包到 `runtime/`
- `run_collector_tests.sh`：采集端 collector 测试入口（unit / ci / all）
- `run_configurator_tests.sh`：配置端 configurator 测试入口（unit / ci / all）
- `run_cloud_tests.sh`：云端 cloud_server 测试入口（unit / 集成 / 压测 / 长稳）

## 部署约束

- 开发环境：模块独立运行、独立调试
- 生产环境：使用打包产物 + systemd 管理
- 不引入额外“总控进程”替代现有部署方式

## 命名约定

- 目录：`snake_case`
- 前端组件目录：`PascalCase`
- 文档：业务文档可中文命名，标准文件按通用约定

## 测试约定

- 每个后端子工程有独立的 `run_<子工程>_tests.sh` 脚本入口
- 各后端子工程的单元测试放在 `子工程/tests/unit/`
- 子工程相关的集成测试/压测/E2E 放在 `子工程/tests/{integration,benchmark,e2e}/`
- GTest 公共基础设施位于 `foundation/cmake/EdgeCollectorTesting.cmake`
- 测试概览文档位于 `docs/testing.md`
- 详细测试文档位于各子工程 `tests/` 目录下