# Java API 技术规范

## 运行环境
- JDK 17

## 框架选型
- Spring Boot 3.3.6 (spring-boot-starter-parent)
- ORM：MyBatis-Plus
- Lombok

## 架构约束
- API 采用多模块 Maven 项目结构，父项目统一管理依赖版本
- 项目名： geo-bps
- 包名前缀：com.geomative.bps.*
- 子模块划分：
  - `api-admin` 后台管理入口模块：需登录鉴权，引入 `website`、`device`、`library`、`permission` 等模块
  - `api-portal` 前端门户入口模块：无需登录，仅引入对外开放的业务模块
  - `device` 设备管理模块
  - `website` 网站管理后台
  - `library` 资料库模块
  - `permission` 权限管理模块
  - `common` 公共模块：工具类、基础配置、统一响应格式、全局异常处理等共享代码

- 项目路径：`apps/geo-bps-api/`
- groupId：`com.geomative.bsp`
- artifactId：`geo-bps-api`
- 项目整体结构：
```
apps/geo-bps-api/
├── pom.xml                 # 父 POM，统一依赖版本管理
├── api-admin/              # 后台管理入口，Spring Security 鉴权配置
├── api-portal/             # 前端门户入口，公开接口无需授权
├── business/               # 业务模块聚合器（pom packaging）
│   ├── pom.xml
│   ├── permission/         # 权限管理模块
│   ├── website/            # 网站业务模块（被两个入口共享）
│   ├── device/             # 设备管理模块
│   └── library/            # 资料库模块
└── common/                 # 公共工具、基础配置、统一响应体
```

## 编码规范

### 命名规范
- 类名使用 UpperCamelCase，如 `DeviceService`、`UserDO`
- 方法名、变量名使用 lowerCamelCase，如 `getUserById`、`deviceList`
- 常量全部大写，单词间用下划线，如 `MAX_RETRY_COUNT`
- 包名全部小写，如 `com.example.device.domain`
- 抽象类命名以 `Abstract` 开头；异常类命名以 `Exception` 结尾；测试类命名以被测类名开头、`Test` 结尾
- POJO 类中布尔类型变量不加 `is` 前缀，避免序列化问题
- 领域对象命名后缀约定：
  - 数据库映射对象：`XxxDO`
  - 数据传输对象：`XxxDTO`
  - 视图对象：`XxxVO`
  - 查询对象：`XxxQuery`
  - 命令对象：`XxxCommand`

### 注释规范
- 所有 public 类、方法必须有 Javadoc 注释
- 方法注释需说明功能、参数含义、返回值、可能抛出的异常
- 代码逻辑复杂处需有行内注释说明意图，而非描述代码本身
- 禁止保留无意义的注释和注释掉的废弃代码

### 异常处理
- 不允许捕获 `Exception` 等大类异常后不做任何处理（空 catch）
- 业务异常统一使用自定义异常类，继承 `RuntimeException`
- 不允许用异常控制正常业务流程
- finally 块中不允许使用 return

### 日志规范
- 使用 SLF4J + Logback，禁止直接使用 `System.out.println`
- 日志变量声明：`private static final Logger log = LoggerFactory.getLogger(XxxClass.class);`
- 日志输出使用占位符，禁止字符串拼接：`log.info("userId: {}", userId)`
- 异常日志必须输出完整堆栈：`log.error("message", e)`

### 集合与并发
- 初始化集合时指定初始容量，如 `new ArrayList<>(16)`
- 禁止在 foreach 循环中对集合进行 add/remove 操作
- 线程池不允许使用 `Executors` 创建，需通过 `ThreadPoolExecutor` 显式配置参数

### 其他
- 所有方法入参需做非空校验，使用 `Objects.requireNonNull` 或断言
- 魔法值（Magic Number）禁止直接出现在代码中，需定义为常量
- 返回值为集合类型时，不允许返回 null，应返回空集合

### DDD 分层架构
- 采用领域驱动设计（DDD）分层架构，每个子模块内部结构如下：

```
{module}/
├── interfaces/          # 接口层：Controller、DTO、Assembler
├── application/         # 应用层：ApplicationService、Command、Query
├── domain/              # 领域层：Entity、ValueObject、DomainService、Repository接口、DomainEvent
└── infrastructure/      # 基础设施层：Repository实现、Mapper、持久化对象(PO)、外部服务适配
```

## 数据库
- PostgreSQL 12.14 (Debian 12.14-1.pgdg110+1)

### 审计字段规范
- 所有业务表必须包含以下审计字段：
  - `created_at` TIMESTAMP NOT NULL — 创建时间，INSERT 时自动填充
  - `created_by` VARCHAR(64) NULL — 创建人（用户ID或用户名），字符类型
  - `updated_at` TIMESTAMP NOT NULL — 最后修改时间，INSERT 和 UPDATE 时自动填充
  - `updated_by` VARCHAR(64) NULL — 最后修改人（用户ID或用户名），字符类型
  - `deleted` TINYINT NOT NULL DEFAULT 0 — 删除状态，0=未删除，1=已删除

### 主键规范
- 所有业务表主键类型为 VARCHAR(64)，由应用层生成（如雪花算法、UUID 字符串等），不使用数据库自增或 UUID 类型

### PostgreSQL Schema 分模块
- 不同子模块的表使用不同的 PostgreSQL schema 进行隔离：
  - `perm` — permission 模块（admin_users、revoked_tokens、admin_menus、admin_roles 等）
  - `web` — website 模块（nav_menus、branches、sub_branches、pages、page_contents、page_seo、fixed_page_contents、enabled_locales 等）
  - `dev` — device 模块（quotations、access_logs、configurator_steps 等）
  - `lib` — library 模块（knowledge_articles 等）
  - `common` — 公共表（contact_submissions、system_config 等）
- MyBatis-Plus 通过 `@TableName(schema = "xxx")` 或全局配置指定 schema
- MyBatis-Plus 配置：
  - 通过 `MetaObjectHandler` 自动填充 `created_at`、`updated_at`
  - 通过 `@TableLogic` 注解标记 `deleted` 字段实现逻辑删除
  - 查询默认过滤 `deleted=1` 的记录

## 部署
- 集成 Nginx 作为前置代理
  - `api-admin`：Nginx 直接流量穿透，转发至单实例后台管理服务
  - `api-portal`：Nginx 4层负载均衡（TCP/stream模块），支持多实例横向扩展