使用与部署帮助
面向宝塔面板新手，从上传到生成，一步步说明。
一、部署到宝塔面板（约 5 分钟）
推荐方式，配置可由多人共用第 1 步：准备站点
- 登录宝塔面板 → 左侧「网站」→「添加站点」；已有站点可直接用。
- 域名填你自己的域名或服务器 IP；PHP 版本任选 7.0 以上（7.4 / 8.0 / 8.1 都可以），数据库选「不创建」，FTP 不创建。
- 提交后记住站点根目录，一般是
/www/wwwroot/你的域名。
第 2 步：上传网站文件
- 把本网站整个文件夹打成
zip压缩包。 - 宝塔 →「文件」→ 进入站点根目录 →「上传」→ 选择 zip → 上传后右键「解压」到当前目录。
- 解压后根目录应能直接看到
index.html、admin.html、api.php、assets、data。
如果多套了一层文件夹（例如根目录里是对账单工具/index.html），请把里面的内容全部移动到根目录。
第 3 步：给配置目录写权限
- 在「文件」里找到
data目录 → 右键「权限」→ 设为755，属主选www，可勾选「应用到子目录」。 - 这一步只影响后台配置能否保存；即使不做，转换功能也能正常使用。
第 4 步：打开并初始化
- 浏览器访问
http://你的域名/index.html。 - 看右上角徽章：服务器配置已连接 表示部署成功；若显示 本地模式，说明 PHP 没生效，请检查站点 PHP 版本是否已安装并启动、
api.php是否在根目录。 - 打开「后台配置」→ 用默认密码
admin888登录 → 立刻修改后台密码 → 填写备注、欠款说明、对账说明、落款 → 保存。
第 5 步：加固配置目录（宝塔默认 Nginx，建议必做）
项目已把后台运行配置存为 data/runtime.php（PHP 文件，直接访问不会输出内容），并附带 data/.htaccess（Apache 生效）。宝塔默认使用 Nginx，不读 .htaccess，请在宝塔「网站 → 设置 → 配置文件」里追加一段：
location ^~ /data/ { deny all; }
这条规则只拦外部 HTTP 访问，不影响 api.php 在服务器内部读取配置。加上后可用浏览器访问 http://你的域名/data/config.json 验证，应显示 403。
不用 PHP 也能用
如果只是自己一台电脑用，直接双击 index.html 也可以：转换和下载全部可用，只是后台配置保存在这台电脑的浏览器里，换电脑不会同步。此时右上角会显示「本地模式」。
二、日常使用流程
- 导出：在你们系统里按客户、按月份导出原始对账单（
.xls或.xlsx）。 - 上传：打开转换台，把文件拖进上传框。文件只在浏览器里解析，不会上传到服务器。
- 核对：检查客户名称、时间段、自动识别的业务员 / 默认账期、明细条数与合计金额是否与原表一致。
- 调整：业务员与默认账期无需手动填写（已从导出文件自动读取，字段为只读）。需要时改统一备注，或逐行修改备注、取消勾选某行。
- 生成：点「生成并下载对账单」，得到标准格式的
.xlsx，可直接打印盖章或发给客户。
SK… 开头的回款单），系统会默认排除并在预览上方提示；若确实需要输出，点「加入明细」即可。三、字段映射（重要，请核对）
兼容新旧两种系统导出格式| 系统导出的原始列 | 生成的对账单列 | 说明 |
|---|---|---|
| 业务员（表头第 3 行） | 业务员 | 自动识别，原样输出，无需手填 |
| 默认账期（表头第 3 行） | 默认账期 | 自动识别，原样输出，无需手填 |
| 客户名称 / 时间段 / 对账日期 | 表头与落款 | 自动识别；客户名称、时间段、对账日期仍可在转换台修改 |
| 单据编号 | 单据编号 | 原样输出 |
| 发货回款日期 | 发货日期 | 按后台设置的日期格式输出 |
| 发货名称 | 发货名称 | 原样输出 |
| 克重 | 克重 | 原样输出 |
| 规格 | 规格 | 原样输出 |
| 吨数 | 数量 | 默认取「吨数」；若想改取「张数」，到后台把「数量取自源表哪一列」改成 张数 |
| — | 单位 | 固定填后台的「默认单位」（默认「吨」） |
| 吨价 | 价格 | 可在后台改取「单价」等列 |
| 销售额 | 销售额 | 原样输出，合计自动求和 |
| — | 备注 | 取后台「默认备注」，可在转换台逐行修改 |
| 张数 / 发票号码 / 已开票金额 / 公司抬头 / 账期（明细级） | 不输出 | 目标模板没有对应列 |
| 本期对账信息汇总、本期回款明细 | 不直接输出 | 汇总金额可用作文案变量（见下节） |
系统导出的两种格式都能识别：旧版为 11 列简易表（底部是一整段文字合计），新版为 22 列完整表（含「本期对账信息汇总」「本期回款明细」）。程序会自动定位出库明细表头，并在合计行之前停止，不会把回款单或汇总文字当成明细。合计行的数量与销售额由勾选的明细自动求和。表头、表尾、合并单元格、字体、边框、列宽、横向 A4 打印设置均按「对账单格式」模板复刻。
四、文案变量
可用于备注、对账说明、欠款说明、落款示例：把「欠款说明」设为 截止到{期末日期}共欠款：{期末应收总额} 元，生成时会自动带入实际日期与金额。其中 {期初余额}、{本期发生金额}、{本期回款总额}、{期末应收总额}、{本期发货吨数} 来自新版导出文件的「本期对账信息汇总」区；旧版简易导出没有该汇总区，这些变量会显示为空。
五、常见问题
上传后提示「没有找到明细表头」？
程序靠识别包含「单据编号 / 发货名称」和「销售额 / 金额」的那一行来定位表头。请确认上传的是系统导出的原始对账单，而不是已经改过表头的表。若你们系统改了列名，在后台「明细表头与数据列映射」里按新列名调整。
业务员 / 默认账期是空的？
这两项取自导出文件表头第 3 行的「业务员:」「默认账期：」。若上传的是不含这两栏的旧版简易导出（只有「地址」行），对应位置会留空，转换台会给出提示。请从系统里重新导出完整版对账单即可，不需要在网站里手工填写。
数量或单价不对？
到「后台配置 → 二、明细表头与数据列映射」，检查「数量取自源表哪一列」「价格取自源表哪一列」是否和源表表头完全一致。样表用的是「吨数」和「吨价」。
后台保存时提示失败 / 提示 data 目录不可写？
在宝塔「文件」里把 data 目录权限设为 755、属主 www。若仍失败，可临时设为 777 测试，成功后改回 755。
打开转换台显示「本地模式」？
说明 api.php 没有被执行。请检查：站点是否已选择并启动 PHP 版本；index.html 与 api.php 是否在同一个根目录；是否启用了「纯静态」站点。转换功能不受影响，只是配置不共享。
生成的文件 Excel 打不开 / 提示格式错误？
请确认 assets/exceljs.min.js 与 assets/xlsx.full.min.js 已完整上传（两个文件合计约 1.8 MB），并刷新页面重试。WPS 与 Excel 2010 以上均可正常打开。
打印时分成了两页？
输出已设置为「横向 A4、宽度缩放到一页」。若仍分页，可在 Excel 的「页面布局」里把缩放调为「将所有列调整为一页」。
数据安全吗？
对账单文件在浏览器本地解析与生成，不经过服务器；服务器只保存后台的文案参数。若网站对公网开放，建议：修改默认后台密码、开启「全站访问密码」，并在宝塔里给站点配置 HTTPS。