# Hermes、本体解析与财务报告多租户安全 概念文档 更新时间：2026-07-17 ## 功能一句话 让本体解析、员工行为画像、Hermes 扫描、数字员工看板和定时财务报告从请求到存储全程绑定可信企业，并在任何租户上下文缺失或冲突时停止运行。 ## 背景与问题 本体解析曾在建立 `AgentRun` 前调用模型，并从全局员工、组织、客户、供应商、项目和单据字典构造提示词；员工画像详情可按任意员工 ID 查询；Hermes 扫描、看板和财务报告存在全表读取、全局收件人以及跨企业复用存储路径的风险。内部 Orchestrator 调用还可在没有认证用户时继续运行，无法证明 `AgentRun` 的企业归属。 ## 目标与非目标 ### 目标 - HTTP 入口只信任 `CurrentUserContext.tenant_id`，内部任务只接受显式、已注册且启用的 `trusted_tenant_id`。 - 本体解析在任何模型调用前创建租户化 `AgentRun`，商业运行上下文和失败证据可追溯。 - 员工、组织、费用、应收、应付、画像、风险、提醒和看板查询在首个 SQL 中限定租户。 - 员工画像仅允许本人、直属领导、财务/高管或管理员读取；越权和跨租户统一返回 404。 - 财务报告按租户配置收件人、生成内容、存储文件和幂等运行账本，不使用全局邮件回退。 - 所有 Hermes 定时任务逐个枚举 `status=active` 的企业，运行记录同时在 route/ontology 保存租户快照。 ### 非目标 - 不提供客户端选择或覆盖租户的兼容参数。 - 不实现跨企业合并分析、集团穿透报表或平台运营后台。 - 不在本切片中重构预算分配等仍属旧模型的全部业务域。 ## 信任边界 ```text HTTP 请求 ── CurrentUserContext.tenant_id ─┐ ├─→ tenant-scoped AgentRun 内部任务 ── active trusted_tenant_id ──────┘ ├─ route_json.tenant_id └─ ontology_json.tenant_id ``` - 客户端 `context_json.tenant_id` 会被可信租户覆盖，不能参与授权。 - 同时传入登录用户和内部租户时，两者必须一致。 - 内部任务租户必须存在于租户注册表且状态为 active；缺失、停用或不存在均在创建 Run 前拒绝。 - 后台消费者从数据库 Run 恢复租户，并校验 route/ontology 两份快照一致。 ## 功能设计 ### 本体解析 - 接口覆盖请求中的 user id，并把认证企业传给 `SemanticOntologyService`。 - `parse()` 先建立 `running/pending_model_analysis` Run，再加载租户字典、商业运行上下文并调用模型。 - 模型、规则降级和失败路径都更新同一 Run；失败不会留下无企业、无状态的调用。 - 员工、部门、费用申请、应收、应付和项目参考目录均以租户作为第一层 SQL 条件。 ### 员工画像 - 快照保存 `tenant_id`，并用 `(tenant_id, subject_id)` 复合外键绑定员工。 - Profile Service 的快照、费用单和 Agent Run 查询均先限定租户。 - 详情接口先在当前企业解析目标员工，再执行本人/直属领导/财务/高管/管理员访问矩阵。 - 附带 `claim_id` 时必须同时属于目标员工和当前企业。 ### Hermes 与数字员工 - 风险扫描、画像扫描、风险线索、提醒扫描和看板均接受显式租户。 - 调度器只枚举 active 企业，并为每个企业独立创建任务与结果。 - 看板只统计 route/ontology 租户快照均匹配的 Run；缺少或冲突快照的历史记录不会被猜测归属。 - 提醒任务的费用单、员工和关联报销查询在首个 SQL 限制当前企业。 ### 财务分析报告 - `TenantFinanceReportConfig` 保存企业启停状态和经校验的收件人。 - `TenantFinanceReportRun` 以 `(tenant_id, idempotency_key)` 防止同企业同周期重复发送。 - 报告上下文只读取当前企业的费用、风险、画像和 Agent Run。 - 邮件发送只使用当前企业配置；未配置、停用或无有效收件人时 fail-closed。 - 文件存储目录使用企业标识哈希，避免路径注入和跨企业文件覆盖。 ## 数据与迁移 `20260717_0028_hermes_ontology_tenant_security.py` 完成： - 员工行为画像、Hermes 任务配置/日志和风险报告新增租户列、索引、唯一约束和复合外键。 - 新增租户财务报告配置和周期运行账本。 - 旧记录回填为 `default`，再移除 server default，后续写入必须显式确定企业。 - 仅支持 PostgreSQL；upgrade/downgrade 在任何 DDL 前检查方言，其他数据库直接拒绝。 - downgrade 在存在非默认企业事实或报告账本时拒绝有损回滚。 ## 降级与回滚 - 租户缺失、停用、不存在或上下文冲突：不创建 Run、不查询业务数据。 - 跨企业员工、画像、费用单：统一按不存在处理。 - 企业未配置报告收件人：保留失败/跳过证据，不回退环境变量中的全局地址。 - 历史 Run 没有双租户快照：看板不纳入企业统计。 - 生产升级前必须在数据库备份副本演练 `0027 → 0028 → 0027 → 0028`。 ## 测试与验收 - 两企业本体目录、画像 IDOR、Hermes 扫描、风险线索、看板和报告内容/收件人/路径/幂等隔离。 - Orchestrator 缺租户、停用租户、不存在租户和认证/内部租户冲突均在 Run 前拒绝。 - 本体模型调用前存在 running Run，失败后仍保存同企业失败证据。 - PostgreSQL 完成 fresh `base → 0028`、`0028 → 0027 → 0028` 及旧表回填/外键验证。 - 所有后端测试和 Ruff 均在 `local-x-financial-linux` 容器内执行，单命令不超过 60 秒。 ## 本轮实现记录 - 2026-07-17：完成本体解析前置 Run、可信商业上下文和租户参考目录。 - 2026-07-17：完成员工画像模型、服务和 API 的租户隔离与访问矩阵。 - 2026-07-17：完成 Hermes 扫描、提醒、看板、调度和财务报告的逐租户运行。 - 2026-07-17：完成 `20260717_0028` PostgreSQL 迁移、反向回滚和安全回归。