feat: isolate administrators from task data plane
This commit is contained in:
inman committed
1 parent
03d01315a9
commit
fd39347603
13 files changed
+644
-112
No files matched your search
+11
-11
@@ -7,9 +7,9 @@
|
||||
- PostgreSQL 是任务、事件、幂等、审计和回查状态的唯一事实源。
|
||||
- 平台账号使用 `admin`（管理员）、`team_lead`（组长）和 `user`（普通用户）三种固定角色登录；服务端会话使用 HttpOnly/Secure/SameSite Cookie。管理员维护账号、角色、状态、密码重置、会话撤销和可执行任务类型；平台不提供组织或租户选择。
|
||||
- 登录会话默认跨浏览器重启持续有效，不按空闲时间或绝对时长自动失效；用户退出、修改密码、账号停用或管理员强制撤销时由服务端立即撤销。
|
||||
- 业务页面通过 REST 创建任务；Agent 返回结构化结果后，任务归属人在自己的任务上一次点击“确认并提交到 ERP 插件”，再通过 SSE 或轮询读取服务端状态。普通用户与组长的任务 API、SSE、附件和插件执行权限覆盖分配给本人的人工任务与 AgentBus 任务；管理员可查看固定部署范围内的全部任务，但确认、插件领取和执行回执仍必须来自任务归属账号，查看权限不等于执行权限。
|
||||
- 业务页面通过 REST 创建任务；Agent 返回结构化结果后，任务归属人在自己的任务上一次点击“确认并提交到 ERP 插件”，再通过 SSE 或轮询读取服务端状态。普通用户与组长的任务 API、SSE、附件和插件执行权限只覆盖分配给本人的人工任务与 AgentBus 任务；管理员是纯管理面身份，不能创建、查看、修改、领取、接收事件或提交任何业务任务。
|
||||
- 手工与 AgentBus 的每个新任务都会按同一组织、同一 18 项业务路由固化解析策略及配置 revision；来源不能覆盖模式。其中两项名单 route 固定为 `program_only`，其余 16 项可配置 `ai / shadow / auto / program`。全消息中的唯一已登记指令可以确定 route；没有指令时，只有全部标签都属于唯一 route、至少两个不同标签且业务定位必填项完整的字段签名才可确定 route。未知、冲突或多 route 输入不猜测。后续补充轮次沿用原任务快照，设置变化只影响新任务和新会话。
|
||||
- 管理员天然拥有全部 18 类人工业务。组长和普通用户使用逐账号白名单，新账号默认没有任何可执行任务类型；管理员在 `/accounts` 逐项授权后才能提交对应的新任务、补充指令或名单附件。已登记但未授权的业务返回 `business_not_authorized`；无法唯一确认 route 的非管理员输入返回 `business_type_unresolved`。两种拒绝都发生在解析器和 ERP 插件之前，并记录不含明文的授权拒绝审计。权限在补充输入、人工确认、全自动确认和插件领取前再次校验；取消授权后的任务不会进入 ERP 队列。AgentBus 入站使用渠道绑定员工的同一白名单，管理员账号不得成为员工渠道归属人。
|
||||
- 组长和普通用户使用逐账号白名单，新账号默认没有任何可执行任务类型；管理员自身的任务白名单固定为空，只能在 `/accounts` 为员工逐项授权。已登记但未授权的业务返回 `business_not_authorized`；无法唯一确认 route 的员工输入返回 `business_type_unresolved`。两种拒绝都发生在解析器和 ERP 插件之前，并记录不含明文的授权拒绝审计。权限在补充输入、人工确认、全自动确认和插件领取前再次校验；取消授权后的任务不会进入 ERP 队列。AgentBus 入站使用渠道绑定员工的同一白名单，管理员账号不得成为员工渠道归属人。
|
||||
- 名单 route 创建后先进入 `awaiting_attachment`，只接收一份 `.xls/.xlsx`；控制面在前 100 行中自动定位唯一的 ERP 名单字段表头，按精确字段语义从任意表头行和列顺序中只选择 12 个必需源字段，并把表头下方连续名单数据在内存中规范化为 13 列 canonical TSV。身份证、年龄、源证件类型和其他普通额外列不参与名单行识别、字段校验或输出；必需字段缺失/重复、多个候选表头、必需字段中的非法公式及宏、外链等主动内容仍失败关闭。原始工作簿不入库，文件名和 canonical TSV 使用字段加密，解析通过或终止后清除 canonical 中间文本。附件到齐前不会领取解析任务，也不会进入 ERP。独立团初始 16 行、散拼子单初始 31 行仅为 ERP 动态扩行基线，5000 为技术上限。
|
||||
- 平台的任务 ID、Agent 会话 ID、确认状态、重要摘要、事件和用户通讯内容只存在于平台任务/会话/结果信封中，不回写到 Agent `operation`，也不成为 ERP 业务字段。
|
||||
- Agent `operation` 只保存解析态业务事实。插件领取已确认任务后先做无需 ERP 查询的前门禁，再在 ERP 内只读唯一解析对象、资源和当前状态，最后对内部 execution operation 执行严格写前门禁。
|
||||
@@ -25,11 +25,11 @@
|
||||
- 微信侧的 `[WeChat attachment: 文件名]` 只是一段传输占位文字，不代表控制面已经收到文件。若同一帧没有符合契约的 `payload.attachments[]`，listener 会在进入任务服务前失败关闭、保留原名单任务的等待状态，并返回“附件内容未传到平台”；不会把占位文字创建成新业务任务。附件元数据、HTTPS URL、DNS、大小或摘要校验失败时返回对应的安全摘要，仍不回显 URL、文件字节或名单内容。当前生产部署位于受信内网，入站附件 URL 可以使用内网域名、私网 IPv4/IPv6 或 localhost；因此 AgentBus 渠道和上游桥接器必须被视为受信输入边界。
|
||||
- AgentBus 入站消息会复用 `TaskService` 的任务/会话/解析队列，并以渠道绑定员工写入 `created_by` 与不可变的 `assigned_user_id`，解析完成后通过同一 WebSocket 返回一次 `task.result`。组织级“全自动化”关闭时，手工与 AgentBus 新任务都需要人工确认；开启后，两种来源的合法解析结果都自动进入 ERP 队列，不再按来源或创建、名单、安排、修改、取消/恢复、导出等业务类型保留人工例外。历史未归属 AgentBus 任务不会自动执行。操作台在 EventSource 建连/重连、30 秒后台刷新以及页面重新可见或聚焦时重新读取数据库权威开关。缺资料、解析失败、歧义、插件校验失败或 ERP 回查不确定时仍会停止，不会绕过校验或重试不确定写入。
|
||||
- 单一部署范围可以维护多个“用户渠道”。每个渠道代表一个外部 AgentBus 用户身份，并且必须一对一绑定一个有效的非管理员平台账号；一个平台账号也只能绑定一个渠道。管理员在 `/channels` 创建、绑定、停用、启用、轮换或删除渠道。只有绑定账号有效且已配置 ERP 账号的启用渠道才启动 listener；未绑定渠道失败关闭。删除会停止对应 listener、移除服务端保存的 key 和该渠道尚存的持久化回执；历史任务本体保留，其 `channel_id` 置空而 `assigned_user_id` 不变。每个渠道独立保存加密后的 AgentBus key，同一 key 不能被多个渠道复用；列表和日志都不会回显 key。`AGENTBUS_WS_URL`、重连策略和客户端类型仍是全局连接配置，`AGENTBUS_BOT_ADDRESS` 可作为渠道 bot address 的默认值。
|
||||
- `/history` 同时提供可恢复的归档/恢复与显式的永久强制删除。`POST /api/tasks/:taskId/archive`、`POST /api/tasks/:taskId/restore` 和 `POST /api/tasks/bulk-archive` 保留归档语义及运行状态门禁；`DELETE /api/tasks/:taskId` 与 `POST /api/tasks/bulk-delete` 会绕过任务状态门禁并物理删除任务及其输入、事件、尝试、会话、投递和附件记录，同时清理任务 outbox，并在提交后尽力清理 OSS 对象。普通用户和组长只能操作本人任务，管理员可以处理全部授权任务；不可逆删除仍保留最小化的删除审计事件。
|
||||
- `/operations-dashboard` 是组长和管理员专用的只读业务操作看板。它以不可变的任务归属账号作为员工口径，纳入同一固定组织中所有已归属的人工与 AgentBus 任务，并支持从结果状态、员工、上海业务日期和业务类型逐层穿透；历史上无法安全归属员工的 AgentBus 任务不在人员看板中被猜测归属。列表和详情只回答“谁负责什么任务、收到什么指令、完成了什么结果”：详情返回员工、业务类型、完整指令轮次、输入附件名称/行数和可读业务结果，不返回任务生命周期、解析/执行 JSON、技术阶段、错误码或产物地址。关键词查询先受日期、人员、业务和状态约束，单次解密匹配候选最多 2,000 条，超过时要求继续缩小范围。该路径不授予他人任务修改、ERP 执行、SSE、产物下载、账号维护或全局安全审计权限。
|
||||
- `/history` 同时提供可恢复的归档/恢复与显式的永久强制删除。`POST /api/tasks/:taskId/archive`、`POST /api/tasks/:taskId/restore` 和 `POST /api/tasks/bulk-archive` 保留归档语义及运行状态门禁；`DELETE /api/tasks/:taskId` 与 `POST /api/tasks/bulk-delete` 会绕过任务状态门禁并物理删除任务及其输入、事件、尝试、会话、投递和附件记录，同时清理任务 outbox，并在提交后尽力清理 OSS 对象。普通用户和组长只能操作本人任务；管理员不能进入该页面或调用这些接口。不可逆删除仍保留最小化的删除审计事件。
|
||||
- `/operations-dashboard` 是组长专用的只读业务操作看板。它以不可变的任务归属账号作为员工口径，纳入同一固定组织中所有已归属的人工与 AgentBus 任务，并支持从结果状态、员工、上海业务日期和业务类型逐层穿透；历史上无法安全归属员工的 AgentBus 任务不在人员看板中被猜测归属。列表和详情只回答“谁负责什么任务、收到什么指令、完成了什么结果”：详情返回员工、业务类型、完整指令轮次、输入附件名称/行数和可读业务结果，不返回任务生命周期、解析/执行 JSON、技术阶段、错误码或产物地址。关键词查询先受日期、人员、业务和状态约束，单次解密匹配候选最多 2,000 条，超过时要求继续缩小范围。该路径不授予他人任务修改、ERP 执行、SSE、产物下载、账号维护或全局安全审计权限；管理员同样无权访问。
|
||||
- 使用数据库渠道时设置 `AGENTBUS_ENABLED=true`；此模式不要求 `AGENTBUS_WS_TOKEN` 或 `AGENTBUS_BOT_ADDRESS`，但启用的渠道仍需要全局 `AGENTBUS_WS_URL`，并可在渠道上覆盖 bot address。保留旧环境变量配置时，服务会按需创建“默认 AgentBus 渠道”兼容旧单渠道部署；兼容渠道初始为未绑定且不启动，管理员必须在 `/channels` 绑定员工账号后再启用。`AGENTBUS_ENABLED=auto` 仅由完整的旧环境连接字段自动启用。
|
||||
- `user_channels`、`tasks.channel_id` 和 `agentbus_deliveries` 共同保存入站归属、accepted 受理回执和最终 result 回执。回执以 `(channel_id, inbound_frame_id, delivery_kind)` 幂等，发送失败会重试，进程重启或 WebSocket 重连后仍会继续投递；因此不会因为超过原等待时长而丢掉最终回复。
|
||||
- ERP 插件领取按任务 `assigned_user_id` 使用账户级数据库锁和 FIFO confirmed 队列：同一平台/ERP 账户在任意时刻最多一个 ERP execution，该账户的其他任务留在服务端等待；不同账户的活跃或待执行任务互不占用队列位置、可独立领取执行。管理员的组织级查看权限与执行权限完全分离：实时执行事件、插件领取、执行回执以及强制删除后的浏览器清理命令都只发送或接受任务 `assigned_user_id` 对应的登录账号，管理员不会因为能查看员工任务而收到或处理该员工的插件任务。已开始写入但结果不确定的任务只阻塞同一账户的后续领取，直到人工回查收敛或任务被明确强制删除。
|
||||
- ERP 插件领取按任务 `assigned_user_id` 使用账户级数据库锁和 FIFO confirmed 队列：同一平台/ERP 账户在任意时刻最多一个 ERP execution，该账户的其他任务留在服务端等待；不同账户的活跃或待执行任务互不占用队列位置、可独立领取执行。管理员不能成为 `assigned_user_id`、渠道 owner、浏览器 worker 或组长任务摘要接收人，也不能打开任务 SSE；实时执行事件、任务摘要、插件领取、执行回执以及强制删除后的浏览器清理命令只发送或接受符合角色约束的员工账号。已开始写入但结果不确定的任务只阻塞同一账户的后续领取，直到归属账号人工回查收敛或任务被明确强制删除。
|
||||
|
||||
## 任务级会话续接
|
||||
|
||||
@@ -77,19 +77,19 @@ Content-Type: application/json
|
||||
- `auto`：程序优先；仅 `program_unsupported_syntax`、`program_unknown_field`、`program_internal_error`、`program_timeout`、`program_contract_invalid` 可整体切到 AI。缺字段、非法值、冲突、歧义、多动作和业务规则阻断不会调用 AI。
|
||||
- `program`：只运行程序；失败时追问或阻断，不调用 AI。
|
||||
|
||||
Auto 一旦发生 AI fallback，任务会永久绑定原 AI 会话。每次解析只有一个完整权威结果，不拼接候选；任务进入确认、插件领取或 ERP 链路后不再自动重解析。尚未进入插件且明确 `no_plugin_dispatch=true / no_erp_write=true` 的解析失败任务，可由管理员授权一次 AI 重解析。
|
||||
Auto 一旦发生 AI fallback，任务会永久绑定原 AI 会话。每次解析只有一个完整权威结果，不拼接候选；任务进入确认、插件领取或 ERP 链路后不再自动重解析。管理员任务隔离后不再从任务详情执行一次性 AI 重解析或解析差异判定。
|
||||
|
||||
操作台根路径 `/parser-routing` 提供逐业务观察统计、即时切换检查、revision 乐观并发控制和事务级“全部切回 AI”。连续天数、任务数量和 fallback 比率不作为等待门槛：18 项已实现业务均可独立进入 Shadow，多个 Shadow 可并行测试且不受固定前序约束；已出现的差异全部判定且本业务程序关键、契约、运行错误为零即可进入 Auto；程序下游失败和上述错误为零即可进入 Program。同一时间最多一个业务处于 Auto，晋级仍只能 `AI → Shadow → Auto → Program` 逐级进行，回退可直接执行。7/30 日统计仅供观察。组织已开启全自动化时，切入 Auto/Program 不增加人工确认期。
|
||||
|
||||
主要接口：
|
||||
主要管理接口：
|
||||
|
||||
- `GET /api/settings/parser-routing`
|
||||
- `PUT /api/settings/parser-routing/:routeId`
|
||||
- `POST /api/settings/parser-routing/emergency-ai`
|
||||
- `POST /api/tasks/:taskId/reparse`
|
||||
- `PUT /api/parser-decisions/:decisionId/review`
|
||||
|
||||
迁移 `013_business_parser_modes` 增加内部固定范围的路由设置、任务快照和加密的 `parse_decisions`；迁移 `014_task_input_attachments` 增加名单输入附件元数据、加密 canonical TSV 与 `awaiting_attachment` 索引；迁移 `015_account_roles_and_task_audit` 增加账号角色、密码更新时间、输入/附件操作者、任务归档和账号级幂等（历史 `must_change_password` 列仅保留兼容，当前流程不启用首次强制改密）；迁移 `016_team_lead_operations_dashboard` 增加组长角色与人工指令看板索引；迁移 `017_user_business_route_authorizations` 增加逐账号业务白名单、授权人和乐观并发 revision；迁移 `018_agentbus_account_workers` 增加 ERP 账号、渠道归属、任务执行归属、唯一在线 worker 与 ERP 身份核验字段；迁移 `020_leader_task_summary_notifications` 增加内部失败关闭的组长路由快照和独立加密通知 outbox，是否启用由运行时角色与渠道核对自动维护。原文、完整程序/AI 候选、名单 canonical 中间文本、人工说明和待发组长摘要使用字段加密保存；统计、全局审计和运行日志不复制明文业务输入。
|
||||
旧的任务详情重解析和解析差异判定路由仍保留兼容响应，但已纳入任务数据面统一门禁；管理员调用会返回 `task_access_forbidden`，管理页面不再提供这两个任务级入口。
|
||||
|
||||
迁移 `013_business_parser_modes` 增加内部固定范围的路由设置、任务快照和加密的 `parse_decisions`；迁移 `014_task_input_attachments` 增加名单输入附件元数据、加密 canonical TSV 与 `awaiting_attachment` 索引；迁移 `015_account_roles_and_task_audit` 增加账号角色、密码更新时间、输入/附件操作者、任务归档和账号级幂等（历史 `must_change_password` 列仅保留兼容，当前流程不启用首次强制改密）；迁移 `016_team_lead_operations_dashboard` 增加组长角色与人工指令看板索引；迁移 `017_user_business_route_authorizations` 增加逐账号业务白名单、授权人和乐观并发 revision；迁移 `018_agentbus_account_workers` 增加 ERP 账号、渠道归属、任务执行归属、唯一在线 worker 与 ERP 身份核验字段；迁移 `020_leader_task_summary_notifications` 增加内部失败关闭的组长路由快照和独立加密通知 outbox；迁移 `021_admin_task_data_plane_isolation` 清除管理员的遗留任务执行绑定和待发组长摘要，并以数据库触发器阻止管理员成为任务创建人/归属人、渠道 owner、浏览器 worker、业务授权对象或任务摘要接收人。原文、完整程序/AI 候选、名单 canonical 中间文本、人工说明和待发组长摘要使用字段加密保存；统计、全局审计和运行日志不复制明文业务输入。
|
||||
|
||||
## AgentBus Bot 接入
|
||||
|
||||
@@ -143,7 +143,7 @@ npm run data:retention
|
||||
npm run dev
|
||||
```
|
||||
|
||||
`npm run dev` 和 `npm start` 会先执行数据库迁移，再启动控制平面；直接运行 `control-plane/src/server.ts` 或构建后的 `server.js` 时，服务也会在启动前检查必需迁移 `020_leader_task_summary_notifications`，缺失时拒绝监听端口。`db:migrate` 和管理员初始化需要可连接的 PostgreSQL。开发机没有数据库时，可以运行 `npm run test:control-plane` 完成无数据库静态/健康烟测。
|
||||
`npm run dev` 和 `npm start` 会先执行数据库迁移，再启动控制平面；直接运行 `control-plane/src/server.ts` 或构建后的 `server.js` 时，服务也会在启动前检查必需迁移 `021_admin_task_data_plane_isolation`，缺失时拒绝监听端口。`db:migrate` 和管理员初始化需要可连接的 PostgreSQL。开发机没有数据库时，可以运行 `npm run test:control-plane` 完成无数据库静态/健康烟测。
|
||||
|
||||
`/health/ready` 同时检查 PostgreSQL 可用性和必需 schema 版本；迁移未完成时返回 503，并标明 `required_migration`，避免任务在数据库结构未升级时进入解析队列。
|
||||
|
||||
|
||||
Reference in new issue
Block a user