# 服务区业务能力与流程开发说明

设计日期：2026-09-28。适用于 A、B、C、D……所有完整业务服务区。本文整理已确认的业务边界和建议实现顺序，供开发拆分模块与验收；不表示完整业务、WeKnora 或多机 Worker 已经上线。

[查看业务架构地图](https://ai.desk99.cn/diagrams/) · [服务区组件图](https://ai.desk99.cn/diagrams/?diagram=zone-components) · [数据库与企业共享](https://ai.desk99.cn/diagrams/?diagram=tenant-data)

## 1. 一个服务区交付什么

服务区是承载一组企业完整业务的逻辑单元，可先运行在一台服务器，再扩展到多台。企业由中央分配，同一企业的成员进入同一区；同一用户加入多家企业时，可以随企业切换进入不同区。A/B/C/D……运行同等软件，承载的企业与数据不同。

用户看到的是完整 React 工作台，其中 AI 对话是一个业务入口。Spring Boot API、Worker、PG 数据库和 WeKnora 是支撑业务的组件，不能用组件清单代替业务功能清单。PG 指 PostgreSQL。

| 业务能力 | 用户操作与产出 | 主要归属及边界 |
| --- | --- | --- |
| AI 工作台 | 提问、引用知识、恢复历史、通过工具发起业务操作 | 会话关联企业和成员，正文持久保存到本区 WeKnora；工具仍走 Java 授权 |
| 企业知识库 | 上传和维护企业、产品资料；检索、阅读、AI 引用 | 每企业一个共享知识库；租户管理员默认管理，可委派成员 |
| 获客中心 | 配置市场与搜索条件、获取线索、筛选去重、导入客户 | 线索及导入结果存本区业务库；搜索等耗时任务由 Java Worker 执行 |
| CRM | 企业共享客户、联系人、分组、跟进及关联报告 | 本区 PG 是主数据来源，created_by 不把企业数据变成个人私有 |
| 客户背调 | 选择客户、分析背景、形成报告与机会评分 | Worker 调用授权依赖，报告回写 CRM 并保留依据和时间 |
| 邮件业务 | 企业邮箱配置、模板、开发信草稿、发送、收信与客户沟通关联 | 业务配置、任务和关联在本区；邮箱存储及收发通道由公共邮件设施提供 |
| 任务中心 | 查看进度、结果、失败原因；按权限重试或取消 | 是持久任务的用户入口；任务结果是否共享取决于业务对象权限，不按创建者一律私有 |
| 企业业务设置与审计 | 模块配置、知识库管理员委派、操作追踪 | 模块授权在本区；企业创建、成员资格、租户角色和归区由中央管理 |

知识库共享不等于所有成员均可编辑。邮件设置共享不等于所有成员均可配置、发送或读取凭据。CRM 操作仍分别校验查看、修改、删除、导出等权限。AI 会话默认本人可见是建议值，成员间共享和管理员查看策略仍待确定。

## 2. 服务区组件及区外依赖

[对应图：服务区组件与能力](https://ai.desk99.cn/diagrams/?diagram=zone-components)

| 组件 | 核心职责 | 持久状态与扩展边界 |
| --- | --- | --- |
| React + Vite 工作台 | 业务页面、AI 流式展示、任务进度、错误与重新登录导航 | 页面不作为业务数据或聊天历史的唯一存储；不持有服务密钥 |
| Java 21 / Spring Boot API | 验证企业成员与权限、业务事务、任务提交、WeKnora 和公共设施适配 | 初期按模块组织应用；每个业务模块不必独立部署为微服务 |
| 持久任务与调度 | 入队、领取、租约、重试、并发与执行状态 | 选择 PG 任务表或消息中间件后续确定；任务状态必须可恢复 |
| Java Worker 池 | 执行获客、背调、邮件、导出等耗时任务 | 同机分进程或增加服务器；共用所属区业务库，按任务类型与企业限制并发 |
| PostgreSQL 业务库 | CRM、邮件配置、模块授权、任务、结果引用、审计及系统映射 | 每区独立，区内共享表以 tenant_id + 强制 RLS 隔离；不为 Worker 建 SQLite 主库 |
| WeKnora 服务及处理组件 | 企业知识管理、解析索引、检索问答、会话与消息持久化 | 与 Java Worker 分开调度；多实例、外部业务工具桥接和会话接续按所选版本验证 |
| WeKnora 专用数据库 | 本区知识索引、会话、消息与引用 | 由 WeKnora 管理内部表，Java 仅通过正式接口操作，不直接写表 |

| 区外依赖 | 提供什么 | 边界 |
| --- | --- | --- |
| 中央与 SSO | 登录、企业目录、成员资格、租户角色、企业归区 | 中央是身份与归区权威，浏览器获授权后直连节点，业务请求不必全部经中央代理 |
| 公共文件服务器 | 知识原文件、附件、图片、导出文件 | 所有区共用存储；每次上传、预览、下载仍检查企业和对象权限 |
| 公共邮件设施 | 邮箱存储、收信、外发及回执 | 每区保留自己的企业邮件业务；外发接受与最终投递成功是不同状态 |
| 模型与搜索供应商 | 模型推理、搜索和其他外部资料 | 仅服务端调用，控制凭据、超时、配额；外部内容不构成执行授权 |

## 3. 数据与请求的共同规则

中央拥有企业成员与归区权威；本区拥有 CRM 等业务主数据和模块授权；WeKnora 拥有知识与会话正文；公共文件设施保存文件内容。通过明确的企业、成员、会话、任务、业务对象和文件标识关联，不通过跨库直接写表联动。

每个企业业务对象带 tenant_id，唯一约束和业务外键保留企业身份。API 和 Worker 使用非表所有者、非超级用户且无 BYPASSRLS 的账号，在同一事务内设置已验证的企业、成员与权限上下文，读写都受 RLS 约束。对象 ID、浏览器企业参数、任务载荷和模型生成的参数均不构成授权。

所有路径都要遵守成员撤权和企业归区变化；中央不可用不能当成授权成功。会话过期按现有强制重新登录流程处理；无操作权限显示拒绝，暂时服务故障显示可恢复错误，不把它们冒充会话过期。中央租户角色与本区模块授权共同决定操作能力。

持久任务不保存浏览器登录 Cookie。发起成员离开企业或失去操作权限后，不能继续以旧授权执行；未来若需要企业级自动任务，应另行定义受限机器身份及授权规则，不能借用永久用户权限。

## 4. 流程一：进入企业工作台

[对应图：企业入口与授权](https://ai.desk99.cn/diagrams/?diagram=enterprise-entry)

1. 用户通过中央和 SSO 登录，中央确认账号、有效成员资格及所选企业归区。
2. 中央为目标节点签发短期一次性票据；浏览器跳转该企业所属节点，节点向中央兑换并验证票据。
3. 节点建立持久会话，加载本企业业务入口与有效权限；后续请求继续向中央复核，长流按现有机制周期复核。
4. 切换企业时重新取得对应企业的入口与授权，清除前一企业的页面状态；不能复用前一企业权限或会话对象映射。

现有基础使用 45 秒一次性票据、mTLS 和短期机器凭据。中央拒绝或不可用时不得访问业务数据；会话过期重新登录，明确撤权拒绝业务请求。导航可见性不替代 API 授权。

## 5. 流程二：普通业务读写

[对应图：业务请求与数据事务](https://ai.desk99.cn/diagrams/?diagram=business-request)

以新增客户或修改企业邮件设置为例：页面提交操作 → API 校验节点会话、中央成员资格和本区模块权限 → 校验对象企业归属与业务参数 → PG 事务设置局部上下文 → RLS 下读写并记录审计 → 提交后返回结果。

建议创建类操作使用幂等标识，避免重复点击创建多条业务记录；共享记录的更新需要检测并发修改，冲突时提示刷新或合并，不能静默覆盖其他成员修改。外部文件或邮件调用不放在长时间占用的数据库事务中。

事务失败则返回明确错误，不显示已保存。若操作需要调用多个外部系统，应记录阶段与关联标识以便补偿或重试；本区 PG 与 WeKnora 之间不存在天然跨库原子事务。

## 6. 流程三：耗时任务与任务中心

[对应图：Worker 横向扩展](https://ai.desk99.cn/diagrams/?diagram=worker-scaling)

页面或 AI 工具发起获客、背调、邮件等操作 → API 授权并保存持久任务 → 返回 job_id 与排队状态 → Worker 互斥领取并取得租约 → 重新验证权限 → 执行外部调用及业务计算 → 提交前复核权限与租约 → 保存结果和审计 → 页面通过 API 查询或订阅进度。

建议任务状态为排队、执行中、成功、失败、取消、权限拒绝，并用重试次数和下一次执行时间表示可重试过程；具体枚举名不作为现有数据库契约。领取、心跳和完成必须绑定同一次租约，超时旧 Worker 不得覆盖新执行结果。

重试针对同一业务意图保持幂等。取消排队任务可阻止执行，取消运行任务需协作检查；已经完成的外部副作用不能靠取消撤回。邮件执行结果不确定时先核对供应商结果，不能把 Worker 中断直接当成发送失败并重发。

同区 Worker 使用相同业务库并按任务类型分配能力，不随扩容复制企业业务数据。Java 任务和 WeKnora 知识任务分别调度，任务中心可以通过适配展示两类状态，但不得混领队列。

## 7. 流程四：企业知识入库

[对应图：企业知识入库与使用](https://ai.desk99.cn/diagrams/?diagram=knowledge-flow)

租户管理员或受委派的知识库管理员上传资料 → Java API 校验当前企业及知识管理权限 → 原文件保存到公共文件设施并记录归属 → 经 WeKnora 接口提交到企业唯一知识库 → WeKnora 解析、切分和索引 → API 获取处理状态 → 完成后企业成员可以检索、阅读及 AI 引用。

上传成功与索引就绪是不同状态，解析失败应展示失败原因与可重试入口，不把尚未索引的文件标为可检索。文档更新和删除需同步知识索引与文件引用，具体版本和清理策略后续确定；删除前也要验证知识管理权限。

文件、WeKnora 入库与业务映射分属不同系统，建议以可重试阶段和幂等关联标识处理部分失败，不宣称全链路由单个 PG 事务保证。检索前验证有效成员与企业知识库绑定，公共文件路径不能代替授权。

## 8. 流程五：AI 对话、工具与历史

[对应图：AI 会话与业务工具](https://ai.desk99.cn/diagrams/?diagram=ai-session)

建议采用单一会话权威：WeKnora 管理会话、消息、知识检索和对话运行；Java 负责企业身份适配与全部业务工具的授权执行。工作台经 Java 进入 WeKnora，不能让现有 ChatService 与 WeKnora 分别维护两套正式会话历史。

1. 工作台提交当前企业、会话标识和本次消息；Java 重新授权并验证会话所属企业与成员映射，不信任浏览器拼接的完整历史。
2. 经 WeKnora 接口创建或恢复会话，持久记录本轮输入，再进行检索、模型推理与回答。纯对话、知识问答和业务工具可在同一会话中衔接。
3. 模型需要业务操作时，使用待验证的工具桥接调用 Java。服务端绑定企业、成员、会话和调用标识，并校验工具白名单、参数、对象归属、当前权限及所需确认；模型不得自行选择其他企业身份。
4. 短操作通过相应业务模块返回结果；耗时操作创建本区持久任务并返回 job_id。排队回执必须显示任务未完成，不能被 AI 描述为执行成功。
5. 工具调用与结果关联同一会话；任务完成后页面可展示任务结果。是否自动唤醒模型生成后续总结单独验证，不能假定已有异步回调续聊能力。
6. 流式回答完成后以持久结果为准；重新进入时从 WeKnora 读取同一会话历史。断流或存储失败要记录可恢复状态，不把未保存的回答标为已保存，也不重复执行已有副作用。

| AI 操作类别 | 建议交互规则 |
| --- | --- |
| 查询 CRM、检索企业知识等只读操作 | 具备读取权限后直接执行，记录关联标识 |
| 创建、修改客户或提交批量任务 | 展示对象范围与关键参数，按明确业务意图执行；模糊或批量变更先确认 |
| 发邮件、删除、批量覆盖等外部或破坏性操作 | 展示具体收件人、内容、对象与范围，确认绑定本次参数和业务意图，执行前再授权 |

上述是工具交互建议，具体动作清单与确认策略在实现前确定；用户在页面明确点击发送本身可构成该次发送确认，不要求机械地重复确认。

接入验收必须验证所选 WeKnora 版本能否完成 Java 业务工具桥接、原生会话持久化、流中断恢复及 API/网页历史归属映射。不能把普通知识查询接口当成任意对话导入接口，也不能把一个企业 API Key 当成成员身份。若接口能力不足，先明确适配或扩展方案并验证，再接入正式会话路径；不能通过直接写其内部表或悄悄丢弃历史绕过。

现有 Java 多模型与只读工具实现可作为协议和工具适配参考；未来普通聊天、知识问答及工具调用的统一路径需要实际验证，本文的编排方案是建议，不宣称 WeKnora 已支持现有全部模型协议或业务工具。

## 9. 流程六：外贸业务闭环

[对应图：服务区内业务协作](https://ai.desk99.cn/diagrams/?diagram=zone-business)

准备企业与产品知识 → 配置目标市场并发起获客 → 筛选去重并沉淀 CRM → 选择客户做背调 → 报告和评分回写 CRM → 结合企业知识生成邮件草稿 → 有发送权限的成员确认发送 → 公共邮件设施投递、收信及回执 → 本区记录沟通并关联客户 → 更新跟进状态，进入下一轮开发。

AI 是这条业务链的另一操作入口，页面和 AI 必须调用相同业务模块与权限逻辑，不能维护两套客户或发送流程。背调和草稿都应保留引用依据；生成草稿不等于发出邮件，供应商接受不等于最终送达。

收信或回执可能来自周期同步或事件回调，具体方式后续确定；接入必须认证来源、定位企业邮箱并去重，不能通过任意浏览器提交的邮箱或客户 ID 归属消息。无法可靠匹配客户的邮件保留待关联状态，不能猜测归属到其他企业。

## 10. 建议的模块边界与开发顺序

建议 Java 模块按 CRM、获客、背调、邮件、知识适配、AI 工具、任务调度、业务设置和审计组织，共享经验证的企业上下文。API 与 Worker 是不同执行职责，业务规则复用，避免各自实现不同权限和状态机；这不是立即拆分多个微服务的要求。

| 顺序 | 开发内容 | 主要验收产出 |
| --- | --- | --- |
| 1 | 明确模块授权和数据契约，保留已有认证路由及 RLS | 两企业隔离、同企业共享、撤权与连接池上下文测试 |
| 2 | 验证 WeKnora 身份映射、唯一知识库、会话持久化和 Java 工具桥接 | 跨企业拒绝、授权编辑、历史恢复和工具调用证据；尽早发现接口缺口 |
| 3 | 建立持久任务契约、任务中心及独立 Java Worker 执行入口 | 多实例互斥、租约恢复、权限复核、幂等及取消边界 |
| 4 | 迁入 CRM 与获客，再接背调、邮件和跟进 | 数据保留、共享权限与完整业务闭环 |
| 5 | 将已验收业务模块接入 AI 工具并验证区内扩展 | 页面与 AI 行为一致，副作用确认、任务关联与重入不重复执行 |

顺序允许并行准备，但不能在会话持久化或企业隔离未经验证时宣称接入完成。约 120 人是 8 核 16GB、22Mbps 服务区的容量目标，不代表已验证 120 个重任务同时运行；Worker 扩展、数据库和供应商配额需要分别评估。

## 11. 当前源码基础与待实现范围

| 证据位置 | 目前可复用的基础 | 不能据此认定已完成 |
| --- | --- | --- |
| backend/.../NodeBrowserAccess.java 与 NodeBrowserController.java | 中央票据兑换、节点持久会话及授权 | 完整业务模块和新模块权限模型 |
| backend/.../NodeStore.java 与 migrations/node/001_business.sql | 企业事务上下文、RLS、基础记录及导出任务 | 本文 CRM、邮件等完整业务表 |
| backend/.../NodeJobWorker.java | 受限连接池、导出任务领取及执行前后中央复核 | 独立多机 Worker 发布、完整心跳治理及所有业务任务类型 |
| backend/.../NodeChatController.java、ChatService.java、ChatTools.java | 多模型流式聊天、时间与报价两个只读工具 | WeKnora 接入、企业业务工具和服务端持久会话 |
| frontend-react/src/main.jsx | 流式展示、工具状态与当前页面历史 | 当前历史随请求传入，不是正式持久历史库 |

以上为本次源码核对范围，不是新的生产验收。WeKnora、多机 Worker、获客/CRM/背调/邮件重构和公共设施接入均需逐项实施。旧 /root/dev 仅作已阅读的业务参考，不重新引入旧 Vue、Python 业务服务或 SQLite 主库。

## 12. 待确定事项与验收边界

待确定：WeKnora 版本及工具桥接方式、会话成员共享/管理员查看策略、具体模块权限矩阵、任务队列技术、收信同步方式、文档版本与删除策略、模型供应商能力和配额、备份 RPO/RTO 与高可用部署。

开发验证至少覆盖：不同企业相同对象 ID 不串数据；同企业成员共享业务但受操作权限限制；离职或撤权后 API、工具、Worker、知识及文件访问均拒绝；重复提交和租约超时不重复产生业务副作用；知识索引失败可重试；会话刷新恢复、断流和异步任务状态真实；邮件发送与回执正确区分。

业务变更按 AGENTS.md 和 docs/spring-boot.md 执行 Java、前端及独立数据库集成测试。本文与地图的验收只证明文档和可视化发布，不代表对应业务已实现，也不授权清空或覆盖生产数据。

### 2026-10-08 知识资料删除实现补充（已发布，验收见 knowledge-delete-release-20261008.md）

知识资料删除采用节点持久任务与独立 WeKnora API 协议，详见 [可靠删除协议](knowledge-delete-api-v1.md)。受理时锁定资料并标记删除中，阻止预览、编辑、共享审批及解析回写；Worker 领取租约后复核中央权限和知识库绑定，经 API 清理原件、解析内容与向量，核对操作身份及完成证据后提交。失败持久保留、退避重试，旧租约不能完成新任务。两端数据库不共享事务、不直接跨库写表。共享文件保留至最后有效引用释放，备份和历史审计不属于在线资料清理范围。