# WorthPath 个人资产负债与净资产管理。NestJS + React/Vite + TypeScript + MySQL，支持手机和电脑。Node.js 22.12+、pnpm 11、MySQL 8+。 ```powershell 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： ```powershell cd E:\WorthPath .\scripts\pnpm.ps1 dev ``` 已有本地环境配置时直接启动，避免重新复制模板。创建数据库前可以在 `apps/api` 中执行 `node scripts/db-preflight.cjs`；脚本先检查同名数据库，仅在不存在时创建空数据库，不删除已有数据。迁移只使用 `migrate deploy`。Windows 上重新生成 Prisma 客户端前需停止 API，以释放其 DLL。 ```powershell pnpm typecheck pnpm build pnpm test pnpm test:integration # 需先启动 API；只创建并清理随机命名的临时测试用户 pnpm db:status pnpm check:staged # git add 后，提交前检查本地凭证和禁止提交的文件 ``` 当前功能：注册登录和退出、资产/负债账户、独立资产、独立债务和关联、分钟余额历史与更正、隐藏项目密码核验、本位币和自动日汇率、净资产趋势和变化归因、分文件 ZIP 备份与事务追加恢复、各菜单项显示开关、统一备注显示开关及无操作退出设置、安全清空本账号数据。 金额原币保留，金额/汇率使用十进制字符串和 MySQL Decimal。归档只停止金额编辑，仍参与统计；需要归零时先更新余额。每次金额更新新增独立历史，同日按记录顺序保留；每日趋势使用当日最后余额；已有错误记录可单独更正，转账及其之前的历史需通过新增余额调整修正，避免破坏双方一致性。币种与资产负债属性创建后固定。详情同时显示原币和本位币金额。 汇率使用 [Frankfurter 公共日汇率 API](https://frankfurter.dev/)。请求使用固定币种表，不发送用户选择、身份或金额。进程运行时每小时检查，每天尝试一次；添加项目、修改本位币会重新触发检查。失败保留原币和历史汇率，显示缺失或实际使用日期，可以点击重试。自动更新保留已有同日历史导入汇率。首次使用不会自动补齐早期历史汇率，缺失日期不绘制完整总额；原币和已有汇率始终保留。 新版 ZIP 备份不限制记录条数，导入先预览、再明确确认。首版只追加新项目并重建关系，不覆盖已有项目；按项目 ID 和导入来源识别重复；同日汇率冲突会拒绝整次导入。已有本位币保留，空空间恢复备份本位币。文件包含财务数据，应由用户妥善保存。 设计见 [数据模型与结构](docs/architecture.md)，已验证范围与后续工作见 [首版验收](docs/acceptance.md)。生产需要 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 文件，包含隐藏项目及全部历史，不含密码或会话凭据。导入先上传并预览，再确认追加；旧 JSON 备份继续兼容。不限制项目、历史、关联或汇率条数；上传文件最大 512 MB，ZIP 解压总计最大 1 GB，用于保护服务器资源。 内网穿透临时测试：本地 `apps/api/.env` 可设置 `WEB_ORIGIN=*` 并重启 API，允许来自任意 HTTP/HTTPS 站点的浏览器写入请求，仍需登录身份并校验数据归属。缺失或无效 Origin 仍拒绝；`NODE_ENV=production` 禁止此通配符。测试结束后恢复准确的站点地址。 账户图标：新增或编辑账户时选择可复用图标；设置页面提供图标库及中文名称搜索。直接上传默认私有，仅当前用户能检索、读取和使用；勾选共享并明确确认公开后，所有登录用户均可搜索复用，名称必须包含中文。支持静态 PNG/JPG/WebP，单张最大 2 MB，转为最长边 256 像素的 PNG 并去除图片元数据。同一用户相同图片和可见范围会复用现有图标。账户图标通过外键关联，不复制图片。 预置银行、支付平台与交易所等共 36 个图标，资源及来源清单在 `apps/api/assets/icons`；银行来自公开银行标识库，支付平台来自官方网站资源及 Simple Icons。图标版权与商标归相应品牌所有，用于识别账户，不代表品牌合作或授权。运行 `pnpm --filter @worthpath/api icons:seed` 初始化共享库或更新固定 ID 的内置透明图标，不修改用户上传图标或财务数据。可离线使用已提交的 PNG，无需访问外部图标网站。 ZIP 格式 v5 增加 transfers.json（转账双方、金额、手续费及配对历史），包含完整转账恢复关系。icons.json（图标名称、图片、内容校验值），包含自己的全部图标及账户引用的共享图标。导入会重建关联并将图标恢复为私有，相同图片复用，避免自动公开；旧 v3/v4 ZIP 和旧 JSON 仍可导入。清空个人数据会删除私有图标，已发布共享图标保留供其他用户使用。 ## 账户转账与显示设置 账户页面和账户详情提供“账户间转账”，详情自动选择当前账户。双方余额和历史在同一数据库事务中更新；正手续费额外扣除，负手续费表示优惠（绝对值不超过本金），同币种到账金额等于转出金额，跨币种填写实际到账金额。转账不调用银行或支付平台，不执行真实资金划转。重复提交使用请求 ID 防止重复记账，并发写冲突有限重试。转账时间不能早于双方最新余额；后续余额调整不能插入已有配对操作之前。 债务分为借入（应付负债）和借出（应收资产），支持借入到账、借出付款、收回应收和偿还应付。账户与债务在同一事务中记账并自动关联；双方详情和往来记录可互相导航。已有债务可录入剩余余额，新发生借贷可先建零余额债务再使用联动操作。ZIP v6 保留操作类型，兼容旧 v3/v4/v5 ZIP 和 v1/v2 JSON。 支持简中、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 Invoke-RestMethod http://localhost:5173/api/openapi.json ``` 接口定义由实际控制器路由和表单校验模式生成。文档本身不包含用户财务数据；除注册、登录及健康检查外，业务接口需登录会话 Cookie。建议先在同一站点登录，再通过前端代理地址使用文档；写入接口仍受来源校验和数据隔离约束。部署时将上述地址中的主机替换为自己的站点，并将 `/api` 代理到后端。实现使用 [NestJS Swagger](https://docs.nestjs.com/openapi/introduction)。 ## 账户分组、定时计划与收支日历 账户可自定义分组，并通过弹窗选择全部或分组账户；快速记账模式点击账户直接录入当前余额。资产账户允许透支，欠债显示负数，负债/支出显示红色。 “定时计划”支持支出及转账，打开账户页时按需执行，每批最多 20 项；仅在本应用内记账。新增“收支日历”默认今天，月历与当日明细在同页上下展示，按账户余额变化估算，排除内部转账、借贷本金及初始余额。 本次需要新增数据库迁移并运行图库初始化，备份导出升级至 ZIP v7。操作步骤、31 个内置图标与验证边界见 [更新说明](docs/update-2026-10-02.md)。 2026-10-03 设置与交互更新：支持 1 小时至 30 天登录有效期、隐藏项目密码开关、自选总览卡片、计划编辑弹窗、右上角操作提示及账户卡片快速转账。详见 [更新说明](docs/update-settings-interaction-2026-10-03.md)。 ## git仓库目录 ```shell git remote add github https://github.com/chyuovo/WorthPath.git git remote add wyh https://git.mashiroart.xyz/chyuovo/WorthPath.git # 将 github 设置为当前项目的默认推送仓库 git config remote.pushDefault github ``` ## 文档维护 文档维护约定：`docs` 目录仅保存文字文档和结构化验收数据，不保存图片。界面验收结果以文字记录，Markdown 不引用已删除的截图；应用使用的图标素材仍保存在 `apps/api/assets/icons`。 ## 第三方接口与外部素材来源 ### 运行时第三方接口 | 服务 | 实际请求地址 | 用途与更新方式 | 密钥与发送数据 | 失败处理 | | --- | --- | --- | --- | --- | | [Frankfurter](https://frankfurter.dev/) | [USD 固定币种日汇率](https://api.frankfurter.dev/v2/rates?base=USD"es=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 返回的参考价只用于持仓估值，不包含饰品工费、买卖价差或回收折价。外币价格使用最新可用公共日汇率，休市时两类报价时间可能不同；报价日期会显示在界面并随备份保存。自动估价为可选项，开启后新增估值历史，不改写历史记录。 ### 图标获取接口与素材来源（仅维护脚本使用） - [GitHub Contents API：bank-icon-cn 图标目录](https://api.github.com/repos/cellier/bank-icon-cn/contents/png/72)：`apps/api/scripts/download-icons.cjs` 查询公开目录，再下载 `raw.githubusercontent.com` 上的银行 PNG。公开访问无需令牌，受 GitHub 匿名访问限额约束。 - [Simple Icons 支付宝 SVG](https://raw.githubusercontent.com/simple-icons/simple-icons/develop/icons/alipay.svg)、[微信官方图标](https://res.wx.qq.com/a/wx_fed/assets/res/NTI4MWU5.ico)：静态素材地址，无需密钥。 - `apps/api/scripts/expand-icons.py` 从下表品牌官网与官方 CDN 获取 favicon 或品牌图标；微众银行脚本还读取 [官网公开资源](https://tctp.tctpwebankcdn.net/owb-res/owb-res/assets/mainGenerator.811f2078.js)。京东金融和大象银行素材使用 Apple App Store 的 `is1-ssl.mzstatic.com` 图标 CDN。脚本的官网备用地址与尝试逻辑可在对应源文件查看。 - 图标已随项目保存在本地并写入数据库；浏览器通过本站 `/api/icons/:id/image` 读取，正常使用不会向上述素材站点请求图片。维护脚本只请求公开素材，不发送财务数据。 以下为当前全部内置图标的来源；原始 URL、文件名和 SHA-256 同时保存在 [素材清单](apps/api/assets/icons/sources.json)。 | 图标 | 来源 | | --- | --- | | 中国工商银行 | [原始素材](https://raw.githubusercontent.com/cellier/bank-icon-cn/master/png/72/中国工商银行@3x.png) | | 中国农业银行 | [原始素材](https://raw.githubusercontent.com/cellier/bank-icon-cn/master/png/72/中国农业银行@3x.png) | | 中国建设银行 | [原始素材](https://raw.githubusercontent.com/cellier/bank-icon-cn/master/png/72/中国建设银行@3x.png) | | 中国银行 | [原始素材](https://raw.githubusercontent.com/cellier/bank-icon-cn/master/png/72/中国银行@3x.png) | | 交通银行 | [原始素材](https://raw.githubusercontent.com/cellier/bank-icon-cn/master/png/72/交通银行@3x.png) | | 招商银行 | [原始素材](https://raw.githubusercontent.com/cellier/bank-icon-cn/master/png/72/招商银行@3x.png) | | 中信银行 | [原始素材](https://raw.githubusercontent.com/cellier/bank-icon-cn/master/png/72/中信银行@3x.png) | | 中国光大银行 | [原始素材](https://raw.githubusercontent.com/cellier/bank-icon-cn/master/png/72/中国光大银行@3x.png) | | 中国民生银行 | [原始素材](https://raw.githubusercontent.com/cellier/bank-icon-cn/master/png/72/中国民生银行@3x.png) | | 兴业银行 | [原始素材](https://raw.githubusercontent.com/cellier/bank-icon-cn/master/png/72/兴业银行@3x.png) | | 平安银行 | [原始素材](https://raw.githubusercontent.com/cellier/bank-icon-cn/master/png/72/平安银行@3x.png) | | 上海浦东发展银行 | [原始素材](https://raw.githubusercontent.com/cellier/bank-icon-cn/master/png/72/上海浦东发展银行@3x.png) | | 广发银行 | [原始素材](https://raw.githubusercontent.com/cellier/bank-icon-cn/master/png/72/广发银行@3x.png) | | 华夏银行 | [原始素材](https://raw.githubusercontent.com/cellier/bank-icon-cn/master/png/72/华夏银行@3x.png) | | 北京银行 | [原始素材](https://raw.githubusercontent.com/cellier/bank-icon-cn/master/png/72/北京银行@3x.png) | | 上海银行 | [原始素材](https://raw.githubusercontent.com/cellier/bank-icon-cn/master/png/72/上海银行@3x.png) | | 浙商银行 | [原始素材](https://raw.githubusercontent.com/cellier/bank-icon-cn/master/png/72/浙商银行@3x.png) | | 支付宝 | [原始素材](https://raw.githubusercontent.com/simple-icons/simple-icons/develop/icons/alipay.svg) | | 微信 | [原始素材](https://res.wx.qq.com/a/wx_fed/assets/res/NTI4MWU5.ico) | | 京东金融 | [原始素材](https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/7d/74/af/7d74af96-af89-ae14-cbf5-5bbd89859ab7/AppIcon-0-1x_U007epad-0-1-0-85-220-0.png/512x512bb.jpg) | | 汇丰香港 | [原始素材](https://www.hsbc.com.hk/etc.clientlibs/dpws/clientlibs-public/clientlib-site/resources/favicons/apple-touch-icon.png) | | 恒生银行 | [原始素材](https://www.hangseng.com/etc.clientlibs/hase/clientlibs/clientlib-header/resources/favicon.ico) | | 渣打香港 | [原始素材](https://av.sc.com/hk/content/images/content/images/cropped-512x512-1-150x150.png) | | 东亚银行 | [原始素材](https://www.hkbea.com/images/favicon.ico) | | 星展香港 | [原始素材](https://www.dbs.com.hk/_next/public/favicon.ico?q=fa411ced-9fa6-4c3e-b208-d878769c84c9) | | 花旗香港 | [原始素材](https://www.citibank.com.hk/views/images/favicon.ico) | | Gate | [原始素材](https://www.gate.com/favicon.ico) | | Bybit | [原始素材](https://www.bybit.com/favicon.ico) | | Bitget | [原始素材](https://www.bitget.com/baseasset/favicon4.png) | | 中银香港 | [原始素材](https://www.bochk.com/etc/designs/bochk_web/images/icon/boc-icon-32.ico) | | 币安 Binance | [原始素材](https://bin.bnbstatic.com/static/images/common/favicon.ico) | | ZA BANK 众安银行 | [原始素材](https://cdn.za.group/if/za-group-portal-web/assets/images/share-logo.png) | | 微众银行 WeBank | [原始素材](https://tctp.tctpwebankcdn.net/owb-res/owb-res/assets/mainGenerator.811f2078.js) | | 大象银行 EleBank | [原始素材](https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/d4/bc/60/d4bc6004-3898-c9c3-3571-f3ffe4b46b48/Bank-Airstar-0-0-1x_U007epad-0-1-sRGB-85-220.png/512x512bb.jpg) | | 抖音月付 | [原始素材](https://p26-infras.byteimg.com/static-assets/be18bb89d2ceeec6407aae38dc5e894c.png~tplv-49obo7mizy-png75.png) | | 东方财富 | [原始素材](https://g1.dfcfw.com/g4/202307/20230731180250.png) | 当前未接入银行账户 API、交易所交易 API、AI API、Apple 查询 API 或外部备份云服务。Git 远程仓库为代码托管地址；本应用业务运行不调用它们。 2026-10-03 补充更新：全部启用账户支持转账，可按全局独立资产设置和逐项目开关控制资产负债总额；贵金属支持黄金/白银参考价与自动估值历史。备份导出为 ZIP v8，旧格式仍可导入。详见 [更新说明](docs/update-inclusion-metals-2026-10-03.md)。