💡 Finhelper 本地数据更新与使用手册
本手册专门为不熟悉技术的财务、行政或管理人员编写，旨在指导您如何独立更新看板数据、录入表格并进行日常查阅。点击下方各模块标题可展开/折叠对应内容。
🌟 最新功能增强与操作指南（2026-07-27 更新）
1. 📊 跨月份对比分析 (Monthly Comparison Mode)
- 开启方法： 点击看板顶部标题旁边的 开启月度对比 按钮。
- 选择基准月： 开启后，顶部中枢会弹出【基准月份】选择框，允许您自由选择历史任意月份（如对比
2026-03与当前2026-05）。 - 表格呈现： 表格工具栏显示 ⚖️ 对比模式: 2026-03 vs 2026-05 徽章，资产明细中自动扩展【基准月价值】与【波动净值】列，以涨绿跌红展示资金变动绝对额与百分比。
2. ↕ 资产明细排序控制 (Sorting Controls)
- 工具栏全局下拉菜单： 表格工具栏提供
[ ⇅ 排序: ... v ]菜单，可一键按“机构归类”、“金额从高到低”、“原币余额”、“账户名称”或“波动变动额”快速重排。 - 表头直接点击排序： 点击表格表头（如
原币余额或展示月价值），标题旁亮起半透明圆圈指示器（▲ 升序/▼ 降序），并与工具栏下拉菜单 100% 双向高亮联动。
3. 👥 持有人资产分析 - 智能归一与分栏 (Holder Auto Merge)
- 大小写智能归一：全自动识别 Excel 中混用的名字大小写（如
KYLIE与Kylie），统一归集至单一Kylie卡片并汇总估值，绝不分裂卡片。 - 法币与加密资产分栏：展开持有人卡片后，系统自动将【法定货币资产】与【加密数字资产】分栏列出。
- 持有人实时搜索：右上角搜索框支持按持有人姓名、分类 Tag (Person/Company/Merchant) 或持仓币种（如 USDT）实时检索。
第一步：环境检查与准备 (Node.js 环境)
如何快速检查您的电脑是否已装好环境？
最简单的检查方法：直接双击项目文件夹下的 双击更新数据.bat 运行文件。
- 若环境已就绪： 会弹出一个黑色窗口闪烁，随后自动在您的电脑浏览器中打开财务看板。这代表环境正常，您可跳过本步骤，直接查阅！
- 若未安装环境： 黑色窗口会停留在屏幕上并显示
[ERROR] Node.js environment not found!。此时，请按下方步骤下载安装。
📥 未安装时的安装指南（只需配置一次）：
访问 Node.js 官网：
https://nodejs.org/
下载 LTS (长期支持版) 的 Windows 安装程序 (.msi)。
双击运行下载好的 .msi 文件，一路点击 Next (下一步)，采用默认勾选完成安装。
安装完成后，建议重启电脑一次，让运行环境生效。随后双击 双击更新数据.bat 即可开始使用。
📅 第二步：日常数据更新流程 (每月只需 3 步)
第一步：放置 Excel 报表 (区分公司主体)
把您需要更新的 Excel 账单文件直接拷贝放入 import_data 文件夹中。
文件名规范：文件名称开头必须带上对应的公司主体，例如 [ysb]_data.xlsx 或 ysb_data.xlsx。系统将自动识别并将数据写入独立的数据库文件中（如 ysb_data.js），从而实现主体之间完全隔离，独立维护。
import_data/processed 进行归档备份。这仅作为原始账单备份，系统运行与后续网页修改（如单价、钱包余额等）已完全独立，不依赖这些备份文件。
第二步：运行更新程序
双击运行项目根目录下的 双击更新数据.bat 文件。
此时会弹出一个黑色命令行窗口自动跑完数据并关闭，过程仅需 2~3 秒。
⚠️ 智能数据体检与自动纠错指引 (可选)
如果运行中发现数据异常（如重复填报、汇率缺失、账户代码未登记等），命令行窗口会显示详细警告，并在 import_data 目录下自动为您生成标记了高亮的 Excel 诊断副本（如 testData2_diagnosed.xlsx）。
- 粉红/红色整行高亮： 代表该行存在严重的格式错误或冲突，必须引起重视。
- 黄色单元格高亮： 代表该单元格是发生错误的具体位置（如未填的网点或未填的汇率单元格）。
- 最右侧「Finhelper 诊断建议」列： 详细写明了每一行出错的具体原因与修复建议。
_diagnosed 后缀覆盖原文件 ➔ 重新双击运行更新即可。
第三步：查看最新看板
数据同步成功后，浏览器会自动打开财务看板网页。在顶部的下拉选择中，选择您刚刚更新的月份，即可浏览所有更新完的财务数据！
📝 第三步：Excel 记账表格格式规范 (V3 横向多工作表)
为了使系统能正确合并数据，请务必保证您的 Excel 包含以下 5 张工作表 (Sheets)，并且第一行（表头）采用如下纯英文命名：
1. 账户维度字典表 (Account Info)
登记所有物理账户、公司名、银行地址或钱包地址的配置表。
2. 银行存款余额表 (Bank Balances)
填报各银行账户的历史余额明细。
3. 零备金与商户钱包余额表 (Petty Balances)
填报备用金、商户钱包、微信、支付宝等流动零钱的各月余额。
4. 加密资产持仓数量表 (Crypto Balances)
填报冷钱包中 BTC、ETH、TRX、SOL 等不稳定币种的期末数量（系统会自动乘以当月估值单价）。
5. 商户账户余额表 (MA)
填报三方收款商户通道（如 MA、Merchant 账户）各月的期末存款余额。
6. 汇率折算与加密单价表 (Exchange Rate)
登记各月法币兑美元的汇率（如 AED、CNY 等）以及代币估值美元价（如 BTC、ETH 等）。
💡 智能代码联动提示 (Code Lookup Linkage)
当您在《银行存款余额表》、《零备金与商户钱包余额表》、《加密资产持仓数量表》或《商户账户余额表》中填写的 Code (代码) 与《账户维度字典表 (Account Info)》中的 Code 一致时（系统已升级为大小写无关、空格无关），网页端在查看明细时会自动联动展示该账户的网点网络 (Bank/Network) 以及账号地址 (Address/Account)，无需重复手动备注。若匹配失败，则零备金记录会默认显示“分类 + 币种”备注（例如“数字钱包 USDT”）。
💡 缺失字典自动修复指引：当系统检测到有缺失的账户代码时，在自动生成的 Excel数据修复指引报告.md 表格里，新增了 Currency (币种) 列，能根据代码后缀（如 DEP_BAONUO_CNY）智能推理出本位币（如 CNY），数字钱包则建议填 多币种。您可以一键复制直接贴入 Excel 字典中。
🌐 第四步：链上余额抓取与代币单价校准 (可选高级功能)
本系统内置了自动请求区块链和交易所接口获取最新状态的功能，专为减少手动录入冷钱包持仓和代币行情波动而设计。
在财务看板的左侧菜单中，点击“账户管理”下方的“链上余额/币价抓取”选项，即可进入专属的操作页面。
在页面最上方的“第一步：选择目标账期与校准基准日”中选择您需要获取的月份（例如 2026-06），并在表格上方选择当前要操作的公司主体（如 YSB 或 SS）。
系统会自动识别您在《Account Info》中登记的所有链上地址（如以太坊 ERC20 钱包、BSC BEP20 钱包、波场 TRC20 钱包等）。点击右上角的“一键链上获取余额”，系统将调用后台服务定位至指定月份最末一秒的区块高度，并自动抓取该时间节点的 USDT、USDC 余额 and 主币数量并填入输入框。您也可以在框内直接修改，最后点击右下角的“确认余额无误，保存并更新”即可写入数据库。
切换到“代币历史单价校准”选项卡，点击右上角“一键获取历史单价”。系统会访问币安 (Binance) 或 CoinGecko 接口，自动拉取选定月份期末当日该代币兑美元的收盘价，回填后点击右下角“确认单价无误，保存并更新”。系统会直接热回写到所有的主体 JS 文件（如 ysb_data.js 和 ss_data.js）以及价格补丁中，看板的美元估值立刻同步更新，无需依赖任何历史 Excel 备份！
📥 第五步：Excel 导出机制与闭环修正指引
本系统不仅能将外部 Excel 转化为可视化看板，还支持将系统处理合并后的结构化数据重新导出为一份干净、高颜值的 Excel 表格，方便您进行分享、存档或直接作为下月记账的新模板。
点击看板右上角的“导出 Excel”按钮。系统会弹出提示框（如 确认导出 公司 [YSB] 的财务 Excel 数据报表吗？），以防导错主体。点击确定，浏览器即会下载形如 [ysb]_data.xlsx 的 Excel 文件。
导出的 Excel 中，Account Info 工作表里包含一些浅奶油黄色（Cream Yellow）高亮的行，这代表它们是由系统自动干预生成的：
- 自动生成的账户行： 某代码在余额表有金额但在字典表漏填，系统解析时自动补充 of 临时字典记录。
- 冲突自动消歧行： 系统为了防止多张卡/地址信息相同发生重名冲突，自动添加了尾标修饰（如网点加上了
(8713)）。
浅黄色高亮行旨在提醒您：“该行有部分信息是系统临时垫付的，建议您进行补齐订正”。您只需要打开这个导出的 Excel 文件，找到黄色的行，**手工将其“网点”、“持有人”或“账号”修正为真实的、更美观的财务信息**。下月更新时，**直接把这个修正过的 Excel 放入 `import_data` 文件夹**，即可完美消除先前的警告冲突。系统会自动擦除黄色标记，数据流自此形成良性闭环！
❓ 第六步：常见问题排查与解决办法
Q1. 双击 “双击更新数据.bat” 后黑框一闪而过，网页没有打开？
原因： 通常是因为您的电脑上没有成功安装 Node.js 运行环境。
解决办法： 请重新阅读上方第一步的安装指南，下载并安装 Node.js，然后重启电脑再次尝试。
Q2. 运行提示 “⚠️ 警告: 未在 import_data 文件夹内发现任何 Excel 报表”？
原因： 您的 Excel 文件放置的地方不对，或者格式尾标不匹配。
解决办法： 请确认您的 Excel 文件确实存放在 import_data 根目录下（或者它已被自动移入了 import_data/processed 目录下），且文件格式必须为 .xlsx 或 .xls，不能是 .csv。
Q3. 看板提示“无法读取工作表中的数据”或金额显示不正确？
原因： Excel 工作簿中缺失了必要的工作表，或者表头第一行英文命名不符。
解决办法： 请确保 Excel 包含了 Account Info, Bank Balances, Petty Balances, Crypto Balances, Exchange Rate 这 5 张工作表，且第一行的表头名称确实为推荐的英文列名（如 Category, Code, Currency 等。新版系统已不再依赖 Account Name 列，由系统根据字典自动关联并防冲突拼装）。
Q4. 以前导入的某个主体旧数据怎么不见了？（或者如何彻底清空旧数据？）
隔离与加载： 当前的看板支持公司主体完全隔离。如果您在网页顶部切换了不同的公司（如在下拉框中选择 YSB 或 SS），系统会自动动态加载对应的数据库文件（如 ysb_data.js 或 ss_data.js）。
彻底清空旧数据： 如果您想要彻底清空某个公司的所有数据，只需在关闭看板后，直接删除 database/ 目录下该公司对应的 _data.js 数据库文件（如 ss_data.js），然后重新放入正确的 Excel 并运行更新脚本即可。processed/ 下的归档文件只是作为原始 Excel 账单的历史备份，删改它不影响网页端直接校准或读取数据的运行独立性。
Q5. 为什么在资产明细列表里看不到当月余额为 0 的账户？
原因： 为了避免无余额的静止死账户挤占页面，使财务报表更加聚焦在活跃资产上，系统实装了智能零余额过滤机制。如果某个账户当月余额是 0.00 或 -0.00，它将自动在列表中隐去。
解决办法： 如果您需要查看，可以在顶部开启“月份对比”。只要该账户上期有余额，系统仍然会保留显示以呈现变动历史。
Q6. 为什么我的 diagnosed 诊断副本里有大片红色的行，却没有写具体的建议？
原因： 这通常是由于在旧版代码中触发了跨文件的全局重复冲突，或者是 ExcelJS 内部的样式引用共享 Bug 导致默认白底的行被意外连带染色。
解决办法： 该问题已在系统最新版中彻底修复（跨文件重名不再报错，切断了底层样式引用，并自动忽略了以 _diagnosed 结尾的副本）。请关闭并清空目前打开的所有 Excel，重新双击运行更新文件，系统便会为您生成只针对异常位置进行精确定位高亮的正确诊断副本。