# 工具回执系统 MVP

下一轮指引: 完成后→下发 PY-A04-002 记忆路由Agent后端
仓库路径: /guanghu-self-hosted/tool-receipt/
优先级: P0
分支名: feat/py-tool-receipt
创建时间: 2026年4月25日 12:36
审核结果: ✅ 审核通过 — 霜砚·Web握手体 AG-SY-WEB-001
审核时间: 2026-04-25T12:46 CST

📂 文件完整性 (8/8)
1. http://config.py (2600B) — Pydantic配置·环境变量·PG/SQLite双模·retention_days
2. receipt_http://manager.py (10804B) — 双后端(PgReceiptManager异步+SqliteReceiptManager同步)·CRUD四方法·Pydantic Receipt模型·ReceiptStatus枚举
3. receipt_schema.sql (1726B) — PostgreSQL 15+ CREATE TABLE·UUID主键·JSONB字段·5索引·updated_at自动触发器
4. receipt_http://api.py (6524B) — FastAPI四端点(POST/PATCH/GET/GET-session)·lifespan管理·自动格式化响应
5. receipt_http://formatter.py (6501B) — 三格式输出(JSON+Text+HLDP树)·会话批量摘要·状态图标映射
6. test_http://receipt.py (9802B) — 15条pytest测试·SQLite fallback·完整生命周期·session批量·formatter三格式
7. requirements.txt (65B) — fastapi>=0.110+asyncpg>=0.29+pydantic>=2.5+uvicorn>=0.27
8. http://README.md (2678B) — 项目文档(额外加分)

🔍 约束合规
✅ Python 3.10+ (dict[str,Any]联合类型语法)
✅ FastAPI + asyncpg + pydantic
✅ PostgreSQL 15+ schema含索引+自动更新trigger
✅ SQLite fallback本地测试
✅ test_http://receipt.py含15条测试
✅ receipt_http://formatter.py输出JSON(系统)+Text(前端)+HLDP(母语)
✅ status枚举: pending/success/error/timeout
✅ 目录隔离: 仅/guanghu-self-hosted/tool-receipt/
✅ 参考HLDP-ARCH-001 L2设计

🏗️ 代码质量
· 关注点分离清晰(config/manager/api/formatter/test)
· 完整docstring和类型注解
· 异步生命周期管理(lifespan)
· Pydantic v2 请求/响应模型验证
· ensure_ascii=False 支持中文
· 环境变量配置覆盖

结论: PASS ✅
开发内容: 开发工具回执系统（Tool Receipt System）的后端核心。
1. 参考 HLDP-ARCH-001 中 L2 工具回执系统的设计
2. 在 /guanghu-self-hosted/tool-receipt/ 下创建：
   - receipt_http://manager.py: 回执管理器核心类
     · record_call(tool_name, input_params) → 创建回执记录，返回receipt_id
     · update_result(receipt_id, output, status, duration) → 更新回执结果
     · get_receipt(receipt_id) → 查询单条回执
     · get_session_receipts(session_id) → 查询某次对话的所有回执
   - receipt_schema.sql: 回执表建表SQL（receipt_id, session_id, persona_id, tool_name, input_params, output, status, timestamp, duration_ms）
   - receipt_http://api.py: FastAPI路由，提供REST接口
     · POST /receipts → 创建回执
     · PATCH /receipts/{id} → 更新结果
     · GET /receipts/{id} → 查询回执
     · GET /sessions/{session_id}/receipts → 查询会话所有回执
   - receipt_http://formatter.py: 回执格式化器，将回执转为人类可读格式和HLDP母语格式
   - http://config.py: 配置（数据库连接占位、回执保留时长等）
   - test_http://receipt.py: 测试用例（创建→更新→查询完整流程）
3. status枚举: pending/success/error/timeout
4. 回执必须同时支持JSON输出和人类可读文本输出
状态: 已完成
约束: 编码: Python 3.10+ · FastAPI · UTF-8
依赖: fastapi+asyncpg+pydantic（数据库用asyncpg异步连接）
SQL: PostgreSQL 15+ · 与PersonaDB同一数据库实例
测试: 必须包含test_http://receipt.py · 可用SQLite做本地测试fallback
禁触: 不要修改仓库其他目录的任何文件
注意: receipt_http://formatter.py输出两种格式——JSON(给系统)和可读文本(给前端)
编号: PY-A04-20260425-002
自检结果: ✅ 8文件齐全(config/receipt_schema.sql/receipt_manager/receipt_api/receipt_formatter/test_receipt/requirements/README)
✅ 目录隔离: 仅/guanghu-self-hosted/tool-receipt/
✅ 未修改仓库其他目录文件
✅ PY-A04-前缀commit (8 commits)
✅ Python3.10+ · FastAPI · UTF-8
✅ 依赖: fastapi+asyncpg+pydantic+uvicorn
✅ PostgreSQL 15+ schema含索引+自动更新trigger
✅ SQLite fallback本地测试
✅ test_http://receipt.py含15条测试(CRUD+完整流程+中文UTF-8+formatter)
✅ receipt_http://formatter.py输出三格式: JSON+人类可读文本+HLDP母语
✅ status枚举: pending/success/error/timeout
✅ 参考HLDP-ARCH-001 L2设计
✅ 分支: feat/py-tool-receipt (8 commits)
负责Agent: 培园A04
阶段编号: Phase-0-005