完善注释

hsweb-system/hsweb-system-authorization/hsweb-system-authorization-api/src/main/java/org/hswebframework/web/entity/authorization/AuthorizationSettingEntity.java

@@ -32,21 +32,24 @@ public interface AuthorizationSettingEntity extends GenericEntity<String> {
     |                属性名常量                |
     ===========================================*/
     /**
-     * 类型
+     * 设置类型,如: role
+     *
+     * @see org.hswebframework.web.service.authorization.AuthorizationSettingTypeSupplier
      */
-    String type       = "type";
+    String type = "type";
     /**
-     * 设置给谁
+     * 设置给谁,通常是{@link this#type}对应的id
+     * @see org.hswebframework.web.service.authorization.AuthorizationSettingTypeSupplier
      */
     String settingFor = "settingFor";
     /**
      * 状态
      */
-    String status     = "status";
+    String status = "status";
     /**
      * 备注
      */
-    String describe   = "describe";
+    String describe = "describe";
 
     /**
      * @return 类型

hsweb-system/hsweb-system-authorization/hsweb-system-authorization-api/src/main/java/org/hswebframework/web/entity/authorization/PermissionEntity.java

@@ -52,6 +52,10 @@ public interface PermissionEntity extends GenericEntity<String> {
 
     void setActions(List<ActionEntity> actions);
 
+    /**
+     * 此权限支持的数据权限类型,此字段只用于前端使用,在分配权限的时候,可以通过此字段来展示相应的数据权限设置,后台并没有使用此字段
+     * @return 支持的数据权限类型
+     */
     List<String> getSupportDataAccessTypes();
 
     void setSupportDataAccessTypes(List<String> supportDataAccessTypes);

hsweb-system/hsweb-system-authorization/hsweb-system-authorization-api/src/main/java/org/hswebframework/web/entity/authorization/UserEntity.java

@@ -25,15 +25,18 @@ import org.hswebframework.web.commons.entity.RecordCreationEntity;
  * @author zhouhao
  */
 public interface UserEntity extends GenericEntity<String>, RecordCreationEntity {
-    String name     = "name";
+    String name = "name";
     String username = "username";
-    String salt     = "salt";
+    String salt = "salt";
     @SuppressWarnings("all")
     String password = "password";
     String status = "status";
 
     void setName(String name);
 
+    /**
+     * @return 用户名, 只读, 只能新增, 不能修改
+     */
     String getUsername();
 
     void setUsername(String username);

hsweb-system/hsweb-system-authorization/hsweb-system-authorization-api/src/main/java/org/hswebframework/web/service/authorization/AuthorizationSettingMenuService.java

@@ -7,16 +7,36 @@ import org.hswebframework.web.service.TreeService;
 import java.util.List;
 
 /**
+ * 权限菜单设置
  *
  * @author zhouhao
+ * @see AuthorizationSettingService
  */
 public interface AuthorizationSettingMenuService extends
         CrudService<AuthorizationSettingMenuEntity, String>
         , TreeService<AuthorizationSettingMenuEntity, String> {
 
+    /**
+     * 根据设置id删除菜单配置
+     *
+     * @param settingId 设置id  {@link org.hswebframework.web.entity.authorization.AuthorizationSettingEntity#id}
+     * @return 删除的数量
+     */
     int deleteBySettingId(String settingId);
 
+    /**
+     * 获取设置id对应的所有权限菜单配置
+     *
+     * @param settingId 设置id {@link org.hswebframework.web.entity.authorization.AuthorizationSettingEntity#id}
+     * @return 永远不为nul .权限菜单设置,如果没有则返回空集合
+     */
     List<AuthorizationSettingMenuEntity> selectBySettingId(String settingId);
 
+    /**
+     * 获取多个设置id对应的所有权限菜单配置
+     *
+     * @param settingId 设置id {@link org.hswebframework.web.entity.authorization.AuthorizationSettingEntity#id}
+     * @return 永远不为nul .权限菜单设置,如果没有则返回空集合
+     */
     List<AuthorizationSettingMenuEntity> selectBySettingId(List<String> settingId);
 }

hsweb-system/hsweb-system-authorization/hsweb-system-authorization-api/src/main/java/org/hswebframework/web/service/authorization/AuthorizationSettingService.java

@@ -20,9 +20,14 @@ import org.hswebframework.web.entity.authorization.AuthorizationSettingEntity;
 import org.hswebframework.web.service.CrudService;
 
 /**
- * 权限设置 服务类,提供通用的权限设置
+ * 权限设置 服务类,提供通用的权限设置. 通过此服务,可实现对用户权限的多维度,自定义,可拓展的权限设置.<br>
+ * 例如: 可对用户自身设置权限信息,可对角色设置权限信息,可对机构,部门设置权限信息。各个维度的权限使用{@link AuthorizationSettingTypeSupplier}进行绑定.
  *
- * @author hsweb-generator-online
+ * @author zhouhao
+ * @see AuthorizationSettingTypeSupplier
+ * @see org.hswebframework.web.authorization.AuthenticationInitializeService
+ *
+ * @since 3.0
  */
 public interface AuthorizationSettingService extends CrudService<AuthorizationSettingEntity, String> {
     /**

hsweb-system/hsweb-system-authorization/hsweb-system-authorization-api/src/main/java/org/hswebframework/web/service/authorization/AuthorizationSettingTypeSupplier.java

@@ -6,7 +6,7 @@ import java.util.Set;
 
 /**
  * 权限设置类型提供者,在初始化权限信息的时候,用于获取被授权用户持有的设置类型.
- *
+ * 通过实现此接口,可实现多维度的通用权限设置
  * @author zhouhao
  * @since 3.0
  */
@@ -23,9 +23,18 @@ public interface AuthorizationSettingTypeSupplier {
 
     class SettingInfo {
 
-        //设置类型 如: user,role,position,person等等
+        /**
+         * 设置类型 如: user,role,position,person等等
+         *
+         * @see org.hswebframework.web.entity.authorization.AuthorizationSettingEntity#type
+         */
         private String type;
-        //type对应的主键信息,如 user.id
+
+        /**
+         * type对应的主键信息,如 user.id
+         *
+         * @see org.hswebframework.web.entity.authorization.AuthorizationSettingEntity#settingFor
+         */
         private String settingFor;
 
         @Override

hsweb-system/hsweb-system-authorization/hsweb-system-authorization-api/src/main/java/org/hswebframework/web/service/authorization/DataAccessFactory.java

@@ -1,12 +1,16 @@
 package org.hswebframework.web.service.authorization;
 
 import org.hswebframework.web.authorization.access.DataAccessConfig;
+import org.hswebframework.web.authorization.builder.DataAccessConfigBuilderFactory;
 import org.hswebframework.web.entity.authorization.DataAccessEntity;
 
 /**
- * TODO 完成注释
+ * 数据权限配置工厂,用户将动态数据权限配置转为权限框架需要的配置,便于实现自定义数据权限
  *
  * @author zhouhao
+ * @since 3.0
+ * @see DataAccessConfig
+ * @see DataAccessConfigBuilderFactory
  */
 public interface DataAccessFactory {
     DataAccessConfig create(DataAccessEntity entity);

hsweb-system/hsweb-system-authorization/hsweb-system-authorization-api/src/main/java/org/hswebframework/web/service/authorization/MenuService.java

@@ -33,8 +33,5 @@ import java.util.List;
 public interface MenuService
         extends CrudService<MenuEntity, String>
         , TreeService<MenuEntity, String> {
-    MenuEntity getByPermissionId(String permissionId);
-
-    List<MenuEntity> getByPermissionId(List<String> permissionId);
 
 }

hsweb-system/hsweb-system-authorization/hsweb-system-authorization-api/src/main/java/org/hswebframework/web/service/authorization/PasswordEncoder.java

@@ -19,8 +19,19 @@
 package org.hswebframework.web.service.authorization;
 
 /**
+ * 密码编码器,用于将明文密码编码成密文
+ *
  * @author zhouhao
+ * @since 3.0
  */
 public interface PasswordEncoder {
+
+    /**
+     * 编码,相同的参数,编码的结果永远相同.
+     *
+     * @param password 明文密码,不能为<code>null</code>
+     * @param salt     加密盐
+     * @return 加密结果
+     */
     String encode(String password, String salt);
 }

hsweb-system/hsweb-system-authorization/hsweb-system-authorization-api/src/main/java/org/hswebframework/web/service/authorization/PasswordStrengthValidator.java

@@ -3,8 +3,10 @@ package org.hswebframework.web.service.authorization;
 import org.hswebframework.web.service.Validator;
 
 /**
+ * 密码强度验证器,在保存用户信息,需要修改密码的时候,会调用此接口来验证密码强度.
  *
  * @author zhouhao
+ * @since 3.0
  */
 public interface PasswordStrengthValidator extends Validator<String> {
 }

hsweb-system/hsweb-system-authorization/hsweb-system-authorization-api/src/main/java/org/hswebframework/web/service/authorization/PermissionService.java

@@ -4,9 +4,10 @@ import org.hswebframework.web.entity.authorization.PermissionEntity;
 import org.hswebframework.web.service.CrudService;
 
 /**
- * TODO 完成注释
+ * 权限管理服务,就一个简单的crud
  *
  * @author zhouhao
+ * @since 3.0
  */
 public interface PermissionService extends CrudService<PermissionEntity, String> {
 

hsweb-system/hsweb-system-authorization/hsweb-system-authorization-api/src/main/java/org/hswebframework/web/service/authorization/RoleService.java

@@ -4,13 +4,27 @@ import org.hswebframework.web.entity.authorization.RoleEntity;
 import org.hswebframework.web.service.CrudService;
 
 /**
- * 角色服务
+ * 角色服务,就是一个简单的crud
  *
  * @author zhouhao
  * @since 3.0
  */
 public interface RoleService extends CrudService<RoleEntity, String> {
+    /**
+     * 启用角色
+     *
+     * @param roleId 角色ID
+     * @see RoleEntity#setStatus(Byte)
+     * @see org.hswebframework.web.commons.entity.DataStatus#STATUS_ENABLED
+     */
     void enable(String roleId);
 
+    /**
+     * 禁用角色
+     *
+     * @param roleId 角色ID
+     * @see RoleEntity#setStatus(Byte)
+     * @see org.hswebframework.web.commons.entity.DataStatus#STATUS_DISABLED
+     */
     void disable(String roleId);
 }

hsweb-system/hsweb-system-authorization/hsweb-system-authorization-api/src/main/java/org/hswebframework/web/service/authorization/UserMenuManagerService.java

@@ -2,14 +2,34 @@ package org.hswebframework.web.service.authorization;
 
 import org.hswebframework.web.entity.authorization.UserMenuEntity;
 
+import java.util.Collection;
 import java.util.List;
+import java.util.function.BiConsumer;
 
 /**
+ * 用户菜单管理服务,用户获取用户分配的菜单信息
+ *
  * @author zhouhao
+ * @see AuthorizationSettingService
+ * @since 3.0
  */
 public interface UserMenuManagerService {
+    /**
+     * 获取用户菜单,返回平铺的list结果,{@link  UserMenuEntity#getChildren()} 永远返回null
+     *
+     * @param userId 用户ID,不能为空
+     * @return 永远不为<code>null</code>,用户不存在或者没有任何菜单时,返回空集合
+     */
     List<UserMenuEntity> getUserMenuAsList(String userId);
 
+    /**
+     * 获取用户菜单,返回树形结构的根节点,通过{@link  UserMenuEntity#getChildren()} 获取子节点
+     *
+     * @param userId 用户ID,不能为空
+     * @return 永远不为<code>null</code>,用户不存在或者没有任何菜单时,返回空集合
+     * @see org.hswebframework.web.commons.entity.TreeSupportEntity#list2tree(Collection, BiConsumer)
+     * @see UserMenuEntity#getChildren()
+     */
     List<UserMenuEntity> getUserMenuAsTree(String userId);
 
 }

hsweb-system/hsweb-system-authorization/hsweb-system-authorization-api/src/main/java/org/hswebframework/web/service/authorization/UserService.java

@@ -2,15 +2,17 @@ package org.hswebframework.web.service.authorization;
 
 import org.hswebframework.web.entity.authorization.RoleEntity;
 import org.hswebframework.web.entity.authorization.UserEntity;
+import org.hswebframework.web.entity.authorization.bind.BindRoleUserEntity;
 import org.hswebframework.web.service.CreateEntityService;
 import org.hswebframework.web.service.InsertService;
 import org.hswebframework.web.service.QueryByEntityService;
 import org.hswebframework.web.service.QueryService;
+import org.hswebframework.web.validate.ValidationException;
 
 import java.util.List;
 
 /**
- * 用户服务
+ * 用户服务,提供对用户信息对常用操作
  *
  * @author zhouhao
  * @since 3.0
@@ -21,19 +23,88 @@ public interface UserService extends
         QueryService<UserEntity, String>,
         InsertService<UserEntity, String> {
 
+    /**
+     * 启用用户
+     *
+     * @param userId 用户Id
+     * @return 是否启用成功
+     * @see UserEntity#setStatus(Byte)
+     * @see org.hswebframework.web.commons.entity.DataStatus#STATUS_ENABLED
+     */
     boolean enable(String userId);
 
+    /**
+     * 禁用用户
+     *
+     * @param userId 用户Id
+     * @return 是否启用成功
+     * @see UserEntity#setStatus(Byte)
+     * @see org.hswebframework.web.commons.entity.DataStatus#STATUS_DISABLED
+     */
     boolean disable(String userId);
 
+    /**
+     * 修改用户信息,如果传入对实体实现了{@link BindRoleUserEntity},将更新用户的权限信息,更新逻辑:<br>
+     * 删除用户的权限信息,将新的权限信息重新insert,⚠️注意: 如果{@link BindRoleUserEntity#getRoles()}等于<code>null</code>,将不更新角色信息.<br>
+     * 用户信息更新后,将发布事件:{@link org.hswebframework.web.service.authorization.events.UserModifiedEvent},在其他服务可通过监听此事件来
+     * 来实现特定的操作,如清空用户权限缓存等.<br>
+     *
+     * @param userId   用户ID
+     * @param userBean 用户信息实体类
+     * @see org.hswebframework.web.service.authorization.events.UserModifiedEvent
+     * @see org.springframework.context.ApplicationListener
+     * @see org.springframework.context.event.EventListener
+     * @see BindRoleUserEntity
+     */
     void update(String userId, UserEntity userBean);
 
+    /**
+     * 根据用户名查询用户信息
+     *
+     * @param username 用户名,区分大小写,不能为空
+     * @return 用户信息, 如果不存在则返回 <code>null</code>
+     */
     UserEntity selectByUsername(String username);
 
+    /**
+     * 根据用户名和密码查询用户信息，在验证用户名密码是否正确是可以使用此方法
+     *
+     * @param plainUsername 用户名,区分大小写,不能为空
+     * @param plainPassword 明文密码,区分大小写,不能为空
+     * @return 用户信息, 如果用户米或者密码错误, 则返回<code>null</code>
+     * @see PasswordEncoder
+     */
     UserEntity selectByUserNameAndPassword(String plainUsername, String plainPassword);
 
+    /**
+     * 对密码进行加密混淆
+     *
+     * @param password 明文密码,不能为空
+     * @param salt     混淆盐,不能为空
+     * @return 加密后对密码
+     * @see PasswordEncoder
+     */
     String encodePassword(String password, String salt);
 
-    void updatePassword(String userId, String oldPassword, String newPassword);
+    /**
+     * 修改用户密码
+     *
+     * @param userId      用户ID,不能为空
+     * @param oldPassword 旧的明文密码,不能为空
+     * @param newPassword 新的明文密码,不能为空
+     * @throws ValidationException 旧密码错误时抛出此异常
+     * @see PasswordEncoder
+     * @see org.hswebframework.web.service.authorization.events.UserModifiedEvent
+     * @see org.springframework.context.ApplicationListener
+     * @see java.util.EventListener
+     */
+    void updatePassword(String userId, String oldPassword, String newPassword) throws ValidationException;
 
+    /**
+     * 获取用户的全部角色信息
+     *
+     * @param userId 用户ID,不能为空
+     * @return 永远不为null, 如果用户不存在或者用户没有任何角色, 返回空集合.
+     */
     List<RoleEntity> getUserRole(String userId);
 }

hsweb-system/hsweb-system-authorization/hsweb-system-authorization-api/src/main/java/org/hswebframework/web/service/authorization/UsernameValidator.java

@@ -3,9 +3,10 @@ package org.hswebframework.web.service.authorization;
 import org.hswebframework.web.service.Validator;
 
 /**
- * TODO 完成注释
+ * 用户名验证器,在保存用户信息的时候,用于验证用户名是否合法
  *
  * @author zhouhao
+ * @since 3.0
  */
 public interface UsernameValidator extends Validator<String> {
 }