Files
tocc-rest/README.md
T
2026-11-20 17:16:18 +08:00

189 lines
8.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 养护开发工程
工程里有两个服务:
- `tocc-infra-maint`:基础服务,端口 `7424`,负责 `SZ_MAINT` 里的表。
- `tocc-system-maint`:系统服务,端口 `8525`,给前端提供接口,通过 Feign 调用基础服务。
## 源码结构
```text
养护开发工程
├── pom.xml # 父工程,统一依赖版本
├── lib # 本机编译用的达梦驱动
│ └── DmJdbcDriver8-8.1.5.60.jar
├── sql # 建表脚本
│ └── sz-maint.sql
├── maint-support # 本地开发支撑,交回时不进入公司工程
│ └── src/main/java/.../maint/support
│ ├── Result.java # 接口返回体
│ ├── PageResult.java # 分页结果
│ ├── CurrentUser.java # 当前用户
│ ├── CurrentUserHolder.java # 取当前用户
│ └── LocalDevAuthFilter.java # 本地固定用户,代替统一登录
├── tocc-infra-maint # 基础服务
│ ├── tocc-infra-maint-api # 给系统服务远程调用的接口包
│ │ └── src/main/java/.../infra/maint
│ │ ├── api # Feign 接口,如 RoadApi
│ │ ├── model/dto # 保存参数、分页参数、返回对象
│ │ └── constants # 服务名与 /rpc-api/maint 前缀
│ └── tocc-infra-maint-biz # 基础服务启动工程,端口 7424
│ └── src/main/java/.../infra/maint
│ ├── MaintInfraApplication.java
│ ├── api/impl # 接口实现,落到达梦
│ ├── mapper # MyBatis Mapper
│ ├── model/po # 表实体
│ ├── support # 各表共用的增删改查
│ └── config # 异常处理
└── tocc-system-maint # 系统服务
├── tocc-system-maint-api # 给其他服务远程调用的契约,目前只有服务名
│ └── constants/ApiConstants.java
└── tocc-system-maint-biz # 系统服务启动工程,端口 8525
└── src/main/java/.../system/maint
├── MaintSystemApplication.java
├── controller # 给前端的接口
└── config # 调用基础服务时带上当前用户
```
## 代码写在哪
库表接口、库表实现、页面业务分三个地方,不要混在一个工程里。
| 写什么 | 放在哪 |
| --- | --- |
| 库表 API | `tocc-infra-maint-api` 的 `api` 包。25 张表已经各有一套,例如道路是 `RoadApi`,路径 `/rpc-api/maint/road/create`。入参和返回对象在同模块的 `model/dto`。 |
| 库表实现 | `tocc-infra-maint-biz` 的 `api/impl`。`RoadApiImpl` 实现 `RoadApi`,通过 `mapper` 和 `model/po` 写入达梦。这里只做单表增删改查。 |
| 业务内容 | `tocc-system-maint-biz` 的 `controller`。给前端的页面接口写在这里,需要查库时注入 `RoadApi` 这类 Feign 接口。不要在系统服务里写 Mapper,也不要在基础服务里写页面流程。 |
`tocc-system-maint-api` 不放页面业务,也不放库表接口。它留给以后别的微服务远程调用养护系统服务,目前只有服务名。
## 前端技术栈
- React 17、Umi 3.5、Ant Design 4.21、Ant Design Pro(`@ant-design/pro-layout`、`pro-table`、`pro-form`)
- 页面用 JSX,样式用 Less
- 请求用 `umi-request`,统一走 `src/utils/request.js`,请求头带 `satoken`
- 路由写在 `config/routes.js`,菜单权限用路由上的 `access`,权限码以 `maint:` 开头
- 开发代理写在 `config/proxy.js`。本地把 `/api-maint` 转到 `http://127.0.0.1:8525`,页面里请求 `/api-maint/maint/...`
```text
src
├── app.jsx # 启动时取当前用户和权限
├── access.js # 按权限码控制菜单
├── assets # 图片等静态资源
├── components # 多个页面共用的组件
├── pages # 按业务分子目录,一个页面一个目录
│ └── RoadManage
│ ├── index.jsx # 页面
│ ├── index.less # 样式
│ ├── service.js # 本页接口,只调用系统服务
│ └── components # 本页弹窗、表单
├── services # 登录用户、权限等公共接口
└── utils
└── request.js # 统一请求
config
├── config.js # Umi 配置
├── routes.js # 菜单和路由
├── proxy.js # 本地代理到系统服务
└── defaultSettings.js # 布局标题、主题
```
页面只调系统服务 `8525`,不直接调基础服务 `7424`。列表、查询、弹窗写在 `pages` 里;接口地址集中在该页的 `service.js`。
## 环境
- JDK 8
- Maven 3.6+
- 本机达梦,端口 `5236`。把 `tocc-infra-maint-biz` 的 `application.yml` 里数据源口令改成本机达梦口令。
建库:用达梦管理工具执行 `sql/sz-maint.sql`,执行前先建模式并切过去:
```sql
CREATE SCHEMA SZ_MAINT AUTHORIZATION SYSDBA;
SET SCHEMA SZ_MAINT;
```
脚本是 UTF-8。用 disql 时先转成 GBK 再执行,否则中文注释会把后面的列吃掉。
## 启动
在本目录执行:
```bash
mvn -pl tocc-infra-maint/tocc-infra-maint-biz -am spring-boot:run
```
另开一个终端:
```bash
mvn -pl tocc-system-maint/tocc-system-maint-biz -am spring-boot:run
```
先起基础服务,再起系统服务。
- 基础服务文档:http://127.0.0.1:7424/doc.html
- 系统服务文档:http://127.0.0.1:8525/doc.html
- 连通检查:http://127.0.0.1:8525/maint/health
## 库表接口
`tocc-infra-maint-api` 里已经按 25 张表各写了一套接口,路径在 `/rpc-api/maint` 下面。每张表都有新增、按主键查询、修改、删除、分页。例如道路是 `/rpc-api/maint/road/create`。
系统服务直接注入对应的 Feign 接口,例如 `RoadApi`,不要在系统服务里写 Mapper。主键是字符串,新增时不传 id 会自动生成。创建人和修改人取当前请求用户。
基础服务文档 http://127.0.0.1:7424/doc.html 能看到全部表接口。
当前用户用 `CurrentUserHolder.get()`。本地没有登录,过滤器会填一个固定用户:养护开发 / 师宗公路分局。系统服务调用基础服务时会把这个用户放进请求头。
## 协作开发约定
协作方按本工程把养护业务做全即可,**不必做登录、Token、UAA、角色权限、网关鉴权**。本地 Swagger 不要求鉴权是正常现象。权限与统一认证交回后由我方接入。
### 交付范围
- 需要交付:页面、系统服务业务接口、基础服务库表能力(含必要的新表/新接口)。
- 不需要交付:自建登录、权限体系、改公司网关/UAA。
### 分层(不要混)
| 写什么 | 放在哪 | 禁止 |
| --- | --- | --- |
| 库表 CRUD | `tocc-infra-maint`(api + biz) | 不要写页面业务流程 |
| 页面业务接口 | `tocc-system-maint-biz` 的 `controller` | 不要写 Mapper、不要直连库 |
| 前端页面 | 前端工程 `pages`,只调系统服务 `8525` | 不要直接调基础服务 `7424` |
已有 25 张表的 CRUD 可直接注入对应 `XxxApi`。系统服务调基础服务时用:
```java
xxxApi.xxx(...).getCheckedData()
```
不要用裸 `.getData()`,否则基础服务失败会被当成成功。
### 当前用户
业务里用 `CurrentUserHolder.get()` 取创建人、机构。本地由 `LocalDevAuthFilter` 填固定用户(养护开发 / 师宗公路分局)。
- 不要自己写登录。
- 不要改 `maint-support`、`LocalDevAuthFilter`(交回时该模块会去掉)。
### 前端约定
- 技术栈、目录结构见上文「前端技术栈」。
- 路由权限码预留 `maint:` 前缀即可,不必接真实权限系统。
- 请求走 `/api-maint/...`,由代理转到系统服务。
### 请不要做的事
- 不要在系统服务连库。
- 不要自建权限/登录体系。
- 不要改父工程依赖版本,不要引入公司内网才能用的包。
- 不要把复杂业务逻辑写进基础服务的单表 CRUD 层。
## 交回
交回整个源码目录。公司合并时采用:
- `tocc-infra-maint` 和 `tocc-system-maint` 里新增的接口、实现、Mapper、实体,以及前端业务页面。
- `maint-support`、`LocalDevAuthFilter` 不进入公司工程。公司侧改为网关传入的用户,并接入 UAA 统一权限。