# Cube 企业应用与 AI 平台开发手册

版本 2.0（详细图解版） · 2026 年 11 月 22 日

本手册面向负责需求梳理、平台配置、应用开发和集成测试的实施团队。开发工作建议采用“小场景、短闭环、留证据”的方式：先确认真实业务对象和负责人，再连接资源，然后逐步加入流程、语义和 AI 能力。

> 本手册以 Cube 源码中的 Portal、Admin、Design、Backend 与业务服务接口为参考，不等同于某个客户环境的实施承诺。具体菜单、License、扩展、外部集成、部署方式和功能状态应以目标版本及现场权限为准。

## 开发生命周期

![应用开发与交付六个检查点](/docs/cube/diagrams/development-lifecycle.svg)

```text
业务目标与边界
      ↓
组织身份与数据来源确认
      ↓
应用数据 / 流程 / 页面 / 报表
      ↓
知识与业务语义建模
      ↓
智能体 / Harness / 业务编排
      ↓
权限、异常、回执与运行审计
      ↓
版本、交付、回归及运维
```

建议每个场景明确：业务负责人、使用角色、涉及的应用与单据、数据源、只读或写入边界、审批人、外部服务负责人及验收人。未确认的依赖登记为阻塞项，不要先用演示数据伪装生产接入。

## 开发环境与协作

1. 按部署指南准备兼容的 Node.js、pnpm、Java/Maven、数据库和缓存，再启动实际采用的 Portal、Admin、Design 与后端服务。
2. 记录前后端版本、环境名称、License 能力、登录身份及目标应用。不同用户可能看见不同菜单和资源。
3. 将本地、集成、验收与生产环境分开。凭据应使用受控服务端配置，代码与文档不得提交令牌、密码或客户数据。
4. 开始前确认目标版本的源码与对应配套指南。不要把未提交开发分支中的接口推断为已部署接口。

## 本机联调、工具链与配置详解 {#environment}

### 仓库结构与代码阅读路线

| 目录             | 职责                                   | 首先查看的内容                           |
| ---------------- | -------------------------------------- | ---------------------------------------- |
| apps/portal      | 员工门户与业务使用端                   | router/routes/modules、api、业务页面     |
| apps/admin       | 组织、安全、模型与系统治理             | org、system、AI 管理客户端与页面         |
| apps/design      | 低代码与 AI 设计端                     | 应用、表单、BPM、报表、语义 API 与设计器 |
| apps/backend     | 后端装配与 AI 相关控制器               | BootApplication、rest、配置与领域调用    |
| apps/service     | 认证、门户、流程、知识、语义等领域服务 | Controller → Service → 数据与权限        |
| platform         | Maven 父配置与平台依赖                 | ac-parent、BOM 和公共版本                |
| docs/ai-platform | 安装、运行与能力契约                   | 安装指南、支持矩阵、对应模块指南         |

建议从“页面路由 → API 客户端 → Controller → Service → 持久化/外部调用 → 对应测试”阅读。前端出现一个按钮并不能证明后端已接通；指南中的历史验收也不能替代当前分支与部署版本核验。

### 工具链基线

当前根 package.json 声明 Node.js `>=20.10.0`、pnpm `>=9.12.0`，并固定 `pnpm@10.12.4`。支持矩阵给出的前端构建基线是 Node.js 22.14.0，Java 运行基线为 JDK 21，字节码目标为 17，后端采用 Spring Boot 3.3.3。最低引擎约束与实际交付基线是两个口径，应优先按目标交付矩阵选择。

DSH、沙箱、插件或独立工程可能需要不同 Node/JDK，不能因为门户构建通过就认定所有工程工具链相同。Maven、数据库、缓存及可选组件的精确版本以平台源码 `docs/ai-platform/support-matrix.md` 为准。

```bash
# 在 cube-dev-package 仓库根执行；这里只给命令，不替现有平台安装或重启。
node --version
pnpm --version
java -version
mvn -version
pnpm install --frozen-lockfile
```

若锁文件与 package.json 不一致，先核对工作区与提交版本；不要直接改用另一套包管理器生成新的锁文件掩盖差异。

### 三个前端的独立启动

根 scripts 提供以下入口，分别在独立终端运行，后端和中间件需事先就绪：

```bash
pnpm run dev:portal
pnpm run dev:admin
pnpm run dev:design
```

对于当前 Nginx 聚合的 macOS 联调方式，三个应用还提供 `dev:nginx`。分别进入 `apps/portal`、`apps/admin`、`apps/design` 后执行 `npm run dev:nginx`，使用 pnpm 安装依赖、npm 执行已有脚本。该路线保留公开入口 `http://127.0.0.1:18086`，映射到本机 Portal 15777、Admin 15888、Design 15999；这些端口属于当前联调方案，不适用于所有安装。

浏览器、OAuth 回调和跨端导航使用同一公开来源，不混用 localhost 与 127.0.0.1。容器访问本机进程时使用该路线配置的 `host.docker.internal`，容器之间用服务名；宿主进程则使用宿主映射端口。

### 后端调试与配置来源

已核对的 IDEA 路线使用主类 `com.redxun.BootApplication`、模块 `ac-boot`，工作目录为平台仓库根。JDK 优先使用交付基线 21，开发 profile 和配置文件在 Run Configuration 中明确设置。不要假定根目录 `.env` 会自动进入 IDE 进程。

```text
-Dspring.profiles.active=dev
-Dspring.config.import=optional:file:PATH_TO_LOCAL_ENV[.properties]
```

将示例路径替换为本机受控配置文件。`optional:` 允许文件不存在，所以“应用未报文件缺失”不代表配置加载成功；检查数据库与服务地址的实际来源，但不把密码打印到普通日志。生产环境不得直接照搬开发 profile。

### 配置分层与服务依赖

| 层次         | 平台指南中的位置      | 维护原则                                |
| ------------ | --------------------- | --------------------------------------- |
| 基础配置     | .env                  | 功能开关与镜像选择，和现场配置区分      |
| 现场配置     | .env.prod / .env.test | 地址、端口、密钥、License、稳定数据目录 |
| 自动地址配置 | cube/.env.runtime     | 安装器生成，不手工覆盖自动生成结果      |
| 包内常量     | release.env           | 制包器生成并校验，随发行包管理          |

数据库与 Redis 是平台核心依赖；全文、向量、消息、对象存储和文档服务按启用模块核对。默认 PostgreSQL 全文不要求 Elasticsearch，向量可用 pgvector，但 embedding 必须独立可用。可选服务未启用时，应显示明确边界，不把配置目录中的服务名当成已运行能力。

容器环境变量变更后，普通 restart 不会重新加载新的容器环境，应采用原部署路线和原 Compose 参数重新创建相关容器。不要对存量业务环境执行新库初始化或删除数据卷。

### 开发验证与构建

以下命令来自各前端 package.json，可在根目录选择需要的应用执行：

```bash
pnpm -F @lowcode/portal run typecheck
pnpm -F @lowcode/admin run typecheck
pnpm -F @lowcode/design run typecheck
pnpm -F @lowcode/portal run build
pnpm -F @lowcode/admin run build
pnpm -F @lowcode/design run build
```

生产构建可能需要较大内存，部分脚本显式设置 8GB 或 16GB 堆。类型检查、单组件构建、专项测试和完整交付构建分别记录，不把某一个通过写成全部通过。后端多模块依赖和私有制品应按平台部署指南构建，不随意绕过依赖链。

环境验收依次检查服务状态、公开入口、登录、License、组织角色、应用读写、文件预览、模型绑定与知识检索。把失败定位在对应层，不用“所有端口都通”代替业务验收。

## 推荐实施顺序

### 1. 定义业务场景

把“建设智能办公平台”改成可验收的问题，例如：“采购申请按金额路由审批，审批人可在门户办理，系统按审批结果更新采购单并发送站内通知。”

形成简短场景卡：目标角色、触发条件、输入、业务对象、输出、写操作、失败处置、验收例子。若业务规则尚未确认，先记录待决事项。

### 2. 核对组织、身份和权限

在目标环境确认租户、组织、人员唯一标识、角色、访问范围、认证客户端和会话有效期。用至少两个业务角色测试菜单、单据、知识、AI 资产和管理配置的正反权限。

SSO 接入时与身份提供方确认协议、回调地址、退出行为、人员映射、令牌更新和时钟要求。禁止依赖隐藏菜单实现授权；后端必须对每次数据读取和写入重新判权。

### 3. 接入数据并构建应用

盘点来源系统的 API、数据表、主键、变更频率、字段字典和数据负责人。选择需要在 Cube 中管理的应用对象，定义主子表、约束、状态、关联与审计字段。

设计时优先建立最小可运行的页面和列表。随后配置按钮、菜单、角色授权与版本。核验创建、查询、更新、删除、附件、空状态、错误回显、主子表一致性及越权拒绝。

AI 生成的资源应检查后再回读原生定义。预览可用不代表数据模型、访问控制、外部连接或交付包正确。

### 4. 配置业务流程

明确每个节点的办理人来源、审批责任、条件分支、表单字段、撤回与超时策略。开发及测试环境至少创建一个真实流程实例，按实际审批链走到预期终态。

抽测条件临界值、审批人缺失、重复提交、驳回、转办、撤回和异常恢复。检查待办、已办与实例历史相互一致，再接入门户聚合展示。

### 5. 建立知识库

确定资料所有人、可见范围、版本和有效期。先试运行少量代表性文件，检查解析状态、分片、搜索结果、引用来源和无结果行为；按业务角色验证知识共享权限。

区分搜索候选、模型回答依据和最终回答。部署或迁移后重新验证向量、问答及重排模型绑定。对过期、冲突和未授权资料建立处置路径。

### 6. 配置业务语义（本体） {#semantic-foundation}

业务语义模块适用于多个应用或智能体需要共享同一套对象关系、字段含义与业务规则的场景。纯文档问答或单个临时只读查询，可先采用知识检索或已有查询能力。

**建议操作路径**：

1. **确认业务域**：选择租户和业务边界，确认管理人和版本责任人。
2. **建立业务概念**：创建客户、合同、设备、工单等实体，定义稳定业务标识、名称、描述与敏感级别。
3. **定义属性和关系**：为属性注明类型、单位、来源和是否敏感；明确对象关系的方向、基数及业务含义。
4. **登记数据资源**：接入受允许的数据库、API 或平台应用资源；检查字段结构和来源授权。
5. **建立资源映射**：把语义属性映射到实际字段，验证类型、空值、编码转换及映射状态。定义不等于接入；没有有效映射就没有可用事实。
6. **编写业务规则**：明确边界条件及未知数据处理，准备正例、反例、边界值和缺失字段样例。
7. **定义受控动作与策略**：区分只读、报告、消息与写入；声明风险、敏感字段、审批要求、预演及权限。
8. **构建场景**：绑定业务域和目标问题，限定可读属性、规则、动作、输入及输出契约。
9. **运行就绪检查**：修复资源、映射、规则、权限和发布版本缺口；保存报告作为评审证据。
10. **发布并绑定**：核验版本内容及消费者，再发布给指定场景或智能体；发布完成后用实际业务问题回归。

**CRM 回款风险示例**：定义客户、合同及回款对象，确认净销售额口径和业务截止日；将授权数据源映射到语义属性；把合同额和逾期条件写成显式规则；把风险报告配置为需预演、审批的动作；检查敏感联系方式不进入 AI 上下文；用命中、未命中及缺事实样例分别回归。

**业务语义验收项**：服务端拒绝无权限域；草稿与已发布版本区分；未映射属性不被当作真实事实；变更版本后旧的运行证据不被沿用；敏感字段按策略限制；审批前高风险动作不得执行；动作回执可以和业务单据核对。

### 7. 配置智能体、提示词、技能、工具与 MCP

先写清楚智能体职责、禁止事项、输入输出和失败时的用户提示，再选择确实可访问的知识、业务语义、技能、工具及 MCP 资源。根据输入输出 Schema 逐项演练，不要仅凭显示名称绑定资源。

提示词模板应标注可变输入和可靠来源。技能定义可复用的方法，不替代资源权限。工具应说明是否会写入、通知或触发外部副作用。MCP 需测试连接、工具发现、参数、认证和返回错误。

逐项测试无知识、无权限、无模型、工具超时、参数缺失、业务拒绝及重复请求。先存草稿，评审绑定与运行边界，再独立发布。普通问答无需把所有可选资产都绑定进去。

### 8. 接入模型网关

按实际模型服务登记提供方、协议、部署类型和模型能力。由管理员在安全配置中保存凭据，再为 `agent.runtime`、`knowledge.answer`、`embedding.retrieve` 等能力选择主备绑定。

执行健康探测后，仍需在目标调用路径完成实际验证。分开检查超时、输入/输出上限、模型退化、内容策略、Token 使用、价格、预算和审计。供应商健康检查可能产生外部请求或费用，应在测试环境使用受控模型。

本手册引用的能力名是接口契约示例；模型能否支持流式、函数调用、视觉、向量或重排，要按网关协议与实际端点验证。

### 9. 构建确定性业务编排

将可重复的业务步骤拆成读取、验证、条件、转换和受控写入节点。为输入、输出和字段映射定义契约。写入操作设置主键、条件、最大影响范围和幂等策略。

以“报价转合同”为例：输入已保存报价 ID → 加载主表和明细 → 校验审批状态 → 转换字段及金额 → 防重创建合同草稿 → 回填来源合同标识 → 读取目标合同核验。

可证明的本地事务才承诺原子性。不同数据库或外部 HTTP 调用之间使用幂等键、业务状态和补偿步骤，不要声称共享事务。测试前后状态、重复提交、并发、超时、部分失败和人工对账。开发 Mock 不应进入生产。

### 10. 规划 Harness 任务

让业务目标先映射到当前用户可用的能力目录和输入契约。任务规划发现信息不足时，先补齐条件；涉及副作用的计划应展示具体对象和参数，并在执行前满足用户确认或领域审批要求。

通过任务 ID、运行 ID 和追踪 ID查看状态、步骤、审批与结果。任务报告应区分已完成、失败、取消及结果未知。写入超时后先查询真实业务状态，再决定是否重试。任务计划不等于 BPM 审批流，也不等于后台定时任务。

### 11. 配置大屏、报表和门户

业务看板优先引用有定义、有来源的指标；写明统计时间、过滤条件、刷新周期和数据延迟。按角色检查图表、导出和分享入口的数据范围。

门户负责把已授权的工作入口汇集起来，不应在门户层复制业务写入规则。接入待办、消息、新闻和业务卡片时，标注来源、刷新状态、链接目标及空数据表现。

### 12. 审计、发布与运行

建立事件关联字段规范。建议在应用、业务编排、智能体、Harness、模型与外部连接器之间传递关联 ID，同时避免将个人信息、凭据和完整敏感提示词写入普通日志。

发布清单至少包含：源码或应用版本、配置导出、权限评审、回归结果、数据映射、模型及连接器配置责任人、备份、升级/回滚方式和现场验收证据。日志保留与访问策略应结合目标组织及合规要求确定。

## 17 模块开发检查清单

| 模块              | 实施产物                               | 必测边界                                 |
| ----------------- | -------------------------------------- | ---------------------------------------- |
| 门户              | 工作台区块、菜单与入口                 | 不同角色的可见和跳转                     |
| 统一待办          | 事项来源与办理链路                     | 实例状态、去重、已办同步                 |
| 统一消息          | 模板、通道与场景接收人                 | 失败、重试、回调和送达状态               |
| 统一新闻公告      | 栏目、发布和下架                       | 权限、内容生命周期与缓存                 |
| 统一安全认证      | 客户端、SSO 与会话策略                 | 回调校验、过期、退出和账户映射           |
| 统一组织          | 人员、组织、角色与映射                 | 同步、离职与数据范围                     |
| 统一应用构建      | 数据模型、表单、页面和版本             | CRUD、权限、主子表和升级                 |
| 统一流程定义      | 节点、条件和办理人                     | 临界值、驳回、撤回及在途变更             |
| 统一大屏或报表    | 指标、模型、图表与发布                 | 口径、刷新、导出和分享权限               |
| 统一知识库        | 文件、解析、共享和问答                 | 来源引用、无结果和越权隔离               |
| 智能体资产        | 提示词、技能、工具、MCP 与绑定         | 输入契约、副作用、认证和发布             |
| 统一 Harness 调度 | 能力目录、计划、任务与结果             | 归属、确认、重试和未知结果               |
| 统一安全审计      | 事件关联、权限和保留策略               | 脱敏、访问控制和跨服务关联               |
| 统一大模型网关    | 提供方、凭据、路由与预算               | 真实健康、能力、费用和故障降级           |
| 统一业务编排      | 步骤、转换、条件与发布快照             | 原子边界、幂等、防重和补偿               |
| AI 应用构建       | 需求、App Spec、资源与版本             | 原生资源回读、实际运行与交付配置         |
| 业务语义          | 域、实体、映射、规则、策略、场景与版本 | 有效来源、敏感字段、就绪、绑定和动作回执 |

## 测试与验收建议

以可重放的业务数据构造验收集，并覆盖以下层次：

1. **页面检查**：桌面及移动宽度、加载、空数据、报错、键盘和链接。
2. **契约测试**：关键读写接口的角色、请求 Schema、租户边界与错误码。
3. **集成测试**：身份、组织、应用、流程、消息、知识、模型和外部连接器。
4. **业务回归**：正常、边界、拒绝、重复、并发、超时和部分成功。
5. **权限与隐私**：不同角色、资源共享和敏感字段访问；检查响应与日志。
6. **运行验收**：从真实触发走到流程/任务终态，保存运行 ID、单据 ID 和实际回执。
7. **交付运维**：备份、版本恢复、告警、升级、许可证和模型配置变化演练。

运行耗时、准确率、并发能力和可用性以目标版本和部署环境实测为准；预览截图或代码单测都不能替代现场端到端验收。

## 问题定位顺序

1. 确认环境、版本、用户、租户、应用与权限。
2. 确认页面资源与后端 API 可达，检查请求的关联 ID 与服务端错误码。
3. 核对资源状态、字段契约、版本、映射、模型能力和依赖服务。
4. 检查计划、审批、流程及业务对象当前状态；判断结果是成功、失败还是未知。
5. 对写操作做回执核对后再重试；对外部消息按投递状态使用幂等补偿。

## 协同模块接入细则

### 门户与统一待办

门户区块应明确数据源、当前用户过滤条件、加载与错误状态。Portal 中聚合任务查询与 BPM 的个人待办是不同接口，集成时先确定事项归属。聚合统计必须与列表采用一致过滤；外部待办应使用稳定来源 ID，跳转办理时由源系统再次认证及判权。

一条典型验收路径是：新建申请 → 提交审批 → 审批人在门户看到事项 → 打开源业务表单 → 办理 → 查询源实例状态 → 门户已办与计数更新。对撤回、转办和重复同步分别检查，不能只测试首屏出现一条卡片。

### 统一消息与新闻公告

在消息中心配置通道、模板、接收人及场景绑定；先预览变量与接收人，再在测试环境触发。按业务 ID、事件类型、接收人建立防重关联，检查任务提交、通道分发、回调、送达与已读各自的状态。

新闻公告独立管理栏目、草稿、发布与下架。调用新闻发布接口不代表自动通知全员；如需消息通知，显式增加业务事件及消息场景。富文本需按平台安全规则处理。公告下架后核对门户可见状态，避免继续展示失效内容。

### 统一安全认证、组织与审计

组织同步先建立来源组织/人员 ID 与平台 ID 的映射，再设计新增、变更、离职及重复导入。分离菜单授权、功能授权和业务数据权限；对 HR、财务、采购等对象分别设计授权测试。人员禁用、会话撤销及在途流程交接应作为独立步骤核验。

安全审计不仅是会话列表。部署时应列出认证会话、系统操作、AI 任务、模型调用、业务语义及编排节点各自的日志位置、访问角色、保留期和关联字段。会话强制退出属于管理写操作，不应嵌入普通诊断脚本。

### AI 应用构建与交付

先用需求分析确认对象、流程、页面、权限和验收，再通过当前模型侧工具 `delivery_app_plan`、`delivery_app_get`、`delivery_app_run`、`delivery_app_status` 推进资源计划和执行。每次运行前检查工具实际暴露的 Schema、当前应用、确认要求和写入影响。

上述工具名是 MCP/DSH 工具契约，不是 REST URL，也不是可以直接执行的 shell 命令。保存应用草稿、运行验证、发布、导出与目标端安装分别记录证据。高码与混合应用还需核对源码、依赖、数据库范围、受管文件、签名服务、License 和安装目标；遇到配置缺失先修复，不把草稿导出作为生产交付成功。

## 分模块开发与操作详解

以下 17 章按实际模块展开。操作步骤用于测试环境；会产生业务写入、通知、发布或模型调用的动作，应使用已确定的测试范围和当前授权。每章的截图、课程和讲义可互相对照，课程中的 UI 是真实产品关键帧与教学标注。

## 模块 01：门户 {#module-portal}

**适用角色**：员工 / 门户管理员。**建议入口**：门户 → 工作台。实际菜单以部署版本与当前权限为准。

### 配置目标与实施步骤

**目标**：让员工从工作台准确找到有权使用的应用、任务、知识与智能体。先准备员工、部门负责人、门户管理员三个测试角色，以及至少一个可正常打开的业务应用。

1. 登录 Portal，检查工作台、审批中心、知识库、应用中心、智能体和消息的实际可见范围，记录与角色的对应关系。
2. 进入应用中心，按应用名称或编码搜索，核对应用归属、图标、描述和目标地址。使用有权限与无权限两个账号分别验证。
3. 把允许的应用设为常用，返回工作台检查入口；收藏关系变化不应修改应用本身的访问权限。
4. 逐一打开待办、消息、新闻和知识卡片，记录查询来源与跳转参数，检查空态、失败与刷新。
5. 配置岗位快捷入口时核对 PC/移动地址和统一公开来源。外部系统使用自己的授权检查；SSO 用户映射需要单独验收。

### 数据与接口接入

`PortalDashboardApi` 位于 `apps/portal/src/api/portal/portalDashboard.ts`。该客户端包含申请、待阅、待办、已办、协同、任务统计、消息、新闻、应用收藏与日程接口。列表请求中存在 `pageNo`、`pageSize`、`sortField`、`sortOrder`、`params` 等字段，具体过滤条件沿用对应服务的查询契约，不自行拼出通用过滤协议。

| 区域 | 实施需要保留的信息               | 验证方法                               |
| ---- | -------------------------------- | -------------------------------------- |
| 应用 | 应用 ID/编码、可见范围、目标地址 | 收藏后重新登录、无权身份、应用停用     |
| 待办 | 原任务、实例与单据 ID            | 从聚合列表打开来源详情，再核对当前状态 |
| 新闻 | 栏目、内容 ID、发布状态          | 发布前后分别查询、下架后检查缓存       |
| 知识 | 库/文档 ID 与授权范围            | 点击引用和下载，确认权限一致           |

### 常见问题与验收

“菜单存在但点不开”先检查接口授权与目标路由；“工作台数量为零”先区分真实无数据与接口失败；“收藏还在但应用不可用”检查应用状态与角色授权，不直接删除用户收藏来掩盖错误。验收至少保留两个角色的菜单、一次应用搜索、一次任务深链接及一次来源服务失败的页面表现。

### 门户：真实界面与操作视频

![门户真实产品界面：应用搜索 · AI-CRM实际筛选结果](/academy/screens/portal-app-search.webp)

图中为已采集的真实产品界面。阅读时重点核对“进入常用应用”涉及的入口与资源；示例或空态以演示环境为准。

[观看《门户》完整动态操作课程](/academy/portal) · [下载本模块操作讲义](/academy/portal/guide.md) · [查看真实界面原图](/academy/screens/portal-app-search.webp)

```academy-video
portal
```

[对应技术原理与能力边界](/docs/cube/whitepaper#module-portal)

## 模块 02：统一待办 {#module-todo}

**适用角色**：业务人员 / 流程实施。**建议入口**：门户 → 审批中心 → 我的待办。实际菜单以部署版本与当前权限为准。

### 先区分任务、实例与单据

准备一张可重复测试的采购或合同单据，明确申请人、当前审批人、实例 ID、任务 ID 与单据 ID。使用测试数据，不把已有真实业务事项当作可随意办理的样本。

1. 从门户审批中心查看“我的待办”，按标题或来源定位测试事项，记录任务与实例标识。
2. 打开详情，检查原业务表单、附件、当前节点、办理人、允许动作及流程历史；只读查看与实际提交分别测试。
3. 按该节点允许的动作提交意见，保存接口业务回执；前端按钮置灰只防止重复点击，后端仍要防并发办理。
4. 返回列表刷新，同时核对待办移出、已办新增、实例状态和源单据变化。
5. 用第二窗口重新尝试已失效任务，确认服务端拒绝重复办理或返回当前状态，而非生成第二次业务副作用。

### 聚合与外部任务适配

门户客户端提供 `POST /task/core/instTask/getMyInstTasks`、`POST /task/core/approvedTask/getMyApprovedTask` 等读取入口；这些是聚合列表接口，不能推断为完成任务的接口。办理动作应使用当前任务详情页实际调用的 BPM 契约。

外部待办适配建议定义来源系统编码、来源任务 ID、业务主键、办理人映射、创建时间、深链接、状态与更新时间。以“来源系统＋来源任务 ID”构建项目防重规则，并设计回调、轮询对账和任务失效处理；这是一种接入规范建议，并非平台所有来源均已有现成适配器。

### 必测用例

| 用例                   | 期望证据                                     |
| ---------------------- | -------------------------------------------- |
| 正常办理               | 原任务、提交回执、历史意见和单据终态相互对应 |
| 无权用户打开深链接     | 服务端拒绝，不返回完整表单或附件             |
| 转办/撤回/他人已办理   | 旧窗口提示任务失效，不继续提交               |
| 网络超时               | 先查询原任务和实例，再判断是否重试           |
| 流程结束但外部同步失败 | 分别记录流程状态与外部执行状态               |

“列表仍在”可能是刷新或同步延迟，也可能是业务失败。先看任务原状态与回执，再检查聚合缓存，不以手工清空列表作为修复。

### 统一待办：真实界面与操作视频

![统一待办真实产品界面：待办详情 · 合同表单与办理入口](/academy/screens/todo-detail-live.webp)

图中为已采集的真实产品界面。阅读时重点核对“打开详情并办理”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一待办》完整动态操作课程](/academy/todo) · [下载本模块操作讲义](/academy/todo/guide.md) · [查看真实界面原图](/academy/screens/todo-detail-live.webp)

```academy-video
todo
```

[对应技术原理与能力边界](/docs/cube/whitepaper#module-todo)

## 模块 03：统一消息 {#module-messages}

**适用角色**：消息管理员 / 集成开发。**建议入口**：管理端 → 消息中心。实际菜单以部署版本与当前权限为准。

### 建立一个采购审批通知场景

前置条件是测试接收人、站内或可用的测试通道、业务事件编码及可访问的测试单据。生产供应商发送涉及实际通知或费用，实施时先在测试范围验证。

1. 在管理端消息中心核对通道和配置，检查通道启用状态、凭据引用、供应商地址与回调规则。
2. 建立审批通知模板，定义标题、正文、摘要与变量。先用模板预览检查缺失变量、中文、特殊字符和业务链接。
3. 配置场景与事件，明确接收人来自申请人、当前审批人还是业务负责人，并检查租户与组织范围。
4. 使用测试业务触发，记录消息任务、分发记录与业务 ID。查看站内收件箱，再核对已读状态。
5. 在受控测试中验证失败、重试与回调，确保重复通知不会因补偿而不断出现。

### 契约与内容模板

`apps/admin/src/api/system/messageCenter.ts` 的 `MessageTriggerCommand` 包含 `sceneType`、`sceneCode`、`eventCode`、`title`、`content`、`receiverIds`，以及可选的 `appId`、业务关联、通道与变量。即使客户端类型中有租户或操作者字段，服务端仍必须从可信身份核对，不能用任意传入值代替授权。

以下是**模板预览数据结构示意**，不是可直接发送的 API 请求体：

```json
{
  "title": "采购申请待审批：{{bizNo}}",
  "variables": {
    "bizNo": "DEMO-PO-001",
    "applicantName": "测试申请人",
    "detailUrl": "已授权的测试单据详情地址"
  }
}
```

`POST /system/message-center/templates/preview` 用于预览，不代表实际发送。具体 body 以 `MessageTemplatePreviewCommand` 为准。接入者应复用项目客户端，而不是照示意 JSON 猜测生产参数。

### 失败定位

| 现象                   | 优先检查                                     |
| ---------------------- | -------------------------------------------- |
| 未生成任务             | 业务事件、场景绑定、模板状态、接收人解析     |
| 任务有但收件箱无       | 通道、分发记录、接收人映射与租户             |
| 供应商成功而状态未更新 | 回调认证、业务关联与重复回调处理             |
| 重复通知               | 触发是否重复、幂等范围、未知结果后是否盲重试 |

验收报告分别记录触发、受理、送达、已读，不合并成一个成功字段。

### 统一消息：真实界面与操作视频

![统一消息真实产品界面：统一消息中心 / 模板管理](/academy/screens/messages-templates.webp)

图中为已采集的真实产品界面。阅读时重点核对“编写并预览模板”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一消息》完整动态操作课程](/academy/messages) · [下载本模块操作讲义](/academy/messages/guide.md) · [查看真实界面原图](/academy/screens/messages-templates.webp)

```academy-video
messages
```

[对应技术原理与能力边界](/docs/cube/whitepaper#module-messages)

## 模块 04：统一新闻公告 {#module-news}

**适用角色**：内容管理员 / 员工。**建议入口**：内容管理 → 新闻公告。实际菜单以部署版本与当前权限为准。

### 发布制度公告的操作过程

准备一篇演示制度、一份无敏感内容的附件、两个不同阅读范围的角色，并确认栏目维护人与内容审核人。

1. 在内容管理入口选定栏目，填写标题、摘要、正文、封面与附件，保存草稿。
2. 检查链接、图片、附件权限和内容适用范围；制度类文章补充版本、生效时间与所有人。
3. 按当前部署允许的发布流程操作，再从员工门户验证栏目、详情与轮播等实际配置入口。
4. 用无权角色访问文章详情和附件直链，确认后端限制同样有效。
5. 修改、下架或归档测试文章，核对门户缓存和引用入口；涉及消息与知识库时分别更新。

### 内容集成与变更处理

客户端入口包括 `apps/portal/src/api/portal/insNews.ts` 与工作台的 `getNewsByTypeKey`。实现栏目聚合时，应保留内容 ID、栏目标识、发布状态、发布时间和详情地址，不只复制文章文本。附件在源文件服务中仍须按访问策略校验。

| 变更         | 新闻侧检查             | 关联模块检查                     |
| ------------ | ---------------------- | -------------------------------- |
| 首次发布     | 列表、正文、封面和附件 | 是否需要单独发消息或建立知识索引 |
| 修订制度     | 版本与生效范围         | 旧知识片段是否需要禁用/重建      |
| 下架         | 列表与详情按规则不可见 | 轮播、缓存、外部引用及旧通知链接 |
| 组织范围调整 | 当前角色可见范围       | 已分享地址与附件直链             |

“发布成功但门户无内容”先核对栏目绑定与当前身份，再检查状态、时间过滤和缓存。“文章下架但 AI 仍引用”检查知识库中的独立文档版本；新闻下架不会天然撤销所有已解析副本。

### 统一新闻公告：真实界面与操作视频

![统一新闻公告真实产品界面：新增新闻公告表单](/academy/screens/news-editor.webp)

图中为已采集的真实产品界面。阅读时重点核对“创建内容草稿”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一新闻公告》完整动态操作课程](/academy/news) · [下载本模块操作讲义](/academy/news/guide.md) · [查看真实界面原图](/academy/screens/news-editor.webp)

```academy-video
news
```

[对应技术原理与能力边界](/docs/cube/whitepaper#module-news)

## 模块 05：统一安全认证 {#module-auth}

**适用角色**：身份管理员 / 集成开发。**建议入口**：管理端 → 认证与客户端配置。实际菜单以部署版本与当前权限为准。

### 客户端与统一公开地址

先区分平台客户端、外部身份提供方和业务应用。记录客户端标识、授权方式、回调白名单、公开来源、会话期限、退出策略和账号映射责任人。文档示例不附带客户端秘密。

1. 在测试环境核对 Portal、Admin、Design 的公开来源。当前本机集成入口为 `http://127.0.0.1:18086`，它是本机部署示例，不是所有客户的默认地址。
2. 注册或检查客户端回调，验证协议、主机、端口和路径精确匹配。采用 PKCE 的客户端核对授权码、state 与 verifier 的生命周期。
3. 走一次首次登录、已有会话恢复、令牌刷新和退出，分别记录行为。
4. 测试账户停用、角色撤销、会话过期与管理员强制退出，确认业务接口按当前身份判权。
5. 外部 SSO 接入时先用测试账号验证人员唯一键、重复账号与未绑定账号处理，再扩展到组织同步。

### 源码阅读与会话边界

`apps/portal/src/api/core/auth.ts` 中可核对 `loginApi`、`passwordSessionLoginApi`、`exchangeOAuthCodeApi`、`refreshTokenApi`、`logoutApi` 等入口；认证服务相关实现位于 `apps/service/ac-service-auth`。这些不同登录路径不应在同一项目中未经选择全部启用。

前端路由守卫用于改善交互，服务端授权决定数据是否可访问。令牌不能放到 URL 查询参数、公开日志或前端仓库中；页面路由不是认证协议端点。Cookie、跨域和会话策略以当前部署及认证模式为准，不在客户端临时放宽校验作为正式修复。

### 排错顺序

| 现象                 | 检查顺序                                       |
| -------------------- | ---------------------------------------------- |
| 登录后循环跳转       | 回调地址 → 来源地址 → Cookie/会话 → 客户端配置 |
| 一个端可用另一端失效 | 两端回调、会话恢复、权限和路径代理             |
| 刷新后丢失身份       | 刷新契约、令牌生命周期、存储与服务端会话       |
| 停用用户仍能查询     | 缓存/会话失效策略、后端每次请求检查            |

验收至少包含未登录、正确登录、错误回调、过期、退出和无权访问六类结果。

### 统一安全认证：真实界面与操作视频

![统一安全认证真实产品界面：统一认证 · 实际登录页配置](/academy/screens/auth-settings-live.webp)

图中为已采集的真实产品界面。阅读时重点核对“核对客户端配置”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一安全认证》完整动态操作课程](/academy/auth) · [下载本模块操作讲义](/academy/auth/guide.md) · [查看真实界面原图](/academy/screens/auth-settings-live.webp)

```academy-video
auth
```

[对应技术原理与能力边界](/docs/cube/whitepaper#module-auth)

## 模块 06：统一组织 {#module-organization}

**适用角色**：组织管理员 / 实施团队。**建议入口**：管理端 → 组织、人员与角色。实际菜单以部署版本与当前权限为准。

### 组织主数据实施步骤

确定 HR/IDaaS、ERP 或 Cube 中哪个是人员与组织的权威来源。建立外部人员 ID、平台用户 ID、组织编码、角色编码的映射，不按姓名或展示标题做唯一匹配。

1. 定义组织维度、根节点与编码规则，区分行政部门、项目分组和应用角色。
2. 导入或创建少量测试部门与人员，检查父子关系、启停状态、主属关系和业务角色。
3. 给测试角色分配应用、功能与数据范围，分别验证列表、详情、附件、导出与 AI 资源。
4. 在流程中验证选人结果，特别检查负责人缺失、兼职、跨部门和停用人员。
5. 测试部门移动与人员离职，核对会话、任务交接、共享资源和维护责任，不直接物理删除历史责任记录。

### 同步设计与回归

`OsUserApi` 与 `OsGroupApi` 分别位于 `apps/admin/src/api/org/osUser.ts`、`osGroup.ts`；组织父节点读取可参考 `GET /user/org/osGroup/getByParentId?parentId=…`。实际创建、同步与角色授权接口应逐项核对服务端实现。

| 同步阶段  | 建议输入与控制                     | 核验内容                               |
| --------- | ---------------------------------- | -------------------------------------- |
| 首次全量  | 唯一键、组织树、字段字典、测试批次 | 重复 ID、缺父节点、非法引用            |
| 增量更新  | 来源版本或水位、变更类型           | 重放幂等、乱序与冲突处理               |
| 停用/离职 | 生效时点与责任交接                 | 登录、现有会话、未办任务与共享范围     |
| 对账      | 来源总量、异常项与处理记录         | 平台与来源的一致性，不只看同步任务成功 |

以上是项目同步方案建议，不表示任意外部 HR 系统已有开箱适配。同步失败应保留原数据、失败范围与水位，先修复映射和冲突再重放。

### 统一组织：真实界面与操作视频

![统一组织真实产品界面：组织与成员](/academy/screens/organization.webp)

图中为已采集的真实产品界面。阅读时重点核对“建立组织与人员”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一组织》完整动态操作课程](/academy/organization) · [下载本模块操作讲义](/academy/organization/guide.md) · [查看真实界面原图](/academy/screens/organization.webp)

```academy-video
organization
```

[对应技术原理与能力边界](/docs/cube/whitepaper#module-organization)

## 模块 07：统一应用构建 {#module-application}

**适用角色**：应用开发者 / 实施团队。**建议入口**：设计端 → 应用中心 → 目标应用。实际菜单以部署版本与当前权限为准。

### 示例：采购申请主子表应用

先写字段字典：申请编号、申请人、部门、申请日期、币种、状态、总额；明细包含物料编码、名称、单位、数量、单价、税率与金额。为每个字段明确类型、精度、必填、默认值、来源和可编辑状态。

1. 创建测试应用并登记负责人，建立主表、明细及关联，确认稳定业务主键。
2. 用表单设计器配置布局、主子表编辑、附件和校验。只读或隐藏属性用于交互，服务端仍需验证权限与约束。
3. 创建列表与查询条件，处理分页、排序、空数据、异常和明细打开。
4. 配置菜单与按钮，绑定流程或编排；明确保存草稿、提交审批、撤回和删除的状态限制。
5. 使用两个角色验证新增、编辑、查询、删除、导出和附件，再检查主子表完整回读。
6. 保存版本并核对导出依赖，在测试目标环境安装或恢复后再验收。

### 建模约定示例

以下为**项目字段字典示例**，不代表平台固定字段名或可直接导入 Schema：

| 字段            | 类型建议     | 规则                                               |
| --------------- | ------------ | -------------------------------------------------- |
| requestNo       | 字符串       | 按业务范围唯一，服务端生成或验证                   |
| applicantId     | 稳定用户标识 | 不接受客户端伪造申请人                             |
| currency        | 字典编码     | 明确允许币种及金额换算策略                         |
| items.quantity  | 十进制       | 是否允许零、负数与小数由业务规则决定               |
| items.unitPrice | 定点金额     | 指定精度与舍入；禁止二进制浮点直接累加作为结算依据 |
| status          | 状态编码     | 仅允许已定义的状态迁移                             |

金额由服务端或可信业务规则重新计算，不能信任页面传入总额。更新时检查版本冲突与主子表关联；删除明细、上传附件后保存失败等路径也要验证。

### 资源回读与故障定位

应用资源入口可从 `apps/design/src/api/system/sysApp.ts` 与原生资源指南开始。列表、表单、定制页面和大屏应使用各自资源契约，不能仅保存一段 HTML 就认为原生应用已完成。若设计器能预览而员工端打不开，优先检查发布版本、资源引用、菜单与角色；若保存成功但明细缺失，检查服务端主子表契约和完整单据回读。

### 统一应用构建：真实界面与操作视频

![统一应用构建真实产品界面：小型进销存 / 业务模型](/academy/screens/application-model.webp)

图中为已采集的真实产品界面。阅读时重点核对“设计主子表模型”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一应用构建》完整动态操作课程](/academy/application) · [下载本模块操作讲义](/academy/application/guide.md) · [查看真实界面原图](/academy/screens/application-model.webp)

```academy-video
application
```

[对应技术原理与能力边界](/docs/cube/whitepaper#module-application)

## 模块 08：统一流程定义 {#module-workflow}

**适用角色**：流程设计者 / 审批人员。**建议入口**：设计端 → 流程定义。实际菜单以部署版本与当前权限为准。

### 示例：按金额审批采购申请

前置准备是已可保存与回读的采购表单、稳定的状态编码、测试申请人和审批人。先画审批规则，再配置画布，避免用试连节点代替业务确认。

1. 创建流程定义，绑定正确应用和表单，明确开始表单与节点表单可编辑范围。
2. 配置办理人来源，使用实际组织关系测试，不把管理员账号作为所有节点的默认审批人。
3. 添加条件分支，确定币种、金额精度与临界值。例如使用 10,000 作为测试阈值时，应分别测试 9,999.99、10,000、10,000.01；该数值仅为示例规则。
4. 明确通过、驳回、撤回、转办及结束时的单据状态，核对实际部署支持的动作。
5. 保存并按平台发布流程处理，用员工角色发起真实测试实例，逐节点走到预期终态。
6. 对照待办、已办、审批意见和单据状态，记录实例 ID 与每个关键任务 ID。

### 流程与编排的接点

审批完成后触发单据转换，应传来源单据 ID，由服务端重新读取状态、金额和明细。不要用流程页面中的缓存对象直接创建目标合同。外部 HTTP 失败时应明确流程是否已完成、业务动作是否受理，以及后续补偿入口。

| 边界             | 需要明确的处理                             |
| ---------------- | ------------------------------------------ |
| 无有效审批人     | 拒绝发起、转人工或项目约定路径，不静默跳过 |
| 两个窗口重复办理 | 任务有效性与后端并发保护                   |
| 驳回后再提交     | 哪些字段可改、原意见是否保留、是否新实例   |
| 定义升级         | 新实例版本与在途实例策略                   |
| 业务动作超时     | 查询回执与源业务状态后再补偿               |

源码可从 Admin/Design 的 `api/bpm/bpmDef.ts` 与 Portal 流程路由追踪到后端。专项 UI 预览不替代真实实例验证；在途迁移、会签或代理等能力需按当前引擎配置逐项确认。

### 统一流程定义：真实界面与操作视频

![统一流程定义真实产品界面：商机阶段审批 / 真实流程设计器](/academy/screens/workflow.webp)

图中为已采集的真实产品界面。阅读时重点核对“发布测试定义”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一流程定义》完整动态操作课程](/academy/workflow) · [下载本模块操作讲义](/academy/workflow/guide.md) · [查看真实界面原图](/academy/screens/workflow.webp)

```academy-video
workflow
```

[对应技术原理与能力边界](/docs/cube/whitepaper#module-workflow)

## 模块 09：统一大屏或报表 {#module-reports}

**适用角色**：数据分析 / 页面开发。**建议入口**：设计端 → 大屏或报表设计。实际菜单以部署版本与当前权限为准。

### 指标先行的设计步骤

1. 选择业务问题，例如“各部门本月待审批采购金额”，明确统计对象、状态、时间字段、币种及取消/作废处理。
2. 用已核对的业务查询得到基准结果，冻结一组测试样本及期望数值。
3. 创建对应报表或大屏资源，配置数据源、维度、指标、筛选、图表与刷新方式。
4. 设置查看、编辑、分享与导出权限，再在员工端以不同角色对账。
5. 发布后验证时间标签、空状态、接口异常、缓存刷新与移动布局，保存资源和数据口径版本。

### 指标字典与可视化约束

| 指标项   | 示例填写方式                         |
| -------- | ------------------------------------ |
| 指标编码 | purchase.pendingAmount（项目示例）   |
| 数据粒度 | 一张有效采购申请，按主单统计         |
| 过滤条件 | 当前允许的审批中状态，排除作废       |
| 时间字段 | 申请日期或提交日期，二选一并明确时区 |
| 金额口径 | 指定币种、税额与舍入规则             |
| 权限范围 | 当前角色允许的组织与数据范围         |
| 新鲜度   | 查询时点、缓存周期与最近成功刷新     |

前端图表不应通过获取全量数据后再隐藏无权行来实现隔离。统计查询、钻取明细、导出和共享必须使用相同数据边界。跨表聚合先确认关系基数，避免主子表 JOIN 造成金额重复累加。

### 开发入口与排错

源码入口包括 `apps/design/src/api/design/screen/screen-view-manage.ts`、`apps/design/src/api/ai/report-designer.ts` 与 `apps/service/ac-service-screen/`。大屏和报表的保存、发布、历史、分享契约应分别核对，不推断为同一 API。

数值不一致时按“粒度 → 状态 → 时间/时区 → 币种 → 关联重复 → 权限 → 缓存”定位；图表空白时区分无数据、无权限、资源未发布和查询异常。验收同时保留图表值、明细基准及无权角色结果。

### 统一大屏或报表：真实界面与操作视频

![统一大屏或报表真实产品界面：报表设计器 / 排版与字段绑定](/academy/screens/reports.webp)

图中为已采集的真实产品界面。阅读时重点核对“连接授权数据”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一大屏或报表》完整动态操作课程](/academy/reports) · [下载本模块操作讲义](/academy/reports/guide.md) · [查看真实界面原图](/academy/screens/reports.webp)

```academy-video
reports
```

[对应技术原理与能力边界](/docs/cube/whitepaper#module-reports)

## 模块 10：统一知识库 {#module-knowledge}

**适用角色**：知识管理员 / 业务人员。**建议入口**：门户 → 知识库。实际菜单以部署版本与当前权限为准。

### 建立可检索、可引用的测试知识库

准备少量代表性资料：一份制度 PDF、一份操作文档、一份表格以及一份明确无答案的测试问题。先确认资料所有人、共享范围、版本与是否允许传给模型提供方。

1. 创建知识库并设置授权，上传资料，逐份检查解析状态、片段和错误日志。
2. 先验证默认全文链路，用制度里的明确短语检索，核对候选内容、文档和章节来源。
3. 需要向量时配置实际向量存储、embedding 模型与 `embedding.retrieve` 绑定，再重建或验证索引。
4. 需要生成回答时配置 `knowledge.answer`，需要重排时配置独立重排能力；分别测试，不用聊天模型代替所有模型类型。
5. 从问答入口检查答案、来源与原文打开；用无权用户、无答案与过期资料样本测试。
6. 更新资料版本并重建相关索引，核对旧片段是否仍被引用；模型与向量空间变化后重新验收。

### 全文、向量与问答分层诊断

当前部署指南的默认全文策略为 `FULLSEARCH_STRATEGY=postgresql`，基于已解析且启用的片段召回，不要求 Elasticsearch 或 embedding。选择 pgvector 时配置 `VECTOR_STORE_PROVIDER=pgvector`、`PGVECTOR_ENABLED=true`、`MILVUS_ENABLED=false`，并提供实际可用 embedding。上述变量是配置说明，不应未经检查覆盖现有环境。

| 现象                   | 检查层次                                     |
| ---------------------- | -------------------------------------------- |
| 上传成功但检索不到     | 解析任务、片段启用、库权限与全文状态         |
| 全文有结果、向量无结果 | embedding 绑定、维度、向量存储与索引         |
| 搜索有结果、问答失败   | knowledge.answer、模型健康、上下文与内容策略 |
| 回答引用不可打开       | 文档/附件权限、版本与资源地址                |
| 更新后仍答旧制度       | 旧片段禁用、索引重建、缓存与问答上下文       |

### 搜索请求与结果验收

`KbsQueryApi.searchKnowledgeV2` 定义 `knowledgeId`、`query`、`topK` 等参数，对应 `POST /kbs/v2/search`。相似度阈值、检索类型、标签与重排等可选项以该版本客户端和服务端为准。验收不仅看返回非空，还要人工核对首批候选是否相关、引用是否来自授权资料、无依据时是否明确说明不足。

文档内的“忽略权限”“调用某 URL”等文本只能作为资料，不可变成执行指令。将这类样本纳入知识与智能体联合测试。

### 统一知识库：真实界面与操作视频

![统一知识库真实产品界面：打开目录文档 · 真实阅读页面](/academy/screens/knowledge-reading-live.webp)

图中为已采集的真实产品界面。阅读时重点核对“验证搜索和引用”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一知识库》完整动态操作课程](/academy/knowledge) · [下载本模块操作讲义](/academy/knowledge/guide.md) · [查看真实界面原图](/academy/screens/knowledge-reading-live.webp)

```academy-video
knowledge
```

[对应技术原理与能力边界](/docs/cube/whitepaper#module-knowledge)

## 模块 11：智能体与能力资产 {#module-agents}

**适用角色**：智能体开发者 / 业务专家。**建议入口**：设计端 → 智能体、提示词、技能、工具与 MCP。实际菜单以部署版本与当前权限为准。

### 从只读助手开始建立资产组合

前置条件是一个可用的 `agent.runtime` 或实际业务所需能力绑定、授权测试知识库，以及已确定的只读业务范围。先让助手能正确回答和拒绝，再接入写入型工具。

1. 定义智能体目标、适用角色、输入、输出、依据不足时行为与禁止操作，建立提示词模板。
2. 绑定知识并测试引用，保存稳定样例；把重复任务方法整理为技能，说明依赖和前提。
3. 登记工具的输入输出 Schema、身份、读写性质、超时、幂等和回执；先用固定合法参数做独立测试。
4. 配置 MCP 服务时核对服务来源、认证引用、工具目录与白名单。连接测试之后逐个验证允许工具。
5. 创建或更新智能体草稿，回读绑定与所属应用；分别验证普通问答、工具调用、错误参数与无权请求。
6. 审阅后按实际发布入口发布，保存绑定版本、模型能力与测试记录。

### 创建、更新与空数组的含义

配套指南 `dsh-agent-configuration.md` 明确，更新时“不传绑定数组”表示保留，传 `[]` 表示清空，非空数组表示替换。更新 `applicationId` 不传表示保留，传 `null` 表示解除关联，传真实 ID 表示迁移且须验证两侧授权。

以下为指南中的**蓝图内容结构示例**，不是完整 HTTP 请求；`requestId` 和外层工具参数应以当前 `delivery_agent_plan` Schema 为准：

```json
{
  "name": "采购制度问答助手",
  "description": "依据已授权制度解释采购要求",
  "prompt": "使用中文回答，注明资料依据；没有依据时说明不足。",
  "openingMessage": "请描述采购问题。",
  "suggestedQuestions": ["采购申请需要哪些附件？"],
  "configurationNotes": "先保存草稿，审阅后单独确认发布。",
  "configuration": {
    "knowledgeBases": [{ "id": "REPLACE_WITH_AUTHORIZED_ID", "bindType": "knowledge" }],
    "tools": [],
    "skills": [],
    "mcpBindings": [],
    "permissions": []
  }
}
```

该示例的空数组适合明确创建空绑定，不能直接用作局部更新已有智能体。六个蓝图基础字段的必填要求和所有枚举以当前工具 Schema 核对。

### 写入型工具与失败处理

读取客户信息与提交跟进单应是可区分的契约。写入前校验权限、参数、审批和防重，执行后保存原回执及业务 ID。超时不等于失败，先按幂等键查询结果；不能让模型凭一句“请重试”重复创建单据。评测覆盖恶意资料指令、无权资源、工具缺失、参数错误、流式中断及模型误报完成。

### 智能体与能力资产：真实界面与操作视频

![智能体与能力资产真实产品界面：提示词模板新建配置表单](/academy/screens/agent-prompt-editor.webp)

图中为已采集的真实产品界面。阅读时重点核对“准备技能与工具”涉及的入口与资源；示例或空态以演示环境为准。

[观看《智能体与能力资产》完整动态操作课程](/academy/agents) · [下载本模块操作讲义](/academy/agents/guide.md) · [查看真实界面原图](/academy/screens/agent-prompt-editor.webp)

```academy-video
agents
```

[对应技术原理与能力边界](/docs/cube/whitepaper#module-agents)

## 模块 12：统一 Harness 调度 {#module-harness}

**适用角色**：业务人员 / AI 管理员。**建议入口**：设计端 → Harness / 任务入口。实际菜单以部署版本与当前权限为准。

### 为一个经营周报建立受控计划

准备单部门、已结束周期的授权销售数据，已发布的只读能力入口，以及指标口径和预期报告。前期不配置自动发消息或业务写入，先验证计划、数据和成果。

1. 选择办公/任务场景入口，明确目标、周期、组织范围、数据来源与成果形式。
2. 生成计划后检查能力、参数、依赖、作用域和风险；缺少事实资源或发布绑定时先修复依赖。
3. 人工确认当前计划，保留计划摘要与需求版本；修改参数或计划后重新确认。
4. 启动执行并记录 planId、jobId 或当前契约返回的运行标识，检查每个步骤实际使用的能力与权限。
5. 打开成果及工具回执，核对报告可访问、统计周期与来源正确；模型总结只作解释，不作完成证据。
6. 若加入“发给负责人”等动作，作为独立受控步骤检查接收人、审批与投递回执。

### 状态与证据设计

| 用户看到的结果 | 实施应核对的证据               | 后续处理                     |
| -------------- | ------------------------------ | ---------------------------- |
| 已生成报告内容 | 内容、来源、周期与资源地址     | 可审阅，不推断已发送或已归档 |
| 业务操作已提交 | 工具原始受理号、业务关联       | 按领域接口继续查询终态       |
| 业务已核验完成 | 目标系统结果、核验时间与操作者 | 才可计入真实业务完成量       |
| 结果未知       | 超时/断连信息、原任务与回执    | 禁止盲重试，先查询或人工对账 |

表中为实施分类，不是某个服务的固定枚举。平台计划与办公受控计划可有不同标识，应建立关联而非互相替换。

### 后台任务、取消与恢复

周期任务必须确认调度所有权。`runtime-job-register.md` 将任务区分为 `INTERNAL_SINGLETON`、`XXL_MANAGED` 与 `MIGRATION_REQUIRED`，不能把遗留未启用任务或普通异步线程直接当成可恢复后台调度。

计划后台运行前逐项测试：可信调用身份、持久化状态、任务领取并发、重启恢复、租约、幂等、取消和业务核验。能力发布检查属于配置预检，不会自动把任意 URL 转成安全执行器。写入失败或回执不明时保留原任务，不以创建新任务绕过防重。

源码阅读从 Harness 相关客户端和 AI 的 plan/job 控制器开始；`GET /ai/harness/overview/summary`、`GET /ai/plan/aiPlan/detail?planId=…`、`GET /ai/job/aiJobRun/detail?jobId=…` 可用于相应授权范围的观察。

### 统一 Harness 调度：真实界面与操作视频

![统一 Harness 调度真实产品界面：Harness / 任务详情与待补充条件](/academy/screens/harness-plan.webp)

图中为已采集的真实产品界面。阅读时重点核对“检查计划与审批”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一 Harness 调度》完整动态操作课程](/academy/harness) · [下载本模块操作讲义](/academy/harness/guide.md) · [查看真实界面原图](/academy/screens/harness-plan.webp)

```academy-video
harness
```

[对应技术原理与能力边界](/docs/cube/whitepaper#module-harness)

## 模块 13：统一安全审计 {#module-audit}

**适用角色**：安全管理员 / 运维。**建议入口**：管理端 → 会话、系统日志、AI 治理。实际菜单以部署版本与当前权限为准。

### 建立跨模块审计约定

1. 列出需追踪的关键事件：登录、授权、发布、配置修改、单据动作、流程办理、工具执行、模型调用和资源导出。
2. 为每类事件定义操作者、租户、资源、动作、时间、结果、错误分类和关联标识。统一字段是项目约定，需逐服务确认落点。
3. 从员工入口执行一条测试业务链，收集应用、BPM、编排、Harness 和模型各自原生 ID，形成对应表。
4. 核对失败路径是否同样留下记录，以及业务事务回滚后是否仍可找到失败原因。
5. 设置查询角色、脱敏、导出权限、保留周期、归档与恢复方案，再测试无权人员查询。

### 事件结构示意

以下为**审计设计示例**，不是平台统一接口字段：

```json
{
  "correlationId": "DEMO-CORRELATION-ID",
  "actorRef": "TEST_USER_ID",
  "resourceType": "purchase_request",
  "resourceId": "DEMO-PO-001",
  "operation": "submit_for_approval",
  "outcome": "accepted",
  "evidence": { "workflowInstanceId": "TEST_INSTANCE_ID" }
}
```

不在示例或普通日志中保存令牌、完整凭据、敏感身份证明或未经允许的完整提示词。若审计需要保留更完整证据，应采用专用授权和保留策略。

### 诊断与验收

| 情况                     | 核查方法                                         |
| ------------------------ | ------------------------------------------------ |
| 页面提示成功但无单据     | 追踪业务回执、事务结果与目标查询，不只看点击日志 |
| 运行失败而普通日志无记录 | 检查运行/节点日志、异常收尾与独立事务记录        |
| 同一动作多次出现         | 区分请求、重试、节点执行与重复业务副作用         |
| 审计查不到其他部门       | 先核对当前身份与数据范围，不直接扩大授权         |

配置审计、业务日志、模型成本报表并不自动组成防篡改合规归档。若有此要求，单独设计存储隔离、访问审批、时钟、保留和恢复验证。

### 统一安全审计：真实界面与操作视频

![统一安全审计真实产品界面：安全审计 / 安全策略](/academy/screens/audit.webp)

图中为已采集的真实产品界面。阅读时重点核对“配置访问和保留”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一安全审计》完整动态操作课程](/academy/audit) · [下载本模块操作讲义](/academy/audit/guide.md) · [查看真实界面原图](/academy/screens/audit.webp)

```academy-video
audit
```

[对应技术原理与能力边界](/docs/cube/whitepaper#module-audit)

## 模块 14：统一大模型网关 {#module-model-gateway}

**适用角色**：模型管理员 / 平台运维。**建议入口**：管理端 → 模型网关。实际菜单以部署版本与当前权限为准。

### 端点、凭据与能力绑定

1. 确认 Backend 已装配网关，使用当前租户具有服务端管理员权限的账号进入 Admin 模型网关。
2. 新建端点，填写真实协议、部署类型、模型 ID、基础地址、上下文/输出限制和超时，核对服务可达性。
3. 单独保存凭据；真正无认证的内网服务选择“无需凭据”，不填虚假 Key。更新凭据是整体替换，应检查目标身份。
4. 在能力绑定选择主模型和受支持的备用模型，启用绑定。文本、embedding、重排与视觉能力分别配置。
5. 执行该能力的真实连接测试，再从实际问答、检索、智能体或设计入口跑完整用例。
6. 根据业务需要配置价格、预算和内容策略，保存版本和正反样例；策略默认状态需现场确认。

### 模型能力对照

| 能力                          | 开发要验证的行为                     |
| ----------------------------- | ------------------------------------ |
| task.chat / agent.runtime     | 流式、工具参数、错误与取消           |
| design.generate               | 结构化资源、Schema 与长输出          |
| knowledge.answer              | 文本生成、上下文长度与引用协同       |
| embedding.retrieve            | 维度、索引兼容、重建与相似度         |
| knowledge.rerank              | 重排协议、输入格式与返回排序         |
| vision.chat / embedding.image | 分别验证视觉消息与图像向量，不能互换 |

### 管理接口与配置生效

已核对指南中的相对接口包括 `/ai/model-gateway/admin/providers`、`/bindings`、`/health/check`、`/pricing`、`/content-policy` 与 `/usage/summary`。读取和保存的 HTTP 方法应按具体路由核对，不能把同一前缀假设为全部 GET。管理身份由服务端检查，不接受客户端随意覆盖租户和操作者。

保存 provider、credential 或 binding 会使相关健康状态失效；保存动作本身不发供应商请求。删除端点受能力绑定引用限制，停用绑定中的引用也要核对。删除能力绑定后，该能力会失去路由，调用可能返回 `MODEL_NOT_BOUND`。

### 典型故障

| 故障             | 检查路径                                   |
| ---------------- | ------------------------------------------ |
| MODEL_NOT_BOUND  | 当前租户能力绑定、启用与可见范围           |
| 保存后调用仍失败 | 健康失效、真实地址/认证、网络、协议与额度  |
| 向量维度不匹配   | embedding 模型和既有索引空间，不只改模型名 |
| 主备切换失败     | 协议、上下文、结构化输出和工具能力兼容性   |
| 成本显示异常     | usage 是否可得、价格版本、币种与生效时间   |
| 流式中途断开     | 保留错误和已输出状态，不静默重放拼接答案   |

连接探测可能发生真实模型调用并消耗额度。本文只描述操作路径，没有替任何供应商做本轮健康或性能认证。

### 统一大模型网关：真实界面与操作视频

![统一大模型网关真实产品界面：统一大模型网关 / 模型端点](/academy/screens/model-gateway.webp)

图中为已采集的真实产品界面。阅读时重点核对“安全保存凭据”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一大模型网关》完整动态操作课程](/academy/model-gateway) · [下载本模块操作讲义](/academy/model-gateway/guide.md) · [查看真实界面原图](/academy/screens/model-gateway.webp)

```academy-video
model-gateway
```

[对应技术原理与能力边界](/docs/cube/whitepaper#module-model-gateway)

## 模块 15：统一业务编排 {#module-orchestration}

**适用角色**：应用开发 / 业务集成。**建议入口**：设计端 → 业务编排。实际菜单以部署版本与当前权限为准。

### 示例：AI-CRM 报价转草稿合同

配套实现文档核对的对象为应用 `crm_ai_app`、来源 `crm_quotation`、目标 `crm_contract`，明细为 `sub__crm_quotation_item` 到 `sub__crm_contract_item`。这些是源码资料中的应用样例标识，不应直接用于其他客户应用或另一套 CRM。

1. 定义输入为已保存来源报价 ID，由服务端读取完整主子表，不从浏览器列表行取金额和明细。
2. 检查报价状态、有效明细、已转换标记与来源版本；允许状态以实际业务配置为准。
3. 配置字段改名、常量、默认值和明细转换，逐项核对金额舍入、日期格式、时区、字典、0、false、null 与缺失字段。
4. 在符合本地事务条件时启用原子转换、防重、来源锁定与回填；跨数据源应显式采用非原子集成方案。
5. 创建草稿合同与明细，回填报价关联字段，返回来源和目标 ID、编号及运行标识。
6. 保存并运行用例，发布指定快照，再把应用按钮绑定到正确版本；回归重复、并发、来源变更和中途失败。

### 原子与非原子边界

| 操作组合                         | 应采用的验证                                        |
| -------------------------------- | --------------------------------------------------- |
| 同一本地事务的目标新增与来源回填 | 失败整笔回滚，验证主表、明细和来源字段              |
| 外部 HTTP 或独立数据源           | 幂等、查询、补偿与未知状态；不承诺本地原子性        |
| 原子图调试                       | 连续执行验证事务，不跨请求单步破坏原子边界          |
| 批量按钮逐条执行                 | 每条 sourceId、index、runId 与成功/失败分别记录     |
| 模型节点输出                     | 真正执行 JSON Schema 校验，拒绝非法结果进入后续节点 |

现有资料还描述输入输出校验、转换预览、用例 JSON 断言、Mock、日志及版本回滚。Mock 仅在允许的 debug/test 环境生效，不作为生产真实依赖的证据。

### 运行与发布验收

精确 JSON 断言要区分 null 与缺失，对象键顺序不应影响相等，数组顺序则有业务含义。发布与回滚后都应回读活动版本，核对画布、IO 和规则，而非只看按钮 Toast。

失败时先保存 runId 和节点日志，再检查目标是否已创建、来源是否已回填。远程请求超时后先查目标幂等键；不得简单再次点击转换。`GET /ai/dsh/orchestration/checkpoints/{rootRequestId}` 是特定授权请求的检查点入口，不能当作所有业务编排的通用运行 API。

### 统一业务编排：真实界面与操作视频

![统一业务编排真实产品界面：统一业务编排真实设计器](/academy/screens/orchestration.webp)

图中为已采集的真实产品界面。阅读时重点核对“编排读取与校验”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一业务编排》完整动态操作课程](/academy/orchestration) · [下载本模块操作讲义](/academy/orchestration/guide.md) · [查看真实界面原图](/academy/screens/orchestration.webp)

```academy-video
orchestration
```

[对应技术原理与能力边界](/docs/cube/whitepaper#module-orchestration)

## 模块 16：AI 应用构建 {#module-ai-builder}

**适用角色**：应用建设者 / 开发团队。**建议入口**：应用 → AI 构建 → 标准或高级模式。实际菜单以部署版本与当前权限为准。

### 输入一份可验收的应用需求

以“设备维修申请”为例，输入应写清使用角色、设备档案、维修主子表、状态、派工/验收流程、附件、权限、列表、看板与测试样例。把“自动完成维修”拆成“生成建议、创建申请、指派、维修记录、人工验收”等可验证动作。

1. 在标准模式下创建需求草稿，检查 AI 识别的对象、字段、关系、页面与流程。
2. 审阅应用规格及资源计划，确认每个资源使用哪种原生类型，避免把全部功能塞入一个定制 HTML 页面。
3. 按确认范围生成资源，保留请求或运行标识，检查依赖阻塞与错误，不重复创建同名应用掩盖问题。
4. 逐个回读原生表单、列表、页面、菜单、流程和大屏，使用对应设计器继续编辑并检查引用。
5. 通过员工端完成新增、查询、流转、权限与异常用例；记录规格、资源和运行时的差异。
6. 根据实际交付类型执行构建或导出，检查配置、依赖、目标版本及安装回归。

### 标准模式、高级模式与应用关联

标准与高级模式的实际入口、所需应用及能力，以部署版本核对。高级模式缺少应用或依赖时，应先完成关联和授权，不把界面提示当成生成成功。应用关联与智能体工具、技能、知识和 MCP 绑定应回读核验。

| 交付层        | 验证重点                                 |
| ------------- | ---------------------------------------- |
| 应用规格      | 业务对象、操作、状态、权限和验收标准完整 |
| 原生资源      | 设计器识别、引用有效、服务端可读取       |
| 平台运行      | 数据保存、按钮、流程、列表与权限         |
| 生成工程/插件 | 构建工具、依赖、入口、运行配置和许可证   |
| 独立交付包    | 目标环境安装、路由、静态资源、配置与回滚 |

### 常见问题

生成停在中间时，先查询原请求和已创建资源，避免重试产生重复定义。预览成功但设计器找不到时，核对是否只生成了临时预览、App Spec 是否已对账、资源标识是否正确。打包失败时按日志定位构建内存、锁文件、工具链、外部服务和交付配置，不以单个页面可预览代替整个应用构建成功。

源码配套资料包括 `dsh-application-development.md`、`dsh-native-resource-authoring.md` 和 `dsh-build-and-package-guide.md`；它们在平台源码仓库中，公开读者使用本手册与课程入口即可。

### AI 应用构建：真实界面与操作视频

![AI 应用构建真实产品界面：AI 应用构建工作台](/academy/screens/ai-builder.webp)

图中为已采集的真实产品界面。阅读时重点核对“审阅应用计划”涉及的入口与资源；示例或空态以演示环境为准。

[观看《AI 应用构建》完整动态操作课程](/academy/ai-builder) · [下载本模块操作讲义](/academy/ai-builder/guide.md) · [查看真实界面原图](/academy/screens/ai-builder.webp)

```academy-video
ai-builder
```

[对应技术原理与能力边界](/docs/cube/whitepaper#module-ai-builder)

## 模块 17：统一业务语义 {#module-semantic}

**适用角色**：业务建模 / 数据与 AI 团队。**建议入口**：设计端 → 业务语义。实际菜单以部署版本与当前权限为准。

![业务语义实施与核验路径图](/docs/cube/diagrams/semantic-lifecycle.svg)

### 从一个“回款风险”业务域开始

前置资料包括业务负责人、客户/合同/应收/回款数据字典、稳定主键、统计时点、币种、风险规则、授权测试数据与允许动作。先做只读分析，再加入报告或跟进动作，避免一次同时引入数据、规则和写入问题。

1. 创建业务域并明确编码与责任人，登记当前租户、用途和发布版本策略。
2. 创建客户、合同、应收、回款概念，定义实体粒度与稳定业务键；属性注明类型、单位、是否必需和敏感程度。
3. 定义关系方向与基数，例如客户到合同为一对多。关系含义要和真实主外键对应，不只画连线。
4. 登记外部资源，选择当前允许的数据库、API、知识或文件入口，检查来源授权、字段结构与结构漂移。
5. 把真实字段映射到语义属性，明确转换、日期、金额、空值、字典和无效状态。相似度推荐只供参考，逐项人工确认。
6. 配置规则与正反例，明确缺失事实时返回 UNKNOWN，不把空回款自动看成零回款。
7. 配置场景、上下文、策略及允许动作，运行服务端就绪/发布检查，修复缺口。
8. 发布版本并绑定到具体场景或智能体，使用实际问题核对事实、来源、规则结果和动作回执。

### 一份可执行的业务口径样例

以下是**项目建模示例**，字段与规则不是平台固定 API Schema：

| 语义项   | 约定                           | 验收样本                   |
| -------- | ------------------------------ | -------------------------- |
| 客户     | 由客户主数据稳定 ID 标识       | 同名客户不自动合并         |
| 应收     | 已生效应收记录，排除作废       | 状态改变后不能继续计入     |
| 截止日   | 按约定业务时区取统计时点       | 跨日、时区与临界时间       |
| 逾期天数 | 截止日与应到期日差，按约定日历 | 未到期、当日、逾期一天     |
| 币种     | 先同币种比较，跨币种用确认汇率 | 缺汇率时不得混加           |
| 规则结果 | 成立、不成立、未知、配置非法   | 缺字段与值为 0 应区分      |
| 跟进动作 | 审批后创建指定类型事项         | 参数、权限、防重与目标单据 |

### 就绪、发布、绑定与运行

`apps/design/src/api/ontology/ontology.ts` 可核对绑定检查、场景就绪、规则预览、资源管理、发布、回滚和运行相关入口。已核对示例：

```text
GET  /ontology/core/design/binding-check?domainCode=...&versionMode=...&versionId=...
GET  /ontology/core/design/readiness?sceneId=...&recordKey=...
GET  /ontology/core/design/release-check?domainCode=...
POST /ontology/core/design/readiness-run
GET  /ontology/core/runtime/trace?planId=...
GET  /ontology/core/runtime/run?runId=...
```

以上为后端相对路径；POST body 的 JSON/表单编码、必填字段和授权以客户端与控制器为准，不能仅凭路径直接构造发布或执行请求。

就绪状态只说明对应检查的结果。发布后仍需绑定；绑定后还需确认真实事实来源、版本与当前权限。前端权重评分、配置建议与真正的服务端结构校验分别判断。已登记的依赖可参与影响分析，不意味着识别所有外部调用。

### 受控动作、回归与版本治理

动作定义注明输入 Schema、执行器、风险、权限、预演与审批。执行相关定义变化后重新审核，不能沿用旧确认。对同一组冻结样例比较两个发布版本时，规则判断差异和业务动作实际结果是不同验证范围。

批量映射发布按逐条保存处理，实施时分批、检查部分成功并保留恢复记录，不宣称整体事务。版本回滚不恢复历史权限，回滚后重新核对策略、绑定和授权。当前资料未承诺完整 OWL/RDFS 推理、跨库自动 JOIN、自动实体消歧或任意岗位委托审批，项目设计不要依赖这些未验证能力。

### 排错矩阵

| 现象                   | 先检查                   | 进一步核验                       |
| ---------------------- | ------------------------ | -------------------------------- |
| 就绪但运行无数据       | 场景绑定、事实资源和授权 | 来源状态、映射、版本与数据新鲜度 |
| 规则始终 UNKNOWN       | 缺失属性与映射           | 值为空、类型转换、单位与时间     |
| 预览可见但智能体不可用 | 发布版本与实际绑定       | 入口权限与资源授权               |
| 动作已提交但未完成     | action/plan/run 原回执   | 执行器与目标业务终态             |
| 回滚后权限不一致       | 当前策略与授权           | 回滚不会恢复的外部配置           |

交付证据至少包括字段字典、关系、资源授权、映射清单、规则样例、就绪记录、发布版本、绑定、真实运行和动作回执。

### 统一业务语义：真实界面与操作视频

![统一业务语义真实产品界面：业务语义 / 业务规则与动作](/academy/screens/semantic-actions.webp)

图中为已采集的真实产品界面。阅读时重点核对“编写规则与动作”涉及的入口与资源；示例或空态以演示环境为准。

[观看《统一业务语义》完整动态操作课程](/academy/semantic) · [下载本模块操作讲义](/academy/semantic/guide.md) · [查看真实界面原图](/academy/screens/semantic-actions.webp)

```academy-video
semantic
```

[对应技术原理与能力边界](/docs/cube/whitepaper#module-semantic)

## 常用接口参考与调用示例

下面均为在源码接口客户端或控制器中核对的**后端相对路径**。网关通常另外添加 `/api` 前缀，实际以目标环境配置为准。页面路径、后端 API 与 MCP 工具名不应混用。此表不是完整 OpenAPI，也不替代运行版本的参数定义。

| 模块       | 方法与路径                                              | 说明                                           |
| ---------- | ------------------------------------------------------- | ---------------------------------------------- |
| 门户任务   | `POST /task/core/instTask/getMyInstTasks`               | 当前用户聚合待办；分页体以客户端为准           |
| BPM 待办   | `POST /bpm/core/bpmTask/myTasks`                        | BPM 当前待办查询                               |
| 新闻       | `GET /portal/core/insNews/get?pkId=…`                   | 新闻详情                                       |
| 新闻       | `POST /portal/core/insNews/publish`                     | JSON 对象含 `pkId`；发布是写操作               |
| 消息       | `GET /system/message-center/channels`                   | 通道目录                                       |
| 消息       | `POST /system/message-center/templates/preview`         | 预览模板及变量，不等于发送                     |
| 组织       | `GET /user/org/osGroup/getByParentId?parentId=…`        | 查询指定父组织下分组                           |
| 会话       | `GET /auth/session/list`                                | 管理会话；响应可能包含敏感信息                 |
| 知识       | `POST /kbs/v2/search`                                   | 知识库搜索                                     |
| 知识       | `POST /kbs/v2/qa`                                       | 问答；需核验回答依据与模型状态                 |
| 提示词     | `GET /ai/prompt/aiPrompt/get?pkId=…`                    | 提示词详情                                     |
| 技能       | `GET /ai/skill/aiSkill/get?pkId=…`                      | 技能详情                                       |
| MCP        | `POST /ai/mcp/aiMcpService/testConnection`              | 会连接配置的服务，按工具配置核对参数           |
| Harness    | `GET /ai/harness/overview/summary`                      | 当前授权范围概览                               |
| Harness    | `GET /ai/plan/aiPlan/detail?planId=…`                   | 计划详情                                       |
| Harness    | `GET /ai/job/aiJobRun/detail?jobId=…`                   | 执行任务详情                                   |
| 模型网关   | `GET /ai/model-gateway/admin/providers`                 | 管理员可见端点配置                             |
| 模型网关   | `GET /ai/model-gateway/admin/bindings`                  | 能力主备绑定                                   |
| 模型网关   | `POST /ai/model-gateway/admin/health/check`             | 真实探测，可能消耗模型额度                     |
| 业务语义   | `GET /ontology/core/design/binding-check`               | 检查域及版本绑定，参数见设计端客户端           |
| 业务语义   | `GET /ontology/core/design/readiness`                   | 场景就绪状态，含 `sceneId`                     |
| 业务语义   | `GET /ontology/core/runtime/tasks`                      | 运行任务；按当前身份过滤                       |
| 业务语义   | `GET /ontology/core/version/detail`                     | 版本详情，参数以控制器为准                     |
| 编排检查点 | `GET /ai/dsh/orchestration/checkpoints/{rootRequestId}` | 已授权请求的运行检查点；不能泛化为所有编排 API |

以下是只读配置查询示例。`CUBE_API_BASE` 应由测试环境提供，示例不附带任何真实凭据；读取结果也不要贴入公开日志。

```bash
# 示例前提：由调用方安全设置 CUBE_API_BASE 与 CUBE_ACCESS_TOKEN。
# CUBE_API_BASE 形如 https://your-test-site.example/api
curl --fail-with-body \
  -H "Authorization: Bearer ${CUBE_ACCESS_TOKEN}" \
  "${CUBE_API_BASE}/ai/model-gateway/admin/bindings"
```

知识库搜索的请求体与当前 `KbsQueryApi.searchKnowledgeV2` 对应。`knowledgeId` 必须替换为当前用户实际可访问的资源 ID。

```json
{
  "knowledgeId": "REPLACE_WITH_AUTHORIZED_KNOWLEDGE_ID",
  "query": "采购申请需要哪些附件？",
  "topK": 5
}
```

服务端返回可能使用 `data`、`result` 或已有项目封装。不要假定所有接口都是同一响应结构；结合接口客户端、控制器返回类型和实际响应适配。业务失败不应只按 HTTP 200 判断，需继续检查业务成功标识与错误。

## 接口与代码阅读地图

开发包中的常见入口包括：Portal `apps/portal/src/api/`；应用设计与业务语义 `apps/design/src/api/`；Admin 的组织、模型网关和系统管理 `apps/admin/src/api/`；后端 AI 执行控制器 `apps/backend/src/main/java/com/redxun/ai/rest/`；业务语义服务 `apps/service/ac-service-ontology/`。

本次核查的组件、接口及关联指南整理在官网仓库 `docs/cube-platform-source-map.md`，供文档维护人员追溯。实施时请在目标代码版本重新检查路由、权限和服务端实现。

## 源码配套指南

- 安装部署：`docs/ai-platform/installation-deployment-guide.md`
- 模型网关：`docs/ai-platform/model-gateway-guide.md`
- 智能体配置：`docs/ai-platform/dsh-agent-configuration.md`
- AI 应用开发：`docs/ai-platform/dsh-application-development.md`
- 原生列表与大屏资源：`docs/ai-platform/dsh-native-resource-authoring.md`
- 业务语义操作：`docs/ai-platform/ontology/ontology-operation-manual-2026-10-25.docx`
- 业务语义功能与成熟度：`docs/ai-platform/ontology/ontology-feature-inventory-2026-10-25.md`
- 报价转合同编排：`docs/ai-platform/business-orchestration-implementation-2026-10-17.md`

以上相对路径对应原始平台源码仓库，独立官网不会自动包含其文件；请用官网在线页面替代公开阅读入口。

## 通用接口契约、编码与错误处理 {#api-contracts}

### 路由、方法与传输编码

前端页面 `/portal/...`、`/admin/...`、`/design/...` 与后端 API 路径不同。已有接口表是后端相对路径，部署入口常额外代理 `/api`，调用前核对 Nginx 与客户端 baseURL，避免出现重复 `/api/api` 或把页面地址当 REST 端点。

平台客户端同时存在 `postJson`、`postUrl`、`postForm`、GET 查询等封装。新增集成应参考具体客户端及 Controller 的参数注解，不能把所有 POST 都改成 JSON。ID 可能在路径、query 或 body 中，必须逐接口确认。

### 分页、空值与版本

分页接口的参数和响应在不同领域不一定一致。先核对页号起点、页大小、总数、排序白名单与过滤结构。请求中不传字段、传空字符串、null、0、false 和空数组可能有不同语义；智能体更新数组、业务编排常量与语义规则尤其需要保留差异。

并发编辑宜使用当前领域支持的版本或预期字段校验。没有明确版本契约时，不自创 header 宣称平台已支持乐观锁。发布与执行要保留资源归属、应用和版本，避免用别的应用资源 ID 触发跨界调用。

### 统一处理 HTTP 与业务结果

```typescript
// 集成边界示例：不是平台所有 API 的统一返回类型。
type ResultEnvelope<T> = {
  success?: boolean
  message?: string
  code?: string | number
  data?: T
  result?: T
}

function inspectResult<T>(response: ResultEnvelope<T>) {
  if (response.success === false) {
    throw new Error(response.message || '业务处理失败')
  }
  // 接口若不用 success，应由该领域专用适配器检查 code 等字段。
  // 保留 false、0 与 null，不使用 data || result。
  return response.data !== undefined ? response.data : response.result
}
```

该代码只展示保留空值和显式业务失败的原则；不能把 success 缺失一律判断成功，也不能替所有接口选择 data/result。每个集成适配器需按真实返回契约处理业务码、异步受理和错误详情。公共错误提示不展示堆栈、SQL、凭据或完整供应商响应。

### 重试、幂等与补偿

| 情况                     | 建议处理                                   |
| ------------------------ | ------------------------------------------ |
| 只读查询超时             | 在总体超时内有限重试，保留失败与取消       |
| 写入已明确拒绝且无副作用 | 修复参数/权限后新请求，不自动反复重试      |
| 写入超时、断连或响应丢失 | 先按原关联查业务结果，保留未知状态         |
| 供应商限流               | 尊重服务端约束与项目退避策略，避免放大请求 |
| 多步骤部分成功           | 根据原回执查询、补偿或人工处理             |
| 用户取消                 | 区分取消等待与外部操作真正停止             |

幂等键应绑定租户、业务场景、来源对象与请求语义；同一键但不同参数应拒绝或明确处理。幂等记录的保留时长、并发领取、失败是否可重试需与业务风险一致。自定义 correlationId 仅用于追踪，不天然具有业务防重作用。

### 文件与长连接

附件上传、解析、下载和预览分别校验授权、大小、类型与资源归属。文件地址可打开并不表示可公开分发。长连接和流式模型响应要处理超时、错误、取消和页面关闭；已输出部分内容后重试应向用户明确说明，避免拼接两次回答。

## 贯穿项目实战：采购申请到受控智能分析 {#project-walkthrough}

### 需求卡与责任划分

首期范围：员工创建采购申请，部门负责人审批，采购负责人查看待执行清单，审批通知到站内收件箱。AI 解释采购制度并生成风险摘要，先不自动写入采购订单。ERP 下单作为后续独立集成，不混入首期验收。

| 角色       | 权限                               | 核验责任                   |
| ---------- | ---------------------------------- | -------------------------- |
| 申请人     | 维护自己的草稿、提交、查看允许内容 | 表单、附件和提交结果       |
| 部门负责人 | 本范围审批与查询                   | 节点责任、意见、拒绝与越权 |
| 采购负责人 | 查看审批完成记录与执行信息         | 转换、来源回填和执行清单   |
| 资料管理员 | 维护采购制度与知识权限             | 解析、版本、引用与过期     |
| 平台管理员 | 配置环境、模型与治理               | 配置、访问、运行与审计     |

### 第一阶段：数据与应用

建立字段字典与测试数据，定义草稿、审批中、审批完成、驳回和作废等业务状态；具体编码由项目确认，不直接套用接口示例。主表和明细的状态、金额与附件使用服务端规则校验。实现新增和回读后，再接入流程，避免同时调试两层问题。

用例包含空明细、负数量、超精度金额、删除明细、重复编号、并发编辑、无权访问详情和导出。保留一份冻结测试单据，作为后续报表与语义规则基准。

### 第二阶段：审批、待办与消息

配置金额分支和实际审批人，完成申请人发起、负责人办理及申请人查询三角色回放。任务 ID、实例 ID 与业务单据 ID 建立对应表。业务事件触发通知，分别检查消息受理、站内收件箱与阅读状态。

审批后转换时，用业务编排重新读取完整申请，验证状态与防重，再创建待执行记录并回填来源。连续点击和两个窗口并发不应重复建单；失败时核对事务与日志，外部调用按独立补偿边界处理。

### 第三阶段：知识与业务语义

导入采购制度并核对引用，定义采购金额、未执行、超交期与风险的业务口径。若多个应用或智能体需要复用规则，再建立业务域、事实映射、规则与场景；简单资料问答不强制引入完整语义模型。

语义验收用同一份冻结数据复核：临界金额、缺事实、不同币种、作废单和跨组织数据。确认没有把缺少数据等同于零或“无风险”。

### 第四阶段：智能体与受控执行

先提供只读采购制度问答与风险摘要，绑定知识、语义上下文和实际模型能力。工具错误时返回可理解说明，避免模型编造业务结果。需要生成正式风险报告或发送负责人时，按 Harness/动作入口建立计划、确认、执行与回执核验。

### 第五阶段：发布与移交

冻结应用、流程、编排、知识、语义与智能体版本，记录模型绑定与环境依赖。交付清单包括源版本、构建包摘要、数据字典、配置责任人、授权、验收记录、已知限制和恢复步骤。发布后按员工实际角色回放完整链路，不能只用管理员账号演示。

## 测试设计与验收记录模板 {#acceptance}

### 分层测试矩阵

| 测试层     | 覆盖内容                                 | 通过证据                            |
| ---------- | ---------------------------------------- | ----------------------------------- |
| 静态与构建 | 类型、依赖、原生 Schema、完整前端/后端包 | 命令、版本、退出状态和产物          |
| 领域接口   | 校验、权限、空值、分页、版本与错误码     | 脱敏请求响应与断言                  |
| 跨模块集成 | 身份→应用→流程→待办→消息                 | 同一单据、实例、任务和回执关联      |
| 知识与模型 | 解析、召回、引用、流式与无答案           | 固定问题集、模型/资料版本和人工评审 |
| 智能执行   | 计划确认、工具、审批、防重、未知结果     | 原计划、工具回执与业务终态          |
| 发布与恢复 | 安装、配置、备份、升级、回滚             | 目标环境重放与恢复核验              |

### 可复用验收记录

```text
用例编号：PO-FLOW-001（项目示例）
环境 / 平台版本 / 应用版本：
测试角色 / 租户 / 授权范围：
前置条件与冻结测试数据：
操作步骤与输入：
预期业务结果与禁止副作用：
实际 HTTP / 业务码：
业务单据 ID / 流程实例 ID / 任务 ID：
计划 ID / 运行 ID / 工具回执（适用时）：
目标系统回查结果：
截图 / 日志 / 附件（脱敏）：
结论 / 遗留问题 / 责任人：
```

不要仅记录“页面正常”“AI 回答成功”或“用例通过”。应注明正确数值、资源范围与终态，并保存失败、无权、重复和未知结果的证据。截图用于解释界面，接口和目标业务回查用于证明执行。

### 建议的最小回归集

1. 两个租户或隔离组织间的列表、详情、附件、导出和知识越权测试。
2. 采购申请正常、驳回、撤回、审批人缺失、重复提交和并发办理。
3. 编排同一来源重复转换、来源版本改变、目标创建失败和外部结果未知。
4. 模型未绑定、额度不足、协议不匹配、流式中断与备用能力不兼容。
5. 知识无答案、旧制度、恶意文档指令、解析失败与向量空间变更。
6. 语义缺事实、规则临界值、映射失效、发布未绑定、动作未经审批。
7. 角色撤销、用户停用、会话失效及恢复后授权一致性。

## 运维、部署与变更管理 {#operations}

### 环境与发布清单

平台安装指南提供源码、在线精简、全离线、挂载和升级等路线，按客户网络、已有环境与交付形态选择。首次安装与存量升级使用不同流程，不能把“重新解压”当作清空环境后重新初始化数据库的理由。

| 类别 | 发布前应登记                                     |
| ---- | ------------------------------------------------ |
| 版本 | 源码提交、前后端包、应用/流程/语义等资源版本     |
| 配置 | 公开来源、回调、数据库、文件、模型与连接器责任人 |
| 依赖 | 必需与可选服务、License、协议及兼容性            |
| 数据 | 备份范围、稳定目录、恢复目标与校验               |
| 操作 | 维护窗口、发布步骤、观察指标、停止条件与恢复路径 |
| 验收 | 真实角色、业务样本、失败路径与证据位置           |

### 备份范围与恢复验证

数据库备份应与当前数据库主版本、工具和平台升级指南一致。上传文件、License、DSH 配置和业务成果另行备份；数据库恢复成功但附件丢失仍属于恢复不完整。不要把可写数据目录放进受校验发行载荷中。

恢复演练使用隔离环境：检查备份可读 → 恢复数据库与文件 → 校验版本与配置 → 登录与授权 → 应用单据与附件 → 流程与任务 → 知识与模型 → 外部连接。恢复测试不向真实客户发送消息或重复提交历史业务动作。

### 监控和告警

| 监控项   | 需要区分的状态                       |
| -------- | ------------------------------------ |
| 服务存活 | 进程存在、依赖可用与业务可用         |
| 任务     | 排队、执行、失败、未知与已核验终态   |
| 文档     | 上传、解析、全文、向量和问答         |
| 模型     | 配置、健康、额度、预算、协议与能力   |
| 外部集成 | 请求、受理、送达、业务回执与对账差异 |
| 存储     | 数据库、附件、索引、日志与备份空间   |

阈值与告警责任人应按业务影响制定。不要把代码中的历史测试数量或模型供应商标称吞吐直接当作现场服务等级。性能测试记录并发、请求分布、数据规模、冷热状态、硬件、模型与错误率。

### 变更与恢复边界

应用资源、流程定义、编排快照、语义版本、知识内容、模型绑定和凭据各有生命周期。一次发布应列出实际变更对象及依赖。回滚某个资源不会自动回滚外部系统已完成的业务动作、恢复历史授权或恢复旧凭据；这些需明确对账与补偿步骤。

## 故障诊断速查 {#troubleshooting}

| 现象              | 第一层定位           | 进一步检查                        | 避免的误判                    |
| ----------------- | -------------------- | --------------------------------- | ----------------------------- |
| 白屏/静态资源 404 | 前端基路径与反向代理 | 构建包、缓存、公开来源            | 把业务权限问题当静态资源问题  |
| 登录循环          | 客户端回调与会话     | 域名/端口、Cookie、刷新与用户映射 | 临时关闭认证校验              |
| 菜单有但接口拒绝  | 服务端角色/资源授权  | 应用、租户、资源归属              | 只改前端菜单                  |
| 表单保存不完整    | 请求编码与模型字段   | 主子表、金额、附件、事务          | 仅凭 Toast 判断成功           |
| 待办不一致        | 原任务与实例状态     | 聚合刷新、组织、并发与回调        | 手工删待办掩盖状态错误        |
| 消息未到达        | 任务与分发记录       | 模板、接收人、通道、回调          | 把受理视为送达                |
| 知识无结果        | 解析与授权           | 全文、向量、模型绑定              | 认为必须先装所有可选中间件    |
| 模型不可用        | 能力绑定与真实健康   | 地址、凭据、协议、额度、内容策略  | 保存成功即健康                |
| 编排重复建单      | 幂等、来源锁与状态   | 并发、来源版本、远程结果          | 失败直接再点一次              |
| Harness 无法开始  | 计划、确认与依赖     | 当前权限、发布绑定、版本          | 计划生成就等于可执行          |
| 语义预览无事实    | 来源与映射           | 场景、版本、绑定、数据时点        | 把前端评分当运行成功          |
| 升级后配置未生效  | 进程与容器环境       | 原启动参数、配置优先级、容器重建  | 只 restart 就认为新环境已加载 |

## 图解与视频学习索引 {#learning-index}

下表课程采用真实产品操作关键帧与中文配音同步剪辑，配有指针、高亮框和步骤路径图。每门低于 4 分钟，适合作为模块入门；复杂配置与异常处理以本手册、目标版本源码及现场验证补充。

| 模块              | 操作课程                           | 操作讲义                                    |
| ----------------- | ---------------------------------- | ------------------------------------------- |
| 门户              | [观看视频](/academy/portal)        | [下载讲义](/academy/portal/guide.md)        |
| 统一待办          | [观看视频](/academy/todo)          | [下载讲义](/academy/todo/guide.md)          |
| 统一消息          | [观看视频](/academy/messages)      | [下载讲义](/academy/messages/guide.md)      |
| 统一新闻公告      | [观看视频](/academy/news)          | [下载讲义](/academy/news/guide.md)          |
| 统一安全认证      | [观看视频](/academy/auth)          | [下载讲义](/academy/auth/guide.md)          |
| 统一组织          | [观看视频](/academy/organization)  | [下载讲义](/academy/organization/guide.md)  |
| 统一应用构建      | [观看视频](/academy/application)   | [下载讲义](/academy/application/guide.md)   |
| 统一流程定义      | [观看视频](/academy/workflow)      | [下载讲义](/academy/workflow/guide.md)      |
| 统一大屏或报表    | [观看视频](/academy/reports)       | [下载讲义](/academy/reports/guide.md)       |
| 统一知识库        | [观看视频](/academy/knowledge)     | [下载讲义](/academy/knowledge/guide.md)     |
| 智能体与能力资产  | [观看视频](/academy/agents)        | [下载讲义](/academy/agents/guide.md)        |
| 统一 Harness 调度 | [观看视频](/academy/harness)       | [下载讲义](/academy/harness/guide.md)       |
| 统一安全审计      | [观看视频](/academy/audit)         | [下载讲义](/academy/audit/guide.md)         |
| 统一大模型网关    | [观看视频](/academy/model-gateway) | [下载讲义](/academy/model-gateway/guide.md) |
| 统一业务编排      | [观看视频](/academy/orchestration) | [下载讲义](/academy/orchestration/guide.md) |
| AI 应用构建       | [观看视频](/academy/ai-builder)    | [下载讲义](/academy/ai-builder/guide.md)    |
| 统一业务语义      | [观看视频](/academy/semantic)      | [下载讲义](/academy/semantic/guide.md)      |

[阅读技术白皮书](/docs/cube/whitepaper) · [进入产品学习中心](/academy) · [返回文档中心](/document-center)
