总体架构

架构概览

开放接口作为艾恋相亲 SaaS 平台的第三层路由体系，与 C 端（/api/v1/）和后台（/admin/）并列，专为内部系统间数据互通设计。

[公司内部系统A]  ──HMAC签名──┐
[公司内部系统B]  ──HMAC签名──┼──> [/api/open/v1/*] ──> [FastAPI 后端]
[公司内部系统C]  ──HMAC签名──┘         │
                                       ├── OpenAPIAuth 依赖（签名验证）
                                       ├── RateLimiter（按 client 限流）
                                       ├── AuditLog（调用审计）
                                       ├── Sanitizer（脱敏，可选）
                                       └── 业务 Service 层（复用现有逻辑）

[FastAPI 后端]  ──Webhook推送──> [内部系统A/B/C]（事件通知）

路由前缀：/api/open/v1/

与现有认证体系的关系

维度	C端 (/api/v1/)	后台 (/admin/)	开放接口 (/api/open/v1/)
认证方式	JWT Bearer Token	JWT Bearer Token	HMAC 签名
身份标识	终端用户	管理员	内部系统（应用级）
权限模型	角色+认证+会员	RBAC	接口级权限白名单
限流策略	按 IP	按 IP	按 app_key
HTTP 状态码	统一返回 200	统一返回 200	标准 HTTP 状态码

文件结构

ailian-api/app/
├── models/
│   └── open_api.py              # OpenApiClient, OpenApiCallLog 模型
├── schemas/
│   └── open_api.py              # 请求/响应 Schema（含字段映射转换）
├── services/
│   ├── open_api.py              # 开放接口业务逻辑
│   └── open_api_webhook.py      # Webhook 事件推送服务
├── api/
│   └── open/
│       ├── __init__.py          # 路由汇总
│       ├── auth.py              # 签名认证依赖 + 权限校验
│       ├── audit.py             # 调用审计日志中间件
│       ├── guest.py             # 嘉宾相关接口
│       ├── match.py             # 匹配相关接口
│       ├── company.py           # 公司相关接口
│       ├── membership.py        # 会员相关接口
│       ├── activity.py          # 活动相关接口
│       └── stats.py             # 数据统计接口
├── core/
│   ├── dependencies.py          # get_open_api_client() 薄封装
│   └── open_api_exceptions.py   # 自定义异常类 + 异常处理器
└── utils/
    ├── signature.py             # HMAC 签名工具函数
    ├── client_ip.py             # 客户端 IP 获取工具
    ├── secret_encrypt.py        # AES-256-GCM 加解密工具
    └── open_api_rate_limit.py   # Redis 滑动窗口限流

实施路线

阶段	内容
Phase 1	数据模型 + 迁移 + 签名认证 + 限流 + 审计中间件 + 健康检查
Phase 2	嘉宾管理 + 匹配管理开放接口（含批量、图片上传、导入）
Phase 3	公司/会员/活动管理开放接口
Phase 4	Webhook 事件推送服务
Phase 5	数据统计接口 + Python SDK + 对接文档
Phase 6	管理后台 — 客户端管理 + 调用日志 + 统计面板