rosercode
923d6db5c0
对照 ledgerly 自文档上次更新以来的全部改动，补充新功能文档、修正品牌与版本残留，并新增下载与安装页；配图已重新截取并上传 OSS，本地截图目录不纳入版本管理。 变更内容： - 新增「智能查数」「账单关系」两个使用文档页，并登记侧边栏与总览 - 设置页扩充为八个面板（账号安全、数据库实时进度、外观、导航等）并改为即时保存 - 收支记录补充关系列、批量操作、AI 搜索浮窗、可配置分页与「账单详情」弹窗 - 统计面板补充饼图/渠道图下钻与筛选双向联动；规则管理补充批量删除 - AI 能力补充智能查数与关系命名；新增下载与安装页 - 开发文档同步：AI 13 类调用、数据模型 24 张表、API、前端偏好、构建部署 - 统一「汇账 Ledgerly」品牌与「设置/日志」菜单文案，版本号对齐 0.1 - 截图脚本新增账单详情等场景并更新登记 说明： - download.md 的 OSS 下载链接保持待发布产物回填，暂不调整 - 已通过 npm run docs:build 与 npm run typecheck:scripts
62 lines
4.3 KiB
Markdown
62 lines
4.3 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`，新增调度器直接标注即可。
|
||
|
||
## 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)
|