chongming-config/README.md

# 配置文件说明

本目录存放应用的 TOML 配置文件，分为三层：应用主配置、Worker 注册配置、端点路由配置。

---

## 文件总览

```text
config/
├── zenoh_config.json5                  # Zenoh 会话配置（JSON5 格式）
└── workers/
    ├── config.toml                     # Worker 插件加载列表
    ├── auth/                           # 鉴权插件
    │   ├── config.toml                 # 分组配置（路由前缀、默认值）
    │   ├── register.toml               # 用户注册
    │   ├── login.toml                  # 登录
    │   ├── me.toml                     # 获取用户信息
    │   ├── change_password.toml        # 修改密码
    │   └── update_profile.toml         # 更新资料
    ├── doubao/                         # 豆包视觉理解插件
    │   ├── config.toml
    │   └── analyze.toml
    ├── aibox_sophon_adapter/           # AI Box 设备监控插件
    │   ├── config.toml
    │   ├── board_ping.toml             # 设备心跳
    │   ├── list_devices.toml           # 设备列表
    │   ├── get_device.toml             # 设备详情
    │   ├── get_offline_devices.toml    # 离线设备
    │   ├── get_alarm.toml              # 告警详情
    │   └── list_alarms.toml            # 告警列表
    └── example/                        # 示例插件
        ├── config.toml
        ├── add.toml
        ├── subtract.toml
        ├── multiply.toml
        ├── divide.toml
        └── count.toml
```

> **注意**：应用主配置 `config.toml` 位于项目根目录，不在本 `config/` 目录下。

---

## 1. 应用主配置（根目录 `config.toml`）

定义应用全局设置：环境、服务器、日志、安全、缓存、MQTT 等。

### 主要节

| 节                           | 说明                                                                                                  |
| ---------------------------- | ----------------------------------------------------------------------------------------------------- |
| `[default]`                  | 应用元信息：`app.name`, `app.version`, `app.description`, `app.debug`, `env`, `prefix`, `upload_path` |
| `[zenoh]`                    | Zenoh 配置：`json5_path` 指向 Zenoh 会话配置文件                                                      |
| `[scheduler]`                | 任务调度器：`job_store_path`                                                                          |
| `[cache]`                    | 缓存：`cache_store_path`                                                                              |
| `[security]`                 | JWT 安全：`secret_key`, `algorithm`                                                                   |
| `[development]`              | 开发环境配置（server、logging、cors、mqtt）                                                           |
| `[production]`               | 生产环境配置                                                                                          |
| `[plugins_worker]`           | 插件 Worker 注册配置路径                                                                              |
| `[pyinstaller_build_import]` | PyInstaller 打包时的隐式导入声明                                                                      |

### 开发环境配置示例

```toml
[development]
debug = true
env = "development"

[development.server]
host = "0.0.0.0"
port = 8000
reload = true
access_log = false

[development.logging]
file = "logs"
level = "DEBUG"
format = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

[development.cors]
allow_origins = ["*"]
allow_methods = ["*"]
allow_headers = ["*"]
allow_credentials = true

[development.mqtt]
enabled = true
host = "0.0.0.0"
port = 1883
```

---

## 2. Worker 加载配置 (`workers/config.toml`)

定义哪些插件被加载及运行时参数。每个插件一个 `[[workers]]` 数组项。

```toml
[[workers]]
type = "auth"                        # 插件类型名
module = "plugins.auth"              # Python 模块路径
factory = "create_workers"           # 工厂函数名
cleanup = "cleanup"                  # 清理函数名（可选）
count = 3                            # Worker 副本数

[workers.config]
type = "auth"
data_dir = "./data"                  # 插件自定义配置
```

### 字段说明

| 字段               | 必填 | 说明                                                 |
| ------------------ | ---- | ---------------------------------------------------- |
| `type`             | ✅   | 插件类型名，需与 `config/workers/<type>/` 目录名一致 |
| `module`           | ✅   | Python 模块导入路径                                  |
| `factory`          | ✅   | 工厂函数名，用于创建 Worker 实例                     |
| `cleanup`          | ❌   | 清理函数名，插件卸载时调用                           |
| `count`            | ✅   | Worker 副本数（并行处理请求数）                      |
| `[workers.config]` | ❌   | 传递给插件的自定义配置字典                           |

---

## 3. 分组配置 (`workers/<type>/config.toml`)

每个插件目录下的 `config.toml` 定义该插件所有路由的公共默认值。

```toml
[worker]
name = "example"
version = "0.1.0"
description = "示例插件"
defaults = { timeout = 3.0, auth_required = false, cacheable = true, internal = false }

[worker.registration]
router_prefix = "/calc"     # 所有路由的统一前缀
tags = ["example"]          # OpenAPI 分组标签
```

### 字段说明

| 字段                     | 说明                                        |
| ------------------------ | ------------------------------------------- |
| `defaults.timeout`       | 默认超时时间（秒）                          |
| `defaults.cacheable`     | 端点结果是否默认缓存                        |
| `defaults.auth_required` | 端点是否默认需要 JWT 鉴权                   |
| `defaults.internal`      | 端点是否默认仅内部调用（不注册 HTTP 路由）  |
| `router_prefix`          | 路由前缀，如 `/calc` → 完整路径 `/calc/add` |
| `tags`                   | OpenAPI 文档分组标签                        |

---

## 4. 端点配置 (`workers/<type>/<operation>.toml`)

每个操作一个 TOML 文件，支持 `[GET]`、`[POST]`、`[MQTT]` 三种节类型。

```toml
# add.toml — 每个方法节独立定义

[GET]
summary = "加法运算（GET）"
docstring = "通过 URL 参数执行加法运算"
params = ["a: float", "b: float"]
cacheable = true
auth_required = false
timeout = 5.0
internal = false

[GET.response_model]
result = { type = "float", required = true }
operation = { type = "str", default = "add" }
timestamp = { type = "float", required = false, default = 0.0 }

[POST]
summary = "加法运算（POST）"
params = ["a: float", "b: float"]
auth_required = true

[POST.response_model]
result = { type = "float", required = true }

[MQTT]
summary = "加法运算（MQTT）"
params = ["a: float", "b: float"]
```

### 端点字段

| 字段            | 类型        | 默认值                   | 说明                                                 |
| --------------- | ----------- | ------------------------ | ---------------------------------------------------- |
| `summary`       | `str`       | —                        | 端点描述，显示在 OpenAPI 文档                        |
| `docstring`     | `str`       | —                        | 详细说明（可选）                                     |
| `params`        | `list[str]` | `[]`                     | 参数列表，格式 `"name: type"`                        |
| `cacheable`     | `bool`      | `defaults.cacheable`     | 结果是否可缓存                                       |
| `auth_required` | `bool`      | `defaults.auth_required` | 是否需要 JWT 鉴权                                    |
| `timeout`       | `float`     | `defaults.timeout`       | RPC 超时（秒）                                       |
| `internal`      | `bool`      | `false`                  | 设为 `true` 则只允许内部 Zenoh RPC，不注册 HTTP 路由 |

### 响应模型字段

```toml
[GET.response_model]
required_field = { type = "str", required = true }
optional_field = { type = "int", required = false, default = 0 }
```

支持的 `type` 值：

| TOML 类型          | Python 类型      |
| ------------------ | ---------------- |
| `str` / `string`   | `str`            |
| `int` / `integer`  | `int`            |
| `float` / `number` | `float`          |
| `bool` / `boolean` | `bool`           |
| `dict`             | `dict[str, Any]` |
| `list[type]`       | `list[type]`     |
| `Optional[type]`   | `Optional[type]` |

---

## 修改配置后

修改任何 TOML 配置后，**必须重新生成 Pydantic 模型**：

```bash
uv run python -m chongming.scripts.gen_models
```

该命令扫描 `config/workers/*/` 下所有 `.toml` 文件，自动更新 `src/plugins/*/models/pydantic.py`。

---

## 配置层级与优先级

```
config.toml (全局)
  └─ workers/config.toml (插件注册)
       └─ workers/<type>/config.toml (分组默认值)
            └─ workers/<type>/<op>.toml (端点覆盖)
```

每层可覆盖上层默认值，端点级字段 (`timeout`, `cacheable`, `auth_required`, `internal`) 优先级最高。