# 架构设计

## 总体架构
```mermaid
flowchart LR
A[Incoming Webhook] --> B[FastAPI /webhook/{namespace}]
B --> C[Router]
C --> D[Targets Forwarder]
B --> E[Event Template]
E --> F[Channels Sender]
D --> G[External Webhook Targets]
F --> H[Feishu]
F --> I[WeCom]
```

## 模块分层
- 接入层：`app/main.py`（FastAPI 入口与 Webhook 接收）
- 管理后台：`app/admin.py`（端点、规则、模板与渠道的增删改查）
- 领域模型与持久化：`app/db.py`, `app/models.py`
- 规则引擎：`app/services/engine.py`（树形规则 + 动作编排）
- 通知发送：`app/services/notify.py`
- 统计与日志：`app/services/stats.py`, `app/logging.py`

## 关键接口
- `engine.process(endpoint_id, payload) -> (routed: List, notified: List)`
- `_exec_forward(target, payload) -> Result`（内部使用）
- `_exec_notify(channel, msg) -> Result`（内部使用）
- 管理接口：`/admin/*` 用于维护端点、规则树、动作、模板与渠道

## 数据契约
- 输入：示例 JSON 结构，关键字段存在于顶层与 `trans_order_info`
- 输出：`{"namespace": str, "routed": [...], "notified": [...]}`，其中：
  - `routed`：每个转发目标的执行摘要（目标名、是否成功、失败原因）
  - `notified`：每个通知渠道的执行摘要（渠道名、是否成功、失败原因）

## 异常策略
- 超时与网络错误重试；失败记录结构化日志
- 非致命错误不影响其他目标或渠道发送

## 部署与运行（概要）
- 本地直接运行：
  - 创建并激活虚拟环境（可选）
  - 执行 `pip install -r requirements.txt`
  - 启动服务：`uvicorn app.main:app --host 0.0.0.0 --port 8080`
- Docker 部署：
  - 构建镜像：`docker build -t webhook-relay .`
  - 运行容器示例：
    - `docker run -d --name webhook-relay -p 8080:8080 webhook-relay`
  - 默认使用 SQLite 数据库，路径由环境变量 `DB_PATH` 控制，默认值为 `sqlite:///./config/data.db`
  - 如需持久化，可将宿主机目录挂载到容器内 `/app/config` 目录