xsl
ecdfbb64c3
POST /quota/tasks/{task_key}/claim：配置驱动任务注册表、
grant_bonus 纯域函数、ledger 幂等键防重、task_bonus_max 封顶（FR-BILL-03/04）。
实现：packages/domain/billing/quota.py 新增 BonusDecision/grant_bonus（mypy strict，
恰好到顶允许、超一格整体拒绝）、grant_idempotency_key、PERIOD_TYPES；
packages/billing/service.py 新增 claim_task_bonus（幂等快捷路径 → 行锁 → 封顶判定
→ 同事务更新 bonus_granted 并写 system_grant 流水，delta=0 且 balance_after 按
remaining 口径；IntegrityError 并发兜底回滚为 40910）；响应模型 TaskBonusClaimResponse
放新建的 packages/billing/schemas.py；路由挂在 apps/api/routers/quota.py，
rules 由 settings.task_bonus_rules 注入（amount 为占位值，产品定稿后改 env）。
测试：新增单测 11 个（封顶边界、amount<=0、不动 used、hard_cap 独立生效、
默认规则形状与 env 覆盖通路）；新增集成 4 个（领取+重复 40910+纯 DB 流水断言、
五类任务全部到账、未知任务 40410、amount=11>max=10 → 40310 且无新流水）。
门禁全绿：ruff check / ruff format --check / mypy 两段 / lint-imports；
单测 180 passed，集成 7 passed。
偏差说明：1) 任务文档提到的 BillingService._load_rule 实际名为 _require_rule，
直接复用现有助手；2) packages/billing/repo.py 无需新增函数（现有
get_ledger_by_idempotency_key/lock_or_create_quota/add_ledger 已覆盖本任务）；
3) 文档设想的「TASK_BONUS_RULES_JSON 空值容错」经 env 源实测不成立——
pydantic-settings 对 dict 字段先做 JSON 解码，空白字符串在 Settings 构造时即
报错（共享校验器/config.py 属禁改，未动）；单测改为覆盖受支持的空配置形态 "{}"。
21 lines
987 B
Python
21 lines
987 B
Python
"""billing 域对外响应模型（FR-BILL-03 任务奖励）.
|
||
|
||
``apps/api/schemas.py`` 是全局共享契约文件，本轮并行开发禁改；billing 新增
|
||
接口的响应模型放本包，由路由层装配进 ``ok(...)`` 信封。字段口径与
|
||
NFR-MAINT-01「契约先行」一致：客户端类型从 OpenAPI 生成。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from pydantic import BaseModel, Field
|
||
|
||
|
||
class TaskBonusClaimResponse(BaseModel):
|
||
"""``POST /quota/tasks/{task_key}/claim`` 的 data 载荷（FR-BILL-03）."""
|
||
|
||
task_key: str = Field(max_length=64, description="任务标识，如 sign_in")
|
||
quota_key: str = Field(max_length=64, description="奖励落入的额度种类")
|
||
amount: int = Field(description="本次发放数额（当前为占位值，正式数值由产品定稿后改配置）")
|
||
bonus_granted: int = Field(description="本周期累计已获得的任务奖励")
|
||
remaining: int = Field(description="发放后该额度的剩余次数")
|