xsl
140a63effa
id_session 落地：opaque refresh（token_urlsafe(48)）+ sha256 哈希存储 + 一次性轮换（旧行撤销与新行同一事务）+ logout 幂等撤销 + 已撤销重放检测 告警（V1 不做家族连坐）；错误码 40103/40104/40105 接入。新增 POST /auth/refresh、POST /auth/logout；dev-token 扩展为双令牌，旧字段 access_token/token_type/expires_in/user_id 原名保留，新增 refresh_token/refresh_expires_in（smoke.sh 不受影响）。 测试：tests/unit/test_refresh_tokens.py 覆盖 token 长度/字符域/唯一性、 哈希稳定性与不可逆（7 例，不连网不连库）；tests/integration/ test_auth_refresh.py 覆盖轮换后新 access 可调 /quota、旧 refresh 二次 使用 40105、logout 后失效 40105、伪造 40103、TTL=0 过期 40104（5 例）。 门禁全绿：ruff check/format、mypy 两段、lint-imports 4 契约、 单测 176 通过、集成 8 通过。 偏差说明：1) SessionIssued 较任务文档字段清单增加 user_id —— /auth/refresh 换发 access JWT 必须知道用户，opaque refresh 本身不携带 信息，只能随签发结果带回；2) 过期分支「顺手落库 revoked=true」在 HTTP 路径会随 401 的统一回滚一起丢失（仅事务内标记，已注释说明，不影响判定 语义）；3) repo 撤销用 SELECT FOR UPDATE + ORM 变更而非 UPDATE rowcount —— 对齐 billing.repo 现行模式，且 rowcount 在 mypy 下类型 不可用。
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。 混队列会让「换装排队把报告拖慢」。