rosercode
41d1a4d5a9
为规则、分类、标签管理页新增的「批量操作模式」与多选删除补充使用与开发文档，同时补上此前已完成但未同步的 AI 规则建议可编辑、编辑后实时重算去重等文档，并登记批量模式截图脚本。 变更内容： - guide/categories-tags.md：补充分类与标签的批量删除说明，并回填 tags-batch.png、categories-batch.png 配图。 - guide/rules.md：批量删除与应用匹配账单改为需先进入「批量操作」模式（默认不显示勾选框）。 - dev/api.md：新增 DELETE /api/tag/batch、/api/category/batch，并补齐规则命中账单预览/一键应用、AI 规则去重校验等接口。 - dev/data-model.md：说明标签删除清理交易标签与规则标签关联、分类删除保留逻辑引用（账单显示未分类）。 - dev/rule-engine.md、dev/ai.md、dev/preferences.md、guide/ai.md、guide/transactions.md：同步 AI 规则建议可编辑、编辑后实时重算去重、应用开关默认开启并持久化等说明。 - scripts/ts/capture-elements.ts：新增 captureBatchModes()（标签/分类批量模式截图）并纳入 main()。 说明： - 截图经测试环境（前端 5174 / 后端 8081，虚构数据）生成，已上传 OSS，正文以 OSS 长期地址引用；public/screenshots 目录不入库。
汇账 · 文档站
本目录是「汇账」（同级目录 ../ledgerly）的使用文档与开发文档站点，基于 VitePress 构建，并附带一套 Node/TypeScript 维护脚本（截图、演示数据、资料抓取）。
在线体验：https://finance.rosercode.cn/（演示账号
demo/demo123456，使用独立的 SQLite 演示库与虚构数据）
快速开始
# 安装依赖（走本地 verdaccio 私服，见 .npmrc）
npm install
# 本地开发（默认 http://localhost:5175）
npm run docs:dev
# 构建静态站点到 .vitepress/dist
npm run docs:build
# 预览构建产物
npm run docs:preview
对外访问（局域网/远程）：
./node_modules/.bin/vitepress dev --host 0.0.0.0
文档结构
站点分为两大板块：
- 使用文档（
guide/）：面向使用者，讲「怎么用」。- 开始使用、记账与整理、智能与自动化、系统
guide/bills/：各类账单的获取与字段说明guide/faq.md：常见问题
- 开发文档（
dev/）：面向开发者，讲「怎么跑、怎么设计、怎么改」。- 整体架构、数据模型、账单解析、规则引擎、AI 集成、定时通知、动态数据源
- 项目结构、构建与部署、开发环境与规范、账单字段说明、API 文档
首页 index.md 提供两个板块的入口。
目录结构
doc-site/
├── index.md # 首页
├── guide/ # 使用文档（含 bills/）
├── dev/ # 开发文档
├── public/ # 静态资源
│ ├── logo.svg
│ └── screenshots/ # 文档配图（整页 + elements/ 关键元素）
├── .vitepress/
│ ├── config.mts # 站点配置（导航、侧边栏、搜索、端口 5175）
│ └── theme/ # 自定义主题（图片全屏查看、图片样式）
├── scripts/
│ ├── ts/ # 维护脚本（TypeScript，含截图、演示数据、OSS 上传）
│ └── samples/ # 虚构样例账单
├── refs/ # 联网检索到的资料原文（不参与构建）
├── jar-home/ # jar 一体化实例运行目录（测试库副本）
├── .env.local # 截图 OSS 上传等本地配置（不入库）
├── package.json
└── tsconfig.json
维护脚本
脚本位于 scripts/ts/，用 tsx 直接运行 TypeScript，浏览器自动化基于 playwright-core（Chromium），HTTP 基于 axios。
npm run capture # 一键重新截图（整页 + 元素 + 卡片 + 编辑/设置面板 + 解析预览，慎用）
npm run capture:pages # 仅整页截图
npm run capture:elements # 仅元素截图
npm run make:bills # 生成虚构样例账单
npm run seed # 导入样例账单（演示数据）
npm run seed:rules # 补充标签与规则
npm run refs:search # 检索资料到 refs/
npm run refs:fetch # 抓取指定 URL 到 refs/
npm run oss:upload # 上传截图到 OSS（读取 .env.local）
npm run test:browser # 验证浏览器链路
npm run typecheck:scripts # 类型检查
运行截图前请确保：
- 应用实例已启动（默认访问
jar-home/下的 jar 实例localhost:18082）； - 测试库中已配置 AI（用于截取启用 AI 后的界面）。
可通过环境变量覆盖：LEDGERLY_WEB、LEDGERLY_API、LEDGERLY_USER、LEDGERLY_PASSWORD。
环境安全：截图与演示数据只操作测试环境，禁止访问真实环境（5173 / 8080 / MySQL 真实库）。
环境要求
- Node.js（建议 20+，本项目使用 v24）
- npm 依赖走本地 verdaccio 私服（
.npmrc已配置registry=http://localhost:4873/） - 浏览器：复用 Playwright 缓存的 Chromium，无需系统安装 Chrome/Firefox
约定
维护本目录时请遵守 AGENTS.md（文档归类、截图规范、构建校验等）。