5.5 KiB

Raw Blame History

边缘人脸区域安全项目开发指南

1. 项目说明

zcloud_gbs_edgeguard 是“边缘人脸区域安全”服务，服务标识为 jjb-saas-zcloud-edgeguard，网关前缀为 edgeguard。

项目用于承载边缘侧人脸与区域安全相关能力。后续可在此服务中逐步实现区域、摄像头、人脸库、人员授权、识别事件和告警记录等业务。

当前脚手架已经提供了一套“风险点（RiskPoint）”的 CRUD 示例。它是开发参考样例，不代表最终业务模型；新业务应按相同分层方式扩展，避免将所有逻辑堆放在 Controller 或 Mapper 中。

2. 模块结构

zcloud_gbs_edgeguard
├── start                 # 服务启动与运行配置
├── web-client            # 对外服务接口、命令对象、查询对象、返回对象
├── web-adapter           # HTTP Controller、接口适配
├── web-app               # 应用层用例编排与事务控制
├── web-domain            # 领域实体、领域网关接口
└── web-infrastructure    # MyBatis、数据库对象、Repository、网关实现

模块依赖应保持从外向内：

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：

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 命令的环境执行：

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 只做请求接收、校验与调用应用服务，不放业务判断和数据库访问。

接口统一使用服务网关前缀：

@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 使用：

@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 模块全部加载成功。

5.5 KiB Raw Blame History Unescape Escape