229 lines
14 KiB
Markdown
229 lines
14 KiB
Markdown
# 项目概述
|
||
- 项目名称：Orgmanax：“Org” 代表 `organization（组织）`，`man` 表示 “人”，`ax` 象征对这些元素进行整合.
|
||
- 项目简介：维护单位、部门、人员、岗位相关的业务及数据，比如：通讯录、项目添加人员、添加班组、更换班组长等
|
||
|
||
## 名词说明
|
||
- 企业/单位（organizational_unit）：分为企业（有营业执照）和团队（无营业执照）；团队主要用于挂载班组；每个企业可以有自己的组织架构。
|
||
项目场景下，称为参加单位；每个单位在不同的项目参建的身份（总包、分包、建设单位等）可以不一致。
|
||
- 部门(organizational_node)：分为普通部门和班组部门，每个部门可设置部门负责人，且此负责人可以不归属于该部门，只是挂职。
|
||
- 岗位(org_job)：岗位主数据，同一个人在一个单位，一个项目下只会存在一个岗位。
|
||
- 人：人挂在部门下；同一个工人可以挂在不同单位/团队（受最大次数限制）；同一个工人可以挂在同一个项目的不同部门/班组。
|
||
|
||
所有人、岗、架相关数据发生变更，都要有统一的日志流水记录（按需发送消息事件）。
|
||
|
||
# 项目约束
|
||
- 引用外部（其它域、第三方）SDK时，需要与Leader确认，禁止私自引入。
|
||
- 枚举不要做成参数的返回值。防止使用方不发布版本，解析失败的问题。
|
||
- service层提供的出参与入参不能包含ApiResult。
|
||
- 所有的写接口都必须经过foundation层进行收口。
|
||
- Server 模块分为 Service 与 Foundation。Foundation 承担基础功能，Service 负责业务功能编排。同域 Service 只能用本域 Foundation，不可用他域 Foundation，若需跨域则必须调用他域 Service。
|
||
- 业务上完全不用的数据，才能标记为is_delete，不使用全局默认值。
|
||
- json框架使用fastjson。
|
||
- 所有涉及到写的接口，都需要增加operatorId（操作人）
|
||
- 只有infra层可以操作数据库。
|
||
-
|
||
|
||
## 接口规范
|
||
- 所有接口统一采用POST，列表接口需要设置默认大小1000条
|
||
- 接口出入参，必须使用可扩展的对象类型。不能直接是 String，Integer，或者List这些无法扩展的类型。
|
||
- 为每个接口定义自己的出入参，不要复用出入参
|
||
- 接口URL使用 【-】符号进行分割，比如: /orgmanax/node/create-team
|
||
- 接口定义规范： 使用```/api/${domain}/${affiliateDomain}/${action}``` 形式进行定义。如：
|
||
```
|
||
/api/unit/create
|
||
/api/unit/update
|
||
/api/node-user/list
|
||
/api/org-user/page
|
||
/api/org-user/operate-log/page
|
||
```
|
||
* domain 为主要操作/查询的对象。包含以下值
|
||
```
|
||
● unit -> 单位
|
||
● node -> 部门
|
||
● cooperate-ship -> 协同关系
|
||
● node-user -> 部门人员
|
||
● org-user -> 组织人员
|
||
● biz - 如确实无法评估接口归属，可使用biz，或其他
|
||
```
|
||
- action 的规定取值如下
|
||
```
|
||
● create
|
||
● update
|
||
● upsert - 创建/更新一体的接口（如幂等接口）
|
||
● page
|
||
● detail
|
||
```
|
||
- affiliateDomain 附属域模型 如快照，操作记录等。按需使用
|
||
|
||
# 项目结构
|
||
|
||
|
||
## 模块描述
|
||
|
||
模块名称 | 功能 | 依赖
|
||
------ |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ----
|
||
`orgmanax-dto` | 通用对象层，提供对外暴露的对象（如：接口的出入参数「Req、Resp」、领域模型DTO、事件的payload等。仅在服务内部使用的模型，不放在dto包里面；<br>哪些对象应该放到dto包，这个较难以甄别。目前暂定dto里面仅提供以下内容：<br> 1.api接口的`入参和出参`；<br> 2.对外统一暴露的`领域聚合对象`，如 NodeDTO、NodeUserDTO、UnitDTO等；<br> 3.对外暴露的`枚举`定义；<br> 4.MQ消息体的`payload`定义 | 无
|
||
`orgmanax-api` | API层，提供给org-gateway的接口 | `orgmanax-dto`
|
||
`orgmanax-common`| 公共组件、UTIL等 |无
|
||
`orgmanax-infra` | 基础设施层，隔离非业务变化，防止外部变化引起内部业务变更。<br/>对接二方服务，数据库，MQ等中件间 | `orgmanax-common`
|
||
`orgmanax-integration`| 封装了二方服务非纯净版本。如：apollo-api、gaia-api等。等两方服务统一规范后，该层就会移除。 | `orgmanax-infra`
|
||
`orgmanax-server`| 核心能力层，分为两块：<br/>1、通用能力:`foundation` 单域核心逻辑如：创建部门，创建单位 <br/>2、人岗架业务能力：`service` 如：创建班组、创建小组 <br/>`service` 依赖本域 `foundation`或他域service完成业务 | `orgmanax-api` `orgmanax-common` `orgmanax-infra`
|
||
`orgmanax-starter`| 启动类 | `orgmanax-api` `orgmanax-common` `orgmanax-infra` `orgmanax-server` `orgmanax-integration`
|
||
|
||
## 各模块参数约束
|
||
|
||
- REQ：请求入参
|
||
- RESP：请求出参
|
||
- XXXQuery：基础功能入参
|
||
- XXXCreate：
|
||
- XXXUpdate：更新入参
|
||
- DO：数据库实体，DO使用充血模型，包括属性和行为，定义行为的范围：只能是本对象内部属性发生变更的行为
|
||
|
||
## 目录层级
|
||
```
|
||
.
|
||
├── orgmanax-dto # 通用对象包，仅提供需对外公开的对象，如：入参、出参、领域聚合对象、枚举等
|
||
│ └── src
|
||
│ └── main
|
||
│ └── java
|
||
│ └── cn
|
||
│ └── axzo
|
||
│ └── orgmanax
|
||
│ └── dto
|
||
│ ├── node
|
||
│ └── enums
|
||
│ └── dto
|
||
│ └── req
|
||
│ └── resp
|
||
│ └── payload
|
||
│ └── nodeuser
|
||
│── orgmanax-api #给org-gateway提供的api
|
||
│ ├── src
|
||
│ │ ├── main
|
||
│ │ │ └── java
|
||
│ │ │ └── cn
|
||
│ │ │ └── axzo
|
||
│ │ │ └── orgmanax
|
||
│ │ │ └── api#各域的fei与req
|
||
│ │ │ ├── config #配置
|
||
│ │ │ ├── cooperateship#协同关系
|
||
│ │ │ │ ├── feign
|
||
│ │ │ │ ├── req
|
||
│ │ │ │ └── resp
|
||
│ │ │ ├── node #节点
|
||
│ │ │ │ ├── feign
|
||
│ │ │ │ ├── req
|
||
│ │ │ │ └── resp
|
||
├── orgmanax-common #公共包，如：常量、枚举、工具类、异常等
|
||
│ └── src
|
||
│ └── main
|
||
│ └── java
|
||
│ └── cn
|
||
│ └── axzo
|
||
│ └── orgmanax
|
||
│ └── common
|
||
│ ├── config
|
||
│ └── entity
|
||
├── orgmanax-infra #基础设施层
|
||
│ ├── src
|
||
│ │ ├── main
|
||
│ │ │ └── java
|
||
│ │ │ └── cn
|
||
│ │ │ └── axzo
|
||
│ │ │ └── orgmanax
|
||
│ │ │ └── infra
|
||
│ │ │ ├── client#外部依赖
|
||
│ │ │ │ ├── apollo#apollo相关依赖
|
||
│ │ │ │ │ └── dto
|
||
│ │ │ │ └── workspace#workspace相关依赖
|
||
│ │ │ │ └── dto
|
||
│ │ │ ├── config# 组件配置
|
||
│ │ │ ├── dao#数据层
|
||
│ │ │ │ ├── node#节点相关
|
||
│ │ │ │ │ ├── dao
|
||
│ │ │ │ │ ├── entity#实体
|
||
│ │ │ │ │ ├── mapper
|
||
│ │ │ │ │ └── repository#防腐gateway
|
||
│ │ │ │ │ └── impl
|
||
│ │ │ │ └── unit#单位相关
|
||
│ │ │ │ ├── dao
|
||
│ │ │ │ ├── entity
|
||
│ │ │ │ ├── mapper
|
||
│ │ │ │ └── repository
|
||
│ │ │ │ └── impl
|
||
├── orgmanax-integration #封装二方非纯净API
|
||
│ └── src
|
||
│ └── main
|
||
│ └── java
|
||
│ └── cn
|
||
│ └── axzo
|
||
│ └── orgmanax
|
||
│ └── integration
|
||
│ ├── config
|
||
│ ├── core
|
||
│ └── sdk
|
||
│ ├── apollo#apollo相关接口
|
||
│ ├── datacollection#datacollection相关接口
|
||
│ ├── elise
|
||
│ ├── gaia
|
||
│ └── profile
|
||
├── orgmanax-server#核心能力层
|
||
│ └── src
|
||
│ ├── main
|
||
│ │ └── java
|
||
│ │ └── cn
|
||
│ │ └── axzo
|
||
│ │ └── orgmanax
|
||
│ │ └── server
|
||
│ │ ├── cooperateship#协同关系域
|
||
│ │ │ ├── controller
|
||
│ │ │ ├── event#协同关系事件
|
||
│ │ │ │ └── inner
|
||
│ │ │ │ └── payload
|
||
│ │ │ └── service# 协同关系相关业务
|
||
│ │ │ └── impl
|
||
│ │ ├── node#部门相关
|
||
│ │ │ ├── controller
|
||
│ │ │ ├── event#部门事件
|
||
│ │ │ │ └── inner
|
||
│ │ │ │ └── payload
|
||
│ │ │ ├── foundation#部门基础能力层
|
||
│ │ │ │ ├── impl
|
||
│ │ │ │ └── req
|
||
│ │ │ └── service# 部门业务（创建班组、解散班组、更换班组长、创建小组）
|
||
│ │ │ ├── impl
|
||
│ │ │ └── processor # 部门业务路由
|
||
│ │ │ └── impl # 部门业务具体现实（创建班组实现类、创建小组实现类）
|
||
└── orgmanax-starter #启动类
|
||
└── src
|
||
└── main
|
||
├── java
|
||
│ └── cn
|
||
│ └── axzo
|
||
│ └── orgmanax
|
||
└── resources
|
||
|
||
```
|
||
|
||
# 公共代码
|
||
* 业务异常处理
|
||
> cn.axzo.orgmanax.common.exception.BusinessException
|
||
>
|
||
|
||
* 错误码定义
|
||
> cn.axzo.orgmanax.common.config.BizResultCode
|
||
> * 快捷创建异常 cn.axzo.orgmanax.common.config.BizResultCode.toException()
|
||
|
||
* 业务异常快捷判定
|
||
> cn.axzo.foundation.exception.Axssert
|
||
|
||
* 分页参数
|
||
入参： cn.axzo.foundation.page.PageReqV2
|
||
出参： cn.axzo.foundation.page.PageResp
|
||
```
|
||
public class ListNodeUserReq extends PageReqV2 {
|
||
|
||
}
|
||
|
||
```
|