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