## 一、概述
`org` 对象用于在 O2OA 平台中获取和操作组织架构数据，包括人员、组织、身份、群组和角色等信息。支持同步/异步调用，可在流程表单、内容管理表单、门户页面、视图和查询视图中通过 `this.org` 访问。

## 二、核心方法分类

### 1. **身份（Identity）管理**
| 方法名 | 功能描述 | 返回值类型 |
|-------------------------|---------------------------------|-----------------------|
| `getIdentity(name)` | 根据身份标识获取身份对象或数组 | `Promise`/`IdentityData` |
| `listIdentityWithPerson(name)` | 根据人员标识获取身份数组 | `Promise`/`Array<IdentityData>` |
| `listIdentityWithUnit(name)` | 根据组织标识获取身份数组 | `Promise`/`Array<IdentityData>` |

**示例**：
```javascript
// 同步获取身份对象
const identity = this.org.getIdentity("李四@lisi@P");

// 异步获取人员的所有身份
this.org.listIdentityWithPerson("张三@zhangsan@P", true).then(identities => {
console.log(identities);
});
```

### 2. **组织（Unit）管理**
| 方法名 | 功能描述 | 返回值类型 |
|-------------------------|---------------------------------|-----------------------|
| `getUnit(name)` | 根据组织标识获取组织对象或数组 | `Promise`/`UnitData` |
| `listSubUnit(name)` | 获取下级组织数组（支持嵌套） | `Promise`/`Array<UnitData>` |
| `listTopUnit()` | 获取所有顶层组织 | `Promise`/`Array<UnitData>` |

**示例**：
```javascript
// 获取直接下级组织
const subUnits = this.org.listSubUnit("开发部@kfb@U");

// 获取顶层组织
this.org.listTopUnit().then(topUnits => {
console.log(topUnits);
});
```

### 3. **人员（Person）管理**
| 方法名 | 功能描述 | 返回值类型 |
|-------------------------|---------------------------------|-----------------------|
| `getPerson(name)` | 根据人员标识获取人员对象或数组 | `Promise`/`PersonData` |
| `listPersonWithUnit(name)` | 根据组织标识获取人员数组 | `Promise`/`Array<PersonData>` |
| `listPersonWithRole(name)` | 根据角色标识获取人员数组 | `Promise`/`Array<PersonData>` |

**示例**：
```javascript
// 同步获取人员对象
const person = this.org.getPerson("李四@lisi@P");

// 异步获取某个角色的所有成员
this.org.listPersonWithRole("Manager@ManagerSystemRole@R").then(people => {
console.log(people);
});
```

### 4. **群组（Group）与角色（Role）管理**
| 方法名 | 功能描述 | 返回值类型 |
|-------------------------|---------------------------------|-----------------------|
| `getGroup(name)` | 根据群组标识获取群组对象或数组 | `Promise`/`GroupData` |
| `listRoleWithPerson(name)` | 根据人员标识获取角色数组 | `Promise`/`Array<RoleData>` |
| `personHasRole(name, roleList)` | 检查人员是否拥有指定角色 | `Promise`/`Boolean` |

**示例**：
```javascript
// 检查用户是否属于某个角色
const hasRole = this.org.personHasRole("张三@zhangsan@P", "Manager@ManagerSystemRole@R");
```

### 5. **属性操作**
| 方法名 | 功能描述 | 返回值类型 |
|-------------------------|---------------------------------|-----------------------|
| `appendPersonAttribute(person, attr, values)` | 为人员添加属性值 | `Promise`/`void` |
| `getPersonAttribute(person, attr)` | 获取人员属性值数组 | `Promise`/`Array<String>` |
| `setUnitAttribute(unit, attr, values)` | 设置组织属性值 | `Promise`/`void` |

**示例**：
```javascript
// 为用户添加标签属性
this.org.appendPersonAttribute("李四@lisi@P", "标签", ["工程师", "管理员"]);
```

## 三、完整方法列表

### 1. **身份相关**
- **`getIdentity(name, asyncOrCallback)`**
获取身份对象或数组，支持同步/异步调用。
- **`listIdentityWithPerson(name)`**
根据人员获取其所有身份。
- **`listIdentityWithUnit(name)`**
根据组织获取其所有身份。

### 2. **组织相关**
- **`getUnit(name)`**
获取组织对象或数组。
- **`listSubUnit(name, nested)`**
获取下级组织（`nested` 控制是否递归）。
- **`listTopUnit()`**
获取所有顶层组织。

### 3. **人员相关**
- **`getPerson(name)`**
获取人员对象或数组。
- **`listPersonWithUnit(name)`**
根据组织获取人员列表。
- **`listPersonWithRole(name)`**
根据角色获取人员列表。

### 4. **群组与角色**
- **`getGroup(name)`**
获取群组对象或数组。
- **`listRoleWithPerson(name)`**
根据人员获取其所属角色。
- **`personHasRole(name, roleList)`**
检查人员是否拥有角色。

### 5. **属性操作**
- **`appendPersonAttribute(person, attr, values)`**
添加人员属性值。
- **`getPersonAttribute(person, attr)`**
获取人员属性值。
- **`setUnitAttribute(unit, attr, values)`**
设置组织属性值。

## 四、使用示例

### 1. **获取当前用户的所有身份**
```javascript
const currentUser = this.org.getPerson("张三@zhangsan@P");
const identities = this.org.listIdentityWithPerson(currentUser);
```

### 2. **获取某个组织的所有下级组织**
```javascript
this.org.listSubUnit("浙江兰德纵横@a706f5f0-4a3b-4785-8e1d-0a944bfad4eb@U", true).then(subUnits => {
subUnits.forEach(unit => console.log(unit.name));
});
```

### 3. **检查用户是否属于某个角色**
```javascript
this.org.personHasRole("李四@lisi@P", "Manager@ManagerSystemRole@R").then(hasRole => {
if (hasRole) {
console.log("用户是管理员");
}
});
```

## 五、注意事项
1. **参数格式**：输入参数需使用 `distinguishedName`、`id` 或 `unique` 标识，如 `"张三@zhangsan@P"`。
2. **异步处理**：建议使用 `Promise` 或回调函数处理异步操作，避免阻塞。
3. **权限控制**：部分方法需要管理员权限，确保用户有权限访问目标数据。
4. **属性操作**：属性值需为数组，支持添加或覆盖操作。

**提示**：更多组织架构配置和权限管理细节，请参考 O2OA 组织架构设计文档。