# 后端问题
# 认证登录
# 配置接口跳过登录
针对某些接口需要跳过登录的需求，我们提供了配置的支持。
可以配置 application.yml 文件中的 hos-security:white-list(值为一个字符串)，这是一个前缀配置。
举例说明：
如果您配置
hos-security:
login:
white-list:
- /api/otp-auth/forget-code
- /core/system/files/other/**
- /openApi/**
那么您的接口http://ip:port/api/core/...都可以跳过登录验证
# token过期设置
# 统一认证对接报错
与统一认证报错时要把基础平台升级到1.1.1版，具体的错误信息如下
# CA或扫码登录错误信息不提示
使用非人大金仓的数据库，在2024年3月22日前升级到2.5.2版本且遇到CA或扫码登录错误信息不提示，可执行hos-app-base-xxx-2.5.2-0322-patch.sql补丁。（xxx为数据库类型，以下为mysql数据库示例）
- 前往 Gitlab 下载页面（http://119.255.194.80/hos/demo/hos-app-demo/-/tree/2.5.0-integration/project-strcutre/project-strcutre-demo/oa-doc/data/mysql/2.5.2） , 用户名/密码：hosuser/99ahivPJt
- 下载
hos-app-base-mysql-2.5.2-0322-patch.sql文件 - 执行更新 SQL
hos-app-base-mysql-2.5.2-0322-patch.sql
# 登录时如果出现序列话失败报错问题
登录时如果出现序列话失败报错问题，需在yml文件中配置
spring:
jackson:
default-property-inclusion: non_null
serialization:
FAIL_ON_EMPTY_BEANS: false
# 登录须知
HOS基础平台在R2.6.1.3.0版本后，将采用岗位单元方式登录（其依赖于资源计划系统的接口及上游推送的业务单元、业务岗位、人员信息等数据）。
登录页面在输入完用户名密码后点击登录按钮，查询本人的岗位单元信息。选择后再次登录才可进入系统。如图所示：
在整个流程中，首先登录系统需要调用资源计划系统的接口。资源计划系统的接口已内置在第三方接口配置中，其中ip、端口地址的修改在内置的第三方应用中。如图所示：
配置完成后，页面登录验证用户名密码成功后就会调用资源计划系统接口获取当前人员（除admin账户）已排班的岗位单元数据。 如果登录时发现不能正常获取到岗位单元数据。如下图：
或者有岗位单元数据，但是还是无法登陆系统，则需要按照下述顺序排查数据问题。
问题排查顺序：
- 进入人员信息菜单（组织人员-->人员管理-->人员信息），点击查看人员排班按钮，查看该人员是否有排班的数据，如果不存在，联系资源计划系统（鲁林）排查问题。
- 如果能获取排班数据后，选择岗位单元后，无法登陆系统。则需要排查岗位单元关联的业务单元和业务岗位在本系统内是否存在，（可在第一步查看人员排班信息中查看业务单元和业务岗位是否为【已禁用】或【未同步】）。如出现以上情况需要找DTS系统（马兆岩、鲁林）给推送相应的数据。
- 如果数据上述问题都排查过了，还是无法登陆，则联系HOS基础平台（曹风雨辰）排查问题。
# 登录界面图形验证码显示不全问题
登录时如果界面出现图形验证码显示不全的问题，需在yml文件中配置
hos-security:
login: #登录相关配置
captcha: #图形验证码配置
captcha-width: 300 #图形验证码的宽度，可以调整
# 组织人员
# 人员相关的关联关系表内容已推送但是页面无法显示
项目上经常碰到生产要素推送完人员以及人员相关的表内容以后在页面中无法找到的问题,下面列举了一些常见原因：
1.分配机构:
1).检查上游推送的机构人员数据的
工作状态是否是在职状态；
2).机构是否可用；
3).人员唯一标识是否正确。
2.分配部门：
1).检查上游推送的部门人员数据是否在职;
2).人员分配部门时部门所在的机构是否与人员分配机构时的机构是否一致;
3).部门是否可用；
4).人员唯一标识是否正确。
3.分配职务：
1).检查上游推送的人员职务数据是否在职;
2).人员分配职务时所在的部门是否与人员分配部门时的部门是否一致;
3).职务是否可用；
4).人员唯一标识是否正确。
# 组织人员v2.6.0数据问题
目前组织人员的数据来自多个系统，分别为【生产要素】【DTS】【资源计划】【后勤管理系统】【统一用户】， 若数据存在确实错误等情况,请联系相关系统. 每个系统负责人以及产生的数据如下：
| 数据来源系统 | 负责人 | 来源数据 | 详细说明 | 备注 |
| 生产要素 | 董红军 | 基础字典 | 人员状态 | |
| 工作状态字典 | ||||
| 性别字典 | ||||
| 国家地区字典 | ||||
| 行政区划-省级 | ||||
| 行政区划-市级 | ||||
| 行政区划-县区级 | ||||
| 婚姻状况字典 | ||||
| 学位字典 | ||||
| 学历字典 | ||||
| 民族字典 | ||||
| 证件类型 | ||||
| 职业大类 | ||||
| 职业序列 | ||||
| 职称字典 | ||||
| 宗教信仰字典 | ||||
| 诊疗科目 | 诊疗科目字典 | |||
| 组织机构 | 机构大类 | |||
| 机构子类 | ||||
| 机构小类 | ||||
| 组织机构 | ||||
| 组织部门 | 组织行政属性 | |||
| 组织部门 | ||||
| 医疗机构 | 医院等级 | |||
| 医疗机构 | ||||
| 职务数据 | 职务等级 | |||
| 职务字典 | ||||
| 组织职务 | ||||
| 职位数据 | 职位字典 | |||
| 组织职位 | ||||
| 人员数据 | 人员基本信息 | |||
| 人员机构信息 | ||||
| 人员部门职位 | ||||
| 人员部门职务 | ||||
| 对象数据 | 对象分类 | |||
| 载体数据 | 载体分类 | |||
| 工作区域 | 工作区域 | |||
| 组织单元 | 组织单元 | |||
| 组织单元设置OO、OP人员 | ||||
| DTS | 马兆岩 | 业务域 | 业务域 | |
| 事项域 | 事项域 | |||
| 工作事项 | 工作事项 | |||
| 岗位 | 岗位 | |||
| 业务岗位 | 业务岗位 | |||
| 流程岗位 | 流程岗位 | |||
| 业务单元关联业务岗位 | 设置业务单元和业务岗位的关联关系 | |||
| 服务等级 | 服务等级 | |||
| 劳动类型 | 劳动类型 | |||
| 业务单元 | 业务单元 | |||
| 输出物 | 输出物 | |||
| 岗位要求字典 | 岗位要求字典 | |||
| 机构诊疗科目配置 | 机构诊疗科目 | |||
| 作业 | 作业 | |||
| 资源计划 | 徐鹏 | 排班岗位 | 排班岗位 | 目前此部分数据不需要推送到HOS基础平台中，但是需要由资源计划提供接口获取人员已排班的岗位单元数据，后续会根据这个数据登录系统 |
| 岗位单元 | 岗位单元 | |||
| 人员排班 | 为人员按照日期排列排班岗位 | |||
| 岗位授权 | 人员授权排班岗位 | |||
| 业务功能区 | 业务功能属性 | |||
| 业务功能区 | ||||
| 业务运行时间 | 节日字典 | |||
| 时段设置 | ||||
| 机构运营时间 | ||||
| 公休假日日历配置 | ||||
| 节气日历配置 | ||||
| 后勤管理 | 郑鸣 | 物理工作地点 | 空间网格 | |
| 工作地点 | ||||
| 统一用户 | 黄桥 | 账号 | 账号 |
# 开发集成
# 导入常见问题
导入时数字类型字符串带小数点
在开发集成-->Excel管理-->导入管理-->sheet管理-->列管理，找到对应的列并将列类型改成
字符型。
导入时必填字段为空导致报错
在开发集成-->Excel管理-->导入管理-->sheet管理-->列管理，找到对应的列并将查看是否开启
数据验证。
导入时更新数据时字段未更新
在开发集成-->Excel管理-->导入管理-->sheet管理-->列管理，找到对应的列并将查看是否开启
导入更新。
导入时提示数据库中不存在字段
在开发集成-->Excel管理-->导入管理-->sheet管理-->列管理，找到对应的列并将查看是否关闭了
是否入库。
下载导入模板时提示模板不存在
如果下载导入模板时提示模板不存在,可以选择导出任意数据，把导出的表格作为导入模板使用。
# 导出常见问题
导出执行脚本中databaseId的使用
var sql ="select code,name,roman_code,roman_desc,foreign_desc,is_activity,start_date,end_date,seq_no,py_code,wb_code,mark,case when is_activity=1 and";
if(databaseId=="gbasedbt"){
sql+=" (end_date is null or TODAY <= end_date) and (start_date is null or TODAY >= start_date) then 0 else 1 end as disabled,case when seq_no is null then 0 else 1 end as snNullFlage from hos_ct_nationality where is_deleted=0";
}
if (databaseId=="mysql" || databaseId=="kingbase" || databaseId=="oracle "){
sql+=" (end_date is null or CURRENT_DATE <= end_date) and (start_date is null or CURRENT_DATE >= start_date) then 0 else 1 end as disabled,case when seq_no is null then 0 else 1 end as snNullFlage from hos_ct_nationality where is_deleted=0";
}
...........
# openApi配置的接口访问不通
1.检查保访问地址是否正确；
2.接口地址路径上是否添加了'${sys.restfulPath}'；
3.接口方法上是否添加了@Openapi注解,且保证注解上编码是否正确。
# pageOffice路径配置而导致的启动报错问题
解决办法：
1、如果是Windows系统，将yml配置文件的 posyspath: 属性，配置一个本地的文件夹路径，例如：D:/。
2、如果是Linux系统，将yml配置文件的 posyspath: 属性，配置一个Linux的目录，例如：/home。
# 消息中心
# 消息配置问题
消息模板中的黑/白名单与安全设置中的黑/白名单关系
1.黑名单： 消息模板黑名单与安全设置黑名单的合集。
2.白名单： 消息模板白名单与安全设置白名单的交集。
重发逻辑
每次进行重发时的时间间隔是上次重发的时间间隔的多少倍，也意味着重发次数越多，重发的频率就越低。
# 消息发送问题
消息或渠道不存在
1.如果按渠道发送时，请检查
channelData中的消息渠道是否在消息平台中存在，
2.如果按消息模板发送时，请检查
templateCode模板编码是否在消息中心中存在。
参数模板内容存在未匹配的自定义参数
请检查模板内容中的自定义参数
channelParamData是否都在其中。
敏感词汇
请检查
channelParamData与channelData中是否存在不合规的字符。
发送目标不存在
请确保接收者在门户中存在且可用。
提示发送成功，实际未收到消息
发送成功仅代表消息没有错误已经发送出去，不代表接收者已经接收到了,详情查看历史消息。
# 消息日志定时清理和定时任务定时发送问题
1.检查yml文件中XxlJob配置是否正确。
2.确保XxlJob服务正常运行，且任务是运行状态。
# 开发类
# Swagger中不显示原来的API接口
2.0.4版优化后，各个模块需要自己配置自己的扫描路径，详情请参考Swagger自定义配置类
# HOS基础平台部反馈在指定版本上已修复某个问题，但本地代码还报错,jar没有自动更新成最新的
因为HOS基础平台的提供的jar都是放在Maven私服的release库中，release库中的jar有更新的话，不会自动下载到本地的Maven仓库。 此时需要到本地的Maven仓库中手动删除相应的jar，然后重新拉取jar即可。
# XXL-JOB执行器自动注册
XXL-JOB中需要手动创建注册方式为自动注册的执行器，接入HOS-JOB客户端后，服务启动时自动将本服务注册到对应执行器的在线机器中
# 数据库varchar类型字段查出为null时需转为''字符串可以添加以下配置
在 application.yml 文件中的 mybatis-plus的文件配置中增加typeHandlersPackage的配置项。
mybatis-plus:
typeHandlersPackage: com.mediway.hos.app.common.handler.mybatis
# 页面元素权限接口list-perm报错
报错内容："element cannot be a null key"
在 application.yml 文件中的 mybatis-plus的文件配置中增加typeHandlersPackage的配置项。
mybatis-plus:
typeHandlersPackage: com.mediway.hos.app.common.handler.mybatis
# 许可证相关问题
# 开启许可，启动报错，获取不到机器码
解决方法：到Oracle官网下载相应的文件 (opens new window),将下载到的zip文件解压到JDK的\jre\lib\security文件夹内即可
示例：本地jdk问题解决
解压下载文件
覆盖到jdk1.x.x\jre\lib\security中
# Linux下使用docker部署服务，开启许可，获取不到机器码，报错信息 [Errno 2] No such file or directory: 'dmidecode'
报错：[Errno 2] No such file or directory: 'dmidecode': 'dmidecode'
docker容器内执行dmidecode命令出现
原因：容器内没有dmidecode工具
解决： 将宿主机的如下两个目录挂载到容器中
/sbin/dmidecode -- 这个目录是dmidecode程序的目录，如果不挂载那么容器中识别不了dmidecode命令
/dev/mem -- dmidecode调用时会使用到mem这个文件，如果不挂载会找不到文件
启动：
docker run -itd -v /sbin/dmidecode:/sbin/dmidecode -v /dev/mem:/dev/mem -p 端口:端口 --name 容器名 镜像名:版本号 /bin/bash
# 激活许可时提示错误信息：许可产品或版本与系统不匹配
原因：申请的许可的产品名和版本 与yml中配置项的值不匹配
解决：
修改framework.security.license.production.name、framework.security.license.production.version的值
与在BOS中申请的许可保持一致
# 激活许可之后，仍提示：机器xx-xx-xx-xx许可无效
可能原因：
1、docker的默认网络模式会生成虚拟网卡，此时容器中的服务获取的mac地址为虚拟网卡地址。后期修改网络模式（例如 Host模式）之后， 获取到的mac地址与原地址不同，导致许可无效
2、启动时未启动所有用到许可的服务，导致机器码缺失。使得后面启动的服务的机器码未包含到许可中
请确保所有使用许可的服务正常启动之后再申请许可，若上述情况发生只能重新申请许可
# 后端控制台报xxljob服务连接错误
解决办法：
1、确定是否使用消息中心模块。如果不使用，请在启动runner模块内移除hos-app-message模块的依赖。
2、如果确定使用消息中心依然报错，请检查yml文件中的framework.job.admin.addresses所配置的服务地址是否正常，不正常请联系服务搭建负责人。
3、如果需要本地搭建xxljob，请详见HOS-JOB
# 初始化文件
问题描述
部分模块导入功能的模板文件是自定义文件，但由于文件服务器的不同会导致下载模板时发生错误 为解决这一问题，可参考如下解决方法。
解决方法
1、下载最新模板文件。
2、在文件存储管理中，配置好需要存储文件的服务器。
3、在文件管理中，导入第一步下载好的zip格式模板文件压缩包。
# 异步处理时当前线程参数的传递
代码中异步处理需要获取当前线程的参数，并在异步线程使用时，可先获取具体参数，
然后放入异步线程中的ThreadLocalManager中，例如
private void threadTest(){
String accountId=AccountUtil.getAccountId();
String user = (String) ThreadLocalManager.get(GlobalConstant.KEY_LOGIN_USER);
new Thread(()->{
ThreadLocalManager.put("accountId",accountId);
ThreadLocalManager.put("user",user);
//具体业务逻辑
}).start();
}
# Kingbase兼容Oracle时日期date问题
关于date 数据类型，Oracle 与 PostgreSQL 格式是不同的，Oracle 是 日期 + 时间的类型，而PG 则只有日期; KingbaseES Oracle 模式则同时实现了二者类型，用户在使用时，需要注意所使用的类型。
1.可以通过查 sys_type 可以看到有date的类型:
select typname,typnamespace::regnamespace from sys_type where typname='date';
2.通过 current_schemas 可以确认用户最优先(自左向右)的schema 是什么：
select current_schemas(true);
schema是sys的,使用的是sys.date;此类型是兼容Oracle date 的,包含时分秒;
pg_catalog,使用的是pg_catalog.date;此类型是PostgreSQL date的,不包含时分秒；
3.日期维护类型举例说明：
创建表时语句如下:
CREATE TABLE my_date (
id character(32 char) NOT NULL,
my_pg_date pg_catalog.date NULL, //不包含时分秒
my_sys_date date NULL, //包含时分秒
CONSTRAINT my_date_pkey PRIMARY KEY (id)
)
表字段日期类型切换如下：
alter table my_date modify my_sys_date pg_catalog.date null;
alter table my_date modify my_pg_date date null;
需要注意的是，更改日期类型后，需要重启KingbaseES服务。
此外如果字段是sys.date类型的,且查询时不需要时分秒时，也可以通过设置来全局设置日期格式：
SET ora_style_nls_date_format = ON ;
SET nls_date_format = 'YYYY-MM-DD';
此方式会在任意sql查询时将date类型的字段内容格式为指定格式，慎用。
# 实体类字段注解校验信息的翻译问题
实体类作为入参对象时需要对其的某些属性进行校验，如果校验不通过，则会抛出异常信息。在支持了国际化的版本上，校验抛出的异常也应当支持国际化。 我们提供对校验异常的拦截处理类 ExceptionValidatedHandlerAdvice 。本类对使用基本注解 @RequestBody,@RequestParam,@validated 的异常信息进行翻译，当入参校验异常时，即可拦截于此，根据国际化语种返回异常信息。但本类只支持校验入参时产生的异常信息， 如若实体类上还有其他类型注解需要支持国际化，还请再自行扩展。
@Override
@ExceptionHandler({MethodArgumentNotValidException.class})
public BaseResponse validationErrorHandler(MethodArgumentNotValidException e) {
List<ObjectError> allErrors = e.getBindingResult().getAllErrors();
StringBuilder stringBuilder = new StringBuilder();
allErrors.forEach(objectError -> stringBuilder.append(HosI18nUtil.mapStaticTrans(objectError.getDefaultMessage())).append(";"));
if (stringBuilder.length() > 0) {
stringBuilder.setLength(stringBuilder.length() - 1);
}
return BaseResponse.error(SysExceptionEnum.PARAM_VALIDATION_ERROR.getCode(), stringBuilder.toString());
}
# 启动成功不能登陆问题
问题描述：
2.5.1及以上版本项目可以正常启动，但是启动后登陆异常，或者登陆不上。
解决方案：
检查启动类所在包中是否存在这两个类 HosSecurityConfig和SecurityLoginConfig,若是没有可前往 Gitlab 下载页面
（http://119.255.194.80/hos/demo/hos-app-demo/-/tree/2.5.0-integration/project-strcutre/project-strcutre-demo/oa-business-parent/oa-runner/src/main/java/com/mediway/hos） , 用户名/密码：hosuser/99ahivPJt。进行下载并放入启动模块中。
# 越权访问处理方案
问题描述：
在一些项目安全等级要求中，会要求处理越权访问的问题点。如需解决，除前端页面元素权限控制外，后端推荐使用接口权限及授权来控制，细化权限颗粒度。
解决方案：
(注意，一旦确认需要导入使用接口权限，则必须对不同角色使用接口做授权处理，否则将不能访问。) 实现逻辑说明详见接口权限配置及接口权限授权
- 下载接口权限初始化导入文件。
- 打开
系统管理-权限管理-接口权限菜单，点击导入按钮。
- 导入后，在角色授权中为各角色授权接口权限。具体使用权限范围，由业务自定。（admin用户不受控制）
# 升级到2.5.4后报seata相关错误
问题描述：
升级到2.5.4后后端报seata相关错误
解决方案：
如果明确代码中不使用租户相关功能，可以在pom.xml中移除hos-app-tenant依赖和hos-framework-tenant-starter依赖。
# 生产环境如何屏蔽Knife4j、Swagger等Ui资源和接口
问题描述：
解决方案：
knife4j:
# 开启增强配置
enable: true
# 开启生产环境屏蔽
production: true
# knife4j4.0.0版以上或者HOS版本2.3.0及以上，需要配置setting.custom-code=200
setting:
custom-code: 200
# 组织人员部分接口入参变更
注意：hosDepartmentApi.searchList --> hosDepartmentApi.searchDeptList。
该api接口method名已做调整由searchList变更为searchDeptList，使用时请注意。
V3版本组织人员，部分关联表关系已修改为id。以下接口如果有使用，需注意入参名及入参值的调整。（接口相关的api、controller入参名均已做调整）
| 修改入参的接口地址 | 变更前入参名 | 变更后入参名 |
|---|---|---|
| org/hos-department/select-dept-by-inst | instCode | instId |
| org/hos-department/search-list | orgCode | orgId |
| org/hos-department/search-effect-list | orgCode | orgId |
| org/hos-department/select-dept-tree | orgCode | orgId |
| org/hos-department/select-effect-dept-tree | orgCode | orgId |
| org/hos-department/select-dept-path | orgCode | orgId |
| org/hos-department/search-dept-list-by-org | orgCode | orgId |
| org/hos-department/search-effect-dept-list-by-org | orgCode | orgId |
# OrgEventPublishImpl提示空指针异常
在保存人员或者机构等信息时，提示使用OrgEventPublishImpl的空指针异常，如下图所示
请检查在xxx-runner的pom.xml中hos-app-org-eventpublish依赖是否导入
<dependency>
<groupId>com.mediway.hos</groupId>
<artifactId>hos-app-org-eventpublish</artifactId>
</dependency>
# 数据库字段填充问题
问题描述：
在页面新增数据，部分字段（例如：is_deleted、create_time等）入库时的默认值没有赋值成功。
解决方案：
检查自定义扩展字段的类,需是继承AbstractMetaObjectHandler类,通过重写customizeInsertFill和customizeUpdateFill方法来定义新增和更新时的填充字段。
更多具体内容可参考字段填充
# xxl-job注册bean不生效
- 查看bean所在类是否已经加入到spring容器中。
- 方法上是否添加了@XxlJob注解,且注解上的名称与xxl-job配置中的名称是否一致，区分大小写
- 创建定时任务时所在执行器是否与服务中配置的执行器是否一致
# 高斯数据库模式兼容问题
问题描述：
高斯数据库默认模式为oracle模式，但部分会设置为PG模式，在PG模式下字段的长度与oracle模式下字段长度的实际长度有所不同，
因此在oracle模式执行sql会有字段长度不足的问题，如果出现此问题，可修改其对应的字段长度。
解决方案：
在已发出的sql中，已知存在问题的字段是hos_sys_config表的remark字段,执行之前将字段长度由varchar(200)改为varchar(2000)。