openxiangda 1.0.226 → 1.0.227

package/README.md

@@ -510,6 +510,8 @@ const PublicAccessError = ({ error }: { error: { message?: string } }) => (
 
 后端业务逻辑优先声明为 App Function：源码放在 `src/functions/<functionCode>/index.ts`，资源 manifest 放在 `src/resources/functions/<functionCode>.json`。函数运行在 trusted_node 中，通过 `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`、`ctx.files.readAsBase64`、`ctx.process.startFromExistingInstance/resolveCapabilities/resubmitTask/withdraw/transferTask`、`ctx.dataView`、`ctx.connector`、`ctx.notification`、`ctx.organization`、`ctx.platform.roles`、`ctx.platform.api` 等受控 API 访问平台能力；自动化、流程和运行时接口都可以调用同一个 function。`ctx.files.readAsBase64` 只读取当前 `formData` 已授权的图片附件，或由当前应用的 `formCode/formUuid + formInstId + fieldId` 定位的图片；它不会下载任意 URL，单文件上限为 10 MiB，Base64 不应写入日志、函数返回值或业务表。已发布可信代码可以访问当前租户、当前应用内的资源，Function `resources` 是可选的环境映射、审计和影响分析信息，不再是逐函数权限白名单；跨应用、跨租户和外部敏感能力仍受平台边界限制。`ctx.process` 复用正式工作流服务，以真实运行时 operator 执行，流程实例、任务授权、操作日志、事件和 replay 语义与 PageSdk 后端接口一致。角色查询和角色成员维护优先使用 `ctx.platform.roles.list/findByCode/addUsers/removeUser`，底层 `ctx.platform.api` 返回 HTTP 包装和平台 envelope，需要业务代码自行解包。运行时页面调用会在 `ctx.operator`、`ctx.currentUser`、`ctx.permissions` 中注入可信的角色上下文；敏感业务动作必须读取这些服务端上下文，不要信任页面 input 里传入的角色字段。`ctx.form.createOne/updateOne/updateById` 是后端受控写入，不是页面用户对目标表单的直接提交入口；内部多表写入应走 App Function，不要为了函数写入给普通用户开放原始 submit 权限。内部业务表单需要关闭原始写入接口时，在表单 settings 中设置 `runtimeWrite.mode="function_only"`。
 
+`trusted_node_v2` 的应用角色正式契约和完整 TypeScript 示例见 [App Function 角色 API](docs/app-function-role-api.md)。业务函数应直接声明 `ctx: AppFunctionContextV2` 后调用 `ctx.platform.roles`；不再自行扩展上下文类型，也不要通过 `ctx.platform.api` 拼角色管理 URL。
+
 App Function 访问第三方凭据时使用 `app_function_secrets_v1`：manifest 顶层只声明 `secretRefs: [{ "name": "dingtalk_org_app_key", "required": true }]`，同时使用 `definitionJson.version="function_v2"`、`runtimeContractVersion="trusted_node_v2"`；源码通过 `await ctx.secrets.get(name)` 解析，并通过 `ctx.utils.http` 访问受控公网 HTTPS（该桥接不会携带平台 Runtime token）。值只能经 `openxiangda secret create|rotate --value-stdin --change <id> --profile <name>` 或隐藏 TTY 输入，禁止进入 Git、manifest、源码、构建产物、plan、日志或异常。带 `secretRefs` 的 Function 必须走 `backend_release_v2`；需要整应用原子发布时先执行 `resource publish function --only <code> --stage-only`，再把返回的真实 `stagedResource` 交给 `release app-finalize --staged-resources-json ...` 完成 `atomic_staged_children_v2`。默认直接激活的 Backend Release 只返回 `activeResource`，不会伪装成 staged；旧平台 capability 不完整时 CLI 会失败关闭，绝不忽略绑定。
 
 平台部门和账号管理走 app-scoped organization 能力。只读查询要求目标应用的 `app:organization:read` 或 `app:organization:manage`，创建、更新和密码操作要求 `app:organization:manage`；平台管理员天然可用，普通应用角色需要显式授权。Runtime service principal 不会直接放行，`ctx.organization` 会按真实操作人 / audit actor 校验权限。新接口不提供删除；`account-update` 不能携带 `password`，重置他人密码必须走 `account-reset-password`，当前用户改密用 SDK / `ctx.organization.accounts.changeMyPassword({ oldPassword, newPassword })`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "1.0.226",
+  "version": "1.0.227",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {
@@ -95,6 +95,7 @@
     "test:help-no-side-effects": "node scripts/help-no-side-effects-smoke.mjs",
     "test:app-function-fallback": "node scripts/app-function-source-fallback-smoke.mjs",
     "test:app-function-secrets": "node scripts/app-function-secrets-cli-smoke.mjs",
+    "test:app-function-role-contract": "node scripts/app-function-role-contract-smoke.mjs",
     "test:change-baseline": "node scripts/change-baseline-smoke.mjs",
     "test:change-baseline-publish": "node scripts/change-baseline-publish-smoke.mjs",
     "test:generic-base-preflight": "node scripts/generic-git-base-preflight-smoke.mjs",