ledgerly-docs/dev/development.md

开发环境与规范

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

AI 测试环境

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

环境	前端	后端	数据库
测试环境	5174	8081	独立 SQLite 空库（ai-home/data/ai-ledgerly.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）三语。
• 界面偏好需持久化记忆，存储键统一以 ledgerly. 前缀命名并集中维护于 frontend/src/utils/storageKeys.ts，读写经 frontend/src/utils/storage.ts（禁止业务代码直接调用 localStorage/sessionStorage）；旧 finance. 前缀由 migrateLegacyPrefixedKeys() 自动迁移。详见前端用户偏好。
• 与 AI 相关的界面元素必须受 AI 启用状态控制：未启用时一律不渲染（v-if="aiEnabled"），启用状态统一走共享状态 frontend/src/composables/useAiEnabled.ts（侧边栏「智能查数」菜单项亦据此显隐）。

后端开发

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

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

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

  docker exec ledgerly-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 ledgerly-backend-dev gradle -I /project/nexus-init.gradle spotlessApply
  • spotlessCheck 已挂到 check，build 时会校验。
• 日志：统一使用 Lombok @Slf4j，按级别使用（error 未预期异常、warn 可预期业务失败、info 关键写操作与外部调用、debug 流程细节）。
• 控制器：方法签名禁止声明 HttpServletRequest / HttpServletResponse，统一使用 cn.rosercode.ledgerly.util.UserContext。
• 数据库表结构变更：需同时维护 sql/init.sql（MySQL）与 sql/schema-sqlite.sql（SQLite），SQLite 以 ;; 分隔语句。
• 对象转换：实体与 VO 之间统一使用 MapStruct（converter.VoConverter），不在 Service 中手写 setter。
• 定时任务：基于 Spring @Scheduled，新增调度器直接标注即可。

代码检查

项目统一引入代码检查工具并挂到构建/打包流程，检查不通过即阻断，详见构建与部署。

后端（Gradle）：

• Spotless：格式化与导入顺序（见「代码规范」），spotlessCheck 已挂到 check 且为 compileJava 前置。

• Checkstyle：配置 gradle/checkstyle/checkstyle.xml、抑制清单 gradle/checkstyle/suppressions.xml，maxWarnings = 0。

• SpotBugs：配置 gradle/spotbugs/exclude.xml，effort = MAX、reportLevel = MEDIUM；工具版本固定 4.8.6（规避其 BCEL 依赖与 Spring Boot BOM 选定 commons-lang3 版本的冲突）。

• 仅检查主源码（checkstyleTest / spotbugsTest 已禁用）。

  # 宿主机
  ./gradlew -I nexus-init.gradle lint          # Spotless + Checkstyle + SpotBugs + 前端 ESLint
  ./gradlew -I nexus-init.gradle checkstyleMain spotbugsMain
  # 容器内（开发模式）
  docker exec ledgerly-backend-dev gradle -I /project/nexus-init.gradle checkstyleMain spotbugsMain
  

前端（ESLint + Prettier）：

• 配置：frontend/eslint.config.js（flat config）、frontend/.prettierrc.json、frontend/.prettierignore。

  cd frontend
  npm run lint          # eslint .
  npm run lint:fix      # eslint . --fix
  npm run format        # prettier --write .
  npm run format:check  # prettier --check .
  

• Gradle 的 frontendLint 在 frontendBuild 前执行；package.sh 打包前也会执行 spotlessCheck checkstyleMain spotbugsMain，任一检查失败都会中断构建与打包。

Git 提交规范

• 提交范围仅包含源码与配置；个人账单原始数据、docs/、reload.sh、.gitignore、nexus-init.gradle 及 AI 测试环境基础设施不纳入提交。
• commit message 采用「标题 + 概述段 + 分组列表」结构；标题为 <type>: <中文简述>，纯重构/规范调整用 refactor:，构建与依赖配置用 chore: 或 build:。
• 远端为本地 Gitea，提交与推送仅使用 dev 分支（master 仅用于稳定/发布，不纳入日常开发）；推送使用一次性内嵌令牌的 URL，避免令牌写入 origin 配置。
• 每次创建 commit 后需执行 ./package.sh 打包验证，并在 frontend/ 执行一次 npx vue-tsc -b --force 类型检查。

相关文档

• 项目结构
• 构建与部署