rosercode
5eb1d331f9
同步 ledgerly 近期开发改动（接口请求/响应体加解密、代码检查工具、安全与稳定性修复、AI 提示词模板抽取），补齐对应开发文档并修正过时表述，同时在快速开始补充小屏适配说明。 变更内容： - dev/api.md：新增「接口数据加密」小节，说明 RSA + AES-GCM 握手流程、信封格式、会话有效期与失效码、豁免范围及编译期开关。 - dev/architecture.md：请求处理流程补入加密会话拦截器与请求/响应体 Advice，关键设计亮点新增接口数据加密一条。 - dev/development.md：新增「代码检查」小节，登记 Spotless / Checkstyle / SpotBugs 与前端 ESLint / Prettier 配置及运行命令。 - dev/build-deploy.md：新增「安全配置」（JWT_SECRET 覆盖、CORS 放行来源），构建任务链补入前端 lint 校验说明。 - dev/ai.md：修正已重命名的提示词模板名，补充「提示词模板」片段机制与图片记账 SSE 超时、心跳说明。 - dev/project-structure.md：补充 config.crypto / util.crypto 包、prompts 资源目录、crypto-keys.json 运行时文件与交易服务拆分说明。 - guide/getting-started.md：新增「小屏与移动端适配」说明。 - guide/transactions.md：导出说明补充单次 10000 条上限。
95 lines
5.9 KiB
Markdown
95 lines
5.9 KiB
Markdown
# 开发环境与规范
|
||
|
||
本章记录本项目的开发约定，供开发者与 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`，新增调度器直接标注即可。
|
||
|
||
## 代码检查
|
||
|
||
项目统一引入代码检查工具并挂到构建/打包流程，检查不通过即阻断，详见[构建与部署](/dev/build-deploy)。
|
||
|
||
**后端（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` 类型检查。
|
||
|
||
## 相关文档
|
||
|
||
- [项目结构](/dev/project-structure)
|
||
- [构建与部署](/dev/build-deploy)
|