AdCloud Server
面向开发者和 coding agent 的广告云埋点与广告推送后端。使用 FastAPI 开发，依赖和虚拟环境统一由 uv 管理。
HTTP Gateway
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 和模块入口，尚未实现业务写入、数据持久化、登录或鉴权。
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。
本地开发
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。
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 只监听回环地址。目标服务器启动后端：
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 多模块路由、Nginx proxy_pass 路径规则。
检查
uv run pytest
uv run ruff check .
uv run ruff format --check .
提交 uv.lock，使用 uv sync --locked 复现依赖。