# AdCloud Server

面向开发者和 coding agent 的广告云埋点与广告推送后端。使用 FastAPI 开发，依赖和虚拟环境统一由 **uv** 管理。

## HTTP Gateway

```text
HTTPS :443 (Nginx，终止 TLS)
  ├── /v1/events/*    → events 路由模块
  ├── /v1/users/*     → users 路由模块
  ├── /v1/ads/*       → ads 路由模块
  ├── /v1/identity/*  → identity 路由模块
  └── /v1/...        → 后续业务模块
                         ↓
                  FastAPI 127.0.0.1:8000
```

目前使用模块化单体：四个业务模块共用一个 FastAPI 进程和版本入口。
Nginx 为各业务域定义了独立 upstream，后续拆分服务时可以替换地址。
Gateway 保留完整路径和查询参数，不剥离 `/v1` 或业务前缀。
未知路径返回 404，不支持的 HTTP 方法返回 405。

| 路径 | 模块职责 | 当前已实现接口 |
| --- | --- | --- |
| `/v1/events/*` | 埋点事件接收与查询 | `GET /v1/events/health` |
| `/v1/users/*` | 平台用户资料管理 | `GET /v1/users/health` |
| `/v1/ads/*` | 广告管理与投放 | `GET /v1/ads/health` |
| `/v1/identity/*` | 登录、令牌与身份权限 | `GET /v1/identity/health` |

各模块健康接口用于验证路由挂载，返回 `{"status":"ok","module":"events"}` 等响应；不代表数据库或外部依赖已就绪。
当前阶段仅实现 Gateway 和模块入口，尚未实现业务写入、数据持久化、登录或鉴权。

```text
src/adcloud_server/
  main.py              # 应用工厂、CORS、系统健康接口
  schemas.py           # 公共响应模型
  api/v1/router.py     # /v1 统一入口和模块注册
  api/v1/events.py
  api/v1/users.py
  api/v1/ads.py
  api/v1/identity.py
```

增加新模块时，在 `api/v1/` 新增 `APIRouter`，并在 `router.py` 中注册前缀和 OpenAPI 标签。
若部署为独立服务，再增加对应的 Gateway upstream 和 location。

## 本地开发

```sh
uv sync --locked
uv run uvicorn adcloud_server.main:app --reload --host 127.0.0.1 --port 8000
```

- 系统健康检查：`http://localhost:8000/health`（保留 SDK 和控制台兼容）
- 模块探测：`http://localhost:8000/v1/events/health`
- API 文档：`http://localhost:8000/docs`
- OpenAPI：`http://localhost:8000/openapi.json`

默认允许来自 `http://localhost:3000`、`http://localhost:5173`、`http://localhost:5174` 的浏览器请求。
`CORS_ORIGINS` 接受逗号分隔的来源；环境配置示例见 `.env.example`。

```sh
CORS_ORIGINS=https://advertiser.example,https://developer.example uv run uvicorn adcloud_server.main:app
```

CORS 已配置写请求方法和 `Authorization`、`Content-Type`、`X-Request-ID` 请求头。
允许预检不代表相应业务端点已实现；CORS 也不代替身份认证和权限校验。

## HTTPS 入口配置

`deploy/nginx.conf.example` 是放入 Nginx `http {}` 上下文的配置模板。
替换 `server_name` 和证书文件路径，然后在目标服务器使用 `nginx -t` 检查，加载配置。
模板未在本机启动 443，也未申请或部署证书。API 文档仅通过内部 FastAPI 地址访问。

Nginx 在公网边缘重写转发头，FastAPI 只监听回环地址。目标服务器启动后端：

```sh
uv run uvicorn adcloud_server.main:app --host 127.0.0.1 --port 8000 --proxy-headers --forwarded-allow-ips 127.0.0.1
```

模板允许最大 1 MiB 请求体，连接超时 5 秒、读写超时 30 秒；可按后续埋点批量策略调整。

参考：[FastAPI 多模块路由](https://fastapi.tiangolo.com/tutorial/bigger-applications/)、[Nginx proxy_pass 路径规则](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass)。

## 检查

```sh
uv run pytest
uv run ruff check .
uv run ruff format --check .
```

提交 `uv.lock`，使用 `uv sync --locked` 复现依赖。