chore: 初始化文档站仓库

2026-09-21 13:38:20 +08:00
commit a4ae7ac979
58 changed files with 4622 additions and 0 deletions
@@ -0,0 +1,58 @@
+# 开发环境与规范
+
+本章记录本项目的开发约定，供开发者与 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` 下的资源文件后，需额外同步资源：
+
+  ```bash
+  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` 配置。
+
+## 相关文档
+
+- [项目结构](/dev/project-structure)
+- [构建与部署](/dev/build-deploy)