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

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