jorgemiranda-alt/cloudapper

cloudapper 是做什么的？

CloudApper 是一个无代码平台：应用由表单（数据模型）、菜单（导航）、角色、UI 工作流（客户端）、后端工作流（自动化）和 DevExpress 报告组成，所有这些都在 App Studio（/design/... 用于表单和菜单，/studio/... 用于工作流）中进行编辑，并在运行时应用（/<clientId>/app/<appId>/...）中使用。

本文件包含适用于每个任务的规则。在执行任务前，请阅读与任务匹配的参考文档：

任务	阅读
了解平台工作原理（表单、字段、工作流、报告、缓存）	references/platform-model.md
调用 API（记录、工作流、表单、菜单、角色、UI 工作流、报告）	references/api-reference.md
构建或更改工作流；调试“不触发”或运行缓慢的工作流	references/workflow-patterns.md
使用 Playwright MCP 驱动浏览器	references/playwright-efficiency.md
将功能或整个应用从一个应用/账户复制到另一个	references/copy-between-apps.md
在设计器中构建新应用或表单	references/building-apps.md
设计、命名或审查任何内容（CloudApper 上的 SOLID 原则、命名约定、工作流/配置/报告约定）	references/conventions.md
设计解决方案或集成架构（UKG、REST、webhooks、SFTP、中间件；扩展性和效率）	references/architecture.md
记录应用（技术/故障排除指南，或 PM 交接指南）	references/documentation.md
审查应用或撰写其发现/建议	references/app-review-checklist.md
使用 UKG（Pro、WFM、Recruiting、HRSD）连接器	references/integrations-ukg.md
用户询问如何与你一起在 CloudApper 上工作，或本技能应包含哪些内容	references/learning-and-prompting.md

环境：在更改前询问

大多数 CloudApper 客户都有一个生产应用和一个UAT（测试）应用，通常位于不同的账户下。在进行任何更改（保存表单、编辑或切换工作流、编辑记录、导入报告、更改菜单）之前，请确认该更改针对哪个环境，除非用户在此对话中已经说明：

• 询问：“这是用于生产环境还是 UAT 环境？”并说明您当前登录的账户/应用，以便用户发现不匹配。
• 默认使用 UAT。将生产环境视为只读：不做更改、不运行工作流、不登录或读取，除非用户明确要求执行该特定操作。从生产环境复制属于读取操作；向生产环境复制属于更改操作。
• 在每次写入操作前检查 URL 的客户端 ID（/<clientId>/app/<appId>）。当页面位于错误的客户端上时，执行写入操作的脚本应拒绝运行。
• 项目事实（账户、客户端/应用 ID、哪个应用是生产环境）不存储在此技能中。请在项目自身的笔记或文档以及记忆中查找；如果找不到，请询问用户。

适用于每个任务的安全规则

• 绝不能自行运行、激活或触发工作流。 由用户启动运行。您可以在被要求时保存定义和切换开/关；明确说明切换何时会改变运行时的行为。
• 编辑前备份。 将要更改的每个工作流/表单的当前定义保存到本地已注明日期的文件夹中，并保留到用户确认结果为止。（过早删除备份曾导致无法回滚。）
• 机密信息。 工作流连接器包含凭据（UKG、其他供应商 API、密钥）。切勿打印、记录或将其放入文档中。检查工作流 JSON 时，屏蔽 password/secret/apikey/token/clientId 等键，仅打印结构。完成后删除包含机密的原始转储，并告知用户哪些本地文件夹仍包含它们。
• 由用户登录。 切勿输入密码。请用户在 Playwright 浏览器中登录并告知您已完成。
• 个人数据。 在您保留或共享的屏幕截图中模糊处理姓名、电子邮件和 ID。
• 如实报告。 如果测试表明某些操作未生效，请附上证据（时间戳、状态、日志行）说明，然后再提出下一个修复方案。

导致最多意外的六个平台事实

从惨痛教训中总结得出；详情和证据见 references/workflow-patterns.md。

1. 工作流顺序很重要 (WP-001)。 由工作流创建/更新的记录仅会触发位于工作流列表后面（更高序号）的工作流。放置在目标工作流之前的工作流不会触发任何操作。保持不同环境之间列表顺序一致。
2. 设计器会执行 API 所不执行的隐藏副作用操作。 在设计器中创建表单还会授予管理员角色访问权限（权限 32655）。通过 API 保存表单正文会创建表单及其默认菜单，但不会创建该权限，因此菜单在运行时中保持隐藏状态。子表单还需要其自身的父子关系调用。
3. 状态触发器需要实际的更改 (WP-002)。 在 Status _IsUpdated 上触发的工作流，如果新值与旧值相同，则不会启动（状态卡在“运行中”的记录无法通过再次设置“运行中”来重新运行）。
4. 一个工作流的触发运行是一个接一个进行的，并且循环并不总是等待它们完成 (WP-005)。 一个更新了 24 条记录的循环在几秒钟内完成，而它触发的 24 个工作流运行则在接下来的一小时内执行；同时启动的第二批工作流会丢失其触发的运行。一次只运行一批。
5. 运行时会缓存应用。 在设计更改后，单击应用名称旁边的刷新图标（或重新登录）；角色无法访问的表单菜单将被隐藏，因此新表单需要角色权限（请参阅复制检查清单）。
6. 路由器会执行其条件为真的每条路线 (WP-009)，而不仅仅是第一条。当只需要一个结果时，确保路线条件是互斥的。

如何高效工作

• 优先使用 API 而不是点击：它们更快、更精确且成本更低。仅对没有已知 API 的操作以及确认用户将看到的内容时使用 UI。
• 在 Playwright 中，从文件运行代码（使用 filename 的 browser_run_code_unsafe），从 localhost 辅助服务提供大型负载，并返回紧凑摘要（计数、名称、状态），绝不要返回整个 JSON。请参阅 references/playwright-efficiency.md。
• 在编辑工作流之前，通过 API 读取其节点树（名称、操作类型、表单），而不是打开设计器。
• 每次更改后，通过回读（API）进行验证，对于工作流，打开生成器一次以检查其是否正常渲染。
• 对于大型或重复性任务：编写一个小型生成器脚本（Python），该脚本根据现有节点的模板生成 JSON，然后编写一个受保护的应用脚本。将两者都保留在项目中，以便更改是可重复和可审查的。

文档默认值

仅限 Markdown（仅应要求提供 PDF），仅限内部受众（无客户电子邮件），在文档内以“为什么/为了什么”的形式提出开放性问题，图表仅显示正在运行的应用及其用户/外部系统。完整方法：references/documentation.md。当一个应用已有文档或项目笔记时，在再次探索该应用之前，请先阅读它们。

向此技能添加知识

当用户要求向此技能添加内容时（“将此添加到 cloudapper 技能中”）：

1. 读取此技能文件夹中的 inbox/TEMPLATE.md，并将草稿写入 inbox/<yyyy-mm-dd>-<short-name>.md，状态为 Hypothesis。请以通用方式编写：不包含客户、应用、表单、工作流或人员姓名、ID、真实主机或凭据。
2. 在 references/ 中搜索草稿确认或反驳的条目，并将它们列在草稿的审查备注中。
3. 除非用户说他们是应用已审查更改的维护者，否则不要自行编辑 SKILL.md 或 references/。请告知用户使用草稿提交拉取请求（CONTRIBUTING.md 中有流程）。