# Studio 用户手册

> 版本：v1.0 · 日期：2026-05-22  
> 面向角色：IT 负责人、数据管理员

---

## 1. 产品定位

Studio 是 ODMS 的数据管理与治理中心。它基于 OData 接入企业数据，提供统一查询、受控写操作、审批流、审计日志、权限管理和数据质量监控，是所有产品组合的**必选基础包**。

**Studio 能做什么：**
- 直连微软 D365 FO / Business Central / Dataverse 的原生 OData
- 通过 Connect Runtime 访问关系数据库（PostgreSQL / MySQL / SQL Server / Oracle）
- 统一查询和操作多个 OData 数据源
- 写操作先生成变更预览，经审批后才执行
- 记录所有操作的审计日志（谁、什么时间、改了什么）
- 管理用户权限、审批人、Connect Client 凭证

**Studio 三大子域：**

```
数据操作    → 查询工作台、Entity Grid、CSV 导入、数据导出
数据治理    → 权限管理、Entity Edit Plan、审批流、审计日志
数据质量    → 字段规则配置、扫描、健康评分
```

---

## 2. 核心概念

| 概念 | 说明 |
|------|------|
| **Connection** | 一个已接入的 OData 数据源（D365 / Connect Runtime / 其他）。Studio 通过 Connection 访问对应的 Entity。 |
| **Entity Grid** | 以表格形式展示某个 Entity 的数据，支持分页、排序、筛选和写操作入口。 |
| **Entity Edit Plan** | 所有写操作（新增/修改/删除）在执行前生成的变更计划，展示影响行数、字段前后值和样本数据。 |
| **风险判断** | 系统根据操作类型、影响行数、字段敏感级别，判定：直接执行 / 需用户确认 / 需审批 / 拒绝。 |
| **审批流** | 高风险操作进入审批队列，审批人在 Studio 或 Portal 中通过/拒绝，通过后系统自动执行。 |
| **Audit Log** | 所有写操作、高敏感读取和导出操作的永久记录，append-only，不可删除。 |

---

## 3. 核心治理三原则

Studio 的所有数据操作必须满足以下三条，缺一不可：

| 原则 | 说明 |
|------|------|
| **① 授权前置** | 无权限 → 拒绝执行，不记录审计 |
| **② 审计必达** | 有操作必有记录；审计写入失败 → 操作回滚 |
| **③ 审批条件触发** | DELETE / 批量 UPDATE / 大量导出 / 高敏感操作 → 人工审批后才执行 |

---

## 4. 操作指南

### 4.1 接入 OData 数据源

#### 接入微软 D365 / Business Central（直连原生 OData）

1. Studio → **连接** → 「新建连接」
2. 类型选择「OData（OAuth 2.0）」
3. 填写：
   - OData 服务地址（如 D365 FO 的 `https://<env>.operations.dynamics.com/data/`）
   - OAuth 2.0 认证信息（Tenant ID / Client ID / Client Secret）
4. 点击「测试连接」→ 保存

#### 接入 Connect Runtime（关系数据库）

1. Studio → **连接** → 「新建连接」
2. 类型选择「Connect Runtime」
3. 填写 Runtime OData 端点地址（如 `https://<runtime-host>/AuroraTradingService/`）
4. 填写 Client ID + Client Secret（在 Connect IAM 中创建的 Client）
5. 测试连接 → 保存

接入后，Studio 自动同步 `$metadata`，列出所有可用 Entity 和字段信息。

---

### 4.2 查询数据

**查询工作台**（适合技术人员）：

1. Studio → **查询工作台**
2. 选择 Connection → 输入 OData URL 或 SQL-like 查询
3. 点击「执行」，结果以表格展示
4. 高敏感 Entity 的查询自动写审计记录

**Entity Grid**（适合日常数据浏览）：

1. Studio → **Entity** → 选择 Connection 和 Entity
2. 表格展示数据，支持：
   - 列排序（点击列头）
   - 条件筛选（顶部筛选栏）
   - 关键词搜索
   - 展开单行查看全部字段详情
3. 点击「写操作」按钮进入 Entity Edit Plan

---

### 4.3 写操作流程（Entity Edit Plan）

**所有写操作都必须先生成 Entity Edit Plan，不允许直接执行。**

#### 步骤：

**1. 发起操作**

| 来源 | 入口 |
|------|------|
| 单行修改 | Entity Grid → 选中行 → 「编辑」 |
| 单行删除 | Entity Grid → 选中行 → 「删除」 |
| 批量操作 | Entity Grid → 多选 → 「批量操作」 |
| CSV 导入 | Entity Grid → 「导入 CSV」 |
| SQL 写操作 | 查询工作台 → 输入 UPDATE/INSERT/DELETE |

**2. 查看 Entity Edit Plan**

系统生成变更计划，展示：
- 操作类型（新增 / 修改 / 删除）
- 影响 Entity 和字段
- 影响行数
- 前 5 条样本数据（字段修改前 → 修改后）
- Dry Run 结果（模拟执行，不实际写入）

**3. 风险判断结果**

| 结果 | 条件 | 操作 |
|------|------|------|
| **直接执行** | 低风险（小批量、低敏感字段） | 用户确认后立即执行 |
| **需确认** | 中等风险（较多行数、中等敏感） | 用户仔细阅读 Edit Plan 后点击「确认执行」 |
| **需审批** | 高风险（DELETE / 大批量 / 高敏感字段） | 进入审批流，等审批人通过后系统自动执行 |
| **拒绝** | 超出系统限制或违反策略 | 操作被终止，显示原因 |

**4. 执行与审计**

操作执行后自动写入审计日志（操作人、时间、字段变更详情）。

---

### 4.4 审批流程

#### 审批人操作（Studio 界面）：

1. Studio → **审批** → 「待处理」
2. 选中审批任务，查看：
   - 申请人和申请原因
   - Entity Edit Plan 详情（影响范围、字段变更样本）
   - 风险评级
3. 点击「通过」或「拒绝」（可填写意见）
4. 通过后系统自动执行操作并写审计

#### 审批人操作（Portal 界面）：

业务侧审批人通常在 Portal 的待办中心处理（见 Portal 用户手册）。

---

### 4.5 查看审计日志

Studio → **审计日志**

支持按以下维度筛选：
- 时间范围
- 操作人（用户名）
- Entity 名称
- 操作类型（CREATE / UPDATE / DELETE / EXPORT）
- Client ID（Connect Runtime 访问记录）
- 审批状态

> **重要**：审计日志 append-only，不提供删除入口。应用账号只能写入，不能修改或删除记录。

---

### 4.6 权限管理

Studio → **IAM**

**用户与角色：**

| 操作 | 路径 |
|------|------|
| 邀请用户 | IAM → 用户 → 「邀请」，填写邮箱 |
| 分配角色 | IAM → 用户 → 选中用户 → 「分配角色」 |
| 创建自定义角色 | IAM → 角色 → 「新建角色」 |

**Entity 级权限配置：**

每个角色可以配置对每个 Entity 的权限：

| 权限 | 说明 |
|------|------|
| Visible | 该 Entity 是否在 Studio 中可见 |
| Read | 是否可查询数据 |
| Update | 是否可修改记录（仍需经过 Edit Plan）|
| Delete | 是否可删除记录（高风险，通常触发审批）|

**Connect Client 管理：**

IAM → API Clients（详见 Connect 用户手册第 4.5 节）

---

### 4.7 CSV 导入

1. Entity Grid → 「导入 CSV」
2. 下载字段模板（自动生成含列头的空白 CSV）
3. 填写数据后上传
4. 系统解析并生成 Entity Edit Plan（预览匹配情况和数据样本）
5. 确认后进入风险判断流程

**注意事项：**
- 首行必须是字段名（与模板一致）
- 主键字段用于判断是新增还是更新
- 日期格式建议统一为 `YYYY-MM-DD`

---

### 4.8 数据导出

Entity Grid → 「导出」→ 选择格式（CSV / Excel）

导出操作：
- 须有 Export 权限
- 自动写审计记录（导出人、时间、Entity、行数、字段范围）
- 大批量导出（超过配置阈值）会触发审批

---

### 4.9 数据质量监控

Studio → **数据质量** → 选择 Entity

**配置质量规则：**

| 规则类型 | 说明 | 示例 |
|---------|------|------|
| 必填检查 | 字段不能为空 | `name` 不能为 null |
| 格式检查 | 字段值满足正则或枚举 | `email` 格式、`status` 在枚举值内 |
| 范围检查 | 数值在合理区间 | `0 ≤ progress ≤ 100` |
| 唯一性检查 | 字段值不重复 | `invoice_no` 唯一 |

**扫描与评分：**

配置规则后，手动触发扫描，系统返回：
- 各规则违规记录数
- 整体健康评分（0-100）
- 违规记录列表（可下载）

---

## 5. 风险策略配置

Studio → **系统配置** → **风险策略**

| 配置项 | 说明 |
|--------|------|
| 批量操作阈值 | 超过 N 行的 UPDATE 触发审批（默认：100） |
| DELETE 默认策略 | 始终需要审批 / 小批量仅确认 |
| 高敏感 Entity | 所有写操作强制审批 |
| 导出行数阈值 | 超过 N 行的导出触发审批 |
| 审批人配置 | 按 Entity 或角色配置审批人链 |

---

## 6. 常见问题

**Q：我点了「编辑」，为什么没有直接修改，而是跳到了 Edit Plan？**  
A：Studio 所有写操作都必须先生成 Entity Edit Plan，这是核心治理原则——你能看到要改什么、影响多少行，再决定是否执行。这不是 Bug。

**Q：审批流卡在待审批状态，但找不到审批人？**  
A：进入 Studio → 系统配置 → 风险策略，检查该 Entity 的审批人配置。如果审批人账号被停用或不存在，审批流会卡住。

**Q：误操作了，能撤销吗？**  
A：不能直接撤销，但你可以：① 查审计日志找到变更前的字段值；② 用 Studio 发起反向操作（把字段改回去），该操作同样走 Edit Plan + 审批流程。

**Q：连接 D365 FO 时提示 401 Unauthorized？**  
A：检查 OAuth 2.0 配置（Tenant ID / Client ID / Client Secret），确认 Azure AD 中该 App Registration 有 D365 的 Dynamics ERP 权限。

**Q：审计日志查不到某条操作记录？**  
A：审计只覆盖通过 Studio 界面发起的操作，以及 Connect Runtime 的访问记录。如果是直接连接数据库执行的操作，不在 Studio 审计范围内。

**Q：导出时提示"超过阈值，需要审批"，但我只需要少量数据？**  
A：在 Entity Grid 使用筛选条件缩小数据范围后再导出，低于阈值即可直接导出。或联系管理员调整导出阈值策略。