以 Service1 开发业务服务
从一个完整调用链开始
当前已提交的 Service1 示例提供应用管理接口，可按以下链路阅读：
Admin → Gateway → Admin BFF → ApplicationFeignClient → Service1 → Mapper / 数据库
本页以该主线代码说明新增业务的方法；应用接入与环境字段见配置规范。
应用分层规范
Samples 以 Controller → Service → Mapper 为业务服务的基本调用方向。先明确每层职责，再新增接口和模型；完整规范见后端开发规范 → 应用分层。
- Controller：接收 HTTP 请求、校验参数并调用 Service，返回业务对象，由 Web Starter 统一包装响应；不直接操作 Mapper、不吞异常。
- Service：实现业务规则、授权与事务边界，需要原子性的写操作在公开业务方法上声明事务。
- Mapper：执行数据访问，查询时落实用户、租户和数据范围，使用参数绑定。
- Converter：使用 MapStruct 转换各层模型，避免在 Controller 中堆叠字段复制。
模型沿用 Query（查询条件）、Form（写入表单）、DTO（传输）、VO（展示结果）、BO（组合业务对象）、Entity（表映射）的语义。Entity 留在持久化边界内，不作为新增 REST / Feign 公共契约。
BFF 负责页面聚合，Service1 负责核心业务；跨服务只依赖 *-api 契约，不直接引用其他服务的 Service 实现、Mapper 或 Entity。方法与资源授权的接入见 Security。
1. 先定义服务间契约
在 macula-samples-api/macula-samples-service1-api 定义请求表单、查询条件、返回 VO、错误约定和 Feign 接口。现有 ApplicationFeignClient 声明 /api/v1/app 的分页、创建、更新、删除与维护人相关操作，服务发现目标为 macula-samples-service1。
BFF 引用契约制品，不引用 Service1 的实现包。新增字段或接口时同步更新调用方，并核对兼容性。
2. 在 Service1 实现业务
| 位置 | 职责 |
|---|---|
| controller | 路径、参数接收、表单校验与调用业务服务 |
| service / impl | 业务规则、事务与操作编排 |
| mapper | MyBatis-Plus 数据访问 |
| pojo/entity、pojo/bo | 持久化实体与业务对象 |
| converter | 不同层模型之间的转换 |
| API 模块的 form/query/vo | 对外请求与返回契约 |
对照 ApplicationController、ApplicationServiceImpl、ApplicationMapper 和 ApplicationConverter 阅读，保持 HTTP、业务、数据访问的职责边界。业务权限和数据可见性在服务端落实，菜单展示不替代接口校验。
3. 管理数据库变更
Service1 已配置 Flyway，当前主线迁移入口是 src/main/resources/db/migration/V1__baseline.sql。新增表或字段时按仓库已有序号追加 V<下一版本>__说明.sql，不修改已执行迁移。
本地连接地址、账号、数据库名和 Flyway 开关放在模块对应的环境配置中。回归时验证空库初始化和已有库升级两条路径。
4. 在 BFF 组织管理端接口
Admin BFF 的 ApplicationServiceImpl 注入 ApplicationFeignClient，将管理端请求转给 Service1。面向页面的聚合与返回编排留在 BFF，核心业务规则和持久化留在 Service1。
平台用户与菜单通过 BFF 的 System Starter 获取。BFF 配置 Cloud endpoint 和应用凭据；BFF 与 Service1 都配置 Samples Gateway 的 JWK 地址。
5. 联调与回归
先运行服务端契约与业务模块的相关测试，再通过 Gateway 与 BFF 联调管理端。验证接口路径、请求 / 返回模型、分页、错误处理、权限与数据库迁移。