From: 刘洪青 <hongqing.liu@supwisdom.com>
Date: Fri, 24 Dec 2021 09:53:07 +0000 (+0800)
Subject: docs: 完善文档 产品部署之中台服务对接数据初始化相关接口的说明
X-Git-Url: https://source.supwisdom.com/gerrit/gitweb?a=commitdiff_plain;h=0799c53dd6aafc5b640a1066f23353f3c23488c5;p=institute%2Fdeploy-authx-service.git

docs: 完善文档 产品部署之中台服务对接数据初始化相关接口的说明
---

diff --git "a/docs/\344\272\247\345\223\201\351\203\250\347\275\262\344\271\213\344\270\255\345\217\260\346\234\215\345\212\241\345\257\271\346\216\245\346\225\260\346\215\256\345\210\235\345\247\213\345\214\226\347\233\270\345\205\263\346\216\245\345\217\243\347\232\204\350\257\264\346\230\216.md" "b/docs/\344\272\247\345\223\201\351\203\250\347\275\262\344\271\213\344\270\255\345\217\260\346\234\215\345\212\241\345\257\271\346\216\245\346\225\260\346\215\256\345\210\235\345\247\213\345\214\226\347\233\270\345\205\263\346\216\245\345\217\243\347\232\204\350\257\264\346\230\216.md"
index a3ad150..44c2def 100644
--- "a/docs/\344\272\247\345\223\201\351\203\250\347\275\262\344\271\213\344\270\255\345\217\260\346\234\215\345\212\241\345\257\271\346\216\245\346\225\260\346\215\256\345\210\235\345\247\213\345\214\226\347\233\270\345\205\263\346\216\245\345\217\243\347\232\204\350\257\264\346\230\216.md"
+++ "b/docs/\344\272\247\345\223\201\351\203\250\347\275\262\344\271\213\344\270\255\345\217\260\346\234\215\345\212\241\345\257\271\346\216\245\346\225\260\346\215\256\345\210\235\345\247\213\345\214\226\347\233\270\345\205\263\346\216\245\345\217\243\347\232\204\350\257\264\346\230\216.md"
@@ -20,81 +20,311 @@
 
 ### CAS认证
 
-**采用 sql 文件执行接口进行部署**
+**采用业务管理接口进行部署**
 
-版本要求：1.2.2
+版本要求：1.2.0
 
 * 部署接口
 
+1. 创建 Service
+
 ```bash
 curl -i -s -X POST \
-  -H 'Content-Type: text/plain' \
-  --data-binary @cas_server_integrate.sql \
-  'http://cas-server-sa.cas-server.svc.cluster.local:8080/deploy/execSql'
+  -H 'Content-Type: application/json' \
+  -d '{
+  "id": "0",
+  "companyId": 1,
+  "name": "示例",
+  "description": "示例",
+  "informationUrl": "https://example.com",
+  "logoutUrl": "https://example.com/slo",
+  "responseType": "REDIRECT",
+  "logoutType": "FRONT_CHANNEL",
+  "evaluationOrder": 0,
+  "friendlyName": "示例",
+  "registeredServiceId": 0,
+  "serviceId": "https://example.com/(.*)",
+  "enabled": true,
+  "ssoEnabled": true,
+  "requireAllAttributes": true,
+  "idTokenEnabled": false,
+  "jwtAsServiceTicket": false,
+  "adaptV4Product": false,
+  "applicationId": "0",
+  "applicationDomain": "example.com",
+  "externalId": "0"
+}' \
+  'http://authx-service-user-data-service-goa.authx-service.svc.cluster.local:8080/v1/admin/services'
 ```
 
-* SQL脚本示例
-
-cas_server_integrate.sql
-```sql
--- Service 的创建
-INSERT INTO TB_SERVICE (ID, COMPANY_ID, DELETED, ADD_ACCOUNT, ADD_TIME, 
-  NAME, DESCRIPTION, INFORMATION_URL, LOGOUT_URL, 
-  RESPONSE_TYPE, LOGOUT_TYPE, 
-  EVALUATION_ORDER, FRIENDLY_NAME, REGISTERED_SERVICE_ID, SERVICE_ID, 
-  ENABLED, SSO_ENABLED, REQUIRE_ALL_ATTRIBUTES, 
-  ID_TOKEN_ENABLED, JWT_AS_SERVICE_TICKET, ADAPT_V4_PRODUCT, 
-  APPLICATION_ID, APPLICATION_DOMAIN, EXTERNAL_ID)
-VALUES ('0', '1', 0, 'admin', null,
-  '示例', '示例', 'https://example.com', 'https://example.com/slo', 
-  'REDIRECT', 'FRONT_CHANNEL', 
-  0, '示例', 0, 'https://example.com/(.*)', 
-  1, 1, 1, 
-  0, 0, 0, 
-  '0', 'example.com', '0');
+2. 更新 Service
 
-commit;
+```bash
+curl -i -s -X PUT \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "id": "0",
+  "companyId": 1,
+  "name": "示例",
+  "description": "示例",
+  "informationUrl": "https://example.com",
+  "logoutUrl": "https://example.com/slo",
+  "responseType": "REDIRECT",
+  "logoutType": "FRONT_CHANNEL",
+  "evaluationOrder": 0,
+  "friendlyName": "示例",
+  "registeredServiceId": 0,
+  "serviceId": "https://example.com/(.*)",
+  "enabled": true,
+  "ssoEnabled": true,
+  "requireAllAttributes": true,
+  "idTokenEnabled": false,
+  "jwtAsServiceTicket": false,
+  "adaptV4Product": false,
+  "applicationId": "0",
+  "applicationDomain": "example.com",
+  "externalId": "0"
+}' \
+  'http://authx-service-user-data-service-goa.authx-service.svc.cluster.local:8080/v1/admin/services'
 ```
 
+
 > 说明
 
-修改 ID、EVALUATION_ORDER、REGISTERED_SERVICE_ID、APPLICATION_ID、EXTERNAL_ID，应用的ID、标识等
+修改 id、registeredServiceId、applicationId、externalId，应用的ID、标识等
 
-修改 NAME、DESCRIPTION、FRIENDLY_NAME，应用的名称
+修改 evaluationOrder
 
-修改 ID_TOKEN_ENABLED、JWT_AS_SERVICE_TICKET，1 启用，0 禁用
+修改 name、description、friendlyName，应用的名称
 
-修改 INFORMATION_URL、LOGOUT_URL、SERVICE_ID、APPLICATION_DOMAIN，相关地址、域名修改
+修改 idTokenEnabled、jwtAsServiceTicket、adaptV4Product，true 启用，false 禁用
 
-> 应用对接表 TB_SERVICE
+修改 informationUrl、logoutUrl、serviceId、applicationDomain，相关地址、域名修改
 
-字段名 | 字段说明
-- | -
-ID | 确保唯一性
-COMPANY_ID | 固定为 1
-DELETED | 是否删除，固定为 0
-ADD_ACCOUNT | 创建帐号
-ADD_TIME | 创建时间，建议为 null；如必要，可填入时间
+
+
+* 接口属性说明
+
+> 应用（Service）的属性说明
+
+属性名 | 说明
 - | -
-NAME | 应用名称
-DESCRIPTION | 描述
-INFORMATION_URL | 应用的访问地址
-LOGOUT_URL | 应用的前端注销地址
-RESPONSE_TYPE | 登录成功后的响应方式，固定为 REDIRECT
-LOGOUT_TYPE | 单点注销方式，固定为 FRONT_CHANNEL
-EVALUATION_ORDER | 优先级
-FRIENDLY_NAME | 同 应用名称
-REGISTERED_SERVICE_ID | 唯一ID，整型
-SERVICE_ID | 应用匹配规则，确保前缀与对接时的 service 相匹配
-ENABLED | 是否启用
-SSO_ENABLED | 是否支持单点登录
-REQUIRE_ALL_ATTRIBUTES | 固定为 true
-ID_TOKEN_ENABLED | 是否返回 ID Token，方便公司内产品的前端，调用后端接口
-JWT_AS_SERVICE_TICKET | 是否返回 JWT 格式的票据，便于纯前端项目对接
-ADAPT_V4_PRODUCT | 是否适配认证V4，用于兼容公司历史版本的认证
-APPLICATION_ID | 应用标识，与 ID 保持一致
-APPLICATION_DOMAIN | 应用域，使用访问地址中的 域名
-EXTERNAL_ID | 外部ID（预留），与 ID 保持一致
+id | 确保唯一性
+name | 应用名称
+description | 描述
+informationUrl | 应用的访问地址
+logoutUrl | 应用的前端注销地址
+responseType | 登录成功后的响应方式，固定为 REDIRECT
+logoutType | 单点注销方式，固定为 FRONT_CHANNEL
+evaluationOrder | 优先级
+friendlyName | 同 应用名称
+registeredServiceId | 唯一ID，整型
+serviceId | 应用匹配规则，确保前缀与对接时的 service 相匹配
+enabled | 是否启用
+ssoEnabled | 是否支持单点登录
+requireAllAttributes | 固定为 true
+idTokenEnabled | 是否返回 ID Token，方便公司内产品的前端，调用后端接口
+jwtAsServiceTicket | 是否返回 JWT 格式的票据，便于纯前端项目对接
+adaptV4Product | 是否适配认证V4，用于兼容公司历史版本的认证
+applicationId | 应用标识，可与 id 保持一致
+applicationDomain | 应用域，使用访问地址中的 域名
+externalId | 外部ID（预留），与 id 保持一致
+
+
+
+### 用户服务
+
+可以添加 用户、账号，部门，用户组，
+
+服务地址：`http://authx-service-user-data-service-goa.authx-service.svc.cluster.local:8080`
+
+* 用户创建接口
+
+版本要求：1.2.7、1.3.2、1.4.1、1.5.0
+
+**仅创建用户的基本信息，不会创建账号**
+
+POST /api/v1/trans/user?transOrigin=init
+Content-Type: application/json
+
+```json
+{
+  "uid": "string",
+  "passWord": "string",
+  "name": "string",
+  "nameSpelling": "string",
+  "fullNameSpelling": "string",
+  "certificateTypeCode": "string",
+  "certificateNumber": "string",
+  "phoneNumber": "string",
+  "email": "string",
+  "imageUrl": "string",
+  "genderCode": "string",
+  "nationCode": "string",
+  "countryCode": "string",
+  "addressCode": "string",
+  "activation": true,
+  "dataCenter": true,
+  "externalId": "string"
+}
+```
+
+> 用户的属性说明
+
+属性名 | 说明 | 是否必填
+- | - | -
+uid | 用户标识 | 否，为空时，随机生成
+passWord | 密码 | 否，为空时，默认 123456，且激活状态为 未激活
+name | 姓名 | 是
+nameSpelling | 姓名简拼 | 否
+fullNameSpelling | 姓名全拼 | 否
+certificateTypeCode | 证件类型代码（参考字典表 证件类型，如 1 居民身份证） | 是
+certificateNumber | 证件号码 | 是
+phoneNumber | 联系电话（预留手机） | 否
+email | 电子邮箱（预留邮箱） | 否
+imageUrl | 头像地址 | 否
+genderCode | 性别代码（参考字典表 性别，如 1 男，2 女） | 否
+nationCode | 民族代码（参考字典表 民族，如 01 汉族） | 否
+countryCode | 国家代码（参考字典表 国家，如 156 中国） | 否
+addressCode | 地区代码（参考字典表 地区，如 110000 北京市，120000 天津市，310000 上海市） | 否
+activation | 是否激活（true 是，false 否） | 是
+dataCenter | 是否来源数据中心（true 是，false 否） | 是
+externalId | 外部Id | 否
+
+
+* 账号（包含用户信息）创建接口
+
+版本要求：1.0+
+
+POST /api/v1/trans/account?transOrigin=init
+Content-Type: application/json
+
+```json
+{
+  "uid": "string",
+  "passWord": "string",
+  "name": "string",
+  "nameSpelling": "string",
+  "fullNameSpelling": "string",
+  "certificateTypeCode": "string",
+  "certificateNumber": "string",
+  "phoneNumber": "string",
+  "email": "string",
+  "imageUrl": "string",
+  "genderCode": "string",
+  "nationCode": "string",
+  "countryCode": "string",
+  "addressCode": "string",
+  "accountName": "string",
+  "organizationCode": "string",
+  "identityTypeCode": "string",
+  "accountExpiryDateMillis": 0,
+  "state": "string",
+  "activation": true,
+  "dataCenter": true,
+  "externalId": "string"
+}
+```
+
+> 账号的属性说明
+
+属性名 | 说明 | 是否必填
+- | - | -
+uid | 用户标识 | 否，为空时，随机生成
+passWord | 密码 | 否，为空时，默认 123456，且激活状态为 未激活
+name | 姓名 | 是
+nameSpelling | 姓名简拼 | 否
+fullNameSpelling | 姓名全拼 | 否
+certificateTypeCode | 证件类型代码（参考字典表 证件类型，如 1 居民身份证） | 是
+certificateNumber | 证件号码 | 是
+phoneNumber | 联系电话（预留手机） | 否
+email | 电子邮箱（预留邮箱） | 否
+imageUrl | 头像地址 | 否
+genderCode | 性别代码（参考字典表 性别，如 1 男，2 女） | 否
+nationCode | 民族代码（参考字典表 民族，如 01 汉族） | 否
+countryCode | 国家代码（参考字典表 国家，如 156 中国） | 否
+addressCode | 地区代码（参考字典表 地区，如 110000 北京市，120000 天津市，310000 上海市） | 否
+accountName | 账号名 | 是
+organizationCode | 组织机构代码（对应组织机构的代码） | 是
+identityTypeCode | 身份代码（对应身份的代码） | 是
+accountExpiryDateMillis | 过期时间（时间戳，毫秒） | 否
+state | 状态（NORMAL: 正常, FREEZE: 冻结, WRITTENOFF: 注销） | 是
+activation | 是否激活（true 是，false 否） | 是
+dataCenter | 是否来源数据中心（true 是，false 否） | 是
+externalId | 外部Id | 否
+
+
+* 部门创建接口
+
+版本要求：1.0+
+
+POST /api/v1/trans/organization?transOrigin=init
+Content-Type: application/json
+
+```json
+{
+  "parentOrganizationCode": "string",
+  "code": "string",
+  "name": "string",
+  "description": "string",
+  "typeCode": "string",
+  "state": 0,
+  "isDataCenter": true,
+  "externalId": "string"
+}
+```
+
+> 组织机构的属性说明
+
+属性名 | 说明 | 是否必填
+- | - | -
+parentOrganizationCode | 上级部门的代码（对应组织机构的代码） | 是
+code | 代码 | 是
+name | 名称 | 是
+description | 描述 | 否
+typeCode | 组织机构类型代码（参考字典表 组织机构类型） | 是
+state | 状态（0: 正常, 1: 冻结, 2: 注销） | 是
+isDataCenter | 是否来源数据中心（true 是，false 否） | 否，为空时，默认为 true
+externalId | 外部Id | 否
+
+
+* 用户组创建接口
+
+版本要求：1.2.9、1.3.5、1.4.3、1.5.0
+
+POST /api/v1/trans/group?transOrigin=init
+Content-Type: application/json
+
+```json
+{
+  "code": "string",
+  "name": "string",
+  "description": "string",
+  "type": "string",
+  "state": 0,
+  "categoryCode": "string",
+  "common": true,
+  "applicationId": "string",
+  "isDataCenter": true,
+  "externalId": "string"
+}
+```
+
+> 用户组的属性说明
+
+属性名 | 说明 | 是否必填
+- | - | -
+parentOrganizationCode | 上级部门的代码（对应组织机构的代码） | 是
+code | 代码 | 是
+name | 名称 | 是
+description | 描述 | 否
+type | 类型（1: 普通用户组, 2: 岗位用户组） | 是
+state | 状态（1: 启用, 0: 禁用） | 是
+common | 是否公共用户组（true 是，false 否） |  否，为空时，默认为 true
+applicationId | 所属应用标识（common 为 false 时，须设置） | 否
+isDataCenter | 是否来源数据中心（true 是，false 否） | 否，为空时，默认为 true
+externalId | 外部Id | 否
+
 
 
 ### 授权服务
@@ -132,17 +362,11 @@ VALUES ('0', '1', 0, 'init', null,
   '1', '0', 
   '示例应用', '0', '', 1);
 
-commit;
-
--- 应用角色的创建脚本
-INSERT INTO TB_ROLE (ID, COMPANY_ID, DELETED, ADD_ACCOUNT, ADD_TIME, 
-  APPLICATION_ID, CODE, NAME, DESCRIPTION, ENABLED, EXTERNAL_ID)
-VALUES ('0', '1', 0, 'init', null, 
-  '0', 'example-admin', '示例管理员', '示例管理员', 1, '0');
-
 commit;
 ```
 
+如须自动同步角色，请修改 `SYNC_URL`
+
 > 系统信息表 TB_R_SYSTEM
 
 字段名 | 字段说明
@@ -177,22 +401,38 @@ SYNC_URL | 角色数据的同步接口。若不需要，可以为空
 ENABLED | 是否启用（1 启用，0 禁用）
 
 
+** 采用业务管理接口进行部署 **
+
+> 创建角色
+
+```bash
+curl -i -s -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "id": "0",
+  "code": "example-admin",
+  "name": "示例管理员",
+  "description": "示例管理员",
+  "enabled": true,
+  "applicationId": "0",
+  "externalId": "0"
+}' \
+  'http://authx-service-user-authz-service-sa.authx-service.svc.cluster.local:8080/v1/admin/roles'
+```
+
+
+
 > 角色表 TB_ROLE
 
-字段名 | 字段说明
-- | -
-ID | 确保唯一性
-COMPANY_ID | 固定为 1
-DELETED | 是否删除，固定为 0
-ADD_ACCOUNT | 创建帐号
-ADD_TIME | 创建时间，建议为 null；如必要，可填入时间
+属性名 | 说明
 - | -
-APPLICATION_ID | 所属应用，同 TB_APPLICATION 的 ID
-CODE | 角色代码
-NAME | 角色名称
-DESCRIPTION | 角色描述
-ENABLED | 是否启用（1 启用，0 禁用）
-EXTERNAL_ID | 对应所在应用内的数据的ID
+id | 确保唯一性
+applicationId | 所属应用，同 TB_APPLICATION 的 ID
+code | 角色代码
+name | 角色名称
+description | 角色描述
+enabled | 是否启用（1 启用，0 禁用）
+externalId | 对应所在应用内的数据的ID
 
 
 
diff --git "a/docs/\344\272\247\345\223\201\351\203\250\347\275\262\344\271\213\344\270\255\345\217\260\346\234\215\345\212\241\345\257\271\346\216\245\346\225\260\346\215\256\345\210\235\345\247\213\345\214\226\347\233\270\345\205\263\346\216\245\345\217\243\347\232\204\350\257\264\346\230\216.pdf" "b/docs/\344\272\247\345\223\201\351\203\250\347\275\262\344\271\213\344\270\255\345\217\260\346\234\215\345\212\241\345\257\271\346\216\245\346\225\260\346\215\256\345\210\235\345\247\213\345\214\226\347\233\270\345\205\263\346\216\245\345\217\243\347\232\204\350\257\264\346\230\216.pdf"
index 3d3313b..0113cfa 100644
Binary files "a/docs/\344\272\247\345\223\201\351\203\250\347\275\262\344\271\213\344\270\255\345\217\260\346\234\215\345\212\241\345\257\271\346\216\245\346\225\260\346\215\256\345\210\235\345\247\213\345\214\226\347\233\270\345\205\263\346\216\245\345\217\243\347\232\204\350\257\264\346\230\216.pdf" and "b/docs/\344\272\247\345\223\201\351\203\250\347\275\262\344\271\213\344\270\255\345\217\260\346\234\215\345\212\241\345\257\271\346\216\245\346\225\260\346\215\256\345\210\235\345\247\213\345\214\226\347\233\270\345\205\263\346\216\245\345\217\243\347\232\204\350\257\264\346\230\216.pdf" differ
diff --git "a/docs/\344\272\247\345\223\201\351\203\250\347\275\262\344\271\213\344\270\255\345\217\260\346\234\215\345\212\241\345\257\271\346\216\245\346\225\260\346\215\256\345\210\235\345\247\213\345\214\226\347\233\270\345\205\263\346\216\245\345\217\243\347\232\204\350\257\264\346\230\216_v1.pdf" "b/docs/\344\272\247\345\223\201\351\203\250\347\275\262\344\271\213\344\270\255\345\217\260\346\234\215\345\212\241\345\257\271\346\216\245\346\225\260\346\215\256\345\210\235\345\247\213\345\214\226\347\233\270\345\205\263\346\216\245\345\217\243\347\232\204\350\257\264\346\230\216_v1.pdf"
new file mode 100644
index 0000000..3d3313b
Binary files /dev/null and "b/docs/\344\272\247\345\223\201\351\203\250\347\275\262\344\271\213\344\270\255\345\217\260\346\234\215\345\212\241\345\257\271\346\216\245\346\225\260\346\215\256\345\210\235\345\247\213\345\214\226\347\233\270\345\205\263\346\216\245\345\217\243\347\232\204\350\257\264\346\230\216_v1.pdf" differ
diff --git "a/docs/\344\272\247\345\223\201\351\203\250\347\275\262\344\271\213\344\270\255\345\217\260\346\234\215\345\212\241\345\257\271\346\216\245\346\225\260\346\215\256\345\210\235\345\247\213\345\214\226\347\233\270\345\205\263\346\216\245\345\217\243\347\232\204\350\257\264\346\230\216_v2.0.pdf" "b/docs/\344\272\247\345\223\201\351\203\250\347\275\262\344\271\213\344\270\255\345\217\260\346\234\215\345\212\241\345\257\271\346\216\245\346\225\260\346\215\256\345\210\235\345\247\213\345\214\226\347\233\270\345\205\263\346\216\245\345\217\243\347\232\204\350\257\264\346\230\216_v2.0.pdf"
new file mode 100644
index 0000000..d35b3f0
Binary files /dev/null and "b/docs/\344\272\247\345\223\201\351\203\250\347\275\262\344\271\213\344\270\255\345\217\260\346\234\215\345\212\241\345\257\271\346\216\245\346\225\260\346\215\256\345\210\235\345\247\213\345\214\226\347\233\270\345\205\263\346\216\245\345\217\243\347\232\204\350\257\264\346\230\216_v2.0.pdf" differ