2026/1/31

整体编码顺序（8 个阶段，循序渐进）
阶段 1：基础配置（先搭骨架，保证项目能启动）
核心目标：让 Spring Boot 项目能正常启动，连接数据库，配置基础功能。
要编写的文件 核心内容 关键注意事项
pom.xml 引入核心依赖：Spring Boot、MyBatis-Plus、MySQL 驱动、Swagger、Lombok、EasyExcel 等 版本要兼容（如 Spring Boot 2.7.x + MyBatis-Plus 3.5.x），避免依赖冲突
application.yml 配置：

1. 服务器端口（如 8080）
2. MySQL 数据库连接（url、username、password）
3. MyBatis-Plus（别名包、XML 扫描路径、日志）
4. Swagger（可选） 数据库 url 要包含useUnicode=true&characterEncoding=utf8mb4，匹配数据库字符集
   ElderlyAssessApplication.java 启动类，添加@SpringBootApplication、@MapperScan("com.elderly.assess.mapper") @MapperScan要指向 mapper 包，否则 MyBatis-Plus 无法扫描 Mapper 接口
   WebConfig.java 配置跨域（允许小程序跨域请求） 允许的请求方法要包含 GET/POST/PUT/DELETE，allowedOriginPatterns设为*（开发环境）
   MyBatisPlusConfig.java 配置 MyBatis-Plus 分页插件、主键生成策略（如雪花算法） 分页插件是必备的，后续查询接口需要分页功能
   阶段 2：实体类（Entity）—— 映射数据库表
   核心目标：让 Java 类和数据库表一一对应，是后续操作数据库的基础。
   要编写的文件 核心内容 关键注意事项
   ElderlyInfo.java 1. 字段对应t_elderly_info表（id、assessNo、name、idCard 等）
5. 添加 MyBatis-Plus 注解：@TableName("t_elderly_info")、@TableId(type = IdType.AUTO)
6. 字段注解：@TableField("id_card")（匹配数据库下划线字段）
7. Lombok 注解：@Data、@NoArgsConstructor、@AllArgsConstructor 字段名用驼峰（如idCard），通过@TableField映射数据库下划线字段（id_card）；日期字段用LocalDate/Date
   AssessResult.java 对应t_assess_result表，同上 关联字段elderlyId要和t_elderly_info的 id 类型一致（BIGINT）
   AssessItem.java 对应t_assess_item表，同上 itemType要和数据库的枚举值（1 - 日常生活活动等）对应，可定义常量
   Assessor.java 对应t_assessor表，同上 密码字段要标注@TableField，后续加密存储
   阶段 3：常量类 + 统一返回工具类
   核心目标：规范代码中的常量和返回格式，避免硬编码。
   要编写的文件 核心内容 关键注意事项
   ResultCodeConstant.java 定义返回码常量：SUCCESS=200、FAIL=500、PARAM_ERROR=400等 前后端约定统一的返回码，小程序端根据返回码处理逻辑
   ResultUtil.java 封装统一返回结果ResultVO（包含 code、msg、data），提供success()、fail()方法 ResultVO要包含泛型（ResultVO），支持返回不同类型的数据
   AssessConstant.java 定义评估相关常量：
8. 能力等级（如FINAL_GRADE_GOOD=0、FINAL_GRADE_LIGHT=1）
9. 评估原因（ASSESS_REASON_INIT=1）
10. 指标类型（ITEM_TYPE_DAILY=1） 常量名要语义化，值要和数据库表中的枚举值完全一致
    阶段 4：异常处理
    核心目标：统一处理项目中的异常，返回友好提示，避免程序崩溃。
    要编写的文件 核心内容 关键注意事项
    BusinessException.java 自定义业务异常，继承RuntimeException，包含code和msg 用于处理业务逻辑异常（如 “身份证号已存在”）
    GlobalExceptionHandler.java 全局异常处理器，添加@RestControllerAdvice：
11. 捕获BusinessException，返回自定义错误信息
12. 捕获SQLException，返回 “数据库异常”
13. 捕获Exception，返回 “系统异常” 异常处理后要返回统一的ResultVO，避免直接抛原生异常给前端
    阶段 5：Mapper 层 —— 操作数据库
    核心目标：定义数据库操作接口，MyBatis-Plus 自动生成基础 CRUD，复杂 SQL 写在 XML 中。
    要编写的文件 核心内容 关键注意事项
    ElderlyInfoMapper.java 接口继承BaseMapper，定义自定义方法（如selectByAssessNo、selectByIdCard） 基础 CRUD（增删改查）无需手写，MyBatis-Plus 已实现；自定义方法需在 XML 中写 SQL
    AssessResultMapper.java 继承BaseMapper，定义自定义方法（如selectByElderlyIdAndDate、selectByFinalGrade） 关联查询（如查老年人 + 评估结果）可在 XML 中写 JOIN SQL
    AssessItemMapper.java 继承BaseMapper，定义selectByResultId（根据评估结果 ID 查指标） -
    AssessorMapper.java 继承BaseMapper，定义selectByUsername（评估员登录用） -
    （XML 文件）如ElderlyInfoMapper.xml 编写自定义 SQL（如复杂查询、多表关联） XML 的 namespace 要和 Mapper 接口全类名一致，参数和返回值要匹配
    阶段 6：DTO/VO —— 入参 / 出参封装
    核心目标：隔离实体类和前端交互数据，避免直接暴露数据库字段。
    要编写的文件 核心内容 关键注意事项
    ElderlyInfoDTO.java 封装小程序提交的老年人信息入参（如 name、idCard、gender 等），可添加@NotBlank、@Pattern（身份证正则）等校验注解 入参只包含前端需要传递的字段，无需包含数据库的 createTime 等字段
    AssessResultDTO.java 封装评估结果提交入参（elderlyId、assessDate、各维度得分 / 等级等） 关联的评估指标可封装为List
    QueryDTO.java 通用查询入参（pageNum、pageSize、keyword、startDate、endDate 等） 用于分页查询、条件筛选
    ElderlyInfoVO.java 封装返回给前端的老年人信息（隐藏敏感字段如 idCard，只返回后 4 位） 出参可包含关联数据（如该老年人的最新评估结果）
    AssessResultVO.java 封装评估结果出参，包含老年人基本信息、各维度得分 / 等级、评估员信息等 多表关联查询的结果，通过 VO 封装后返回给前端
    阶段 7：服务层（Service + Impl）—— 业务逻辑核心
    核心目标：实现业务逻辑（如保存老年人信息、计算评估等级、提交评估结果），是 Controller 的底层支撑。
    要编写的文件 核心内容 关键注意事项
    ElderlyInfoService.java 接口定义：saveElderlyInfo(ElderlyInfoDTO dto)、getElderlyInfoById(Long id)、getElderlyInfoByIdCard(String idCard)、pageQuery(QueryDTO dto) 接口只定义方法名和参数，不写实现逻辑
    ElderlyInfoServiceImpl.java 实现类添加@Service，重写接口方法：
14. 保存前校验身份证号是否重复（抛业务异常）
15. 生成唯一评估编号（assessNo）
16. 转换 DTO 为 Entity，调用 Mapper 保存 业务逻辑全部在 ServiceImpl 中实现，避免 Controller 写复杂逻辑
    AssessResultService.java + AssessResultServiceImpl.java 核心逻辑：
17. 提交评估结果时，计算各维度等级、最终能力等级
18. 保存评估结果主表 + 指标明细表
19. 分页查询评估结果、按等级筛选 最终等级的计算规则要严格按业务标准实现（如总分阈值）
    AssessorService.java + AssessorServiceImpl.java 核心逻辑：
20. 评估员登录（校验账号密码，密码解密）
21. 新增评估员（密码加密存储） 密码用 BCrypt 加密，避免明文存储
    ExportService.java + ExportServiceImpl.java 核心逻辑：
22. 导出评估结果为 Excel（用 EasyExcel）
23. 导出老年人信息列表 EasyExcel 要自定义表头、数据格式，避免内存溢出
    阶段 8：控制层（Controller）—— 暴露接口给小程序
    核心目标：定义 HTTP 接口，接收小程序请求，调用 Service 处理，返回统一结果。
    要编写的文件 核心内容 关键注意事项
    ElderlyInfoController.java 1. @PostMapping("/elderly/save")：保存老年人信息
24. @GetMapping("/elderly/getById")：根据 ID 查老年人信息
25. @GetMapping("/elderly/page")：分页查询 接口路径统一前缀/api（如/api/elderly/save），方便跨域配置和权限控制
    AssessResultController.java 1. @PostMapping("/assess/submit")：提交评估结果
26. @GetMapping("/assess/getByElderlyId")：根据老年人 ID 查评估结果
27. @GetMapping("/assess/page")：分页查询评估结果 提交评估结果时，要接收AssessResultDTO + List，调用 Service 保存主表 + 明细表
    AssessorController.java 1. @PostMapping("/assessor/login")：评估员登录
28. @GetMapping("/assessor/getInfo")：获取评估员信息 登录接口返回 JWT Token（可选），后续接口携带 Token 认证
    ExportController.java @GetMapping("/export/assessResult")：导出评估结果 Excel 响应头要设置Content-Disposition，指定文件名和格式