xsl
a4d59aca30
把单一日预算熔断升级为架构 §13.3 的四档分级降级（T-P1-25b / NFR-COST-02）：
- budget.py：新增 BudgetTier 配置模型与档位判定（current_tier/tier_name/
blocked_scenes）。阈值相对 LLM_DAILY_BUDGET_CENTS：warn ≥60% 只告警；
degrade_secondary ≥80% 拒 hd_export/report_regen；degrade_generation ≥90%
追加拒 hairstyle/tryon；block_all ≥100% 拒全部非 critical、allow 名单
（默认 agent_chat）放行。高档位 blocked 取「截至当前档的并集」（架构原文
「追加拒绝」）。critical 场景全档豁免但照常计成本。
- 手动 override：Redis 键 llm:budget:override（值 "1"~"4"），优先于成本水
位，读不到/非法则忽略；set_override TTL 到当日 UTC+8 24 点，跨预算日必然
失效。CostCounter 协议相应增加 set/delete。
- 指标：Gauge llm_budget_tier + Counter llm_budget_blocked_total{scene}
挂到共享 REGISTRY 随 /metrics 暴露；档位上升沿只告警一次
（budget_tier_raised，实例内记 last_tier）。
- errors.py 新增 SceneDegradedError（tier2/3 拒绝）；gateway.py 调用点换成
ensure_scene_allowed（保留 ensure_within_budget 兼容入口）；agent.py 映射
LLM_SCENE_DEGRADED(60006)；100% 档维持 DailyBudgetExceededError/60003 语义。
- 单测：新增 tests/unit/test_tiered_budget.py（27 例：四档边界、各档放行/
拒绝、critical 豁免、override 加严/放宽/非法值/TTL、配置驱动）。
- 集成：tests/integration/test_vertical_slice.py 新增用例——预算 1 分 +
block_all allow 清空 + Redis 注入当日成本，POST /agent/chat 返回 60003，
断言 bl_ledger 中 consume(refunded,-1)+refund(committed,+1) 净和为 0，
覆盖「reserve 之后才熔断 → refund」路径；fixture 重构为共享
FakeProvider/fake_client，断言语义未弱化。
门禁：ruff check/format、mypy（packages/llm strict + 其余包）、lint-imports、
单测 196 passed、集成 4 passed。
偏差说明：
1. tests/unit/test_gateway.py 的 test_daily_budget_rejects_non_critical_
scenes_before_spending 把被测场景 AGENT_CHAT 换成 REPORT_COPY（test_daily_
budget.py 同用例换 tryon）：block_all 档默认 allow=["agent_chat"]（架构
「仅保留纯文本对话」）后 agent_chat 在 100% 档不再被拒，原场景选择与新
语义冲突；断言本身（进 provider 前被拒）未弱化。
2. 集成测试的 block_all 档配置为 blocked="*"+allow=[]（文档示例为
blocked=["agent_chat"]）：后者按档位规则会走 SceneDegradedError/60006，
前者才能按设计走既有 60003 语义（文档允许二者取其一且"按上面设计应为
60003"）。
packages/ — 业务域与能力包
架构 §3.2：单体不等于混乱。这里的每个子目录都是一个边界，越界会被 CI 拦下。
目录含义
| 包 | 类型 | 内容 |
|---|---|---|
domain/ |
纯逻辑层 | 领域模型与业务规则。无 IO、无框架、可纯单测 |
shared/ |
基础设施 | 配置、日志、错误码、统一响应、DB、Redis、可观测 |
llm/ |
AI 能力 | LLM 网关（已实现） |
retrieval/ rules/ memory/ |
AI 能力 | 混合检索 / 规则引擎 / 记忆系统（占位） |
compliance/ |
业务域 | 统一合规出口（占位，CR-05/CR-06） |
identity/ billing/ task/ agent/ |
业务域 | 已有实现 |
profile/ report/ tryon/ kb/ notify/ wardrobe/ |
业务域 | 占位 |
每个业务域包的标准结构：
packages/<域>/
├─ __init__.py
├─ README.md 这个域负责什么、不负责什么
├─ service.py 对外唯一入口。其他域只能调这里
└─ repo.py SQL。只有本域可以 import
硬性规则（由 make importlint 机器校验）
- 禁止跨域直接查表。要用别的域的数据，调它的
service，不要 import 它的repo，更不要在自己的 SQL 里 JOIN 别人的表。表名的域前缀（id_/bl_/tk_/ …）就是为将来拆库预留的边界。 packages/domain/必须保持纯净。不许 importfastapi、sqlalchemy、httpx、redis、celery，也不许 importpackages/shared。放不进去说明 它不是领域逻辑，是应用逻辑，应该待在service.py。compliance不得依赖任何业务域。它必须能被任何模块安全调用。identity不得依赖任何其他业务域。登录链路不能被业务拖累。- AI 能力包（
llm/retrieval/rules）不得依赖业务域，也不得 importapps。它们要能在 V2 原样拆成独立服务。
加一个新业务域时
- 建目录，写
README.md说明职责与不负责的事。 - 在
pyproject.toml的[tool.importlinter]契约里把它加进相应的layers/forbidden_modules列表 —— 新域默认没有约束，忘了加就等于没有边界。 - 领域规则先写进
packages/domain/<域>/并配单测，再写service.py。 - 表加域前缀，走 Alembic，迁移必须向后兼容（NFR-MAINT-06）。