126 lines
5.5 KiB
Markdown
126 lines
5.5 KiB
Markdown
# 边缘人脸区域安全项目开发指南
|
||
|
||
## 1. 项目说明
|
||
|
||
`zcloud_gbs_edgeguard` 是“边缘人脸区域安全”服务，服务标识为 `jjb-saas-zcloud-edgeguard`，网关前缀为 `edgeguard`。
|
||
|
||
项目用于承载边缘侧人脸与区域安全相关能力。后续可在此服务中逐步实现区域、摄像头、人脸库、人员授权、识别事件和告警记录等业务。
|
||
|
||
当前脚手架已经提供了一套“风险点（RiskPoint）”的 CRUD 示例。它是开发参考样例，不代表最终业务模型；新业务应按相同分层方式扩展，避免将所有逻辑堆放在 Controller 或 Mapper 中。
|
||
|
||
## 2. 模块结构
|
||
|
||
```text
|
||
zcloud_gbs_edgeguard
|
||
├── start # 服务启动与运行配置
|
||
├── web-client # 对外服务接口、命令对象、查询对象、返回对象
|
||
├── web-adapter # HTTP Controller、接口适配
|
||
├── web-app # 应用层用例编排与事务控制
|
||
├── web-domain # 领域实体、领域网关接口
|
||
└── web-infrastructure # MyBatis、数据库对象、Repository、网关实现
|
||
```
|
||
|
||
模块依赖应保持从外向内：
|
||
|
||
```text
|
||
web-adapter → web-client / web-app → web-domain → web-infrastructure
|
||
start 负责组装并启动全部模块
|
||
```
|
||
|
||
不要让 `web-client` 依赖 `web-app`、`web-domain` 或 `web-infrastructure`；不要在 `web-adapter` 中直接访问 Mapper。
|
||
|
||
## 3. 运行与配置
|
||
|
||
启动类是 `start/src/main/java/com/zcloud/gbs/edgeguard/Application.java`。
|
||
|
||
Nacos 配置在 `start/src/main/resources/nacos.yml`：
|
||
|
||
```yaml
|
||
application:
|
||
name: jjb-saas-zcloud-edgeguard
|
||
gateway: edgeguard
|
||
cn-name: 边缘人脸区域安全
|
||
```
|
||
|
||
公共配置通过 `bootstrap.yml` 导入，包括 Nacos、SDK 与 Swagger 配置。开发环境使用当前 `nacos.yml` 和 `sdk.yml`；生产环境配置应根据部署环境另行提供，不能直接复制其他服务的地址、密钥或账号。
|
||
|
||
在 IDEA 中从根 `pom.xml` 重新加载 Maven 后，运行 `Application` 启动服务。也可在已配置 Maven 命令的环境执行：
|
||
|
||
```bash
|
||
mvn clean package -DskipTests
|
||
```
|
||
|
||
## 4. 新增业务功能的规范
|
||
|
||
以下以当前 `RiskPoint` 样例为参考。假设需要新增“安全区域（SecurityZone）”功能，应同时补齐各层，不要只新增一张表或一个 Controller。
|
||
|
||
| 模块 | 放置内容 | RiskPoint 样例 |
|
||
| --- | --- | --- |
|
||
| `web-client` | API 接口、`AddCmd`、`UpdateCmd`、`PageQry`、`CO` | `RiskPointServiceI`、`RiskPointAddCmd` |
|
||
| `web-adapter` | REST Controller、Swagger 注解、参数校验 | `RiskPointController` |
|
||
| `web-app` | `*AddExe`、`*UpdateExe`、`*RemoveExe`、`*QueryExe`、应用服务 | `RiskPointAddExe` |
|
||
| `web-domain` | `*E` 领域实体、`*Gateway` 接口 | `RiskPointE`、`RiskPointGateway` |
|
||
| `web-infrastructure` | `*DO`、Mapper、Mapper XML、Repository、Gateway 实现 | `RiskPointDO`、`RiskPointMapper` |
|
||
|
||
### 4.1 包与命名
|
||
|
||
- Java 包统一以 `com.zcloud.gbs.edgeguard` 开头。
|
||
- 领域实体使用 `XxxE`，例如 `SecurityZoneE`。
|
||
- 持久化对象使用 `XxxDO`，例如 `SecurityZoneDO`。
|
||
- 返回对象使用 `XxxCo`，命令使用 `XxxAddCmd`、`XxxUpdateCmd`，分页查询使用 `XxxPageQry`。
|
||
- 应用层执行器使用 `XxxAddExe`、`XxxUpdateExe`、`XxxRemoveExe`、`XxxQueryExe`。
|
||
- 网关接口使用 `XxxGateway`，其实现放在 `gatewayimpl` 包。
|
||
|
||
### 4.2 HTTP 接口
|
||
|
||
Controller 只做请求接收、校验与调用应用服务，不放业务判断和数据库访问。
|
||
|
||
接口统一使用服务网关前缀：
|
||
|
||
```java
|
||
@RequestMapping("/edgeguard/securityZone")
|
||
```
|
||
|
||
参照现有样例使用：
|
||
|
||
- `POST /save`：新增
|
||
- `POST /list`：分页查询
|
||
- `GET /{id}`：详情
|
||
- `PUT /edit`：修改
|
||
- `DELETE /{id}`：删除
|
||
- `DELETE /ids`：批量删除
|
||
|
||
入参使用 `@Validated` 和 Bean Validation 注解，例如 `@NotEmpty`、`@NotNull`；接口返回使用 COLA 的 `SingleResponse`、`PageResponse`、`MultiResponse` 或 `Response`。
|
||
|
||
### 4.3 应用层与事务
|
||
|
||
用例逻辑放在 `web-app`。涉及写入的执行器参照 `RiskPointAddExe` 使用：
|
||
|
||
```java
|
||
@Transactional(rollbackFor = Exception.class)
|
||
public boolean execute(SecurityZoneAddCmd cmd) {
|
||
// 参数转换、业务校验、调用领域网关
|
||
}
|
||
```
|
||
|
||
保存失败时抛出 `BizException`，不要仅返回 `false` 或吞掉异常。跨表写入必须在同一个应用层事务中完成。
|
||
|
||
### 4.4 领域与持久化
|
||
|
||
- `web-domain` 只定义领域模型和网关能力，不依赖 MyBatis Mapper。
|
||
- `web-infrastructure` 实现领域网关，负责 Entity/DO 转换和数据库读写。
|
||
- Mapper 接口放在 `persistence.mapper`，XML 放在 `src/main/resources/mybatis`。
|
||
- 新增表或变更表结构时，同步维护 `web-infrastructure/src/main/resources/TableCreationDDL.sql`，并按实际发布流程补充数据库迁移脚本。
|
||
- 通用审计字段、逻辑删除等规则优先复用项目依赖中的基础模型，不要重复造字段和能力。
|
||
|
||
## 5. 提交前检查
|
||
|
||
- 根 POM 可识别全部六个模块。
|
||
- 新功能的 API、DTO、应用层、领域层、基础设施层均已补齐。
|
||
- Controller 没有直接调用 Mapper；领域层没有依赖基础设施层。
|
||
- Nacos 服务名和网关前缀保持 `edgeguard`，不要遗留 `risk`、`org.example` 等脚手架名称。
|
||
- Swagger 标签、接口路径、日志和异常提示与实际业务一致。
|
||
- 数据库字段、DO、Mapper、Mapper XML 和 DDL 保持一致。
|
||
- 执行 Maven 构建并在 IDEA 中确认 Maven 模块全部加载成功。
|
||
|