模块定义开发

属性、方法、事件和接口使用统一类型系统；本页只说明源码位置和模块发布流程。

模块版本来自项目 Git 快照。运行时可调用方法来自 methods/*.json，不能只修改数据库记录、Manager 页面或已经安装的运行态服务。

模块登记和专属源码项目通过 Bundle 内的创建入口完成。<bundle> 可以是 bundleId 或精确名称；CLI 会先解析 并校验唯一 Bundle，再把稳定 bundleId 写入模块定义：

baijimu bundle resource module create <bundle> \
  --workspace-id <workspaceId> \
  --resource-key daily-report \
  --name <projectName>

不要使用隐藏的旧版顶层 module create 作为新流程入口，也不要创建没有 Bundle 归属的 模块记录。

创建时必须通过 --resource-key 指定 Module 的资源 key，例如 daily-report；缺失、空值或非法 key 会被拒绝。完整身份为 environmentKey/bundleId/MODULE/resourceKey；不同 Bundle 可以使用相同 key，大小写不同的 key 表示不同资源。资源 key 不要求是 UUID，数据库行 ID 由 Owner 内部管理。后续命令中的 --resource-key 填写该资源 key，并始终同时选择 Bundle。

创建结果返回平台项目 ID；按项目分支策略检出并修改模板中的 module.json，填写非空名称后提交主线。名称、描述、属性、接口和用户域以项目源码为准。

登记保存资源 key、项目、工作区、Bundle 归属、归档状态和审计时间；不接受第二份名称、描述或元数据。改名直接修改 module.json 并提交主线，无需同步修改平台登记。开发态列表和详情读取当前主线，缺失或无效源码会明确报错。

模块资源 key 的唯一权威是 Module Owner 登记。module.json 不声明 id、resourceKey 或 resourceLocator；即使值与登记相同，重复声明也会被拒绝。项目与模块的关联由平台登记维护，读取源码和创建版本时由 Owner 注入资源身份，不能通过修改源码文件改写登记身份。

Bundle 清单及 Bundle 管理器引用使用登记返回的资源 key。跨服务引用使用完整的 environmentKey/bundleId/MODULE/resourceKey，精确版本引用另带 semanticVersion。Owner 内部数据库行 ID 不参与这些引用；历史数字或 UUID 形式的资源 key 仍是合法 key，不按其外观推断为内部编号，也不重命名历史不可变版本。

不可变版本始终来自发布指定的精确 Git 提交。后续改名不会改变已经发布或安装的版本；身份、权限、归属和历史版本查询不依赖当前源码。

主要文件

不同历史项目中的 JSON 字段可能使用数组或 JSON 字符串。修改时保留现有字段形状，除非当前版本迁移明确要求规范化。

属性

属性需要声明类型、必填、默认值、敏感性和管理方。常见分类：

• 连接凭据：appId、appSecret、token
• 路由配置：serviceBaseUrl
• 运行开关：autoStart、syncEnabled
• 运行态回填：外部实例 ID、状态、最后同步时间

敏感属性不能出现在页面文案、日志、Bundle Manifest 或普通返回值中。

模块需要引用另一个模块时，声明 Interface 属性，以 ServiceReference 表达逻辑目标。 Bundle 与 Module 使用相同的 propertyDefinition 声明。引用属性不能用 defaultValue 设置运行态目标。 Module 的 Interface、InterfaceMap 引用属性省略 autoBinding 时默认自动绑定，也可明确声明 true； 平台在同一 Application Runtime 中发现匹配提供方并维护引用，资源变化通过正常配置流程交付。 显式 false 关闭默认自动绑定；安装后的手动目标与清空配置优先，配置操作见下方属性指南。 两种方式均由 Runtime 校验当前目标、接口与授权，再向配置阶段交付调用凭据。 完整声明、单值冲突和 Map 收集规则见Bundle 与 Module 属性。 跨 Bundle 调用不声明 Bundle 安装依赖，完整方式见 ServiceReference 声明、绑定与运行时交付。

需要通过稳定业务键绑定多个同接口目标时，属性类型使用 InterfaceMap，属性值使用 ServiceReferenceMap。两者的 JSON 结构、安装后配置、整组替换和生命周期引用解析与配置更新规则见 InterfaceMap 与 ServiceReferenceMap。

方法

每个方法应明确：

• 稳定业务名称
• 参数类型、必填和默认值
• 返回类型和错误模型
• 需要的属性与用户域
• 超时、幂等和重试语义

方法行为写入该方法现有的 description，与方法源码一起创建不可变 Module 版本；完整要求见 方法行为与重试契约。 这些说明不会自动变成网关重试或超时策略，不能添加未定义的 idempotent、retryPolicy 等字段。

不要把内部 Controller 名、第三方原始路径或临时实现细节作为公共方法名。

paramDefinitions 是模块方法面对所有调用方的公共 JSON 输入契约。平台应用页面发送的 JSON 顶层字段与参数名称一一对应；模块内部 HTTP 请求的 methodBody 不属于页面协议。 通过 CLI 创建 HTTP 方法时使用 --type HttpMethod；这里的 HttpMethod 是平台方法实现类型， 不是 GET 或 POST。HTTP 动词写入 methodBody.http_method，查询参数映射写入 methodBody.query，不能把 GET、POST 或 QUERY 传给 --type。 methodBody 的可编辑源必须使用 snake_case，具体字段、示例和历史兼容边界见 HTTP methodBody 源契约。 浏览器侧的完整调用方式见 平台应用调用模块方法。

事件

后端模块事件是 module.json 顶层 events 数组中的版本化声明，不使用独立的 events/*.json 文件。事件的创建、修改和删除都通过修改这个数组完成，不要求独立的事件 CRUD 命令。

{
  "events": [
    {
      "name": "orderStatusChanged",
      "description": "订单状态发生变化后触发。",
      "paramDefinitions": [
        {
          "name": "orderId",
          "type": {
            "@type": "JsonSchema",
            "schema": {
              "type": "string"
            }
          },
          "description": "订单 ID。",
          "required": true
        },
        {
          "name": "status",
          "type": {
            "@type": "JsonSchema",
            "schema": {
              "type": "string"
            }
          },
          "description": "变更后的订单状态。",
          "required": true
        },
        {
          "name": "occurredAt",
          "type": {
            "@type": "JsonSchema",
            "schema": {
              "type": "integer"
            }
          },
          "description": "事件发生时间，Unix epoch 毫秒。",
          "required": true
        }
      ]
    }
  ]
}

新定义必须把 events 写成实际 JSON 数组，不要写成包含 JSON 文本的字符串。事件和参数名称 是调用方、订阅方和触发规则共同依赖的稳定契约；已经发布后若重命名或改变参数类型，应创建 明确的后继事件，而不是静默改变原事件语义。

paramDefinitions 描述事件载荷的顶层参数，类型结构与模块方法参数相同。必填、可空和对象内部约束统一见类型系统；时间业务单位见时间类型。

模块事件声明不同于本地 Connector 的 payload_schema，不要在两种能力之间复制字段名。 声明事件只会把事件加入模块版本和安装后的服务定义，不会自动发送事件，也不会自动创建 订阅或动作。事件生产方必须通过目标 Runtime 提供的事件发布能力发送与声明一致的载荷； 需要把事件绑定到模块方法或其他动作时，应把 Event Trigger 作为独立的 Bundle 资源管理。 工作流和独立模块后端的发布方式、地址来源、回调属性及安全边界见 模块事件与发布机制。

提交时检查并只提交预期源码，再使用该提交创建模块版本：

baijimu workspace project checkout <projectId> --workspace-id <workspaceId> --directory <directory>
cd <directory>
git diff -- module.json
git add -- module.json
git commit -m '<message>'
git push
commitId="$(git rev-parse HEAD)"

baijimu bundle resource module version create <bundle> \
  --workspace-id <workspaceId> \
  --project-id <projectId> \
  --resource-key daily-report \
  --version <semanticVersion> \
  --git-commit-id <commitId>

版本创建后应从版本定义或安装后的 Runtime 服务中回读事件名称和 paramDefinitions，确认它们来自 预期 Git 提交。只有整个 Bundle 的版本创建、市场审核和安装完成后，新事件才会进入目标 Runtime； 仅修改工作区文件或创建模块版本都不会升级已经安装的 Bundle。

用户身份

模块方法从运行时调用上下文获取当前 Runtime、已验证调用方、工作区和访问用户。不要依赖浏览器把 userId 作为普通业务参数传入。

需要映射第三方账号时，服务端保存百积木用户与外部账号的映射，并在调用前同时校验平台权限和外部系统权限。

当前可用字段、不同入口下的出现条件以及 HTTP 方法映射方式见 模块调用上下文。

与 Bundle 管理器开发的边界

模块声明属性、方法、事件和接口引用，不拥有 Bundle 的安装状态机。需要独立后端协调外部状态或 在生命周期中解析和保存 Runtime 引用凭据时，统一使用Bundle 管理器开发。 管理器登记、请求协议、阶段处理和安装验证均在该入口维护；模块文档仅负责资源声明和服务调用。

创建模块版本遇到管理器退役或安装时协议不匹配，请按 从旧插件迁移到 Bundle 管理器 定位精确源码与失败资源，完成后继版本迁移；不能只升级 CLI 或替换管理器名称。