From 5e2891cc238384905a43e36c7aa0149e3a1f5c16 Mon Sep 17 00:00:00 2001 From: yimingchang Date: Fri, 20 Nov 2026 16:30:03 +0800 Subject: [PATCH] first commit --- README.md | 188 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..c4d4744 --- /dev/null +++ b/README.md @@ -0,0 +1,188 @@ +# 养护开发工程 + + +工程里有两个服务: + +- `tocc-infra-maint`:基础服务,端口 `7424`,负责 `SZ_MAINT` 里的表。 +- `tocc-system-maint`:系统服务,端口 `8525`,给前端提供接口,通过 Feign 调用基础服务。 + +## 源码结构 + +```text +养护开发工程 +├── pom.xml # 父工程,统一依赖版本 +├── lib # 本机编译用的达梦驱动 +│ └── DmJdbcDriver8-8.1.5.60.jar +├── sql # 建表脚本 +│ └── 养护数据库结构20261111.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/养护数据库结构20261111.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 统一权限。