xsl
746b66da01
One request exercises every layer: JWT auth, quota reservation, a versioned prompt through the LLM gateway, a cost row, quota commit or refund, and the unified envelope. The trivial ping task proves the queue routing and the tk_task transitions before any real long-running task is written. Routes are mounted at the /api/v1 base path of 架构文档 §9.1; /v1/* is rewritten to it at the ASGI layer so both spellings work from one route table.
34 lines
1.4 KiB
Markdown
Executable File
34 lines
1.4 KiB
Markdown
Executable File
# `apps/` — 可部署的进程
|
||
|
||
| 目录 | 进程 |
|
||
| --- | --- |
|
||
| `api/` | FastAPI 应用：路由、依赖注入、中间件 |
|
||
| `worker/` | Celery 任务定义与四队列配置（gpu / cpu / io / beat） |
|
||
| `admin/` | 极简运营后台（占位，FR-ADM-01~05） |
|
||
|
||
## API 层的职责边界（架构 §3.1 L3）
|
||
|
||
**只做编排**：认证鉴权、参数校验、幂等、配额校验与预扣、统一响应、OpenAPI。
|
||
|
||
## 不能放什么
|
||
|
||
- **业务规则**。路由函数里出现 `if` 判断业务条件，几乎总是应该下沉到
|
||
`packages/<域>/service.py` 或 `packages/domain/`。
|
||
- **直接写 SQL 或用 ORM 查表**。走域的 `service`。
|
||
- **直接调用外部 API**。LLM 走 `packages/llm`；未来的审核、视觉、换装同理。
|
||
- 裸 `dict` 返回。所有响应必须经过 `packages.shared.response.ok()` / `fail()`。
|
||
|
||
## 契约先行（NFR-MAINT-01）
|
||
|
||
先在 `apps/api/schemas.py` 定义 Pydantic schema，再写实现。客户端类型由
|
||
OpenAPI 生成，schema 一变客户端立刻可见。
|
||
|
||
## Worker 的规矩
|
||
|
||
- 每个长耗时任务都必须落 `tk_task`，走 `packages/task` 的状态机。
|
||
不要自己维护状态字段。
|
||
- 失败必须退还配额（`billing.refund()`，FR-BILL-05）。
|
||
`apps/worker/tasks.py` 里的 `ping_task` 是形状示例。
|
||
- 队列按资源画像分：GPU 推理进 `gpu`，视觉/渲染进 `cpu`，外部调用进 `io`。
|
||
混队列会让「换装排队把报告拖慢」。
|