99 lines
3.8 KiB
Markdown
99 lines
3.8 KiB
Markdown
# 收支管理系统 · 文档站
|
||
|
||
本目录是「收支管理系统」（同级目录 `../finance-app`）的**使用文档**与**开发文档**站点，基于 [VitePress](https://vitepress.dev/) 构建，并附带一套 Node/TypeScript 维护脚本（截图、演示数据、资料抓取）。
|
||
|
||
> **在线体验**：[https://finance.rosercode.cn/](https://finance.rosercode.cn/)（演示账号 `demo` / `demo123456`，使用独立的 SQLite 演示库与虚构数据）
|
||
|
||
## 快速开始
|
||
|
||
```sh
|
||
# 安装依赖（走本地 verdaccio 私服，见 .npmrc）
|
||
npm install
|
||
|
||
# 本地开发（默认 http://localhost:5175）
|
||
npm run docs:dev
|
||
|
||
# 构建静态站点到 .vitepress/dist
|
||
npm run docs:build
|
||
|
||
# 预览构建产物
|
||
npm run docs:preview
|
||
```
|
||
|
||
对外访问（局域网/远程）：
|
||
|
||
```sh
|
||
./node_modules/.bin/vitepress dev --host 0.0.0.0
|
||
```
|
||
|
||
## 文档结构
|
||
|
||
站点分为两大板块：
|
||
|
||
- **使用文档**（`guide/`）：面向使用者，讲「怎么用」。
|
||
- 开始使用、记账与整理、智能与自动化、系统
|
||
- `guide/bills/`：各类账单的获取与字段说明
|
||
- `guide/faq.md`：常见问题
|
||
- **开发文档**（`dev/`）：面向开发者，讲「怎么跑、怎么设计、怎么改」。
|
||
- 整体架构、数据模型、账单解析、规则引擎、AI 集成、定时通知、动态数据源
|
||
- 项目结构、构建与部署、开发环境与规范、账单字段说明、API 文档
|
||
|
||
首页 `index.md` 提供两个板块的入口。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
doc-site/
|
||
├── index.md # 首页
|
||
├── guide/ # 使用文档（含 bills/）
|
||
├── dev/ # 开发文档
|
||
├── public/ # 静态资源
|
||
│ ├── logo.svg
|
||
│ └── screenshots/ # 文档配图（整页 + elements/ 关键元素）
|
||
├── .vitepress/
|
||
│ ├── config.mts # 站点配置（导航、侧边栏、搜索、端口 5175）
|
||
│ └── theme/ # 自定义主题（图片全屏查看、图片样式）
|
||
├── scripts/
|
||
│ ├── ts/ # 维护脚本（TypeScript）
|
||
│ └── samples/ # 样例账单
|
||
├── refs/ # 联网检索到的资料原文（不参与构建）
|
||
├── jar-home/ # jar 一体化实例运行目录（测试库副本）
|
||
├── package.json
|
||
└── tsconfig.json
|
||
```
|
||
|
||
## 维护脚本
|
||
|
||
脚本位于 `scripts/ts/`，用 `tsx` 直接运行 TypeScript，浏览器自动化基于 `playwright-core`（Chromium），HTTP 基于 `axios`。
|
||
|
||
```sh
|
||
npm run capture # 一键重新截图（整页 + 元素 + 卡片 + 编辑/设置面板 + 解析预览）
|
||
npm run capture:pages # 仅整页截图
|
||
npm run capture:elements # 仅元素截图
|
||
npm run seed # 导入样例账单（演示数据）
|
||
npm run seed:rules # 补充标签与规则
|
||
npm run refs:search # 检索资料到 refs/
|
||
npm run refs:fetch # 抓取指定 URL 到 refs/
|
||
npm run test:browser # 验证浏览器链路
|
||
npm run typecheck:scripts # 类型检查
|
||
```
|
||
|
||
运行截图前请确保：
|
||
|
||
1. 应用实例已启动（默认访问 `jar-home/` 下的 jar 实例 `localhost:18082`）；
|
||
2. 测试库中已配置 AI（用于截取启用 AI 后的界面）。
|
||
|
||
可通过环境变量覆盖：`FINANCE_WEB`、`FINANCE_API`、`FINANCE_USER`、`FINANCE_PASSWORD`。
|
||
|
||
> **环境安全**：截图与演示数据只操作测试环境，禁止访问真实环境（5173 / 8080 / MySQL 真实库）。
|
||
|
||
## 环境要求
|
||
|
||
- **Node.js**（建议 20+，本项目使用 v24）
|
||
- npm 依赖走本地 verdaccio 私服（`.npmrc` 已配置 `registry=http://localhost:4873/`）
|
||
- 浏览器：复用 Playwright 缓存的 Chromium，无需系统安装 Chrome/Firefox
|
||
|
||
## 约定
|
||
|
||
维护本目录时请遵守 [AGENTS.md](./AGENTS.md)（文档归类、截图规范、构建校验等）。
|