# SageAPI

独立 API 服务器模块，为外部客户提供余额查询、记账、用户/定价查询等 RESTful 接口。

## 架构

SageAPI 是独立于 Sage 的 API 服务器，支持多实例部署和水平扩展：

- 每个实例独立运行：自己的数据库连接池、内存缓存、同步调度器
- 多实例共享同一 MySQL 数据库，数据天然同步
- 增量同步模式：基于变更时间戳和事件驱动的混合策略
- 通过 dapi 提供认证，uapi 保障数据交互安全
- 纯 RESTful API 服务（无 Web 界面，除管理后台）

## 目录结构

```
sageapi/
├── sageapi/                    # Python 包
│   ├── __init__.py             # 空文件（模块规范）
│   ├── init.py                 # 模块初始化：ServerEnv 注册
│   ├── config.py               # 配置管理
│   ├── router.py               # API 路由注册
│   ├── auth/                   # 认证模块
│   │   ├── dapi_auth.py        # dapi 认证中间件
│   │   └── uapi_sign.py        # uapi 签名验证
│   ├── sync/                   # 数据同步模块
│   │   ├── base_sync.py        # 同步基类
│   │   ├── user_sync.py        # 用户数据同步
│   │   ├── pricing_sync.py     # pricing 数据同步
│   │   ├── uapi_sync.py        # uapi 数据同步
│   │   └── llmage_sync.py      # llmage 数据同步
│   ├── cache/                  # 缓存层
│   │   └── cache_manager.py    # 进程内存 LRU 缓存管理
│   ├── api/                    # API 业务逻辑
│   │   ├── balance.py          # 客户余额查询
│   │   ├── accounting.py       # 记账接口
│   │   ├── users.py            # 用户查询
│   │   ├── pricing.py          # pricing 查询
│   │   └── health.py           # 健康检查
│   └── utils/                  # 工具函数
│       ├── http_client.py      # 上游 HTTP 客户端
│       └── crypto.py           # 加解密工具
├── wwwroot/                    # 前端（管理界面）
├── models/                     # 数据库表定义
├── json/                       # CRUD 定义
├── init/data.json              # 初始化数据
├── conf/config.yaml            # 运行配置
├── pyproject.toml
├── build.sh
└── README.md
```

## API 端点

| 方法 | 路径 | 描述 | 认证 |
|------|------|------|------|
| GET | /api/v1/health | 健康检查 | 无 |
| GET | /api/v1/balance | 客户余额查询 | dapi |
| POST | /api/v1/accounting | 创建记账记录 | dapi |
| GET | /api/v1/accounting | 查询记账记录 | dapi |
| GET | /api/v1/users | 用户查询 | dapi |
| GET | /api/v1/pricing | 定价查询 | dapi |

## 配置

配置文件位于 `conf/config.yaml`。支持环境变量覆盖，命名规则为 `SAGEAPI_<SECTION>_<KEY>`：

```bash
export SAGEAPI_DATABASE_HOST=10.0.0.1
export SAGEAPI_UPSTREAM_DAPI_KEY=your_key
export SAGEAPI_UPSTREAM_DAPI_SECRET=your_secret
```

## 构建

```bash
bash build.sh
```

## 模块注册

在 Sage 启动时，`load_sageapi()` 函数自动注册所有公共函数到 `ServerEnv`，使它们在 dspy 脚本中可访问。