# 开发环境与规范

本章记录本项目的开发约定，供开发者与 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()` 自动迁移。详见[前端用户偏好](/dev/preferences)。
- **与 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`，新增调度器直接标注即可。

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

## 相关文档

- [项目结构](/dev/project-structure)
- [构建与部署](/dev/build-deploy)