企业官网建设流程全解析

--- trigger: always_on --- # 后端架构与分支规范 ## 分层架构 - 严格遵守 Controller → Service → Store → Mapper 的分层原则 - Controller层：负责API映射，参数接收，不处理业务逻辑 - Service层：核心业务逻辑，参数校验 - Store层：数据储存层，负责数据查询和事务处理（@DSTransactional） - Mapper层：数据库操作 ## 扩展分层 - **Agg（聚合根/Model）层**：领域模型对象，位于 `sales` 模块的 `model` 包下 - 使用 `@Getter` + `@ToString`（不用 `@Data`，通过方法封装属性设置） - 必须提供 `create()` / `modify()` / `fillingDbId()` 方法封装属性设置 - `create` 和 `modify` 共用私有 `fillingMainData()` 方法 - 全参构造函数用于 Entity→Agg 的转换 - **Bond层**：复杂业务编排层，承载核心业务逻辑（几千行级别），命名如 `XxxBond` - 标注 `@Component`，直接注入多个 Mapper/Service/Store - 不遵循标准 CRUD 模板，按业务场景定制方法 - **Trans层**：跨领域业务编排层，命名如 `XxxServiceTrans` - 标注 `@Component`，使用 `@DSTransactional` 保障多数据源事务 - 整合多个 Service/Store 的调用 ## 各层注解规范 | 层 | 类注解 | 注入方式 | 事务注解 | |---|--------|---------|--------| | Controller | `@RestController` + `@Slf4j` + `@Api(tags="...")` | `@Autowired` | 无 | | Service接口 | 无 | - | - | | ServiceImpl | `@Slf4j` + `@Service` | `@Autowired` | 无（事务放Store层） | | Store接口 | 无 | - | - | | StoreImpl | `@Slf4j` + `@Component` | `@Autowired` | `@DSTransactional`（写操作） | | Agg | `@Getter` + `@ToString` + `@ApiModel` | - | - | | Bond | `@Component` | `@Autowired` | 按需 | **关键规则**： - Store层用 `@Component` 而非 `@Service` - 事务使用 `@DSTransactional`（`com.baomidou.dynamic.datasource.annotation.DSTransactional`），而非 `@Transactional` - 特殊场景使用 `@DS("primary")` 或 `@DS("hologres")` 指定数据源 ## 各层包路径归属 | 类型 | 包路径 | 所属模块 | |------|--------|----------| | Entity | `com.lvcc.biz.entity.sales.{module}` | biz | | DTO | `com.lvcc.biz.dto.sales.{module}` | biz | | QueryDTO | `com.lvcc.biz.dto.sales.{module}` | biz | | VO | `com.lvcc.biz.vo.sales.{module}` | biz | | Mapper | `com.lvcc.biz.dao.sales.{module}` | biz | | Mapper XML | `biz/src/main/resources/mapper/{module}/` | biz | | Controller | `com.lvcc.sales.{module}.controller` | sales | | Service | `com.lvcc.sales.{module}.service` | sales | | ServiceImpl | `com.lvcc.sales.{module}.service.impl` | sales | | Agg(Model) | `com.lvcc.sales.{module}.model` | sales | | Store | `com.lvcc.sales.{module}.store` 或 `com.lvcc.biz.store.sales.{module}` | sales/biz | | StoreImpl | `com.lvcc.sales.{module}.store.impl` 或 `com.lvcc.biz.store.sales.{module}.impl` | sales/biz | | Bond | `com.lvcc.sales.{module}.bond` | sales | ## 各层返回值规范 | 层 | 操作类型 | 返回类型 | 示例 | |----|---------|---------|------| | Controller | 所有 | `RestResponse` | `RestResponse.success().setData(data)` | | Service | 分页查询 | `Page<VO>` | `Page<AiOutboundCallVO>` | | Service | 新增/删除/更新 | `boolean` | throws FebsException | | Service | 详情查询 | `VO` | throws FebsException | | Store | 分页查询 | `List<VO>` | Mapper直返 | | Store | 新增或修改 | `Long`（主键ID） | - | | Store | 删除 | `boolean` | - | | Store | 详情 | `Agg` 或 `VO` | - | ## Controller 标准方法模板 ```java // 新增：POST /save @PostMapping("/save") public RestResponse create(@RequestBody XxxDTO dto) throws FebsException // 单删：GET /delete/{id} @GetMapping("/delete/{id}") public RestResponse delete(@PathVariable("id") String id) throws FebsException // 批删：POST /delete/batch @PostMapping("/delete/batch") public RestResponse deleteBatch(@RequestBody String ids) throws FebsException // JSON字符串手动解析 // 分页查询：POST /list @PostMapping("/list") public RestResponse queryXxxPage(@RequestBody XxxQueryDTO queryDto) // 不throws // 详情查询：GET /get/{id} @GetMapping("/get/{id}") public RestResponse findXxxById(@PathVariable("id") String id) throws FebsException // 更新：POST /update/{id} @PostMapping("/update/{id}") public RestResponse update(@PathVariable("id") String id, @RequestBody XxxDTO dto) throws FebsException ``` **关键规则**： - id 参数类型统一为 **String**（Controller层），在Service层转为Long - 批量操作接收 JSON字符串，用 `JSON.parse()` 手动解析 - 更新操作路径为 `/update/{id}`，将 id 设置到 dto：`dto.setId(Long.valueOf(id))` - 分页查询方法 **不throws FebsException** - 返回格式：`RestResponse.success().setData(data)` 或 `RestResponse.success("成功")` ## 分页查询模式 - QueryDTO 继承 `PageBaseDTO`（含 pageNum=1, pageSize=10） - Service层构造 `Page<VO>` 对象：`new Page<>(pageNum, pageSize)` - Store层方法签名：`List<VO> queryXxxPage(Page<VO> queryPage, XxxQueryDTO queryDto)` - Mapper方法签名：`List<VO> queryXxxRecord(Page<VO> queryPage, @Param("data") XxxQueryDTO queryDto)` - MyBatis-Plus 自动将分页信息填充到 Page 对象 ## DDD设计原则 - 领域模型优先，数据库仅为持久化细节 - 通过聚合根(Agg)维护数据一致性 - 通过限界上下文将系统拆分为高内聚、低耦合的模块 - Agg不使用 `@Setter` / `@Data` 注解（通过 `create`/`modify`/`fillingDbId` 方法保证不可变性） - 添加字段需同步改动：Entity → StoreImpl → ServiceImpl → Agg → VO/DTO（按需） ## Store层保存模式 ```java @DSTransactional public Long saveXxxRecord(XxxAgg saveEntity, String userKey) { XxxEntity curEntity = this.findXxxEntityByDataKey(saveEntity.getId()); // 1. 查询现有实体 curEntity = this.buildXxxEntity(curEntity, saveEntity, userKey); // 2. 构建实体 if (ObjectUtil.isEmpty(curEntity.getId())) { xxxMapper.insert(curEntity); // 3. id为空 → insert } else { xxxMapper.updateById(curEntity); // 4. id有值 → updateById } saveEntity.fillingDbId(curEntity.getId()); // 5. 回填聚合根的id return curEntity.getId(); // 6. 返回主键 } ``` - `buildXxxEntity` 方法处理新增/修改场景的Entity构建 - 逻辑删除：`set(XxxEntity::getDeleted, 1)` 而非物理删除 - 查询实体时必须加 `eq(XxxEntity::getDeleted, 0)` 条件 ## 获取当前用户 - Service层：`UserInfo user = JWTUtil.getCurrentUser(); String userKey = String.valueOf(user.getUserId());` - Controller层日志：`FebsUtil.getCurrentUser()` ## 数据权限注解 ```java @ComplexPermissions(andPermissionEnums = MenuPermEnum.XXX, message = "暂无访问权限") ``` - 用于Controller方法上，控制菜单权限 - 权限码在 `MenuPermEnum` 枚举中定义 ## 操作日志注解 ```java @Log("操作描述") ``` - 用于Controller方法上，记录操作日志 ## 代码生成器 - 新增表必须采用代码生成器生成的代码风格 - 添加字段时需改动位置：Entity → StoreImpl → ServiceImpl → Agg层 → VO和DTO（按需补充） ## 代码分支规范 - 主分支：`master_test`，禁止在未经允许的情况下直接修改并提交代码 - 需求合集：`factory_platform+合集名称`，如 `factory_platform_M20250901` - 线上优化：`master_online_optimization+日期`，如 `master_online_optimization_20251101` - 普通需求：`factory_+需求英文命名+日期`，如 `factory_ai_perms_20250929` - 合并规范：完成需求后进行代码提测，测试完成后由组长根据上线清单进行代码合并 - 提测时必须在提测单标明是否有SQL，并将SQL粘贴到提测单 - 测试开始时需重新合并 `master_production` 到自己的提测分支 ## 本地开发环境 - 本地开发禁止连接测试环境的消息队列 - 微服务版本禁止注册测试环境的注册中心 - 启动顺序：Nacos → Gateway → Sales → 其他按需启动 - 外网映射在dev环境 `t_service_config` 表中配置，地址格式 `http://factorytransmit.frp.lbbtech.com/服务标识/接口路径`