16 KiB
WorthPath
个人资产负债与净资产管理。NestJS + React/Vite + TypeScript + MySQL，支持手机和电脑。Node.js 22.12+、pnpm 11、MySQL 8+。
pnpm install
if (!(Test-Path apps/api/.env)) { Copy-Item apps/api/.env.example apps/api/.env }
# 仅在本地 .env 设置 DATABASE_URL，先检查数据库是否存在
pnpm db:generate
pnpm db:migrate
pnpm --filter @worthpath/api build
pnpm --filter @worthpath/api icons:seed # 幂等初始化或更新内置图标，保留用户上传和财务数据
pnpm dev
前端 http://localhost:5173，API http://localhost:3100/api。若命令行找不到 pnpm，本机可用项目启动器；它优先使用已安装的 pnpm，随后检查 Codex 随附版本，不修改 PATH：
cd E:\WorthPath
.\scripts\pnpm.ps1 dev
已有本地环境配置时直接启动，避免重新复制模板。创建数据库前可以在 apps/api 中执行 node scripts/db-preflight.cjs；脚本先检查同名数据库，仅在不存在时创建空数据库，不删除已有数据。迁移只使用 migrate deploy。Windows 上重新生成 Prisma 客户端前需停止 API，以释放其 DLL。
pnpm typecheck
pnpm build
pnpm test
pnpm test:integration # 需先启动 API；只创建并清理随机命名的临时测试用户
pnpm db:status
pnpm check:staged # git add 后，提交前检查本地凭证和禁止提交的文件
当前功能：注册登录、资产与负债账户、独立资产及债务、账户分组、快速记账与撤回、双边还款及转账、月份还款和当天记账标记、单项统计开关、余额历史管理、收支日历、按需执行的定时计划、隐藏资产、净资产趋势、多币种换算、贵金属按克估价、ZIP v9 备份恢复，以及 OAuth/MCP 助手接入。
金额原币保留，金额/汇率使用十进制字符串和 MySQL Decimal。归档只停止金额编辑，仍参与统计；需要归零时先更新余额。每次金额更新新增独立历史，同日按记录顺序保留；每日趋势使用当日最后余额；已有错误记录可单独更正，转账及其之前的历史需通过新增余额调整修正，避免破坏双方一致性。币种与资产负债属性创建后固定。详情同时显示原币和本位币金额。
汇率使用 Frankfurter 公共日汇率 API。请求使用固定币种表，不发送用户选择、身份或金额。进程运行时每小时检查，每天尝试一次；添加项目、修改本位币会重新触发检查。失败保留原币和历史汇率，显示缺失或实际使用日期，可以点击重试。自动更新保留已有同日历史导入汇率。首次使用不会自动补齐早期历史汇率，缺失日期不绘制完整总额；原币和已有汇率始终保留。
新版 ZIP 备份不限制记录条数，导入先预览、再明确确认。首版只追加新项目并重建关系，不覆盖已有项目；按项目 ID 和导入来源识别重复；同日汇率冲突会拒绝整次导入。已有本位币保留，空空间恢复备份本位币。文件包含财务数据，应由用户妥善保存。
设计见 数据模型与结构，已验证范围与后续工作见 首版验收。生产需要 HTTPS、COOKIE_SECURE=true、WEB_ORIGIN 为准确站点地址；前端构建由反向代理托管并代理 /api。API 生产启动：在 apps/api 中执行 node dist/main.js。生产认证限速需迁移到共享存储，数据库用户需最小权限，部署与运行监控尚未配置。
备份下载为 ZIP：manifest、settings、currencies、accounts、assets、debts、history、links、rates、icons、transfers 各一个 JSON 文件，包含隐藏项目及全部历史，不含密码或会话凭据。导入先上传并预览，再确认追加；仅接受当前 ZIP v9，所有 JSON 备份和旧 ZIP 均不支持。不限制项目、历史、关联或汇率条数；上传文件最大 512 MB，ZIP 解压总计最大 1 GB，用于保护服务器资源。
网络配置集中在 apps/api/.env，API 与 Vite 开发服务共同读取；配置模板 逐项用中文说明作用。当前本地配置支持 HTTP、所有监听网卡及有效 HTTP/HTTPS 来源；登录、权限与数据归属校验仍生效。上线需按域名收紧 Host/Origin、关闭开放开关、启用 HTTPS 与 Secure Cookie。显式配置优先于 NODE_ENV，仅改成 production 不会覆盖已设置的开放开关。修改后重启 API 和网页开发服务，详见 网络配置。
账户图标：新增或编辑账户时选择可复用图标；设置页面提供图标库及中文名称搜索。直接上传默认私有，仅当前用户能检索、读取和使用；勾选共享并明确确认公开后，所有登录用户均可搜索复用，名称必须包含中文。支持静态 PNG/JPG/WebP，单张最大 2 MB，转为最长边 256 像素的 PNG 并去除图片元数据。同一用户相同图片和可见范围会复用现有图标。账户图标通过外键关联，不复制图片。
预置银行、支付平台与交易所等共 36 个图标，资源及来源清单在 apps/api/assets/icons；银行来自公开银行标识库，支付平台来自官方网站资源及 Simple Icons。图标版权与商标归相应品牌所有，用于识别账户，不代表品牌合作或授权。运行 pnpm --filter @worthpath/api icons:seed 初始化共享库或更新固定 ID 的内置透明图标，不修改用户上传图标或财务数据。可离线使用已提交的 PNG，无需访问外部图标网站。
当前 ZIP v9 的 transfers.json 保存转账双方、金额、手续费及配对历史，恢复时重建关系；icons.json 保存图标名称、图片和内容校验值。恢复图标为私有，相同图片复用，避免自动公开；不支持旧 ZIP 或单文件 JSON。清空个人数据会删除私有图标，已发布共享图标保留供其他用户使用。
账户转账与显示设置
账户页面和账户详情提供“转账”，详情自动选择当前账户。双方余额和历史在同一数据库事务中更新；正手续费额外扣除，负手续费表示优惠（绝对值不超过本金），同币种到账金额等于转出金额，跨币种填写实际到账金额。转账不调用银行或支付平台，不执行真实资金划转。重复提交使用请求 ID 防止重复记账，并发写冲突有限重试。转账时间不能早于双方最新余额；后续余额调整不能插入已有配对操作之前。
债务分为借入（应付负债）和借出（应收资产），支持借入到账、借出付款、收回应收和偿还应付。账户与债务在同一事务中记账并自动关联；双方详情和往来记录可互相导航。已有债务可录入剩余余额，新发生借贷可先建零余额债务再使用联动操作。当前 ZIP v9 保留操作类型，不保留任何旧备份兼容。
支持简中、English、繁中，在登录页或顶部切换，语言保存在当前浏览器。用户名称和备注保留原文。账户/资产/债务按页查询当前余额，历史和往来使用最多 100 条的游标分页；趋势默认最近 90 天，支持日、周、月。查询实现、迁移步骤、实测性能和验证边界见 性能与联动验收。
设置分类使用下拉菜单；资产总览、账户、独立资产、债务、变化记录分别使用显示开关，设置入口始终保留。顶部重复导航已移除。“显示备注”关闭后隐藏列表、详情与表单备注，原有备注不删除，备份仍完整包含。图标通过弹窗检索、选择或上传，透明背景显示；接近纯白的背景像素会转为透明，彩色背景需上传透明 PNG。
“清空本账号数据”以红色显示。先下载当前完整备份并确认已保存，再输入“确定清空”，依次完成两次确认弹窗；第一次取消在左、确认在右，第二次确认在左、取消在右，两次默认聚焦取消。服务端仍校验当前登录身份、近期备份凭据及数据完整性，财务数据发生变化后须重新下载备份。
OpenAPI / Swagger
启动开发服务后可访问：
- Swagger 交互文档：http://localhost:5173/api/docs
- OpenAPI JSON：http://localhost:5173/api/openapi.json
- 后端直连文档：http://localhost:3100/api/docs
Invoke-RestMethod http://localhost:5173/api/openapi.json
接口定义由实际控制器路由和表单校验模式生成。文档本身不包含用户财务数据；除注册、登录及健康检查外，业务接口需登录会话 Cookie。建议先在同一站点登录，再通过前端代理地址使用文档；写入接口仍受来源校验和数据隔离约束。部署时将上述地址中的主机替换为自己的站点，并将 /api 代理到后端。实现使用 NestJS Swagger。
账户分组、定时计划与收支日历
账户可自定义分组，并通过弹窗选择全部或分组账户；快速记账模式点击账户直接录入当前余额。资产账户允许透支，欠债显示负数，负债/支出显示红色。
“定时计划”支持支出及转账，打开账户页时按需执行，每批最多 20 项；仅在本应用内记账。新增“收支日历”默认今天，月历与当日明细在同页上下展示，按账户余额变化估算，排除内部转账、借贷本金及初始余额。
2026-10-02 历史更新的迁移和验收见 更新说明；该文档中的 ZIP v7 为当时版本，当前仅支持 ZIP v9。
2026-10-03 设置与交互更新：支持 1 小时至 30 天登录有效期、隐藏项目密码开关、自选总览卡片、计划编辑弹窗、右上角操作提示及账户卡片快速转账。详见 更新说明。
快速记账与独立资产
独立资产支持房产、车辆、贵金属、纪念币和纪念钞。普通独立资产手动录入估值；贵金属按克数自动估价，可选填每克买入成本。独立资产页可开启“快速设置计入总资产”，点击卡片切换统计状态；独立资产总开关仍以个人设置为准。
账户页开启“快速记账”后使用紧凑卡片直接更新余额；转账按钮紧邻模式入口。右侧显示本次保存成功的余额、转账、还款及标记，支持逐项撤回；窄屏记录面板显示在账户列表下方。列表为当前页面会话，刷新或重新进入后清空，已保存账目仍在变化记录中。
欠款账户弹窗提供“还款”，通过付款账户与欠款账户双边记账更新余额。信用卡与独立债务还款支持优惠：正数减少扣款，负数表示手续费，欠款按本金减少。可手动标记“本月已还款”和“当天已记账”，并筛选未还款或隐藏当天已记账的账户。数据库保留最后完成月份/日期，跨月、跨日只按当前 UTC+8 时间判断是否显示，无需定时删除；标记不会改变金额。
账户、独立资产和债务可在详情删除。存在配对往来或定时计划时需先处理依赖，避免破坏另一账户余额。详见 快速记账更新与验收 和 项目删除说明。
净资产轨迹支持分别隐藏总资产、总负债和净资产折线；悬停或点击图表查看对应日期的金额，方向键切换日期。缺失汇率或估值时保留断线并提示不完整。详见 还款优惠与图表更新。
连接 Agent / MCP
设置中的“连接助手”提供可复制的接入提示词、能力说明及权限选择。OAuth 授权使用独立页面，草稿在弹窗中审阅并可全选批量同意；可选择 1、3、7、30 天、1 年或永久授权，并分别控制读取、修改隐藏账户。普通权限分为只读、草稿修改、直接写入，草稿需本人在网页审阅确认后才生效。
密码修改、清空数据、备份恢复、共享图标发布、汇率及贵金属报价修改在网站完成，MCP 不提供这些敏感操作。远程接入必须配置客户端可访问的 MCP_PUBLIC_URL 与 MCP_WEB_URL；localhost 仅代表客户端本机。详见 连接与授权更新。
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 gitee https://gitee.com/REMOTE_CY/worth-path.git
# 将 github 设置为当前项目的默认推送仓库
git config remote.pushDefault github
'github','gitee','wyh' | ForEach-Object { git push $_ main }
文档维护
文档维护约定：docs 目录仅保存文字文档和结构化验收数据，不保存图片。界面验收结果以文字记录，Markdown 不引用已删除的截图；应用使用的图标素材仍保存在 apps/api/assets/icons。
第三方接口与外部素材来源
运行时第三方接口
| 服务 | 实际请求地址 | 用途与更新方式 | 密钥与发送数据 | 失败处理 |
|---|---|---|---|---|
| Frankfurter | USD 固定币种日汇率 | 外币换算；同时将贵金属美元报价换算为持仓原币。每小时检查、每日尝试一次，也支持手动刷新。 | 无需密钥；仅发送固定 USD 和九种公开币种，不发送用户身份、账户、金额或持仓重量。 | 12 秒超时；保留原币、已有汇率和估值，显示错误状态。 |
| Gold API | 黄金 XAU、白银 XAG | 美元/金衡盎司参考价；以 31.1034768 克/金衡盎司换算为每克价格。已配置贵金属每日尝试更新，可在网站手动刷新。 | 无需密钥；请求固定 XAU/XAG 品种，不发送个人数据和持仓。 | 12 秒超时；格式、时间或汇率异常时保留之前的报价与估值；已有历史导入报价保留。 |
上述接口由后端访问，浏览器业务请求使用本站 /api，第三方不会收到本应用登录 Cookie。Gold API 返回的参考价只用于持仓估值，不包含饰品工费、买卖价差或回收折价。外币价格使用最新可用公共日汇率，休市时两类报价时间可能不同；报价日期会显示在界面并随备份保存。自动估价为可选项，开启后新增估值历史，不改写历史记录。
MCP 同一连接、同一账目快照下的多个新增账号草稿可依次审阅确认；其他修改仍保留状态冲突检查。修复前已失效的草稿需只为尚未新增的账号重新生成，见 多账号草稿确认修复。
独立资产支持现金分类和快速估值。登录页可记住账号并交由浏览器密码管理器保存密码。草稿弹窗支持全量分页、批量同意与取消，提交失败整批回滚。详见 现金、草稿审阅与登录更新。