开发环境与规范

本章记录本项目的开发约定，供开发者与 AI 助手参考。

AI 测试环境

为避免污染真实数据，AI 访问网页、截图、操作界面或验证前端功能时，必须使用测试环境入口：

环境	前端	后端	数据库
测试环境	5174	8081	独立 SQLite 空库（ai-home/data/ai-finance.db）
真实环境	5173	8080	MySQL（真实数据）

• 两个环境共用同一份源码：前端改动经 Vite HMR 两边同步；后端改动执行 ./reload.sh 后两边 devtools 同时热重启。
• 启动脚本：run/ai-dev/start-ai-backend.sh（8081）、run/ai-dev/start-ai-frontend.sh（5174）。
• ai-home/、run/ai-dev/ 为本地专用，不提交仓库。

前端开发

• 前端改动不使用 npm run build 验证，直接依赖 Vite 开发服务器的 HMR。
• npm run build（vue-tsc -b && vite build）的产物仅用于生产部署，与开发模式无关。
• 界面文案统一在 frontend/src/locales/messages.ts 维护，新增 key 需同时提供中文（zh）、英文（en）、日文（ja）三语。

后端开发

• 后端以开发模式运行在容器中（Gradle bootRun，JDK 21，--network host）。

• 修改 Java 代码后执行 ./reload.sh（容器内增量编译），spring-boot-devtools 会在 1–3 秒内热重启。

• 修改 src/main/resources 下的资源文件后，需额外同步资源：

  docker exec finance-backend-dev gradle -I /project/nexus-init.gradle processResources

• 仅在新增依赖、修改配置等需要彻底重启时才重启容器。

• 数据库支持运行时配置与切换（SQLite / MySQL），切换数据库或新增 JDBC 驱动后需重启容器。

代码规范

• Javadoc：新增 Java 文件的类级 javadoc 末尾必须加一行 @date，格式 yyyy-MM-dd HH:mm:ss，时间取文件创建时间。
• 导入顺序：由 Spotless 管理，三组、组间空行分隔：java/javax → 第三方 → cn.rosercode。
  • 格式化：docker exec finance-backend-dev gradle -I /project/nexus-init.gradle spotlessApply
  • spotlessCheck 已挂到 check，build 时会校验。
• 日志：统一使用 Lombok @Slf4j，按级别使用（error 未预期异常、warn 可预期业务失败、info 关键写操作与外部调用、debug 流程细节）。
• 控制器：方法签名禁止声明 HttpServletRequest / HttpServletResponse，统一使用 cn.rosercode.finance.util.UserContext。
• 数据库表结构变更：需同时维护 sql/init.sql（MySQL）与 sql/schema-sqlite.sql（SQLite），SQLite 以 ;; 分隔语句。
• 对象转换：实体与 VO 之间统一使用 MapStruct（converter.VoConverter），不在 Service 中手写 setter。
• 定时任务：基于 Spring @Scheduled，新增调度器直接标注即可。

Git 提交规范

• 提交范围仅包含源码与配置；个人账单原始数据、docs/、reload.sh、.gitignore、nexus-init.gradle 及 AI 测试环境基础设施不纳入提交。
• commit message 使用 feat: 中文描述 风格；纯重构/规范调整用 refactor:，构建与依赖配置用 chore: 或 build:。
• 远端为本地 Gitea，主分支 master；推送使用一次性内嵌令牌的 URL，避免令牌写入 origin 配置。

相关文档

• 项目结构
• 构建与部署