147 lines
8.1 KiB
Markdown
147 lines
8.1 KiB
Markdown
# 项目概述
|
||
- 项目名称：Orgmanax：“Org” 代表 `organization（组织）`，`man` 表示 “人”，`ax` 象征对这些元素进行整合.
|
||
- 项目简介：维护单位、部门、人员、岗位相关的业务及数据，比如：通讯录、项目添加人员、添加班组、更换班组长等
|
||
|
||
# 项目约束
|
||
- 引用外部（其它域、第三方）SDK时，需要与Leader确认，禁止私自引入
|
||
- service分为`foundation`(基础功能)与`biz`(业务功能)。`foundation`不可依赖`biz`，`biz`应依赖`foundation`完成部分功能。原则上`biz`与`biz`也不应该互相依赖
|
||
- 枚举不要做成参数的返回值。防止使用方不发布版本，解析失败的问题。
|
||
- 为每个接口定义自己的出入参，不要复用出入参
|
||
- 所有接口统一采用POST，列表接口需要带上分页且设置默认大小1000条
|
||
- 接口URL使用 【-】符号进行分割，比如: /orgmanax/node/create-team
|
||
- service层提供的出参与入参不能包含ApiResult；
|
||
- 提供出去的feign api，要自己注入spring容器
|
||
|
||
|
||
|
||
# 项目结构
|
||
|
||
|
||
## 模块描述
|
||
|
||
模块名称 | 功能 | 依赖
|
||
------ |--------------------------------------------------------------------------------------| ----
|
||
`orgmanax-api` | API层，提供给二方的SDK，方便二方快速接入人岗架相关功能 |无
|
||
`orgmanax-common`| 公共组件、UTIL等 |无
|
||
`orgmanax-infra` | 基础设施层，隔离非业务变化，防止外部变化引起内部业务变更。<br/>对接外部依赖，数据库，MQ等中件间 | `orgmanax-common`
|
||
`orgmanax-server`| 业务层，核心分为两层：<br/>1、基础业务层:`foundation`<br/>2、业务层：`biz` <br/>`foundation`依赖`biz`完成业务编排 | `orgmanax-api` `orgmanax-common` `orgmanax-infra`
|
||
|
||
|
||
## 各模块参数约束
|
||
|
||
- REQ：请求入参
|
||
- RESP：请求出参
|
||
- XXXQuery：基础功能入参
|
||
- XXXCreate：
|
||
- XXXUpdate：更新入参
|
||
- DO：数据库实体，DO使用充血模型，包括属性和行为，定义行为的范围：只能是本对象内部属性发生变更的行为
|
||
|
||
## 接口层级
|
||
|
||
|
||
### 接口路径定义规范
|
||
接口定义按照 ```/api/org/${domain}/${affiliateDomain}/${action}``` 形式进行定义。如
|
||
|
||
> * /api/org/unit/create
|
||
> * /api/org/unit/update
|
||
> * /api/org/node-user/list
|
||
> * /api/org/org-user/page
|
||
> * /api/org/node-user/operate-log/list - affiliateDomain的示例
|
||
#### ${domain} 为主要操作/查询的对象。包含以下值
|
||
* unit -> 单位
|
||
* node -> 部门
|
||
* cooperate-ship -> 协同关系
|
||
* node-user -> 部门人员
|
||
* org-user -> 组织人员
|
||
* biz - 如确实无法评估接口归属，可使用biz，或其他
|
||
#### action 的建议取值如下
|
||
* create
|
||
* update
|
||
* upsert - 创建/更新一体的接口（如幂等接口）
|
||
* list
|
||
* page
|
||
* detail - 查询单个对象及其聚合信息
|
||
#### affiliateDomain 附属域模型 如快照，操作记录等。按需使用
|
||
|
||
## 目录层级
|
||
```
|
||
.
|
||
├── orgmanax-api #提供给二方的功能，包括基础功能、业务功能。
|
||
│ └── src
|
||
│ ├── main
|
||
│ │ └── java
|
||
│ │ └── cn
|
||
│ │ └── axzo
|
||
│ │ └── orgmanax
|
||
│ │ └── api
|
||
│ │ ├── config #配置，如：将Feign接口托管至spring
|
||
│ │ ├── feign #配置，如：将Feign接口托管至spring
|
||
│ │ | ├── node #部门相关接口
|
||
│ │ │ | ├── feign #API
|
||
│ │ │ | ├── req #请求入参
|
||
│ │ │ | └── resp #请求出参
|
||
│ │ | ├── unit #单位相关接口
|
||
│ │ │ | ├── feign #API
|
||
│ │ │ | ├── req #请求入参
|
||
│ │ │ | └── resp #请求出参
|
||
│ │ | ├── team #班组业务相关接口
|
||
│ │ │ | ├── feign #API
|
||
│ │ │ | ├── req #请求入参
|
||
│ │ │ | └── resp #请求出参
|
||
│ └── resources
|
||
│ └── META-INF #SPI（service provider interface)
|
||
|
|
||
├── orgmanax-common #公共包
|
||
│ └── src
|
||
│ └── main
|
||
│ └── java
|
||
│ └── cn
|
||
│ └── axzo
|
||
│ └── orgmanax
|
||
│ └── common
|
||
│ ├── config
|
||
|
|
||
├── orgmanax-infra #基础设施层，主要是对接二方依赖，数据库，MQ等中件间。依赖domain层
|
||
│ └── src
|
||
│ ├── main
|
||
│ │ ├── java
|
||
│ │ │ └── cn
|
||
│ │ │ └── axzo
|
||
│ │ │ └── orgmanax
|
||
│ │ │ └── infra
|
||
│ │ │ ├── client #外部API防腐层
|
||
│ │ │ ├── config #基础配置，如mybatis_plus的配置
|
||
│ │ │ └── dao #数据访问层
|
||
│ │ │ └── node #部门相关
|
||
│ │ │ ├── convert #数据转换相关，比如将entity转换为数据实体do
|
||
│ │ │ ├── dao #mybatisplus的service实现，用于CRUD，可与Lambda表达式配合使用。
|
||
│ │ │ ├── DO #数据实体 包含实体的属性及行为
|
||
│ │ │ ├── repos # 业务查询防腐层，提供给service层使用，用于隔离service层与dao层
|
||
│ │ │ │ └── impl #gateway的具体实现可以调用dao完成相关功能，也可以作为聚合根获取数据的实现
|
||
│ │ │ └── mapper
|
||
|
|
||
└── orgmanax-server
|
||
└── src
|
||
├── main
|
||
│ ├── java
|
||
│ │ └── cn
|
||
│ │ └── axzo
|
||
│ │ └── orgmanax
|
||
│ │ └── server
|
||
│ │ ├── controller# 继承API实现
|
||
│ │ │ ├── biz #业务接口
|
||
│ │ │ │ └── team #班组业务接口
|
||
│ │ │ └── foundation #基础接口
|
||
│ │ │ ├── node #部门基础接口
|
||
│ │ │ └── unit #单位基础接口
|
||
│ │ └── service # 业务实现
|
||
│ │ ├── biz #业务接口
|
||
│ │ │ └── team # 班组相关API
|
||
│ │ └── foundation #基础接口
|
||
│ │ └── node #部门
|
||
│ │ ├── check #校验
|
||
│ │ ├── convert # 转换
|
||
│ │ ├── entity #foundation的业务入参指定为XXXQuery、XXXCreate
|
||
│ │ └── service #基础接口的业务实现
|
||
|