chyuovo/worthpath
0
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: improve project introduction and README

Browse Source
This commit is contained in:
陈煜 committed 2026-10-07 21:00:49 +08:00
1 parent fb8cf1c938
commit f3028cd19c
1 file changed
+200 -112
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+200 -112
View File
@@ -1,156 +1,244 @@
# WorthPath # WorthPath
Docker 前后端合并容器部署见 [Docker 部署说明](docker.md)。 **把账户、资产与负债汇聚成一条清晰的净资产轨迹。**
Docker 上传图标持久化到宿主机 `/opt/worthpath/data/icons`（容器 `/app/data/icons`）；更新已部署项目需同步 Compose 挂载配置并重建镜像，具体步骤见部署说明。数据库继续保留图标内容，用于现有 ZIP 备份及文件缺失修复。 WorthPath 是一个支持自托管的个人资产、负债与净资产管理应用。它将多币种账户、信用卡、独立资产和借贷往来集中管理，提供快速记账、双边转账与还款、收支日历、贵金属估值和净资产趋势，并支持通过 OAuth / MCP 连接 AI 助手。基于 NestJS、React、TypeScript 和 MySQL 构建，适配手机与电脑，可使用 Docker 部署。
个人资产负债与净资产管理。NestJS + React/Vite + TypeScript + MySQL，支持手机和电脑。Node.js 22.12+、pnpm 11、MySQL 8+。 [快速开始](#快速开始) · [Docker 部署](docker.md) · [连接 AI 助手](#连接-ai-助手) · [文档索引](#文档索引)
## 主要功能
| 功能 | 说明 |
| --- | --- |
| 账户与分组 | 管理资产账户、信用卡和贷款，自定义分组与排序，支持透支及信用卡溢缴余额 |
| 独立资产 | 记录现金、房产、车辆、贵金属、纪念币和纪念钞；手动估值或按贵金属克数估价 |
| 借入与借出 | 管理应付负债与应收资产，记录借入到账、借出付款、收回应收及偿还应付 |
| 快速记账 | 紧凑卡片更新余额，查看本次操作并逐项撤回，筛选当天已有实际记录的账户 |
| 转账与还款 | 同币种或跨币种双边记账，支持手续费、还款优惠和月份还款标记 |
| 净资产趋势 | 查看总资产、总负债、净资产及余额历史，支持日、周、月粒度与独立折线开关 |
| 收支日历与计划 | 按日查看账户变化估算的收支，配置按需执行的支出和转账计划 |
| 多币种与估值 | 保留原币金额，按本位币汇总；公共日汇率和黄金、白银参考价支持自动更新 |
| 隐私与显示 | 隐藏项目、密码解锁、单项统计开关、自选总览卡片、备注和菜单显示设置 |
| 备份与恢复 | 完整 ZIP v9 备份，包含隐藏项目、历史、图标和配对往来；导入先预览再确认 |
| AI 助手接入 | OAuth / MCP 授权，分别提供只读、网页确认草稿和直接写入权限 |
| 多用户与界面 | 管理员创建账号、角色与封禁管理；简中、繁中、English，浅色/深色及移动端适配 |
WorthPath 记录和整理账目。转账、还款、借贷和定时计划仅更新应用内的数据，不执行真实资金划转。收支日历由账户余额变化估算，排除内部转账、借贷本金和初始余额。
## 技术栈与目录
- **前端**：React 19、Vite 7、TypeScript、Lucide 图标。
- **后端**：NestJS 11、Prisma 6、MySQL 8+、Zod。
- **金额计算**：Decimal.js 与 MySQL Decimal；API 使用十进制字符串传递金额和汇率。
- **助手接入**：MCP Streamable HTTP、OAuth、PKCE。
- **部署**：pnpm workspace；Docker 将前后端打包为一个应用容器。
```text
WorthPath/
├── apps/
│ ├── api/ # 后端、Prisma 迁移、测试和内置图标
│ └── web/ # 前端页面、国际化和界面测试
├── docs/ # 架构、配置、验收和更新文档
├── scripts/ # 开发启动器与提交检查
├── Dockerfile # 前后端合并镜像
├── compose.yaml # 应用服务、网络与图标持久化配置
├── .env.production.example # 生产环境模板
└── docker.md # Docker 部署与更新说明
```
## 快速开始
### 1. 准备环境
需要 Node.js 22.12+、pnpm 11 和可连接的 MySQL 8+。项目锁定 pnpm **11.19.0**，Docker 镜像使用 Node.js 24。
以下本地开发示例使用 PowerShell，在项目根目录执行：
```powershell ```powershell
git clone https://github.com/chyuovo/WorthPath.git
cd WorthPath
pnpm install pnpm install
if (!(Test-Path apps/api/.env)) { Copy-Item apps/api/.env.example apps/api/.env }
# 仅在本地 .env 设置 DATABASE_URL，先检查数据库是否存在 # 已有配置时保留，避免覆盖
if (!(Test-Path apps/api/.env)) {
Copy-Item apps/api/.env.example apps/api/.env
}
```
### 2. 配置数据库与管理员
编辑 `apps/api/.env`，至少设置数据库连接和初始管理员凭据：
```dotenv
DATABASE_URL="mysql://USER:PASSWORD@HOST:3306/worthpath"
ADMIN_USERNAME=admin
ADMIN_PASSWORD=REPLACE_WITH_A_STRONG_PASSWORD
```
将占位值替换为实际配置，密码中的特殊字符需要 URL 编码。完整选项见 [开发配置模板](apps/api/.env.example) 和 [网络配置说明](docs/network-settings.md)。真实环境文件不要提交到 Git。
先准备数据库。也可使用以下预检查脚本：已有数据库只检查；仅在不存在时创建空数据库，需要数据库账号具备相应权限。
```powershell
Push-Location apps/api
node scripts/db-preflight.cjs
Pop-Location
```
### 3. 迁移、初始化与启动
确认数据库地址正确；已有数据先备份。依次执行，前一步失败时先解决错误：
```powershell
pnpm db:generate pnpm db:generate
pnpm db:migrate pnpm db:migrate
pnpm --filter @worthpath/api build pnpm --filter @worthpath/api build
pnpm --filter @worthpath/api icons:seed # 幂等初始化或更新内置图标，保留用户上传和财务数据 pnpm --filter @worthpath/api icons:seed
pnpm dev pnpm dev
``` ```
前端 http://localhost:5173，API http://localhost:3100/api。若命令行找不到 pnpm，本机可用项目启动器；它优先使用已安装的 pnpm，随后检查 Codex 随附版本，不修改 PATH： `icons:seed` 幂等初始化或更新内置图标，保留用户上传图标和财务数据。迁移入口按依赖顺序执行 Prisma `migrate deploy`；不要用 `db push` 或数据库重置替代迁移。历史空库迁移失败的恢复见 [数据库迁移说明](docs/database-migrations.md)。Windows 重新生成 Prisma 客户端前需停止 API，以释放 DLL。
| 入口 | 默认地址 |
| --- | --- |
| 网页 | <http://localhost:5173> |
| API | <http://localhost:3100/api> |
| Swagger 文档（前端代理） | <http://localhost:5173/api/docs> |
| OpenAPI JSON | <http://localhost:5173/api/openapi.json> |
| 本机 MCP 服务 | <http://localhost:3100/mcp> |
首次登录必须修改初始密码，新密码至少 10 个字符、最多 72 字节。已有本地配置和已迁移数据库时，直接运行 `pnpm dev`。
Windows 找不到 pnpm 时，可使用项目启动器。它优先使用已安装的 pnpm，其次检查 Codex 随附版本，不修改 PATH：
```powershell ```powershell
cd E:\WorthPath
.\scripts\pnpm.ps1 dev .\scripts\pnpm.ps1 dev
``` ```
已有本地环境配置时直接启动，避免重新复制模板。创建数据库前可以在 `apps/api` 中执行 `node scripts/db-preflight.cjs`；脚本先检查同名数据库，仅在不存在时创建空数据库，不删除已有数据。迁移使用 `pnpm db:migrate`，由项目入口按依赖顺序执行 Prisma `migrate deploy`；空库的历史 `005_account_icons` 失败恢复见 [数据库迁移](docs/database-migrations.md)。Windows 上重新生成 Prisma 客户端前需停止 API，以释放其 DLL。 ### 4. 创建自己的账目
1. 登录并完成首次改密，设置本位币。
2. 添加账户、独立资产或债务，填写当前余额或估值。
3. 使用快速记账、转账、还款或借贷联动记录变化。
4. 在总览和日历查看净资产轨迹与每日变化，按需下载完整备份。
## Docker 部署
前后端运行在同一个容器，同一端口提供网页、`/api`、`/mcp` 和 OAuth。当前 `compose.yaml` 只管理应用，使用已有 MySQL 和外部 Docker 网络 `worthpath`，不创建数据库。
部署前准备生产环境文件、MySQL、外部网络、图标目录与 HTTPS 反向代理。完整步骤、镜像构建/传输、迁移、更新和回退说明见 [docker.md](docker.md)；生产配置参考 [.env.production.example](.env.production.example)。
- 应用端口默认绑定 `127.0.0.1:3100`，由反向代理对外提供 HTTPS；代理需覆盖全部应用路径。
- 图标持久化：宿主机 `/opt/worthpath/data/icons` → 容器 `/app/data/icons`，目录需允许容器 UID/GID 1000 读写。
- 数据库继续保存图标内容，用于自包含 ZIP 备份及文件缺失修复；服务器备份应包含 MySQL 和图标目录。
- 更新已有部署时同步 Compose 挂载配置并重建镜像，具体操作见部署文档。
- 上线需设置准确的 Host/Origin、启用 `COOKIE_SECURE=true` 并关闭开发环境开放开关。显式配置优先于 `NODE_ENV`，仅改为 `production` 不会收紧已有配置。
非 Docker 部署可构建网页静态文件，通过反向代理托管并代理 API；后端在 `apps/api` 执行 `node dist/main.js`。当前认证限流使用进程内存，多实例部署前需完善共享限流、代理信任与调度策略；运行监控需自行配置。
## 账号与隐私
公开注册已关闭，账号由管理员后台创建。初始管理员仅在数据库没有管理员时建立；未配置凭据时默认 `admin/admin`，不会覆盖已有管理员密码或提升同名普通用户权限。若同名用户冲突，需设置其他初始管理员用户名。
管理员可创建账号、设置管理员/普通用户/只读角色、封禁与解除封禁。账号数据按用户隔离，管理员角色不授予查看其他用户财务数据的能力。角色或封禁变化会撤销该用户全部登录会话和 MCP 授权；只读用户不能写入业务数据或创建修改草稿。
删除账号仅支持默认 `admin` 管理员，需另一位已完成改密的管理员操作并完成验证，且必须保留一位可用管理员。删除清理该账号私人数据及授权，共享图标保留。详情见 [管理员功能说明](docs/admin-accounts.md)。
隐藏项目可要求再次验证密码；网页解锁与 MCP 隐藏账户授权分别管理。关闭备注显示不删除备注，完整备份仍包含隐藏项目和备注。清空个人数据须先下载并保存当前完整备份，再输入“确定清空”并完成两次确认；账目变化后需重新下载备份。
## 金额、历史与备份规则
- **多币种**：保留原币，详情同时显示原币和本位币。缺少汇率或估值时明确提示不完整，趋势保留断线。
- **余额历史**：每次金额更新新增独立记录，同日按顺序保留；每日趋势使用当日最后余额。业务日期与时间采用 UTC+8。
- **统计范围**：支持单项计入开关；归档仅停止金额编辑，仍参与统计。币种及资产/负债属性创建后固定。
- **配对往来**：转账与借贷双方余额及历史在同一数据库事务中更新，重复提交使用请求 ID 防止重复记账。配对记录按整笔操作编辑或撤销；历史调整规则见更新与验收文档。
- **定时计划**：打开账户页时按需执行，每批最多 20 项；不代表后台持续运行的支付任务。
- **备份范围**：当前仅支持完整 **ZIP v9**，包含全部项目、隐藏项目、历史、关系、汇率、图标和转账，不包含密码或会话凭据。旧 ZIP 和单文件 JSON 均不支持。
- **恢复方式**：先上传预览，再确认追加新项目并重建关系，不覆盖已有项目；按项目 ID 与导入来源识别重复，同日汇率冲突拒绝整次导入。已有空间保留本位币，空空间恢复备份本位币。
- **文件限制**：不限制项目及记录条数；上传最大 512 MB，ZIP 解压总计最大 1 GB。恢复图标默认私有，相同图片复用。
## 连接 AI 助手
在设置中的“连接助手”复制实际 MCP 地址与接入提示词，在客户端配置服务并完成网页授权。远程接入需设置客户端可访问的 `MCP_PUBLIC_URL` 和 `MCP_WEB_URL`；`localhost` 仅代表客户端本机。
| 权限 | 普通修改行为 |
| --- | --- |
| 只读 | 查询账户、余额、资产、负债、历史等数据 |
| 草稿修改 | 创建修改草稿，由本人在网页审阅确认后生效 |
| 直接写入 | 在授权范围内直接执行普通业务写入 |
隐藏账户的读取与修改单独授权，可选择授权期限，在“我的连接”调整权限或撤销连接。连接后先发现实际工具，并核对一次 `connection_info` 返回的当前资源和权限；重连、权限变更或授权错误后重新核对。申请权限和旧聊天记录不代表当前授权。
写入前使用 `state_get` 获取状态，随操作提交 `expectedState` 和唯一 `idempotencyKey`；同一次网络重试复用完全相同的参数和键。返回 `pending` 时由用户通过 `confirmationUrl` 审阅，再查询 `operation_get`，不能将待确认草稿视为已完成。
密码修改、清空数据、备份导出/恢复、共享图标发布、汇率及贵金属报价编辑保留在网站完成，MCP 不提供这些操作。接入流程、协议和验证边界见 [MCP 文档](docs/mcp.md) 与 [功能覆盖矩阵](docs/mcp-coverage.md)。
## API 文档与开发检查
启动后可访问 `/api/docs` 与 `/api/openapi.json`，后端直连地址为 <http://localhost:3100/api/docs>。接口定义由实际控制器路由与校验模式生成；业务接口需登录会话 Cookie，建议先登录网页，再通过同站前端代理访问交互文档。写入仍受来源校验与数据隔离约束。
```powershell ```powershell
pnpm typecheck pnpm typecheck
pnpm build pnpm build
pnpm test pnpm test
pnpm test:integration # 需先启动 API；只创建并清理随机命名的临时测试用户
pnpm --filter @worthpath/api test:isolated # 临时 MySQL 库与独立 API，包含管理员及 MCP 测试；需创建/删除测试库权限
pnpm db:status pnpm db:status
pnpm check:staged # git add 后，提交前检查本地凭证和禁止提交的文件
# 需先启动 API；创建并清理随机命名的临时测试用户
pnpm test:integration
# 临时 MySQL 数据库与独立 API，包含管理员和 MCP 测试
# 需要创建、删除测试数据库的权限
pnpm --filter @worthpath/api test:isolated
# git add 后、提交前检查本地凭证及禁止提交的文件
pnpm check:staged
``` ```
当前功能：登录、首次改密与管理员账号管理、资产与负债账户、独立资产及债务、账户分组、快速记账与撤回、双边还款及转账、月份还款标记和当天实际记录筛选、单项统计开关、余额历史管理、收支日历、按需执行的定时计划、隐藏资产、净资产趋势、多币种换算、贵金属按克估价、ZIP v9 备份恢复，以及 OAuth/MCP 助手接入。 具体测试环境、已验证范围及性能数据以对应验收文档为准。
公开注册已关闭，账号由管理员后台创建。`apps/api/.env` 可配置 `ADMIN_USERNAME` 和 `ADMIN_PASSWORD`，未配置时均为 `admin`。仅在数据库没有管理员时创建初始管理员；不会提升同名已有用户，也不会在重启时覆盖管理员密码。同名已有用户冲突时请配置其他管理员用户名。首次登录必须修改初始密码，新密码至少 10 个字符、最多 72 字节。 ## 第三方接口与图标
管理员登录并改密后，侧栏显示“管理员后台”，可添加账号、设置管理员/普通用户/只读用户权限、封禁和解除封禁。新建账号也需要首次改密。现有账号保留普通用户权限；管理员账号管理不会授予查看其他用户财务数据的能力。权限或封禁状态变化会撤销该用户全部登录会话和 MCP 授权；只读账号的业务写入、MCP 写入和草稿均由服务端拒绝，仍可改自己的登录密码、授权只读连接。详细验证见 [管理员功能验证](docs/admin-accounts.md)。 | 来源 | 用途 | 请求与失败处理 |
| --- | --- | --- |
| [Frankfurter](https://frankfurter.dev/) | 公共日汇率，外币及贵金属美元报价换算 | 固定 USD 与 CNY/HKD/EUR/GBP/JPY/AUD/CAD/CHF/SGD 币种；每小时检查、每天尝试一次，失败保留原币与历史汇率 |
| [Gold API](https://gold-api.com/docs) | 黄金 XAU、白银 XAG 的美元/金衡盎司参考价 | 固定品种请求；按 31.1034768 克/金衡盎司换算，格式、时间或汇率异常时保留已有报价及估值 |
仅允许删除默认 `admin`（账号名为 admin 且角色为管理员），其他管理员、普通用户和只读用户均禁止删除。先设置并登录另一位已完成改密的管理员，再输入 admin、验证当前管理员密码并确认。不能删除当前登录账号，且必须保留一位未封禁、已完成改密的管理员。删除会清理被删除账号的全部私人数据和授权，请先由该用户保存需要的备份；共享图标保留。仍有其他管理员时，重启不会重新创建默认账号。 第三方行情请求由后端发起，无需密钥，不发送用户身份、账户、金额、持仓重量或登录 Cookie。网站支持手动刷新；已有同日历史导入汇率与报价保留。首次使用不自动补齐早期历史汇率。贵金属自动估价为可选项，开启后新增估值历史，不改写历史；参考价不包含工费、买卖价差或回收折价，报价日期随界面与备份保存。
金额原币保留，金额/汇率使用十进制字符串和 MySQL Decimal。归档只停止金额编辑，仍参与统计；需要归零时先更新余额。每次金额更新新增独立历史，同日按记录顺序保留；每日趋势使用当日最后余额；已有错误记录可单独更正，转账及其之前的历史需通过新增余额调整修正，避免破坏双方一致性。币种与资产负债属性创建后固定。详情同时显示原币和本位币金额。 图标库预置银行、支付平台及交易所等 36 个图标，PNG 与来源清单位于 `apps/api/assets/icons`。图标版权和商标归相应品牌，用于识别账户，不代表品牌合作或授权。
汇率使用 [Frankfurter 公共日汇率 API](https://frankfurter.dev/)。请求使用固定币种表，不发送用户选择、身份或金额。进程运行时每小时检查，每天尝试一次；添加项目、修改本位币会重新触发检查。失败保留原币和历史汇率，显示缺失或实际使用日期，可以点击重试。自动更新保留已有同日历史导入汇率。首次使用不会自动补齐早期历史汇率，缺失日期不绘制完整总额；原币和已有汇率始终保留。 用户上传默认私有；共享发布须明确确认且名称包含中文。支持静态 PNG/JPG/WebP，单张最大 2 MB，转换为最长边 256 像素的 PNG 并去除元数据。内置图标通过 `icons:seed` 更新，后续维护直接修改 PNG 和 `sources.json`。
新版 ZIP 备份不限制记录条数，导入先预览、再明确确认。首版只追加新项目并重建关系，不覆盖已有项目；按项目 ID 和导入来源识别重复；同日汇率冲突会拒绝整次导入。已有本位币保留，空空间恢复备份本位币。文件包含财务数据，应由用户妥善保存。 ## 文档索引
设计见 [数据模型与结构](docs/architecture.md)，已验证范围与后续工作见 [首版验收](docs/acceptance.md)。生产需要 HTTPS、COOKIE_SECURE=true、WEB_ORIGIN 为准确站点地址；前端构建由反向代理托管并代理 /api。API 生产启动：在 `apps/api` 中执行 `node dist/main.js`。生产认证限速需迁移到共享存储，数据库用户需最小权限，部署与运行监控尚未配置。 | 文档 | 内容 |
| --- | --- |
| [Docker 部署](docker.md) | 镜像构建、环境配置、HTTPS、图标持久化、更新与回退 |
| [网络配置](docs/network-settings.md) | Host、Origin、HTTP/HTTPS、Cookie 与开发配置 |
| [数据库迁移](docs/database-migrations.md) | 迁移顺序、状态检查及历史失败恢复 |
| [架构与数据模型](docs/architecture.md) | 领域模型、金额计算、历史及权限；含历史版本说明 |
| [管理员账号](docs/admin-accounts.md) | 角色、封禁、默认管理员删除与验证 |
| [MCP 接入](docs/mcp.md) / [覆盖矩阵](docs/mcp-coverage.md) | 连接、授权、工具能力与验证范围 |
| [首版验收](docs/acceptance.md) / [性能与联动](docs/performance.md) | 历史验收记录、性能数据与验证边界 |
| [快速记账](docs/update-quick-entry-2026-10-04.md) / [项目删除](docs/update-position-deletion-2026-10-04.md) | 快速操作、撤回、还款与删除依赖 |
| [还款优惠与图表](docs/update-repayment-trend-2026-10-04.md) | 优惠、手续费与净资产趋势交互 |
| [连接权限与还款](docs/update-connections-repayment-users-2026-10-05.md) / [OAuth 权限缓存](docs/update-oauth-permissions-2026-10-05.md) | 当前授权与权限调整流程 |
| [现金、草稿审阅与登录](docs/update-cash-drafts-login-2026-10-05.md) / [草稿确认修复](docs/fix-mcp-create-drafts-2026-10-04.md) | 现金分类、批量草稿与登录偏好 |
| [移动端导航与当天筛选](docs/update-mobile-navigation-2026-10-07.md) | 当前导航、实际记账筛选、滚动条与无障碍适配 |
备份下载为 ZIP：manifest、settings、currencies、accounts、assets、debts、history、links、rates、icons、transfers 各一个 JSON 文件，包含隐藏项目及全部历史，不含密码或会话凭据。导入先上传并预览，再确认追加；仅接受当前 ZIP v9，所有 JSON 备份和旧 ZIP 均不支持。不限制项目、历史、关联或汇率条数；上传文件最大 512 MB，ZIP 解压总计最大 1 GB，用于保护服务器资源。 `docs` 中的更新与验收文档保留对应时间的实现记录，旧备份版本和旧界面说明属于历史信息；当前仅支持 ZIP v9。文档目录保存文字与结构化验收数据，不保存界面截图；应用图标保存在资源目录。
网络配置集中在 `apps/api/.env`，API 与 Vite 开发服务共同读取；[配置模板](apps/api/.env.example) 逐项用中文说明作用。当前本地配置支持 HTTP、所有监听网卡及有效 HTTP/HTTPS 来源；登录、权限与数据归属校验仍生效。上线需按域名收紧 Host/Origin、关闭开放开关、启用 HTTPS 与 Secure Cookie。显式配置优先于 NODE_ENV，仅改成 production 不会覆盖已设置的开放开关。修改后重启 API 和网页开发服务，详见 [网络配置](docs/network-settings.md)。 ## 仓库维护
账户图标：新增或编辑账户时选择可复用图标；设置页面提供图标库及中文名称搜索。直接上传默认私有，仅当前用户能检索、读取和使用；勾选共享并明确确认公开后，所有登录用户均可搜索复用，名称必须包含中文。支持静态 PNG/JPG/WebP，单张最大 2 MB，转为最长边 256 像素的 PNG 并去除图片元数据。同一用户相同图片和可见范围会复用现有图标。账户图标通过外键关联，不复制图片。 维护者可按需添加远程仓库，并将 GitHub 设为默认推送目标：
预置银行、支付平台与交易所等共 36 个图标，资源及来源清单在 `apps/api/assets/icons`；银行来自公开银行标识库，支付平台来自官方网站资源及 Simple Icons。图标版权与商标归相应品牌所有，用于识别账户，不代表品牌合作或授权。运行 `pnpm --filter @worthpath/api icons:seed` 初始化共享库或更新固定 ID 的内置透明图标，不修改用户上传图标或财务数据。可离线使用已提交的 PNG，无需访问外部图标网站。
图库的首次下载、固定品牌扩充和 ICO 转换脚本已移除。后续维护直接更新 PNG 与 `sources.json` 来源清单，再通过 `icons:seed` 更新内置图库。开发、迁移、诊断、隔离测试、性能基准和回归测试入口继续保留；一次性工具使用完后及时清理。
当前 ZIP v9 的 transfers.json 保存转账双方、金额、手续费及配对历史，恢复时重建关系；icons.json 保存图标名称、图片和内容校验值。恢复图标为私有，相同图片复用，避免自动公开；不支持旧 ZIP 或单文件 JSON。清空个人数据会删除私有图标，已发布共享图标保留供其他用户使用。
## 账户转账与显示设置
账户页面和账户详情提供“转账”，详情自动选择当前账户。双方余额和历史在同一数据库事务中更新；正手续费额外扣除，负手续费表示优惠（绝对值不超过本金），同币种到账金额等于转出金额，跨币种填写实际到账金额。转账不调用银行或支付平台，不执行真实资金划转。重复提交使用请求 ID 防止重复记账，并发写冲突有限重试。转账时间不能早于双方最新余额；后续余额调整不能插入已有配对操作之前。
债务分为借入（应付负债）和借出（应收资产），支持借入到账、借出付款、收回应收和偿还应付。账户与债务在同一事务中记账并自动关联；双方详情和往来记录可互相导航。已有债务可录入剩余余额，新发生借贷可先建零余额债务再使用联动操作。当前 ZIP v9 保留操作类型，不保留任何旧备份兼容。
支持简中、English、繁中，在登录页或顶部切换，语言保存在当前浏览器。用户名称和备注保留原文。账户/资产/债务按页查询当前余额，历史和往来使用最多 100 条的游标分页；趋势默认最近 90 天，支持日、周、月。查询实现、迁移步骤、实测性能和验证边界见 [性能与联动验收](docs/performance.md)。
主导航为总览、日历、账号、设置四项；变化记录位于总览，账户、独立资产、债务位于账号，定时计划和管理员后台位于设置（仅管理员可见后台）。设置分类使用下拉菜单；子页面分别使用显示开关，设置入口始终保留。手机底栏适配安全区，操作按钮提供眼睛图标、当前页状态和触屏点击反馈。“显示备注”关闭后隐藏列表、详情与表单备注，原有备注不删除，备份仍完整包含。图标通过弹窗检索、选择或上传，透明背景显示；接近纯白的背景像素会转为透明，彩色背景需上传透明 PNG。
“清空本账号数据”以红色显示。先下载当前完整备份并确认已保存，再输入“确定清空”，依次完成两次确认弹窗；第一次取消在左、确认在右，第二次确认在左、取消在右，两次默认聚焦取消。服务端仍校验当前登录身份、近期备份凭据及数据完整性，财务数据发生变化后须重新下载备份。
## OpenAPI / Swagger
启动开发服务后可访问：
- Swagger 交互文档：[http://localhost:5173/api/docs](http://localhost:5173/api/docs)
- OpenAPI JSON：[http://localhost:5173/api/openapi.json](http://localhost:5173/api/openapi.json)
- 后端直连文档：[http://localhost:3100/api/docs](http://localhost:3100/api/docs)
```powershell ```powershell
Invoke-RestMethod http://localhost:5173/api/openapi.json
```
接口定义由实际控制器路由和表单校验模式生成。文档本身不包含用户财务数据；除登录及健康检查外，业务接口需登录会话 Cookie。建议先在同一站点登录，再通过前端代理地址使用文档；写入接口仍受来源校验和数据隔离约束。部署时将上述地址中的主机替换为自己的站点，并将 `/api` 代理到后端。实现使用 [NestJS Swagger](https://docs.nestjs.com/openapi/introduction)。
## 账户分组、定时计划与收支日历
账户可自定义分组，并通过弹窗选择全部或分组账户；快速记账模式点击账户直接录入当前余额。资产账户允许透支；余额（含信用卡溢缴存款）显示绿色，欠款和透支显示负数、红色；变化记录与账户选择器使用相同颜色。
“定时计划”支持支出及转账，打开账户页时按需执行，每批最多 20 项；仅在本应用内记账。新增“收支日历”默认今天，月历与当日明细在同页上下展示，按账户余额变化估算，排除内部转账、借贷本金及初始余额。
2026-10-02 历史更新的迁移和验收见 [更新说明](docs/update-2026-10-02.md)；该文档中的 ZIP v7 为当时版本，当前仅支持 ZIP v9。
2026-10-03 设置与交互更新：支持 1 小时至 30 天登录有效期、隐藏项目密码开关、自选总览卡片、计划编辑弹窗、右上角操作提示及账户卡片快速转账。详见 [更新说明](docs/update-settings-interaction-2026-10-03.md)。
## 快速记账与独立资产
独立资产支持房产、车辆、贵金属、纪念币和纪念钞。普通独立资产手动录入估值；贵金属按克数自动估价，可选填每克买入成本。独立资产页可开启“快速设置计入总资产”，点击卡片切换统计状态；独立资产总开关仍以个人设置为准。
账户页开启“快速记账”后使用紧凑卡片直接更新余额；转账按钮紧邻模式入口。右侧显示本次保存成功的余额、转账、还款及标记，支持逐项撤回；窄屏记录面板显示在账户列表下方。列表为当前页面会话，刷新或重新进入后清空，已保存账目仍在变化记录中。
欠款账户弹窗提供“还款”，通过付款账户与欠款账户双边记账更新余额。信用卡与独立债务还款支持优惠：正数减少扣款，负数表示手续费，欠款按本金减少。可手动标记“本月已还款”并筛选未还款账户。当天状态自动依据 UTC+8 账目日期的实际余额记录显示，可隐藏或显示当天有记录的账户；不再提供当天手动标记。撤回、删除或修改记录后同步重新计算；跨天刷新不执行定时计划。
账户、独立资产和债务可在详情删除。存在配对往来或定时计划时需先处理依赖，避免破坏另一账户余额。详见 [快速记账更新与验收](docs/update-quick-entry-2026-10-04.md) 和 [项目删除说明](docs/update-position-deletion-2026-10-04.md)。
净资产轨迹支持分别隐藏总资产、总负债和净资产折线；悬停或点击图表查看对应日期的金额，方向键切换日期。缺失汇率或估值时保留断线并提示不完整。详见 [还款优惠与图表更新](docs/update-repayment-trend-2026-10-04.md)。
## 连接 Agent / MCP
设置中的“连接助手”提供可复制的接入提示词、能力说明及权限选择。OAuth 授权使用独立页面，草稿在弹窗中审阅并可全选批量同意；可选择 1、3、7、30 天、1 年或永久授权，并分别控制读取、修改隐藏账户。普通权限分为只读、草稿修改、直接写入，草稿需本人在网页审阅确认后才生效。
密码修改、清空数据、备份恢复、共享图标发布、汇率及贵金属报价修改在网站完成，MCP 不提供这些敏感操作。远程接入必须配置客户端可访问的 MCP_PUBLIC_URL 与 MCP_WEB_URL；localhost 仅代表客户端本机。详见 [连接与授权更新](docs/update-agent-accounts-2026-10-04.md)。
## git仓库目录
```shell
git remote add github https://github.com/chyuovo/WorthPath.git git remote add github https://github.com/chyuovo/WorthPath.git
git remote add wyh https://git.mashiroart.xyz/chyuovo/WorthPath.git git remote add wyh https://git.mashiroart.xyz/chyuovo/WorthPath.git
git remote add gitee https://gitee.com/REMOTE_CY/worth-path.git git remote add gitee https://gitee.com/REMOTE_CY/worth-path.git
# 将 github 设置为当前项目的默认推送仓库 git remote add cy https://git.chyuovo.top/chyuovo/WorthPath.git
git config remote.pushDefault github git config remote.pushDefault github
'github','gitee','wyh' | ForEach-Object { git push $_ main } # 需要同步多个远程时手动执行
'github','gitee','wyh','cy' | ForEach-Object { git push $_ main }
``` ```
## 文档维护
文档维护约定：`docs` 目录仅保存文字文档和结构化验收数据，不保存图片。界面验收结果以文字记录，Markdown 不引用已删除的截图；应用使用的图标素材仍保存在 `apps/api/assets/icons`。
## 第三方接口与外部素材来源
### 运行时第三方接口
| 服务 | 实际请求地址 | 用途与更新方式 | 密钥与发送数据 | 失败处理 |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| [Frankfurter](https://frankfurter.dev/) | [USD 固定币种日汇率](https://api.frankfurter.dev/v2/rates?base=USD&quotes=CNY,HKD,EUR,GBP,JPY,AUD,CAD,CHF,SGD) | 外币换算；同时将贵金属美元报价换算为持仓原币。每小时检查、每日尝试一次，也支持手动刷新。 | 无需密钥；仅发送固定 USD 和九种公开币种，不发送用户身份、账户、金额或持仓重量。 | 12 秒超时；保留原币、已有汇率和估值，显示错误状态。 |
| [Gold API](https://gold-api.com/docs) | [黄金 XAU](https://api.gold-api.com/price/XAU)、[白银 XAG](https://api.gold-api.com/price/XAG) | 美元/金衡盎司参考价；以 31.1034768 克/金衡盎司换算为每克价格。已配置贵金属每日尝试更新，可在网站手动刷新。 | 无需密钥；请求固定 XAU/XAG 品种，不发送个人数据和持仓。 | 12 秒超时；格式、时间或汇率异常时保留之前的报价与估值；已有历史导入报价保留。 |
上述接口由后端访问，浏览器业务请求使用本站 `/api`，第三方不会收到本应用登录 Cookie。Gold API 返回的参考价只用于持仓估值，不包含饰品工费、买卖价差或回收折价。外币价格使用最新可用公共日汇率，休市时两类报价时间可能不同；报价日期会显示在界面并随备份保存。自动估价为可选项，开启后新增估值历史，不改写历史记录。
MCP 同一连接、同一账目快照下的多个新增账号草稿可依次审阅确认；其他修改仍保留状态冲突检查。修复前已失效的草稿需只为尚未新增的账号重新生成，见 [多账号草稿确认修复](docs/fix-mcp-create-drafts-2026-10-04.md)。
独立资产支持现金分类和快速估值。登录页可记住账号并交由浏览器密码管理器保存密码。草稿弹窗支持全量分页、批量同意与取消，提交失败整批回滚。详见 [现金、草稿审阅与登录更新](docs/update-cash-drafts-login-2026-10-05.md)。
已授权的 OAuth 与个人令牌可在“我的连接”修改只读、草稿或直接写入权限和隐藏账户权限，验证当前密码后生效；不延长授权期限，实际变更会取消该连接未确认草稿。MCP `movement_create(operation=repay)` 支持信用卡等负债账户，并保留真正还款类型及优惠、编辑和撤销语义。详见 [连接权限、还款与账号删除更新](docs/update-connections-repayment-users-2026-10-05.md)。
OAuth 授权页始终提供只读、草稿和直接写入三档，普通用户可明确选择最终权限。Agent 教程和 Codex 配置提示词要求连接时核对一次当前权限并缓存，发生重连、权限变更通知、授权错误或缓存不足时才再次检查。详见 [OAuth 三档选择与权限缓存](docs/update-oauth-permissions-2026-10-05.md)。
移动端导航、实际记账筛选和滚动条已按原作者 Skills for Design Engineers 的 apple-design 及适用规范更新。界面采用 Apple 风格，支持浅色/深色、减少动画/透明度与高对比度，详见 [更新与验收说明](docs/update-mobile-navigation-2026-10-07.md)。