add-dataverse

📋 共享说明：shared-instructions.md - 跨领域注意事项。

参考资料：

• dataverse-reference.md - 选项集字段、虚拟字段、查找、文件/图像列、表单模式（关键）
• api-authentication-reference.md - Dataverse API 身份验证、令牌、发布者前缀
• table-management-reference.md - 查询、创建、扩展表和列
• data-architecture-reference.md - 关系类型、依赖层级

添加 Dataverse

有两种路径：现有表（跳至步骤 5）或新建表（完整工作流）。

工作流

1. 规划 → 2. 设置 API 身份验证 → 3. 检查现有表 → 4. 创建表 → 5. 添加数据源 → 6. 检查生成的文件 → 7. 构建

---

步骤 1：规划

检查记忆库中的项目上下文。询问用户：

1. 他们需要哪些 Dataverse 表？（例如，account、contact、cr123_customentity）
2. 这些表在其环境中是否已存在，还是需要新建？

如果表已存在： 跳至步骤 5。

如果要创建新表：

• 询问所需数据，并设计合适的架构
• 在适当情况下使用 Dataverse 标准表（人员使用 contact，组织使用 account）
• 构建依赖关系图——有关层级分类，请参阅 data-architecture-reference.md
• 使用 EnterPlanMode 进入计划模式，展示包含表、列、关系和创建顺序的 ER 模型
• 使用 ExitPlanMode 获取批准

步骤 2：设置 API 身份验证（如果要创建表）

完整详情请参阅 api-authentication-reference.md。

az account show   # Verify Azure CLI logged in

# Find your Dataverse environment URL:
# In make.powerapps.com → Settings → Developer resources → Web API endpoint
# It looks like: https://<org-name>.crm.dynamics.com/api/data/v9.2/
# Use the base URL: https://<org-name>.crm.dynamics.com

$api = Initialize-DataverseApi -EnvironmentUrl "https://<org>.crm.dynamics.com"
$headers = $api.Headers
$baseUrl = $api.BaseUrl
$publisherPrefix = $api.PublisherPrefix

需要 System Administrator 或 System Customizer 安全角色。

步骤 3：检查现有表（如果要创建表）

创建前务必先查询现有表：

$existingTables = Invoke-RestMethod -Uri "$baseUrl/EntityDefinitions?`$filter=IsCustomEntity eq true&`$select=SchemaName,LogicalName,DisplayName" -Headers $headers

有关 Find-SimilarTables、Compare-TableSchemas 和 Build-TableNameMapping 函数，请参阅 table-management-reference.md。

使用 AskUserQuestion 向用户展示结果：

• 可以复用的表（已存在且列匹配）
• 需要扩展的表（已存在，但缺少列）
• 必须创建的表（未找到匹配项）

步骤 4：创建表（如果要创建表）

创建前需获得明确确认。按依赖顺序创建：

• 第 0 层：引用表（无依赖项）
• 第 1 层：主要实体（引用第 0 层）
• 第 2 层：依赖表（引用第 1 层）

使用 table-management-reference.md 中的安全函数：

• New-DataverseTableIfNotExists
• Add-DataverseColumnIfNotExists
• Add-DataverseLookupIfNotExists（参见 data-architecture-reference.md）

步骤 5：添加数据源

对于每个表：

pa app add data-source --connector dataverse --table <table-logical-name>

逐个运行该命令即可添加多个表。

第 6 步：检查生成的文件

此命令会生成：

• src/generated/models/{Table}Model.ts —— TypeScript 接口；如果表包含文件/图像列，还会生成 {Table}FileColumnName、{Table}ImageColumnName、{Table}UploadColumnName 联合类型
• src/generated/services/{Table}Service.ts —— CRUD 方法（create、get、getAll、update、delete）；如果存在文件/图像列，还会生成 upload、downloadFile、downloadImage、deleteFileOrImage

向用户展示用法示例：

import { AccountsService } from "../generated/services/AccountsService";

const result = await AccountsService.getAll({
  select: ["name", "accountnumber"],
  filter: "statecode eq 0",
  orderBy: ["name asc"],
  top: 50
});
const accounts = result.data || [];

关键规则：

• 使用生成的服务（例如 AccountsService.getAll()），不要使用 fetch/axios
• 检查 result.data 以获取实际数据
• 除非必要，否则不要编辑生成的文件
• 编写任何 Dataverse 代码之前，请先阅读 dataverse-reference.md —— 选项集字段、虚拟字段、查找字段以及文件/图像列都有需要特别注意的事项

第 7 步：构建

npm run build

继续之前，请先修复 TypeScript 错误。暂时不要部署。

更新 Memory Bank

记录已添加（或创建）的表、生成的文件以及任何架构说明。