.role 文件 Schema¶
位置：
/{软件名}.application/role/{角色名}.role（单文件） | XML 根：role| 与技能对齐：generate-role-file机制背景见 [[design/table-schema/overview]]。
1. 用途与落盘¶
角色 = 把域用户接到软件的权限载体（RBAC）。前台用户可见非系统软件的条件：域绑定 + activated=true + 拥有该软件下 status=1 角色。
2. 属性表¶
| 属性 | XML 形态 | 类型 | 默认 | 说明 |
|---|---|---|---|---|
id |
根属性 | string | 须生成 | __ + 短 UUID；鉴权缓存键组成部分 |
name |
子元素 | string | — | 必填；文件名；同应用唯一 |
roleNo |
子元素 | string | — | 必填（设计态校验）；同应用唯一；脚本 getRoleByRoleNo 用 |
parentId / applicationid |
子元素 | string | — | = 软件 id（applicationid 须手写） |
status |
子元素 | int | 1 | 1=有效；0=失效（有绑定也不当有效角色） |
defaultRole |
子元素 | bool | true=默认角色；新建用户/微信钉钉飞书同步自动挂上 | |
orderNo |
子元素 | int | 0 | 排序 |
permissions |
子元素 CDATA | string | 可省略 | JSON 数组，见 §3 |
sortId |
子元素 | string | 可选 | |
description / remark |
CDATA |
3. permissions JSON¶
CDATA 内 JSON 数组，每项一个 Permission：
[{
"operationCode": 1002, "operationId": "资源或操作id", "resId": "资源id",
"resName": "菜单|打开|详情|编辑|按钮名", "resType": 2, "type": 1, "roleId": ""
}]
运行时鉴权键：{roleId}_{resId}_{operationId}_{operationCode} 命中即有权。
resType¶
| 值 | 含义 | 值 | 含义 |
|---|---|---|---|
| 0 | 视图 | 3 | 表单字段 |
| 1 | 表单 | 4 | 文件夹 |
| 2 | 菜单（PC/移动同源） |
operationCode（常用）¶
| 值 | 含义 | 说明 |
|---|---|---|
| 1000 | 所有操作 | |
| 1002 | 菜单授权 | 菜单授权实际用此码 + type=1（历史命名 MENU_INVISIBLE 勿按字面理解） |
| 1032 | 打开 | 表单/视图允许打开；operationId=resId=表单/视图 id |
| 1033 / 1034 | 详情 / 编辑 | 视图操作；operationId 可为 {viewId}_1033 形式，落盘归一为 viewId |
| 1011–1014 | 字段权限 | 只读/修改/隐藏/禁用 |
| 其它 | activity.type() | 工具栏按钮；operationId=activity.id |
type：1=允许，2=禁止。
4. XML 骨架¶
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<role id="__roleAdmin000000001">
<name>管理员</name>
<parentId>__a1b2c3d4e5f6g7h8i9j</parentId>
<applicationid>__a1b2c3d4e5f6g7h8i9j</applicationid>
<roleNo>1</roleNo>
<status>1</status>
<defaultRole>true</defaultRole>
<orderNo>0</orderNo>
</role>
带授权时追加 <permissions><![CDATA[{json}]]></permissions>。
5. 校验（设计态）¶
name/roleNo 空 → 拒存；同应用 name 或 roleNo 重复 → 「名称已存在」/「编号已存在」。用户绑定在运行库（UserDepartmentRoleSet），不在 workspace 文件内。KM 模块有固定角色 id/编号特例，见技能文档 §8。
6. 相关¶
| 资源 | 文档 |
|---|---|
| 所属软件 | [[application-file]] |
| 菜单授权对象 | [[menu-file]] |
| 用户体系表 | design/table-schema/usercenter-tables.md |
| 生成操作指南 | agent-skills-usage/skills/generate-role-file/SKILL.md |