# Insight 用户手册

> 版本：v1.0 · 日期：2026-05-22  
> 面向角色：业务架构师

---

## 1. 产品定位

Insight 是 ODMS 的 AI-aware 轻应用构建平台。它在 Connect / Studio 接入的数据基础上，为数据引入业务语义，定义受控写操作，配置 AI 推理逻辑，最终搭建可发布给业务用户使用的轻应用。

**Insight 解决的问题：**
- 技术字段（`status = 2`、`risk_level = 'H'`）对业务人员不可读 → **Semantic 赋予业务语义**
- 想让 AI 帮忙分析和操作数据，但怕 AI 乱做 → **Ontology + Action 设定操作边界，AI 只在边界内推荐**
- 业务新需求排队等 IT 开发 → **Workshop 低代码搭应用，业务架构师自己发布**

**Insight 四大能力区：**

```
Semantic   → 定义业务对象是什么（Object / Property / Link / Term）
Logic      → 定义能对对象做什么（Action / Function / Automate / AIP Logic）
Workshop   → 组装页面和交互（Widget / 变量 / 事件 / 发布）
Data Table → 管理轻应用自己的数据（多字段类型 / 多视图 / 公开表单）
```

---

## 2. 核心概念

| 概念 | 说明 | 类比 |
|------|------|------|
| **EntityDef** | 对一个 OData Entity 的业务描述（显示名、描述、敏感级别） | 给数据库表起一个"业务名片" |
| **PropertyDef** | 对 Entity 字段的业务描述（显示名、是否脱敏、是否必须走 Action 才能修改） | 给每列字段标注"业务含义" |
| **LinkDef** | 定义两个 Entity 之间的关联关系 | 外键关系的业务语言表达 |
| **OntologyTerm** | 业务术语定义（Business Term / Business Rule） | 内部词汇表 |
| **ActionDef** | 定义一个受控写操作（如"标记逾期"、"创建催款任务"）及其审批条件 | 有审批和审计记录的操作按钮 |
| **FunctionDef** | 可被 Action 或 AIP Logic 调用的 Python 业务函数，只读访问白名单 Entity | 业务计算逻辑的封装 |
| **AutomateDef** | 自动化规则，监听触发条件后自动执行 Action 或 AIP Logic | 定时任务 + 数据变化触发器 |
| **AIPLogicDef** | AI 推理配置：给 AI 看什么数据、让它推荐哪些操作、是否需要人工确认 | 有边界的 AI 助手 |
| **AIPProposal** | AI 推荐的操作建议，进入 Portal 待办等待人工确认（24 小时过期） | AI 的建议单，不直接执行 |
| **Data Table** | Insight 自建的轻应用数据表（任务单、备注、标签、审批记录等），不进企业治理链路 | Airtable / Notion Database |
| **DataTableView** | 同一张 Data Table 的多种展示方式（Grid / Kanban / Calendar / Form） | Notion 的多视图 |
| **Workshop App** | 由 Widget + 变量 + 事件 + 页面组成的轻应用，发布到 Portal 供业务用户使用 | 低代码 App |

---

## 3. 快速开始

以**应收款催收管理**为例，完整演示从接入数据到发布应用的全流程。

**前提**：IT 负责人已通过 Connect 接入数据库，Studio 中 Connection 已可用。

```
步骤 1：Semantic — 给 Entity 加上业务标签
步骤 2：Semantic — 定义 Entity 间的关联关系
步骤 3：Logic   — 定义"创建催款任务" Action
步骤 4：Logic   — 配置 AIP Logic（AI 分析信用风险，推荐操作）
步骤 5：Workshop — 搭建"催款管理"应用页面
步骤 6：Workshop — 发布到 Portal
```

---

## 4. 操作指南

### 4.1 Semantic — 创建 EntityDef

> **入口**：Insight → Semantic → Entity Definitions

**从 OData $metadata 同步：**

1. 点击「同步 Entity」→ 选择 Connection
2. 系统读取 `$metadata`，列出所有可用 EntitySet
3. 勾选需要引入语义层的 Entity（如 `Customers`、`CollectionTasks`）→ 确认
4. 系统自动创建 EntityDef 和对应的 PropertyDef 骨架

**AI 语义初始化（推荐）：**

1. 选中一个 EntityDef → 点击「AI 初始化」
2. 系统读取字段定义 + 前 20 条样本数据 → 调用 AI 生成建议
3. 前端展示对比表：字段原名 vs AI 推荐的显示名 / 描述 / 敏感级别
4. 逐条勾选采纳 → 点击「应用选中」

**手动编辑 PropertyDef：**

选中 EntityDef → 右侧属性表格，每行对应一个字段，可行内编辑：

| 列 | 说明 |
|----|------|
| 显示名 | 在应用中展示给用户看的名称（如 `balance` → `应收余额`） |
| 描述 | 该字段的业务含义说明 |
| 敏感级别 | normal / sensitive / restricted（影响是否需要权限才能查看） |
| 脱敏展示 | 开启后 Portal App 中该字段显示为 `***` |
| 对用户隐藏 | 开启后该字段不在 Portal App 中展示 |
| 必须走 Action | 开启后该字段只能通过 Action 修改，不能直接 Studio 编辑 |
| 条件格式化 | 配置值满足条件时的样式（如余额 > 10000 显示红色） |

---

### 4.2 Semantic — 定义 LinkDef

> **入口**：Insight → Semantic → Link Definitions

1. 点击「新建关联」
2. 配置：
   - **来源 Entity / 字段**：如 `CollectionTasks.customer_id`
   - **目标 Entity / 字段**：如 `Customers.id`
   - **关联类型**：many-to-one / one-to-many / one-to-one / many-to-many
3. 保存后，Workshop 中的 `RelationList` Widget 可沿此关联导航

> **提示**：如果 OData NavigationProperty 已在 `$metadata` 中定义（如 D365 系统），同步时系统会自动创建只读的 LinkDef，无需手动配置。

---

### 4.3 Semantic — 定义 OntologyTerm

> **入口**：Insight → Semantic → Ontology

用于沉淀业务语言，让 AI 和应用更准确理解业务上下文。

| 类型 | 用途 | 示例 |
|------|------|------|
| **Business Term** | 业务术语定义 | "逾期"：应收余额超过信用额度且逾期 30 天以上 |
| **Business Rule** | 触发条件或约束规则 | `balance > credit_limit * 1.2` → 高风险客户 |

配置完成后，AIPLogicDef 的 system_prompt 中可引用这些术语，让 AI 准确理解"高风险"的含义。

---

### 4.4 Data Table — 创建轻数据表

> **入口**：Insight → Semantic → Data Tables

Data Table 适合存放应用自己的数据：催款任务备注、AI 建议确认记录、临时标签、例外处理台账等。

**创建 Data Table：**

1. 点击「新建 Data Table」→ 填写名称和描述
2. 添加字段：

| 字段类型 | 用途 |
|---------|------|
| `text` | 短文本（标题、名称） |
| `long_text` | 多行文本（备注、说明） |
| `number` | 数值（金额、数量）；支持 currency / percent 格式 |
| `date` / `datetime` | 日期和时间 |
| `boolean` | 是/否开关 |
| `single_select` | 单选枚举（可设置颜色标签），如状态字段 |
| `multi_select` | 多选标签 |
| `relation` | 关联另一张 Data Table 的记录 |
| `email` / `url` | 邮件地址 / 网址 |
| `attachment` | 文件附件 |

3. 保存后自动创建 Grid 视图

**添加更多视图：**

Data Table 右上角 → 「+ 新建视图」→ 选择视图类型：

| 视图类型 | 适合场景 |
|---------|---------|
| **Grid（表格）** | 查看和编辑所有记录，类似 Excel |
| **Kanban（看板）** | 按状态字段分列管理任务，拖拽改变状态 |
| **Calendar（日历）** | 按日期字段在月历上查看记录（如截止日期） |
| **Form（表单）** | 生成可填写的表单，支持公开链接供外部提交 |

**Form 视图公开表单：**

1. 选中 Form 视图 → 设置 → 开启「公开表单」
2. 配置表单标题、描述、可填字段
3. 复制公开链接，分享给外部填写者（无需登录）
4. 提交记录自动写入 Data Table（source = 'form'）

---

### 4.5 Logic — 定义 ActionDef

> **入口**：Insight → Logic → Actions

Action 是受控写操作的封装，所有对 External Entity 的写操作都必须通过 Action 执行。

**新建 Action：**

1. 点击「新建 Action」
2. 填写基本信息（名称、显示名、描述）
3. 配置类型：

| 类型 | 说明 | 适用场景 |
|------|------|---------|
| `rule_based` | 配置式字段映射，直接指定改哪些字段到什么值 | 状态变更、字段更新等简单操作 |
| `function_backed` | 先调用 FunctionDef 计算，再用返回值驱动字段映射 | 需要复杂计算逻辑的操作 |

4. 配置参数（Parameters）：Action 执行时需要传入的值（如 `customer_id`、`task_note`）
5. 配置字段映射（Field Mappings）：参数值如何映射到 Entity 字段
6. 配置审批条件（Approval Conditions）：满足什么条件需要人工审批

| 审批条件示例 | 含义 |
|------------|------|
| `always: true` | 该 Action 每次执行都需审批 |
| `when_amount_gt: 50000` | 金额超过 5 万时需审批 |
| `operation_type: delete` | 删除操作始终需审批 |

7. 配置副作用（Side Effects，可选）：Action 执行完成后触发通知或 Webhook

**测试 Action：**

Action 详情页 → 「手动执行」→ 填写参数值 → 执行 → 查看 ActionRun 结果

---

### 4.6 Logic — 定义 FunctionDef

> **入口**：Insight → Logic → Functions

Function 是可被 Action 或 AIP Logic 调用的 Python 业务函数，适合封装复杂计算逻辑（如信用评分算法、逾期天数计算）。

**新建 Function：**

1. 点击「新建 Function」
2. 配置输入参数（input_schema）和输出结构（output_schema）
3. 配置可访问的 Entity 白名单（accessible_entities）及每个 Entity 的最大查询行数
4. 编写 Python 函数体（body）

**Function 的安全约束：**
- 只能通过 OData 只读访问白名单内的 Entity，不能直接操作数据库
- 执行超时 30 秒自动中止
- 执行结果写 FunctionRun 记录

**Function 函数体示例（信用风险评分）：**

```python
# 输入: {"customer_id": "C001"}
# 可访问: Customers（max_rows=1）, Invoices（max_rows=200）

customer = odata.get("Customers", filter=f"id eq '{customer_id}'", top=1)[0]
invoices = odata.get("Invoices", filter=f"customer_id eq '{customer_id}'", top=200)

overdue_amount = sum(inv["amount"] for inv in invoices if inv["status"] == "overdue")
overdue_ratio = overdue_amount / customer["credit_limit"] if customer["credit_limit"] > 0 else 0

risk_score = min(100, int(overdue_ratio * 100))
risk_level = "high" if risk_score >= 80 else "medium" if risk_score >= 40 else "low"

return {"risk_score": risk_score, "risk_level": risk_level, "overdue_amount": overdue_amount}
```

---

### 4.7 Logic — 配置 Automate

> **入口**：Insight → Logic → Automation

Automate 监听触发条件，自动执行 Action 或 AIP Logic。

**新建 Automation：**

1. 点击「新建 Automation」
2. 选择触发类型：

| 触发类型 | 说明 | 示例 |
|---------|------|------|
| `schedule` | 定时触发 | 每天早上 9:00（cron: `0 9 * * 1-5`） |
| `entity_change` | Entity 数据变化时触发 | `CollectionTasks.status` 变为 `approved` |
| `condition` | 满足条件时触发 | `Customers.balance > credit_limit` |
| `action_done` | 某个 Action 执行完成后触发 | `action_create_task` 完成后 |

3. 选择目标：执行某个 Action 或运行某个 AIP Logic
4. 配置通知（可选）：触发时向相关人员发送站内通知
5. 启用 Automation

---

### 4.8 Logic — 配置 AIP Logic

> **入口**：Insight → Logic → AIP Logic

AIP Logic 让 AI 在定义好的数据边界和操作边界内进行推理，生成建议而不直接执行操作。

**新建 AIP Logic：**

1. 点击「新建 AIP Logic」
2. 配置输入参数（input_schema）：触发时传入的上下文（如 `customer_id`）
3. 配置可访问 Entity（accessible_entities）：AI 可以读取哪些 Entity 的数据
4. 配置可调用的 Function（callable_functions）：AI 可以调用哪些业务计算函数
5. 配置可推荐的 Action（recommendable_actions）：AI 只能推荐白名单内的操作
6. 编写系统 Prompt（system_prompt）：告诉 AI 它是谁、要分析什么、如何决策
7. 配置输出结构（output_schema）：AI 返回的数据结构
8. 设置 `human_confirm = true`（**强烈建议**）：AI 推荐的操作进入 Portal 待办，由人工确认后才执行

**System Prompt 示例（信用催款分析）：**

```
你是一名应收款风险分析助手。
你的任务是分析指定客户的信用状况，并推荐合适的催款行动。

分析维度：
1. 逾期天数和逾期金额
2. 信用额度使用率
3. 历史还款记录

输出格式：
- 风险等级：high / medium / low
- 分析摘要（中文，不超过 100 字）
- 推荐操作：从可用 Action 中选择最合适的 1-3 个，并说明理由

重要约束：
- 不要推荐超出权限范围的操作
- 不确定时，推荐"人工复核"而非直接操作
```

**手动触发 AIP Logic：**

AIP Logic 详情页 → 「手动触发」→ 填写输入参数 → 执行 → 查看结果（AI 分析摘要 + 推荐 Action 列表）

如果 `human_confirm = true`，结果会生成 AIPProposal，进入 Portal 待办供用户确认。

---

### 4.9 Workshop — 搭建应用

> **入口**：Insight → Workshop

**新建应用：**

Workshop → 「新建 App」→ 填写应用名称和描述

**添加页面：**

应用编辑器左侧面板 → 「+ 新建页面」

**添加 Widget：**

拖拽或点击添加以下 Widget 类型：

| 分类 | Widget | 说明 |
|------|--------|------|
| 展示 | EntityTable | 显示 Entity 数据列表（绑定 EntityDef，自动用字段显示名） |
| 展示 | PropertyCard | 显示单个对象的所有属性 |
| 展示 | StatCard | 显示统计数字（如逾期客户数） |
| 展示 | RelationList | 沿 LinkDef 显示关联对象列表 |
| 展示 | DataTableGrid | 显示和编辑 Data Table 记录 |
| 展示 | DataTableKanban | 看板视图 |
| 展示 | DataTableCalendar | 日历视图 |
| 输入 | FilterBar | 筛选栏，绑定变量 |
| 输入 | SearchBox | 关键词搜索 |
| 操作 | ActionButton | 一键触发 Action |
| 操作 | ActionForm | 弹出表单触发 Action（从 ActionDef.parameters 自动生成表单字段） |
| AI | AIPSuggestionCard | 显示 AI 推荐操作，支持逐条确认/忽略 |
| 图表 | BarChart / LineChart / PieChart | 数据可视化 |
| 布局 | Container / Tabs / Modal | 页面结构 |

**配置 Widget 数据绑定：**

选中 Widget → 右侧配置面板：
- `EntityTable`：选择 EntityDef，配置显示列、筛选条件（支持 `{{变量名}}` 插值）、排序
- `ActionButton`：选择 ActionDef，配置参数来源（从变量或行数据取值）

**定义变量（Variable）：**

页面配置 → 变量 → 「+ 新建变量」

| 变量类型 | 典型用途 |
|---------|---------|
| `string` | 筛选状态、搜索词 |
| `entity_ref` | 当前选中的行对象 |
| `date` | 日期范围筛选 |

变量在 Widget 配置中用 `{{变量名}}` 引用。

**配置事件（Event）：**

选中 Widget → 事件 → 「+ 新建事件」→ 选择触发器 + 配置动作链

常用事件组合：

| 触发器 | 动作 | 效果 |
|--------|------|------|
| `row_select`（EntityTable）| `set_variable` | 行选中后更新变量，驱动 PropertyCard 显示该行详情 |
| `button_click`（ActionButton）| `run_action` → `refresh_widget` → `show_toast` | 点击执行 Action，完成后刷新表格并提示 |
| `form_submit`（ActionForm）| `run_action` → `close_modal` | 表单提交后关闭弹窗 |
| `page_load` | `set_variable` | 页面加载时初始化筛选条件 |

---

### 4.10 Workshop — 发布应用

1. 应用编辑器右上角 → 「发布」
2. 填写版本号（如 `1.0.0`）和发布说明
3. 配置访问权限：选择可以看到该 App 的角色
4. 点击「确认发布」

发布后，有权限的业务用户在 Portal → 我的应用 中即可看到并使用该应用。

**版本管理：**

Workshop → 应用列表 → 选中应用 → 「版本历史」，可查看历史版本，或回滚到上一个版本。

**下架应用：**

应用详情 → 「下架」，Portal 中用户将无法再看到该应用（历史数据保留）。

---

## 5. 典型场景：应收款催收管理 App

**场景**：业务架构师为财务团队搭建一个"催款管理"应用，集成 AI 信用分析。

**应用结构：**

```
催款管理 App
├── 客户列表页
│     EntityTable（绑定 Customers EntityDef）
│     FilterBar（按状态筛选）
│     SearchBox（关键词搜索客户名）
│     ActionButton「创建催款任务」（绑定 action_create_collection_task）
│
├── 客户详情页
│     PropertyCard（客户基本信息）
│     RelationList（该客户的逾期发票）
│     StatCard（应收余额 / 信用使用率）
│     ActionButton「AI 信用分析」（触发 aip_credit_analysis）
│     AIPSuggestionCard（展示 AI 推荐的催款操作）
│
└── 催款任务页
      DataTableKanban（按任务状态分列：待处理 / 跟进中 / 已完成）
      ActionForm「记录跟进情况」
```

---

## 6. 常见问题

**Q：AI Logic 推荐了一个 Action，为什么没有立即执行？**  
A：`human_confirm = true` 时，AI 推荐会生成 AIPProposal 进入 Portal 待办，需要人工确认后才执行。这是设计如此——AI 不能直接写数据，必须人在回路。

**Q：AIPProposal 不见了？**  
A：AIPProposal 默认 24 小时后自动过期（参考 Palantir 设计）。你会收到过期通知。如需重新分析，手动再次触发 AIP Logic 即可。

**Q：Function 执行超时了怎么办？**  
A：检查 accessible_entities 中的 max_rows 设置，减少单次查询数据量。或优化 Python 逻辑，避免全量循环。超时限制 30 秒是安全边界，不可调高。

**Q：Workshop 里搭好的页面，Portal 显示不一样？**  
A：Portal 按 AppPublish 快照渲染，如果你修改了 App 但没有重新发布，Portal 看到的还是旧版本。修改后重新点击「发布」即可。

**Q：Data Table 的记录能导入 CSV 吗？**  
A：可以。Data Table Grid 视图 → 「导入 CSV」，按字段模板上传文件。

**Q：Data Table 和 External Entity 有什么区别，什么时候用哪个？**  
A：Data Table 是应用自建的轻数据，不走企业治理（无审批、无 Studio 审计），适合任务单、备注、临时数据。External Entity 是企业原有系统数据（ERP/CRM/数据库），有完整治理链路。如果你的 Data Table 变得越来越重要（需要审批、审计、多人管理），就该通过 Connect 把它迁移到 External Entity。

---

## 7. 与 Portal 的协作关系

Insight 是**配置方**，Portal 是**运行方**。你在 Insight 里配置的每一个规则，最终都会在 Portal 中产生具体效果。

### 7.1 你在 Insight 配置什么 → Portal 里发生什么

| 你在 Insight 配置 | Portal 里发生的事 |
|-----------------|-----------------|
| ActionDef.approval_conditions（审批条件） | 审批人的 Portal 待办中心出现审批任务 |
| ActionDef.side_effects（通知配置） | 指定接收人的 Portal 通知中心收到消息 |
| AutomateDef.notification_config | 触发时相关人员收到 Portal 通知 |
| AIPLogicDef.human_confirm = true | AI 建议进入相关用户的 Portal AI 确认待办 |
| Workshop App 发布（+ 权限配置） | 有权限的用户在 Portal「我的应用」看到该 App |
| Workshop App 下架 | 该 App 从 Portal 消失 |

### 7.2 Portal 的四项平台服务

Portal 为 Insight 提供以下运行环境，你无需自己实现：

| Portal 平台服务 | 说明 |
|---------------|------|
| **通知中心** | 接收 Insight 写入的通知并展示给用户，支持点击跳转到相关任务 |
| **待办中心** | 聚合审批任务（来自 ActionRun）和 AI 确认任务（来自 AIPProposal），提供处理入口 |
| **App 运行环境** | 加载你发布的 App Definition，渲染 Widget，执行变量和事件逻辑 |
| **App 市场** | 展示你发布的应用模板，支持其他人安装使用 |

### 7.3 作为业务架构师，你需要告知业务用户的事

发布 App 后，记得告知 Portal 端的业务用户：

- **哪些操作会触发审批**：配置了 approval_conditions 的 Action，执行后会进他们的待办中心等待审批
- **AI 建议有 24 小时时效**：AIPProposal 不处理会自动过期，建议他们每天检查 Portal 待办
- **通知来源**：Portal 通知中心的消息来自 Insight 配置的业务规则，不是系统广播，每条都有业务含义
- **App 更新需重新发布**：你修改 Workshop App 后必须点「发布」，业务用户才能看到新版本