endpoint-creator

端点创建器

在 Datex Studio 分支上创建、修改或移除 API 端点。端点将流程或数据源公开为 HTTP API 路由。仅适用于 API 应用（类型 6）。

参考资料

• ../datex-studio-shared/branch-setup.md —— 分支和连接选择（多个技能共用）
• references/command-syntax.md —— 所有 dxs endpoint 命令及示例

依赖项

• requirements-gathering 技能 — 如果当前对话上下文中尚无需求概要，则调用此技能生成需求概要
• function-creator 技能 — 需要新建流程作为端点目标时调用
• datasource-creator 技能 — 需要新建数据源作为端点目标时调用

工作流

[Phase 1: Setup + Validation]
Follow branch-setup.md for branch selection
        |
dxs source branch show <id> → check isApiApplication
        |
  +-----+-----+
  |           |
 YES          NO → error: "Endpoints only supported for API Applications"
  |
[requirements brief in context?]
  +-----+-----+
  |            |
 YES          NO → invoke requirements-gathering skill
  |            |
  +-----+------+
        |
[Phase 2: Intent Detection]
        |
  +-----+-----+-----+
  |           |       |
 ADD       MODIFY   REMOVE
  |           |       |
  |           |     ⚠ warn: "Removing may break external consumers"
  |           |     get user confirmation
  |           |     dxs endpoint remove --alias <x> --branch <id>
  |           |     → Phase 5
  |           |
  |     dxs endpoint get --alias <x> --branch <id>
  |     determine changes needed
  |     ⚠ warn if contract change (alias, target, params)
  |     get user confirmation
  |     dxs endpoint update ... --branch <id>
  |     → Phase 5
  |
[Phase 3: Target Resolution]
For each endpoint to add:
  [does target flow/datasource exist on branch?]
    +-----+-----+
    |           |
   YES          NO
    |           |
   use it    [ask user: flow or datasource?]
    |           +-----+-----+
    |           |           |
    |        FLOW       DATASOURCE
    |           |           |
    |       invoke       invoke
    |       function-    datasource-
    |       creator      creator
    |           |           |
    +-----------+-----------+
        |
[Phase 4: Endpoint Wiring]
dxs endpoint add --alias <x> --flow/--datasource <target> -d "<desc>" --branch <id>
        |
[Phase 5: Verification]
Build change summary from actions taken
Verify each added/modified endpoint with dxs endpoint get
Present focused changelog to user

阶段详情

阶段 1：设置和验证

1. 按照 branch-setup.md 选择分支
2. 运行 dxs source branch show <id> 并检查 isApiApplication
   • 如果为 false → 报错：“端点仅支持 API 应用（类型 6）。此分支属于 {appTypeName} 应用。”
3. 检查当前对话上下文中是否已有需求概要
   • 已有需求概要 — 使用该概要
   • 没有需求概要 — 调用 requirements-gathering 技能
4. 从需求中提取：端点别名、描述、目标类型（流程/数据源），以及目标是新建还是现有

如果分支不是 API 应用，切勿继续阶段 1 之后的操作。端点仅适用于 API 应用。

阶段 2：意图检测

根据需求概要和用户请求确定意图：

• 添加 — “创建端点”“公开流程”“为 X 添加 API”
• 修改 — “更改端点”“重命名别名”“切换目标”
• 移除 — “移除端点”“删除端点”“停止公开”

契约变更警告（修改和移除）：

修改或移除端点前，先显示警告：

“更改/移除此端点可能会影响依赖它的外部使用方。是否继续？”

等待用户明确确认后再继续。以下操作均适用：

• 移除任何端点
• 更改端点别名（URL 路径会改变）
• 更改端点目标（响应结构可能改变）

未显示契约变更警告并获得用户明确确认之前，切勿修改或移除端点。

阶段 3：解析目标

对于要添加的每个端点：

1. 检查目标流程/数据源是否已存在于分支上：
   • 流程使用 dxs function list --branch <id>
   • 数据源使用 dxs datasource list --branch <id>
2. 如果存在 → 使用其引用名称，进入阶段 4
3. 如果不存在 → 询问用户：“此端点应由流程还是数据源提供支持？”
   • 流程 → 调用 function-creator 技能。流程可以访问数据库、外部 API 和其他后端服务。
   • 数据源 → 调用 datasource-creator 技能。数据源可直接查询 OData 实体，或使用自定义 JavaScript 代码（基于流程的数据源）。
4. 创建器技能完成后，记录所创建项目的引用名称

阶段 4：端点接线

使用 command-syntax.md 接入每个端点。

添加：

dxs endpoint add --alias <alias> --flow/--datasource <ref_name> \
  --description "<desc>" --branch <id>

修改：

dxs endpoint update --alias <alias> [--new-alias/--flow/--datasource/-d/--module] \
  --branch <id>

移除：

dxs endpoint remove --alias <alias> --branch <id>

阶段 5：验证

整理简明的变更摘要并呈现给用户：

Endpoint changes applied:
  - Added: "orders" → flow get_orders_flow ("Get orders")
  - Added: "materials" → datasource ds_materials ("Materials lookup")
  - Renamed: "old-name" → "new-name"
  - Removed: "deprecated-endpoint"

对于添加或修改的端点，使用 dxs endpoint get --alias <alias> --branch <id> 验证服务端接线是否正确。对于已移除的端点，确认其别名已不存在。

仅展示刚刚变更的端点，不要列出完整清单。

别名规则

• 必须匹配：^[a-zA-Z0-9]+(?:[/\-_~]*[a-zA-Z0-9]+)*$
• 必须以字母或数字开头和结尾
• 允许的分隔符：/、-、_、~
• 保留别名（不可使用）：app、settings、$treeshakelog、导入的应用引用名称

常见错误

错误	修正方法
尝试在非 API 应用上添加端点	在第 1 阶段通过 dxs source branch show 检查 isApiApplication
别名包含空格或特殊字符	必须匹配别名正则表达式
使用保留别名（app、settings、$treeshakelog）	选择其他别名
修改或移除内容时未提醒外部使用方	务必提醒契约变更，并征求用户确认
引用了分支上不存在的流程或数据源	在第 3 阶段确认其是否存在；如果不存在，则通过相应的技能创建
跳过需求收集并猜测端点结构	务必先收集需求
将端点添加到错误的分支	在第 1 阶段通过 branch-setup.md 与用户确认分支

---

编辑完成后，调用 post-edit-verification，以发现描述/JSON/架构违规。若要进行最终审查，请调用 component-validator。