houhuan
2bc7460f1f
- 添加FastAPI应用基础结构，包括主入口、路由和模型定义
- 实现Webhook接收端点(/webhook/{namespace})和健康检查(/health)
- 添加管理后台路由和模板，支持端点、目标、渠道和模板管理
- 包含SQLite数据库模型定义和初始化逻辑
- 添加日志记录和统计服务
- 包含Dockerfile和配置示例文件
- 添加项目文档，包括设计、流程图和验收标准
49 lines
2.3 KiB
Markdown
49 lines
2.3 KiB
Markdown
# 任务名称
|
||
|
||
Webhook中继与通知系统（Docker化）
|
||
|
||
## 背景与目标
|
||
- 统一接收外部Webhook，按规则路由到目标端点，并生成通知消息推送至飞书/企业微信。
|
||
- 基于配置可扩展，支持新增目标、remark映射与事件模板。
|
||
|
||
## 业务范围
|
||
- 接收JSON负载，至少包含 `remark`、`event_define_no`、`trans_amt`、`trans_order_info.cash_resp_desc`、可选 `actual_ref_amt`。
|
||
- 路由策略：按 `remark` 映射至一个或多个目标Webhook；若无匹配使用 `default_targets`。
|
||
- 通知策略：按 `event_define_no` 模板生成文本，支持多渠道并发推送。
|
||
|
||
## 技术范围
|
||
- Python 3.12、FastAPI、httpx
|
||
- Docker 容器化；SQLite 持久化，模型定义见 `app/db.py`
|
||
- 管理后台 `/admin` 维护端点、规则、动作、模板与通知渠道
|
||
- 结构化日志；失败重试（在转发逻辑中可扩展）；请求与分发记录持久化
|
||
|
||
## 输入与输出
|
||
- 输入：`POST /webhook/{namespace}` JSON
|
||
- 输出：200 返回路由与通知结果结构
|
||
|
||
## 验收标准
|
||
- 能正确解析示例 JSON 并生成消息，包含商户名、支付方式、金额、状态与日期，例如：`【某商户】支付宝 收款 5.50 元，状态：成功，日期：20251220`
|
||
- `remark=imcgcd03` 时转发至配置第3个目标；`remark=imcgcd02` 时至第2个目标
|
||
- 同时推送至飞书与企业微信（若配置存在多个机器人则全部发送）
|
||
- 失败记录与重试可配置（次数与退避）
|
||
|
||
## 部署与运行方式（概要）
|
||
- 运行模式：
|
||
- 作为独立 FastAPI 服务运行，暴露 `POST /webhook/{namespace}` 与 `/admin` 管理界面
|
||
- 通过 Docker 镜像部署到服务器
|
||
- 最低运行环境：
|
||
- Python 3.12 或兼容的 Docker 运行时
|
||
- 对外开放的 HTTP 端口（默认 8080）
|
||
- 配置与数据：
|
||
- 数据库：默认 `sqlite:///./config/data.db`，可通过环境变量 `DB_PATH` 调整
|
||
- 规则、模板、渠道均通过 Web 管理后台写入数据库，无需修改代码或 YAML
|
||
|
||
## 边界与不做事项
|
||
- 不实现目标端点的认证协议，默认匿名POST；可通过配置扩展签名
|
||
- 不提供长期持久幂等存储，默认进程内短期去重
|
||
|
||
## 风险与约束
|
||
- 目标Webhook不可达导致延迟；通过重试与超时保护
|
||
- 通知渠道限流；并发可控与错误日志
|
||
|