feat(ai): unify verified expense application workflow

document/development/2026-07-13/feature/ai-expense-closed-loop-and-value-proof/CONCEPT.md

@@ -253,6 +253,8 @@
 - API 新字段优先追加，不在同一阶段破坏现有前端契约。
 - 从未成功签发 `decision_id` 的旧申请预览，或签发接口失败且服务端没有当前会话有效决策时，保存/提交继续走现有 `client_observed` 路径；当前会话一旦存在有效服务端决策，省略 `decision_id` 必须拒绝，不能主动降级绕过核验。兼容路径不得在用户已经编辑后把最终值反向登记成“原始建议”。
 - 新预览使用 30 分钟有效的服务端 `decision_id`。保存草稿或提交成功后一次消费；保存草稿会尽力签发基于已保存事实的新 `decision_id`，供后续提交继续核验，但续签属于业务提交后的派生能力，续签失败不能把已成功保存返回为失败。相同动作请求 ID、动作和最终指纹允许安全重放，其他重放拒绝。
+- AI 工作台、小财管家和通用 Orchestrator 的结构化申请预览统一复用服务端签发/消费工作流。小财管家签发失败时保持可编辑和可重试，但保存、提交必须 fail-closed，不再降级到旧 Orchestrator 副作用；只有没有结构化预览的历史消息保留旧兼容入口。
+- Orchestrator 将已签发 decision 保存在服务端会话状态，后续保存/提交只消费该状态，不采信浏览器回传的 preview 或 decision。保存草稿返回的新 decision 继续写回会话，服务端消息中的结构化预览可在刷新或换端后恢复。
 - 迁移桥接期集中维护 migration-owned 表集合；所有 legacy bootstrap 只能创建集合之外的表。标准启动在 `alembic upgrade head` 前只读核对 revision 与自有表集合，发现漂移时拒绝启动，不自动猜测、stamp 或修复。
 - 所有表结构通过 Alembic 迁移，不继续在请求路径执行 DDL。
 
@@ -272,6 +274,7 @@
 - P0 数据契约即引入最小 `tenant_id`、数据库约束、行级过滤、向量库命名空间和对象存储前缀隔离；删除传播、数据导出和私有部署加固可在商业化阶段继续完善。
 - Expense Case 用户态查询只返回流程摘要：Case 基础状态、关系类型、事件类型、操作人、发生时间及白名单业务载荷；不返回关联资源 ID、幂等键、correlation、causation、聚合标识或 Outbox 投递状态。有权查看入口单据的本人、当前审批人、财务和管理员可查看整 Case 的安全摘要，无权限与跨租户查询继续以 404 隐藏资源存在性。
 - 申请预览签发与消费同时绑定 `tenant_id`、actor、Bearer 登录会话和会话 ID；动作入口按这些服务端事实锁行校验，不能只凭随机 UUID 授权。浏览器提供的模型来源、`finalValue`、用户和角色声明均不作为可信事实。
+- 外部 `/orchestrator/run` 的用户消息、定时任务和系统事件都必须携带有效登录会话，不能由请求体中的 `source` 自行声明可信内部来源；其中 `schedule` / `system_event` 只允许平台管理员触发。服务端使用登录态覆盖用户、租户、角色、管理员、员工、审批人和调度操作人别名，并移除客户端 preview/decision 状态。最近会话查询与删除只使用当前登录用户和租户，查询参数中的 `user_id` 仅保留协议兼容，不参与授权。
 - 预览与学习账本中的字段值使用独立、可版本化的费用申请密钥计算 HMAC-SHA256 指纹，密钥目录和文件权限分别为 `0700`、`0600`；核验旧决策必须使用其签发版本，缺失版本直接拒绝，不静默生成替代密钥。字段指纹同时编码“字段是否存在”，避免新增或删除字段被误判为采纳；训练资格仍保持关闭，直至审批、付款或人工核验闭环完成。
 - 自动化权限按动作、金额、场景、风险和有效期授予，不使用全局“允许 Agent 自动执行”开关。
 - 收款账户变更、资金支付、制度发布、高风险驳回和敏感主数据变更执行双人或更高等级复核。
@@ -458,6 +461,7 @@ docker exec -w /app -e SERVER_VENV_DIR=/tmp/x-financial-server-venv \
 - 历史证据边界：旧单快照只表达回填时可确认的当前状态，迁移前逐节点办理过程仍以原单据和既有审计为准；后续分析不得把快照事件误当成历史审批事实。
 - 认证和租户：当前客户端身份头不适合自动化和 SaaS，多租户、记忆和高风险动作开发前必须修复。
 - 会话运维：不透明会话已经替代客户端身份头，但仍需补充定时清理、活跃会话查看/全部退出、密钥轮换策略、登录限流和企业 SSO；当前 `tenant_id` 仍是最小契约，不代表跨租户查询守卫已经完成。
+- Agent 会话租户边界：Orchestrator 与 Steward 动作运行时都把可信 `tenant_id` 写入会话状态；创建、恢复、幂等检查点重放、单条删除和批量删除同时校验租户与用户名，同名用户不能跨租户复用 decision 或动作结果。历史无租户状态的会话在认证入口 fail-closed，不会被恢复或删除。`agent_conversations` 仍缺少独立 `tenant_id` 列和数据库复合约束，后续迁移需要把当前应用层守卫下沉为结构化租户键。
 - 费用事件读取边界：用户态精简 DTO 和首批 HTTP 权限测试已完成；剩余风险是同一 URL 若已有外部客户端依赖旧内部字段会产生契约变更，且未来新增敏感 payload 字段必须继续显式进入白名单，不能恢复任意字典透传。
 - 反馈投毒：一次点击或违规习惯不能直接成为记忆，需要候选态、最小样本、制度约束和结果权重。
 - 自动化失控：高准确率不代表高风险动作可以无人值守，必须按动作授权并支持 shadow、Canary、抽检和回滚。
@@ -528,3 +532,9 @@ docker exec -w /app -e SERVER_VENV_DIR=/tmp/x-financial-server-venv \
 - 2026-07-14（服务端预览决策）：新增认证的 `POST /api/v1/reimbursements/application-previews`。服务端从原始申请文本和当前登录身份重新解析字段、重跑规则测算，再签发 30 分钟有效的 `decision_id`；浏览器返回的模型来源和建议值不被直接认证。预览绑定租户、actor、登录会话和 conversation，字段只保存独立版本密钥生成的 HMAC 指纹；字段存在性也纳入指纹，新增、删除和改值都能由服务端识别。
 - 2026-07-14（消费与续签）：快速保存/提交显式携带动作类型、`decision_id` 和稳定请求 ID。服务端锁行校验后，在 Claim、Expense Case、Business Event、AIDecision、Feedback、Outcome 的同一事务中一次消费；当前会话已有有效决策时禁止省略 ID 降级。保存草稿提交成功后再尽力签发基于服务端事实的新 `decision_id`，续签失败只返回无新 ID，不反转已成功业务动作；相同请求安全重放不会重复建单或重复写学习账本。
 - 2026-07-14（0004 迁移与验证）：新增 `20260714_0004_ai_application_preview_decisions.py`，预览决策表和正式 Decision 复合租户外键纳入集中迁移所有权。一次性隔离 PostgreSQL 17 完整 upgrade、重复 upgrade、约束/索引、downgrade 和再次 upgrade 4 项通过；容器内新增决策安全用例 9 项、旧快速保存/提交 4 项、申请学习账本 9 项、迁移与所有权 26 项通过且条件型 PostgreSQL 用例 1 项跳过，3 组前端定向测试及 Vite 生产构建通过。持久开发库只读确认 8 张 migration-owned 表数量仍为 0。
+- 2026-07-14（多入口统一决策闭环）：抽取 `ExpenseApplicationPreviewWorkflow`，认证签发、锁行消费、动作幂等、学习落账和草稿续签不再由 HTTP 端点重复编排。Steward、小财管家结构化预览和通用 Orchestrator 均复用该工作流；用户纠正字段后仍消费原始 decision，使服务端能够把建议值与最终业务事实记为 `server_verified` 接受或纠正证据。
+- 2026-07-14（Orchestrator 身份与会话边界）：外部用户消息、定时任务和系统事件统一强制认证，`schedule` / `system_event` 进一步要求平台管理员；登录态覆盖请求中的身份、租户和调度操作人别名，堵住匿名或普通用户伪造来源触发 Hermes 管理任务的路径。会话创建、恢复和删除同时绑定可信租户与用户名，历史无租户状态会话 fail-closed。申请 decision 只从服务端会话恢复，客户端 preview/decision 在进入编排前被移除；保存草稿后的 next decision 回写会话并支持刷新/换端恢复结构化预览。
+- 2026-07-14（小财管家 fail-closed）：完整预览展示前先使用稳定 request ID 签发 canonical decision；签发失败时允许继续编辑和以同一 ID 重试，但禁止保存/提交且不回退旧副作用链路。保存/提交失败重试复用稳定 action request ID，保存成功同步草稿信息与 next decision。
+- 2026-07-14（decision 生命周期加固）：同一租户、用户、登录会话、conversation 和 HMAC 快照即使使用不同签发 request ID，也复用当前 active decision，避免多个并行 decision 命中草稿幂等捷径后遗留未消费状态。动作发现 decision 过期、已消费或不可用时，前端清空旧 ID、生成新的签发 request ID 并开放重新签发。
+- 2026-07-14（跨租户检查点加固）：Steward 动作会话创建显式写入服务端租户；租户 A/B 即使使用相同用户名、conversation 和 trace，也会获得独立会话与 decision，不再跨租户返回幂等结果或敏感预览内容。
+- 2026-07-14（统一闭环验证）：容器内服务端预览、Steward 动作/图运行、Orchestrator 外部来源授权及决策消费组合回归 50 项通过，Python Ruff F/I 通过；前端结构化动作、会话恢复、工作台路由、富确认和动作脚本共 18 项通过，Vite 生产构建通过。并行读取用户正在变动的规则工作簿曾触发 `openpyxl` ZIP 句柄竞争，相关套件改为串行后全部通过，未修改规则工作簿。

document/development/2026-07-13/feature/ai-expense-closed-loop-and-value-proof/TODO.md

@@ -81,6 +81,8 @@
   证据：`expense_application_draft_events.py`、`user_agent_application.py`、`reimbursements.py`、`steward_action_executor.py`、`test_user_agent_application_draft_events.py`、`test_reimbursement_endpoints.py`、`test_steward_action_executor.py`；完全相同 HTTP 保存重放复用同一草稿和事件，同一 run 内不同快照分别留痕，事件失败后草稿与 Case 数据整体回滚。
 - [x] [CONCEPT: 权限与安全] 将 AI 申请预览快速入口的用户、租户、角色与管理员身份强制绑定到服务端会话，拒绝请求体伪造身份编辑他人申请。
   证据：`reimbursements.py`、`test_reimbursement_endpoints.py`；对抗用例修复前返回 200，修复后返回 400，且目标申请和费用事件保持不变。
+- [x] [CONCEPT: 权限与安全] 收口通用 Orchestrator 用户消息和会话管理的认证边界，拒绝客户端身份与 decision 注入。
+  证据：`orchestrator.py`、`agent_conversations.py`、`orchestrator_expense_application_workflow.py`、`steward_graph_action_runtime.py`、`test_orchestrator_auth_endpoints.py`、`test_steward_action_executor.py`、`test_orchestrator_review_flow.py`；用户消息、定时任务和系统事件无认证均返回 401，普通用户触发 `schedule` / `system_event` 返回 403，登录态覆盖请求身份和调度操作人别名；Orchestrator 会话创建/恢复/删除及 Steward 幂等检查点同时校验租户与用户名，申请动作只消费服务端会话 decision。
 - [x] [CONCEPT: 兼容策略] 建立迁移桥接：服务启动先执行 Alembic，旧 metadata bootstrap 排除 migration-owned 表。
   证据：`server_start.sh`、`schema_ownership.py`、`migration_preflight.py`、`20260713_0001_expense_case_business_events.py`、`20260713_0002_auth_sessions.py`；容器 Shell/静态检查及一次性 PostgreSQL 完整 upgrade/downgrade/re-upgrade 通过。
 - [x] [CONCEPT: 兼容策略] 为迁移前已有 `ExpenseClaim` 提供显式、幂等且不伪造办理历史的费用事件快照回填。
@@ -117,7 +119,8 @@
 - [ ] [CONCEPT: 记忆激活] 实现用户、部门、企业记忆优先级、冲突解释、时间衰减和最小样本要求。
 - [x] [CONCEPT: 记忆与学习] 为 AI 申请预填记录用户原样采纳、显式字段修改和草稿/提交结果证据。
   证据：`expenseApplicationDecisionFeedback.js`、`useApplicationPreviewEditor.js`、`expense_application_learning.py`、`expense_application_preview_decisions.py`；改回原建议会清除字段差异，日期联动同步记录天数，最终值由服务端 facts 重建。旧预览保持 `client_observed`；服务端签发预览由版本化 HMAC 快照与最终 facts 逐字段比对，字段新增、删除或改值都标记为 `server_verified` 编辑。两者均保持 `training_eligible=false`，尚不直接训练模型或激活记忆。
-- [ ] [CONCEPT: 记忆与学习] 将小财管家/通用 Orchestrator 的申请预览切换到认证签发与消费链路；在此之前不得把其客户端 preview 升级为服务端核验证据。
+- [x] [CONCEPT: 记忆与学习] 将小财管家、Steward 与通用 Orchestrator 的申请预览切换到认证签发与消费链路，并把结构化预览失败策略收口为 fail-closed。
+  证据：`expense_application_preview_workflow.py`、`orchestrator_expense_application_workflow.py`、`steward_action_executor.py`、`useTravelReimbursementApplicationPreviewActions.js`；签发/动作请求 ID 可稳定重试，草稿续签回写服务端会话，字段接受/纠正按 `server_verified` 落账，未签发结构化预览不能保存或提交。
 - [ ] [CONCEPT: 记忆与学习] 从字段接受/修改/拒绝、退回、审批覆盖、付款和审计结果生成记忆证据。
 - [ ] [CONCEPT: 记忆与学习] 将已确认 few-shot 扩展到报销预审和审批辅助，并按租户、场景、制度版本过滤。
 - [ ] [CONCEPT: 风险与预审] 完成 golden case、Prompt/规则版本、Canary、回归门禁和自动回滚。
@@ -187,6 +190,8 @@
 - [ ] [CONCEPT: 测试方案] 补充其余前端组件、键盘操作、移动真实接口和完整浏览器关键流程验证。
 - [x] [CONCEPT: 测试方案] 验证服务端预览决策签发、字段新增/改值差异判定、跨会话拒绝、无 ID 降级防绕过、安全重放、独立密钥权限、续签失败容错、旧路径兼容、会话恢复和真实 PostgreSQL 迁移。
   证据：容器内新增决策安全用例 9 项、旧快速保存/提交 4 项、申请学习账本 9 项、迁移与所有权 26 项通过且条件型 PostgreSQL 用例 1 项跳过；一次性 PostgreSQL 17 迁移 4 项、前端定向 3 组及 Vite 生产构建已通过。临时 PostgreSQL 已清理，持久开发库 8 张 migration-owned 表数量仍为 0。
+- [x] [CONCEPT: 测试方案] 验证小财管家、Steward、通用 Orchestrator 的统一预览闭环、认证绑定、fail-closed、稳定重试和跨刷新恢复。
+  证据：容器内后端组合回归 50 项通过，覆盖服务端预览、Steward 动作/图运行、跨租户 checkpoint、Orchestrator 匿名/普通用户/管理员来源授权及决策消费，Python Ruff F/I 通过；前端结构化动作、会话恢复、工作台路由、富确认和 `ai-application-preview-actions` 共 18 项通过，Vite 生产构建通过。共享规则工作簿相关套件按容器内串行执行，避免并行读取正在变动的 XLSX 产生非业务性 ZIP 竞争。
 - [ ] [CONCEPT: 测试方案] 所有后端、集成和迁移测试在当前主应用容器内执行，单条命令最大超时 60s。
 - [ ] [CONCEPT: 指标与验收] 记录测试、lint、typecheck、构建、端到端和未覆盖风险证据。