Add versioned HTTP gateway routing by business domain

README.md

@@ -2,26 +2,86 @@
 
 面向开发者和 coding agent 的广告云埋点与广告推送后端。使用 FastAPI 开发，依赖和虚拟环境统一由 **uv** 管理。
 
-当前为开发脚手架，提供健康检查与 API 文档；埋点与广告推送功能待实现。
+## 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
+uv sync --locked
 uv run uvicorn adcloud_server.main:app --reload --host 127.0.0.1 --port 8000
 ```
 
-- 健康检查：`http://localhost:8000/health`
+- 系统健康检查：`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:3000`、`http://localhost:5173`、`http://localhost:5174` 的浏览器请求。
+`CORS_ORIGINS` 接受逗号分隔的来源；环境配置示例见 `.env.example`。
 
 ```sh
-CORS_ORIGINS=https://your-frontend.example uv run uvicorn adcloud_server.main:app
+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
@@ -30,4 +90,4 @@ uv run ruff check .
 uv run ruff format --check .
 ```
 
-提交 `uv.lock`，在其他电脑使用 `uv sync --locked` 复现依赖。
+提交 `uv.lock`，使用 `uv sync --locked` 复现依赖。