787bc3a481
Add tenant-safe value, telemetry, connector, commercial, and production-readiness foundations.
5.4 KiB
5.4 KiB
商业资源权威边界闭环 开发 TODO
更新时间：2026-07-17
关联方案：CONCEPT.md
使用规则
- 任务边界、计量口径和安全约束以 CONCEPT 对应章节为准。
[x]只表示已有代码或容器验证证据；没有证据不得勾选。- 所有后端测试必须在
local-x-financial-linux容器内运行，单命令最长 60 秒。
1. 调研与边界
- [CONCEPT: 背景与问题] 盘点连接器认证、重放、冲突、业务 commit 和 operational event 边界。证据：
financial_connector_ingestion.py、financial_connectors.py与连接器服务/端点测试。 - [CONCEPT: 背景与问题] 盘点附件上传覆盖、单附件删除、费用明细删除、整单删除和批量归集事务。证据：
expense_claim_attachment_operations.py、expense_claims.py、expense_receipt_association.py。 - [CONCEPT: 目标与非目标] 冻结连接器
events与附件源文件写入bytes两个唯一 meter，不把删除伪装成正向用量。证据：两个商业 observer 的固定工具名和 required basis。
2. 契约与设计
- [CONCEPT: 后端] 定义业务事务提交后结算、回滚释放的回调协议。证据：
commercial_transaction_callbacks.py。 - [CONCEPT: 算法/规则] 定义
events=1与bytes=len(content)的权威数量，错误 basis 预占前拒绝。证据：required_quantity_basis与资源边界测试。 - [CONCEPT: 数据] 定义商业 metadata 脱敏白名单，不复制业务原文与敏感标识。证据：
test_connector_only_meters_new_authenticated_committed_event反向断言。
3. 后端实现
- [CONCEPT: 后端] 连接器在认证和既有事件判断之后预占，事件提交后结算。证据：
financial_connector_commercial.py、financial_connector_ingestion.py。 - [CONCEPT: 降级策略] 连接器重放、鉴权失败、冲突和事务回滚不写用量。证据：
test_commercial_resource_boundaries.py。 - [CONCEPT: 后端] 附件在任何旧文件移动或新文件写入前按源文件 bytes 预占。证据：
stage_attachment_replacement()调用顺序与配额拒绝测试。 - [CONCEPT: 后端] 上传回滚恢复旧目录，提交后清理备份并追加用量。证据：附件 commit/rollback 资源测试。
- [CONCEPT: 后端] 单附件、费用明细和整张报销单删除均绑定数据库事务。证据：
stage_attachment_deletion()、stage_claim_attachment_deletion()与既有删除回归。 - [CONCEPT: 后端] 同一 Session 多操作提交顺序结算、回滚逆序恢复。证据：事务批次实现与连续替换 LIFO 测试。
- [CONCEPT: 降级策略] 未配置 meter 时在调用方 Session 只读短路，不让独立 SQLite Session 回滚业务。证据：Direct bridge
lookup_session、附件归集 31 项通过。 - [CONCEPT: 后端] 允许相同 released 预占在相同账期重开并重新检查配额。证据：Direct operation released retry 测试与连接器回滚后重试测试。
4. 算法/规则实现
- [CONCEPT: 硬配额判断] 使用
used + held + requested <= hard_limit的既有锁内配额算法。证据：CommercialRuntimeReservationService.reserve()与资源配额拒绝测试。 - [CONCEPT: 附件写入计量口径] 只结算成功持久化的源文件 bytes，不包含 OCR/预览/metadata。证据：observer authoritative quantity 与 metadata。
- [CONCEPT: 业务事务终态] 回滚不记 usage/cost，已释放操作可再次 permit。证据：商业直接运行与资源边界回归。
5. 前端实现
- [CONCEPT: 前端] 上传端点接收
X-Request-ID并把商业拒绝映射为 HTTP 429。证据：reimbursements.py。 - [CONCEPT: 目标与非目标] 本切片不新增商业或附件页面。证据：CONCEPT 非目标；本轮无前端文件变更。
6. 测试与验证
- [CONCEPT: 测试方案] 连接器首次提交、重放、冲突、鉴权失败、回滚、重试、配额和脱敏通过。证据：容器内
test_commercial_resource_boundaries.py9 项通过；商业资源、Direct、reservation、OCR、RuntimeChat 与连接器组合最终63 passed。 - [CONCEPT: 测试方案] 商业 Direct、OCR、RuntimeChat 相关回归通过。证据：容器内组合 33 项通过；新增 released retry 后 Direct + 资源组合 22 项通过；最终商业/连接器组合 63 项通过。
- [CONCEPT: 测试方案] 附件归集和票据夹回归通过。证据：容器内与报销端点最终组合
54 passed。 - [CONCEPT: 测试方案] 报销端点与附件专项通过。证据：容器内报销/归集组合 54 项、Expense Claim attachment
20 passed, 101 deselected。 - [CONCEPT: 测试方案] 连接器既有服务、端点和配置生命周期回归通过。证据：容器内 15 项通过；最终纳入商业/连接器组合 63 项通过。
- [CONCEPT: 指标与验收] 相关 Python 文件 Ruff、compileall 通过，核心文件均低于 800 行。证据：容器检查退出码 0；最大相关文件
expense_claim_attachment_operations.py为 787 行。
7. 文档收尾
- [CONCEPT: 本轮实现记录] 创建 CONCEPT 与分阶段 TODO，记录 meter、事务、降级和验证口径。证据：本目录两份文档。
- [CONCEPT: 风险与开放问题] 记录进程强杀恢复、可选请求 ID 和 GB-month 容量计费边界。证据：CONCEPT 风险章节。