平台文档的意义与价值
平台文档是平台的重要组成部分,这块容易被忽视或不被重视。即使一个平台或系统架构优秀、设计合理、代码优雅,但文档缺失,对于平台的使用方而言,熟悉成本高、难度大。不可避免存在疑问,需要动手尝试验证或翻看源码才能确定系统的实际处理逻辑,效率低下。
此外,有些平台或系统虽然有文档,但文档流于形式化,为了写文档而写文档的产物。这样的文档质量堪忧,常见的问题主要有两个:
1.形式化与套路化,把功能模块和实体一列,然后增删改查,放几张截图,实际上都是些正确而无用的套话,提供的价值非常有限。
2.文档与系统实现不符,没有随系统重构或优化同步调整,这种实际危害更大,容易产生误导。
个人认为,文档应该站在使用者角度去编写,除了把属性和功能说清楚说完整,更重要的是把注意事项、最佳实践表达出来。在描述过程中,也应该提下为什么这么设计,有什么优点,以及有什么局限。
这样的文档,才能发挥自身的作用,给使用者必要的指引,让使用者快速了解与入门,遵循平台的设计,合理使用平台,追求最佳实践,发挥平台价值。
好了,就说这么多,接下来进入今天的正题,系统管理模块整体介绍。
概述
系统管理是平台的核心模块,是其他功能的基础支撑,主要包括以下几个部分:
组织机构:管理系统树状组织机构,支持无限级扩展
用户:管理用户,设置用户属性,查看和设置人员对应的用户组
用户组:定义用户组,为用户组分配权限项,管理用户组对应的人员
权限项:定义系统中权限项(资源),包括模块、菜单、页面、按钮、请求
数据字典:系统使用的枚举类型数据,按类型分别管理和维护
系统参数:对系统使用的可配置化参数进行统一管理和维护
系统日志:实现系统的运行日志、操作日志、审计日志、调度日志
模块:定义系统功能模块。
系统管理:全局性系统维护功能,如重建缓存。
功能清单
组织机构
对于企业应用,组织机构是重要的基础数据,用来组织和管理人员。
同时,组织机构往往是系统数据权限控制的重要维度。
对于新系统,初始化组织机构通常是第一步工作。
一般而言,企业不是简单的公司-部门两级机构,而是复杂的组织层次,集团-公司-部门-模块(小组)。同时,公司还会存在子公司和分公司。
用户
对于新系统,如果说初始化组织机构是第一步工作,那么初始化用户则是第二步工作。
对于企业应用,人员是重要的基础数据。
在不少平台和系统中,对“人”的概念进一步细分,将人员与用户区分来。人员对应真实世界中的人,用户则特指具备系统操作账号的人。人员和用户的关系通常是一对一的,当然也不排除个别系统允许1个人对应多个账户。
将人员独立出来,有人员没用户,意味着这部分人员,不需要登录和操作系统,如某些业务场景下的专家库。但是,这类场景下,需要根据业务需求建立单独的实体,因为要更多特定的业务属性需要承载,不会复用平台的人员实体。
考虑到大多数业务场景下,其实没必要细分人员和用户的区别,我的平台中,系统的人员,同时拥有系统的操作账号,即人员和用户实际是一回事,统称为用户。
用户组
在RBAC模型中,资源、角色、用户三个关键元素,构成权限体系。在平台设计和实现的时候,以下几个核心问题处理如下:
角色,单层平铺还是树形结构?
在小型应用中,角色数量有限的情况下,单层平铺简单实用,但在大中型应用中,角色数量在几十个甚至上百个,如果依旧平铺则难以管理和使用。采用树形结构后,可以方便地添加虚拟节点(如角色分类)。
角色还是用户组?
角色的称呼偏技术,对于业务用户而言,称为用户组更合适,即一组用户的集合;
业务意义上的岗位和职务,与传统意义的角色含义基本一致,如部门经理、固定资产接口人。
更改为树形结构后,可以进一步扩展其功能,例如,新建通讯(通知)组,将一部分人放到其下,可以供消息模块(短信、邮件、电话)等使用。
涉及到流程审批,同样存在一部分流程中的环节处理人员,往往也是某些特定用户集合,并非出于功能权限分配目的,放到用户组角色里更合适。
换个角度想,传统意义上用于功能权限控制的角色,更适合作为用户组的一个分支,因此最终方案将平铺的角色,调整为树形结构的用户组。
是否需要权限继承?
构建成树形结构后,面临一个新的问题,即是否要考虑权限继承问题,例如,给某一角色(用户组)分配的某一权限,则其上级角色和权限自动也自动拥有了其权限,也就是通常意义上的员工有的权限,领导也自动有了,这么做看上去会减轻一定的权限初始化工作以及权限维护工作量,但实际上结果可能是相反的,增加权限维护的复杂性,并且某些业务功能并不适配这种模式。例如,某个底层功能,如班组作业,需要获取当前班组编码或数据,这个功能菜单,让部门经理打开会无法正常显示或使用。
上面这个例子,实际深入思考下,并不是权限继承机制的问题,而是使用这种机制,需要从全局好好规划角色,明确哪些角色是继承关系。班组成员和部门经理是上下级关系,但是从角色继承角度而言,并不应该存在继承关系。存在继承关系的角色,应该是部门管理员-》公司管理员-》集团管理员。
引入权限继承,会增加系统设计、实现、运维的复杂性,因此,不考虑权限继承问题,树形结构仅用于组织角色(用户组)。
用户组规划
按照上述用户组的分类考虑,规划如下:
1.角色:传统意义上的岗位和职务,如部门经理、固定资产接口人,其下可以进一步分公共角色和专用角色,公共角色全局公用,如部门经理、固定资产接口人,每个部门都有该角色;专用角色往往是特定部门特定岗位才有的,如采样人员、巡检人员,可以在用户组下建组织机构虚拟节点,将这些专用角色挂靠在下面,更方便管理(使用角色时,不会显示在公共角色下,从而避免展示的总数量过多而影响选择)。
2.通讯组:预置的消息通知用户集合,可供消息模块(短信、邮件、电话)等使用,在某些业务事件发生时,如发生火灾,系统自动发送应急短信给通讯组用户。
3.流程岗位:工作流流程审批专用,如合同审查人员,会签人员,往往是为某条或某几条流程设置的人员集合,与管理上的岗位和职务没有很强的关联性,也不适合在常规功能权限分配时显示出来。
权限项
在RBAC模型中,资源、角色、用户三个关键元素,构成权限体系。资源是权限控制的对象,因此常称之为权限项。
平台中所有的权限项进行集中管理,菜单、按钮、请求、分组等通过类型进行区分,实体与库表公用,通过树形结构来展现其从属关系。
数据字典
软件系统中,会有一些成组的常量值,来描述业务实体的属性,如性别、证件类型、审批状态等。我们通常称之为数据字典,由平台来统一规划与设计,集中存储与管理,主要功能是维护字典类型以及对应的字典值,并供单据来使用。
注意,这里实际是两个实体,字典类型和字典值,对应着两张库表,不过这两个实体密切相关,对外输出数据字典功能。
系统参数
通过配置化,可以提升系统灵活性和运维便利性。
配置化往往分为两大类,一类是偏技术层面的,如平台的发送邮件提醒的邮箱,相对固化,不会频繁调整,一般放在系统的配置文件里,如springboot项目的application.yml中;另一类则偏业务层面,与业务规则有关,如密码长度,由系统管理员来维护。这类配置由系统参数功能来管理,平台提供可视化的功能菜单,通过数据库来持久化,修改实时生效。
系统日志
日志是系统的重要组成部分,往往容易被忽视。在生产环境,出现异常进行排查的时候,日志是重要的手段甚至在很多情况下是唯一可提供有价值信息的途径。
从定位上说,日志可以分为几类:
运行日志:平台启动或执行关键组件初始化、功能组件、中间件的启动和警告、报错等信息。
操作日志:用户在系统中操作留下的记录,如访问哪个菜单,点击了哪个按钮。
审计日志:与安全相关的日志,如用户登录系统,修改密码,锁定用户等。
调度日志:调度任务产生的日志,包括任务名称、执行时间、执行结果等。
日志的持久化有多种方式,运行日志,通常直接以日志文件的形式输出到磁盘;对于其他三类,操作日志、审计日志、调度日志,需要考虑系统的规模,用户的数量以及运维的便利性。在中小型系统或系统初上线阶段,可以考虑放到数据库表中,查询日志比去磁盘文件中找日志文件要便利得多,并且可以使用sql进行查询或统计。但如果系统规模很大,把日志放到数据库表中明显是不合理的,还是需要以日志文件的方式输出,但这样还不够。为了解决日志查询的问题,通常会使用ELK来实现日志的采集、存储和查询。
本平台中,运行日志是输出到磁盘的日志文件,操作日志、审计日志和调度日志默认是输出到数据库表中。
模块
这里的模块是系统的功能模块定义。
可以基于开发平台开发多个应用,每个应用由多个功能模块组成。
使用自身的定义使用数据字典来定义,当前有个名为“开发平台”的应用,依托开发平台实现具体的业务系统,如OA系统,只需要在添加新的字典项即可。
实际上,模块实体应归属于实体配置模块的一部分,放到“低层”的系统管理管理模块来,是出于避免模块间循环依赖需要。
系统维护
系统维护菜单下实际只挂了一个名为“重建缓存”功能按钮,日后可以扩展。
重建缓存功能实际跟上面的数据字典有关系。数据字典因为高频使用,使用redis做了缓存,当遇到以下场景时,需要重建缓存:
- 开发环境搭建:如在一台新电脑上搭建开发环境
- 环境迁移:如从开发到测试,测试到生产
- 缓存数据校准:如未使用平台功能,直接在数据库中维护字典类型或字典项
以上情况出现后,会因为redis缓存中缺少数据字典数据,导致部分数据列表中数据字典类型的属性不显示名称。
这时候,点击“重建缓存”按钮,系统会自动将数据库的字典数据写入到redis中。
本篇为系统管理模块整体简要设计,用于快速了解模块,接下来会对模块下功能逐个输出使用说明,包括功能的说明、属性、功能项、界面和注意事项。
开源平台资料
平台名称:一二三开发平台
简介: 企业级通用开发平台
设计资料:csdn专栏
开源地址:Gitee
开源协议:MIT
欢迎收藏、点赞、评论,你的支持是我前行的动力。