@alanwang-merit/meritdata-platform-skill-package 1.0.8 → 1.0.10

package/skills/meritdata-platform-integration/references/external-api/full/29_2.3/350/247/222/350/211/262/347/273/264/346/212/244-/344/270/212/345/215/212.md

@@ -0,0 +1,576 @@
+---
+name: 角色维护-上半（2.3.1-2.3.8）
+source-file: 外部接口清单
+source-section: 2 组织机构 → 2.3 角色维护 → 2.3.1–2.3.8
+keywords: [角色维护, 添加角色人员, 角色列表, 用户角色, 角色下人员, 角色查询]
+use-cases: [角色CRUD, 角色人员管理, 角色列表查询, 当前用户角色]
+related: [30]
+---
+
+# 角色维护-上半（2.3.1-2.3.8）
+
+> **原文章节**：外部接口清单 → 2 组织机构 → 2.3 角色维护 → 2.3.1–2.3.8
+> **行号范围**：L4450–L4995
+
+## 🎯 一句话
+角色维护的前 8 个接口：添加角色人员、新增角色、删除角色、角色下人员列表、用户角色查询、角色 ID 查询、当前用户角色、角色人员查询（分页）。
+
+## 📋 接口清单
+
+---
+
+## 2.3 角色维护
+
+---
+
+### 2.3.1 添加角色下的人员
+
+- **接口地址**：`/api/ou/role/assign`
+- **请求类型**：`multipart/form-data`
+- **请求方式**：`post`
+- **接口备注**：`添加角色下的人员`
+- **调试工具**：`ApiPost`
+
+**请求体参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 是否必填 | 参数描述 |
+|---|---|---|---|---|
+| roleId | 6e6651515835488 3997b25f575e6947 4 | String | 是 | 暂无描述 |
+| emps | [{"tenantId":"","sec retCode":null,"secr etName":null,"crea teTime":null,"updat eTime":166123630 1714,"creatorId":n ull,"reviserId":null," id":"52b421b7c8a1 45a6ab9d32f0255a b9d2","name":"wei jiahui","code":"wjh ","sex":null,"birthd ay":null,"folk":"汉 族 ","education":null," handset":null,"fami lyPhone":null,"ema il":null,"sortNo":3," systemUser":1,"de ptId":"3f2883b282 1950330182199cb9 6e0047","deptCode ":"merit","deptNa me":"美林数据 ","userId":null,"use rState":null,"weixin No":null,"province" :null,"city":null,"co unty":null,"grade":" ","workgroupName ":null,"workgroupId ":null,"postName": null,"postId":null,"p ostFlag":null,"roleI d":null,"ipAddress": null,"macAddress": null,"gradeName": null,"manageDeptN ame":null,"manage | String | 是 | 暂无描述 |
+
+**返回成功参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 参数描述 |
+|---|---|---|---|
+| 无请求参数 KEY/VALUE类型 |  |  |  |
+
+**返回失败参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 参数描述 |
+|---|---|---|---|
+| 201 | Object | Object | Created |
+| 401 | Object | Object | Unauthorized |
+| 403 | Object | Object | Forbidden |
+| 404 | Object | Object | Not Found |
+
+**返回成功示例**：
+
+```json
+{
+"result": "true"
+}
+```
+
+
+**返回失败示例**：
+
+```json
+{"201":{},"401":{},"403":{},"404":{}}
+```
+
+---
+
+### 2.3.2
+
+- **接口地址**：`/api/ou/role/create`
+- **请求类型**：`multipart/form-data`
+- **请求方式**：`post`
+- **接口备注**：`新增角色接口`
+---
+
+### 新增角色接口
+
+- **接口备注**：`新增角色接口`
+- **调试工具**：`ApiPost`
+
+**请求体参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 是否必填 | 参数描述 |
+|---|---|---|---|---|
+| name | 888 | String | 是 | 暂无描述 |
+
+**返回成功参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 参数描述 |
+|---|---|---|---|
+| 无请求参数 KEY/VALUE类型 |  |  |  |
+
+**返回失败参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 参数描述 |
+|---|---|---|---|
+| 201 | Object | Object | Created |
+| 401 | Object | Object | Unauthorized |
+| 403 | Object | Object | Forbidden |
+| 404 | Object | Object | Not Found |
+
+**返回失败示例**：
+
+```json
+{"201":{},"401":{},"403":{},"404":{}}
+```
+
+---
+
+### 2.3.3
+
+- **接口地址**：`/api/ou/role/delete`
+- **请求类型**：`multipart/form-data`
+- **请求方式**：`post`
+- **接口备注**：`删除角色接口`
+---
+
+### 删除角色接口
+
+- **接口备注**：`删除角色接口`
+- **调试工具**：`ApiPost`
+
+**请求体参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 是否必填 | 参数描述 |
+|---|---|---|---|---|
+| ids | 1972cbba12d14fc1 9a1f9942cf4949f6 | String | 是 | 暂无描述 |
+
+**返回成功参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 参数描述 |
+|---|---|---|---|
+| 无请求参数 KEY/VALUE类型 |  |  |  |
+
+**返回失败参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 参数描述 |
+|---|---|---|---|
+| 201 | Object | Object | Created |
+| 401 | Object | Object | Unauthorized |
+| 403 | Object | Object | Forbidden |
+| 404 | Object | Object | Not Found |
+
+**返回成功示例**：
+
+```json
+{
+"names": "888",
+"success":true
+}
+```
+
+
+**返回失败示例**：
+
+```json
+{"201":{},"401":{},"403":{},"404":{}}
+```
+
+---
+
+### 2.3.4
+
+- **接口地址**：`/api/ou/role/empList`
+- **请求类型**：`multipart/form-data`
+- **请求方式**：`post`
+- **接口备注**：`角色下人员列表`
+---
+
+### 角色下人员列表
+
+- **接口备注**：`角色下人员列表`
+- **调试工具**：`ApiPost`
+
+**请求体参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 是否必填 | 参数描述 |
+|---|---|---|---|---|
+| id | 112c9e1c1b634e6e 96a4104e79ee262d | String | 是 | 暂无描述 |
+
+**返回失败参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 参数描述 |
+|---|---|---|---|
+| 201 | Object | Object | Created |
+| 401 | Object | Object | Unauthorized |
+| 403 | Object | Object | Forbidden |
+| 404 | Object | Object | Not Found |
+
+**返回成功示例**：
+
+```json
+[
+{
+"tenantId": "",
+"secretCode": null,
+"secretName": null,
+"createTime": null,
+"updateTime": 1661237458042,
+页 110/276
+"creatorId": null,
+"reviserId": null,
+"id": "3d6887c59b5642899425ea21202287b8",
+"name": "sadasd",
+"code": "sds",
+"sex": null,
+"birthday": null,
+"folk": null,
+"education": null,
+"handset": null,
+"familyPhone": null,
+"email": null,
+"sortNo": null,
+"systemUser": null,
+"deptId": null,
+"deptCode": "dsd",
+"deptName": "dsd",
+"userId": null,
+"userState": null,
+"weixinNo": null,
+"province": null,
+"city": null,
+"county": null,
+"grade": null,
+"workgroupName": null,
+"workgroupId": null,
+"postName": null,
+"postId": null,
+"postFlag": null,
+"roleId": null,
+"ipAddress": null,
+"macAddress": null,
+"gradeName": null,
+"manageDeptName": null,
+"manageDeptId": null,
+"empCategorys":{},
+"cateCodes": null,
+"userName": null,
+"detptype": null,
+"roleName": null,
+"did": null,
+"isSubDsAdmin": null,
+"isCGSysadmin": null,
+"authStatus": null,
+"parentsOrgs":{},
+"resultName": null,
+"cycleDeptName": null,
+页 111/276
+"userType": null,
+"d": null,
+"addTime": null,
+"lastTime": null,
+"e": null,
+"f": null,
+"g": null,
+"h": null,
+"i": null,
+"j": null,
+"k": null,
+"l": null,
+"m": null,
+"n": null,
+"o": null,
+"p": null,
+"q": null,
+"r": null,
+"s": null,
+"t": null,
+"u": null,
+"v": null,
+"w": null,
+"x": null,
+"y": null,
+"z": null
+}
+```
+
+
+**返回失败示例**：
+
+```json
+{"201":{},"401":{},"403":{},"404":{}}
+```
+
+---
+
+### 2.3.5 查询用户角色列表接口
+
+- **接口地址**：`/api/ou/role/getCurrentRole`
+- **请求类型**：`multipart/form-data`
+- **请求方式**：`post`
+- **接口备注**：`角色列表接口`
+---
+
+### 角色列表接口
+
+- **接口备注**：`角色列表接口`
+- **调试工具**：`ApiPost`
+
+**请求体参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 是否必填 | 参数描述 |
+|---|---|---|---|---|
+| userId | 3d6887c59b564289 9425ea21202287b8 | String | 是 | 暂无描述 |
+
+**返回成功参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 参数描述 |
+|---|---|---|---|
+| 无请求参数 KEY/VALUE类型 |  |  |  |
+
+**返回失败参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 参数描述 |
+|---|---|---|---|
+| 201 | Object | Object | Created |
+| 401 | Object | Object | Unauthorized |
+| 403 | Object | Object | Forbidden |
+| 404 | Object | Object | Not Found |
+
+**返回失败示例**：
+
+```json
+{"201":{},"401":{},"403":{},"404":{}}
+```
+
+---
+
+### 2.3.6 Id
+
+- **接口地址**：`/api/ou/role/getRoleIdByCode`
+- **请求类型**：`multipart/form-data`
+- **请求方式**：`post`
+- **接口备注**：`根据编码获取角色Id`
+- **调试工具**：`ApiPost`
+
+**请求体参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 是否必填 | 参数描述 |
+|---|---|---|---|---|
+
+**返回成功参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 参数描述 |
+|---|---|---|---|
+| 无请求参数 KEY/VALUE类型 |  |  |  |
+
+**返回失败参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 参数描述 |
+|---|---|---|---|
+| 201 | Object | Object | Created |
+| 401 | Object | Object | Unauthorized |
+| 403 | Object | Object | Forbidden |
+| 404 | Object | Object | Not Found |
+
+**返回失败示例**：
+
+```json
+{"201":{},"401":{},"403":{},"404":{}}
+```
+
+---
+
+### 2.3.7
+
+- **接口地址**：`/api/ou/role/getRoleIds`
+- **请求类型**：`multipart/form-data`
+- **请求方式**：`post`
+- **接口备注**：`获取当前用户的所有角色信息`
+---
+
+### 获取当前用户的所有角色信息
+
+- **接口备注**：`获取当前用户的所有角色信息`
+- **调试工具**：`ApiPost`
+
+**请求体参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 是否必填 | 参数描述 |
+|---|---|---|---|---|
+| userId | 3d6887c59b564289 9425ea21202287b8 | String | 是 | 暂无描述 |
+
+**返回成功参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 参数描述 |
+|---|---|---|---|
+| 无请求参数 KEY/VALUE类型 |  |  |  |
+
+**返回失败参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 参数描述 |
+|---|---|---|---|
+| 201 | Object | Object | Created |
+| 401 | Object | Object | Unauthorized |
+| 403 | Object | Object | Forbidden |
+| 404 | Object | Object | Not Found |
+
+**返回失败示例**：
+
+```json
+{"201":{},"401":{},"403":{},"404":{}}
+```
+
+---
+
+### 2.3.8
+
+- **接口地址**：`/api/ou/role/getRoleUser`
+- **请求类型**：`multipart/form-data`
+- **请求方式**：`post`
+- **接口备注**：`查询角色下人员列表接口`
+---
+
+### 查询角色下人员列表接口
+
+- **接口备注**：`查询角色下人员列表接口`
+- **调试工具**：`ApiPost`
+
+**请求体参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 是否必填 | 参数描述 |
+|---|---|---|---|---|
+| page | 1 | String | 是 | 分页页码，数字类型 |
+| rows | 10 | String | 是 | 暂无描述 |
+
+**返回成功参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 参数描述 |
+|---|---|---|---|
+| timestamp | 1661239361522 | String | 时间戳 |
+| status | 1 | Integer | 状态 |
+| message | 成功 | String | 返回消息 |
+| stackmessage |  | String | 堆栈消息 |
+| path | /api/ou/role/getRoleUser | String | api 路径 |
+| data |  | String | 返回数据 |
+
+**返回失败参数说明：**
+
+| 参数名 | 示例值 | 参数类型 | 参数描述 |
+|---|---|---|---|
+| 201 | Object | Object | Created |
+| 401 | Object | Object | Unauthorized |
+| 403 | Object | Object | Forbidden |
+| 404 | Object | Object | Not Found |
+
+**返回成功示例**：
+
+```json
+{
+"timestamp": 1661239361522,
+"status": 1,
+"message": "成功",
+"stackmessage": null,
+"path": "/api/ou/role/getRoleUser",
+"data":{
+"rows": [
+{
+"tenantId": "",
+"secretCode": null,
+"secretName": null,
+"createTime": null,
+"updateTime": 1661239361512,
+"creatorId": null,
+"reviserId": null,
+"id": "602b31e6555d43e6aacc109a2ec464d8",
+"name": "张彦 2",
+"code": "zhangyans",
+"sex": null,
+"birthday": null,
+"folk": null,
+"education": null,
+"handset": null,
+"familyPhone": null,
+"email": null,
+"sortNo": null,
+"systemUser": null,
+"deptId":
+"3f2883b282195033018219a0be6b004e",
+"deptCode": "11",
+"deptName": "11",
+"userId": null,
+"userState": null,
+"weixinNo": null,
+"province": null,
+"city": null,
+"county": null,
+"grade": null,
+"workgroupName": null,
+"workgroupId": null,
+"postName": null,
+页 116/276
+"postId": null,
+"postFlag": null,
+"roleId": null,
+"ipAddress": null,
+"macAddress": null,
+"gradeName": null,
+"manageDeptName": null,
+"manageDeptId": null,
+"empCategorys":{},
+"cateCodes": null,
+"userName": null,
+"detptype": null,
+"roleName": null,
+"did": "3f2883b2821a524201821a54b9d40008",
+"isSubDsAdmin": null,
+"isCGSysadmin": null,
+"authStatus": null,
+"parentsOrgs":{},
+"resultName": null,
+"cycleDeptName": null,
+"userType": null,
+"d": null,
+"addTime": null,
+"lastTime": null,
+"e": null,
+"f": null,
+"g": null,
+"h": null,
+"i": null,
+"j": null,
+"k": null,
+"l": null,
+"m": null,
+"n": null,
+"o": null,
+"p": null,
+"q": null,
+"r": null,
+"s": null,
+"t": null,
+"u": null,
+"v": null,
+"w": null,
+"x": null,
+"y": null,
+"z": null
+},
+页 117/276
+],
+"deptcodes": null,
+"total": 12,
+"pageSize":0,
+"pageNumber":0,
+"totalPages":0,
+"records":0
+},
+"extraInfo":{},
+"success":true
+}
+```
+
+
+**返回失败示例**：
+
+```json
+{"201":{},"401":{},"403":{},"404":{}}
+```
+
+---
+
+## 💡 使用建议
+- 2.3.1 `assign` 是 **角色分配人员的核心接口**，`emps` 字段需要传完整的 emp JSON 数组
+- 2.3.4 `empList` 与 2.3.8 `getRoleUser` 都是角色下人员查询：前者返回纯数组，后者返回分页对象（带 `rows/total`）
+- 2.3.5 `getCurrentRole` 与 2.3.7 `getRoleIds` 命名相似但功能不同：前者查"当前用户角色"，后者查"指定用户角色 ID 列表"
+- 2.3.6 `getRoleIdByCode` 用于业务编码反查平台 ID，常用于同步场景
+
+## 🔗 相关章节
+- [28_2.2人员维护-下半](./28_2.2人员维护-下半.md)
+- [30_2.3角色维护-下半（待生成）]