hivecore_robot_system/README.md

# hivecore_robot_system

面向机器人系统的企业级 ROS 2 基础设施工作空间。

## 1. 简介

`hivecore_robot_system` 是 HiveCore 机器人系统的核心 ROS 2 工作空间，提供一套高质量、生产就绪的基础设施组件。

本仓库采用 **monorepo** 结构，每个功能领域以独立子目录的形式进行组织，所有组件统一由顶层 `colcon` 工作空间管理，可按需选包编译。各包的详细说明从第 5 章起依次展开，每个顶层包独占一章。

当前已包含的软件包：

| 软件包 | 所属模块 | 说明 |
| :--- | :--- | :--- |
| `hivecore_logger` | 日志系统 | 面向 C++/Python 业务节点的异步非阻塞日志 SDK |
| `hivecore_log_manager` | 日志系统 | 集中式日志管理服务：磁盘配额、压缩、动态调级 |
| `hivecore_logger_interfaces` | 日志系统 | ROS 2 服务接口定义（`SetLogLevel.srv`） |
| *(更多组件持续添加中)* | — | — |

## 2. 系统要求

以下为整个工作空间的通用基础要求，各组件若有额外依赖，请参阅对应子目录的文档。

| 项目 | 要求 |
| :--- | :--- |
| 操作系统 | Ubuntu 20.04 / 22.04（或其他 POSIX Linux） |
| ROS 2 | Foxy / Humble |
| C++ 编译器 | GCC 9+，支持 C++17 |
| CMake | 3.14+ |
| Python | 3.8+ |

## 3. 快速开始

### 3.1 克隆与初始化

```bash
git clone <repo-url> hivecore_robot_system
cd hivecore_robot_system
```

### 3.2 安装通用依赖

```bash
sudo apt-get update && sudo apt-get install -y \
    build-essential cmake \
    python3-pip
```

各组件的额外依赖请参阅对应子目录的 README 或 `USER_GUIDE.md`。

### 3.3 编译工作空间

编译整个工作空间中的所有组件：

```bash
colcon build --symlink-install
source install/setup.bash
```

如仅需编译指定组件：

```bash
colcon build --packages-select <package_name> [<package_name> ...]
source install/setup.bash
```

各包需要选择哪些包名，请参阅对应包章节的说明。

### 3.4 验证安装

```bash
# 列出工作空间内所有已注册的 ROS 2 接口
ros2 interface list | grep hivecore

# 查看已安装的可执行命令
ros2 pkg executables | grep hivecore
```

## 4. 工程目录结构

本仓库以功能模块为单位组织子目录，每个模块是独立的 ROS 2 包（或包组），可单独编译和部署。

```text
hivecore_robot_system/
├── hivecore_logger/        # 【日志系统】详见第 5 章
├── <future_module>/        # 【预留】后续新增功能模块
├── build/                  # colcon 构建输出（不纳入版本管理）
├── install/                # colcon 安装输出（不纳入版本管理）
└── log/                    # colcon 构建日志（不纳入版本管理）
```

**新增模块约定**：每个新模块在仓库根目录下创建独立子目录，建议包含：

```text
<module_name>/
├── README.md         # 模块说明
├── USER_GUIDE.md     # 安装与使用手册
├── ros2/             # ROS 2 接口包及示例（如有）
├── examples/         # 接入示例
└── scripts/          # 验证脚本
```

## 5. hivecore_logger — 日志系统

面向 C++/Python 业务节点的企业级异步非阻塞日志基础设施。

### 5.1 目录结构

```text
hivecore_logger/
├── cpp/                    # C++ 日志 SDK（基于 spdlog，异步非阻塞）
├── python/                 # Python 日志 SDK（基于 QueueHandler）
├── manager/                # 集中式日志管理模块（独立部署或 ROS 2 节点）
├── ros2/
│   ├── hivecore_logger_interfaces/   # ROS 2 接口包
│   └── examples/                     # ROS 2 最小调用示例
├── examples/               # 外部业务节点接入示例（C++/Python）
└── scripts/                # 一键验证与演示脚本
```

### 5.2 核心特性

| 特性 | 说明 |
| :--- | :--- |
| 异步非阻塞日志 | C++/Python SDK 均采用异步队列，极低业务侧开销 |
| 热更新日志级别 | Python SDK 支持 inotify 零 CPU 占用热更新，无需重启节点 |
| 日志限流与条件宏 | Python SDK 原生支持 `throttle`（限流）与 `expression`（条件）扩展 |
| 集中式管理 | 统一的磁盘配额控制、后台异步压缩、节点级文件轮转 |
| 安全性 | 防路径穿越攻击，日志目录强制沙箱隔离 |
| 双调级入口 | 支持 HTTP REST 与 ROS 2 Service 两种运行时动态调级方式 |

### 5.3 快速编译与验证

**一键编译、安装并启动 Manager（发行版）：**

```bash
DEPLOY_MODE=prod bash hivecore_logger/scripts/build_install_and_start_manager.sh
```

该脚本依次执行：编译 SDK（C++ + Python + ROS 2 接口）→ 安装至 `/opt/hivecore/` → 启动日志管理服务。

如需仅编译和安装 SDK，不启动服务：

```bash
DEPLOY_MODE=prod bash hivecore_logger/scripts/build_install_sdk.sh
```

验证服务健康状态：

```bash
bash hivecore_logger/scripts/check_manager_health_prod.sh
```

其他常用脚本：

| 脚本 | 用途 |
| :--- | :--- |
| `scripts/start_manager.sh` | 单独启动日志管理服务 |
| `scripts/stop_manager.sh` | 停止日志管理服务 |
| `scripts/check_manager_health_prod.sh` | 检查发行版服务健康状态 |
| `scripts/run_all_checks.sh` | 运行全量验证（单元测试 + 集成检查） |
| `scripts/run_manager_demo.sh` | 运行演示流程 |

### 5.4 文档

| 文档 | 链接 |
| :--- | :--- |
| 模块说明 | [hivecore_logger/README.md](hivecore_logger/README.md) |
| 安装与使用手册 | [hivecore_logger/USER_GUIDE.md](hivecore_logger/USER_GUIDE.md) |
| 测试报告 | [hivecore_logger/TEST_REPORT.md](hivecore_logger/TEST_REPORT.md) |

---

<!-- ============================================================
  【新增包模板】
  当有新的顶层包加入本仓库时，参照以下模板在此处追加一章，
  并同步更新第 1 章的软件包列表与第 4 章的目录结构。

## N. <package_name> — <功能领域>

<一句话描述该包的定位与用途。>

### N.1 核心特性

| 特性 | 说明 |
| :--- | :--- |
| ...  | ...  |

### N.2 文档

| 文档 | 链接 |
| :--- | :--- |
| 模块说明        | [<package_name>/README.md](<package_name>/README.md) |
| 安装与使用手册  | [<package_name>/USER_GUIDE.md](<package_name>/USER_GUIDE.md) |

============================================================ -->

## 6. 许可证

© HiveCore. All rights reserved.