Skip to content

开发环境与规范 ​

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

AI 测试环境 ​

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

环境前端后端数据库
测试环境51748081独立 SQLite 空库(ai-home/data/ai-ledgerly.db)
真实环境51738080MySQL(真实数据)
  • 两个环境共用同一份源码:前端改动经 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 下的资源文件后,需额外同步资源:

    bash
    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 已禁用)。

    bash
    # 宿主机
    ./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。

    bash
    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 类型检查。

相关文档 ​

基于 Spring Boot 3 + Vue 3 的个人汇账