﻿# 视觉物料 BOM 整理工具 · 使用说明

## 成本权限

- 默认未登录，所有成本显示为 0，导出文件中的成本也为 0
- 点击顶部「显示成本」，输入管理员密码 `10086` 后显示真实成本
- 状态栏显示「权限：未登录 / 权限：管理员」
- 再次点击「隐藏成本」可退出管理员状态

## 一、运行环境

1. Windows 10 / 11（64 位）
2. .NET Framework 4.7.2（Win10 1809 及以上通常已自带；缺失时请先安装）

## 二、启动方式（单文件绿色版）

1. 把 `视觉物料 BOM 整理工具.exe` 放到任意目录即可（桌面、U 盘、共享目录都行）。
2. 双击运行，无需安装，也不需要携带其他文件。
3. 首次运行会自动把运行文件释放到 `%LOCALAPPDATA%\VisionBomTool\app\<版本>`，之后双击直接启动。
4. 程序支持在线升级：启动时自动检查新版本，主界面左下「检查更新」可随时手动检查；升级只替换程序本体，业务数据不受影响，详见「九、在线升级」。
3. 首次启动会弹出「U8 用户配置」：
   - 服务器地址、U8 操作员账号与密码可留空；**三项都留空即离线模式**（使用本地存货档案）
   - 连接 U8 时填写，如 Z005 / 叶少锋；账套号与会计年度按实际情况填写
   - 账套号、会计年度可选，用于显示与核对
   - 点击密码框右侧的眼睛图标可切换显示/隐藏密码
   - 点击「测试连接」，成功会显示登录用户、数据库与存货档案条数
   - 点击「保存并进入」完成配置；也可选择「稍后配置（离线使用）」

## 三、数据与配置位置

- 配置：`%LOCALAPPDATA%\VisionBomTool\config\u8.json`
- 数据：`%LOCALAPPDATA%\VisionBomTool\data\bom.db`
- 日志：`%LOCALAPPDATA%\VisionBomTool\logs\`

说明：

- 密码使用 Windows DPAPI 加密，仅当前 Windows 用户可解密；
- 以上内容都不写在软件安装目录，卸载/移动软件不影响数据。

## 四、日常使用

1. 左侧选择工位；顶部「项目名称」「项目编码」为导入导出必填项。
2. **工位操作**：
   - 新增：点击「+」后立即弹出命名框，可直接修改名称
   - 重命名：**双击工位名**、选中后按 **F2**，或右键「修改名称」
   - 复制 / 删除：在工位上右键，选择「复制工位」或「删除工位」
   - 排序：工位标题右侧上移/下移按钮
   - 删除会弹出确认框（与界面同风格），工位下有物料时一并删除
3. **物料操作**：
   - 新增：表格右上「新增物料」
   - 检索：在搜索框输入编码/名称/规格，实时列出**全部匹配项**（超过 2000 条时显示前 2000 条并提示总数），选中自动回填
   - 编辑：直接双击单元格；文本过长自动换行；编辑后点击任意区域自动提交
   - 排序：每行右侧上移/下移
   - 多选：鼠标按住拖动、Shift 连续选择、Ctrl 点选
   - 复制/粘贴：Ctrl+C 复制选中行（可多行），Ctrl+V 粘贴（支持从 Excel 多行粘贴），Delete 删除选中行
   - 列宽：拖动表头分隔线即可调整，松开后自动保存为默认列宽
4. **自动保存**：修改后约 0.8 秒自动保存，关闭窗口前会再保存一次。
5. **状态栏**：左下角显示从 U8 加载的物料总条数（如 `U8 物料 57,553 条`）。

## 五、存货类别（设置页）

- 类别 = 存货编码**第一个 “-” 之前**的部分，例如 `VTC11-001` → `VTC11`
- 在「设置」页勾选允许参与检索的类别；未勾选的类别不会出现在搜索下拉中
- 支持类别搜索、全选、清空；默认全选
- 只影响检索候选，**不影响**已录入物料、导入导出与汇总

## 六、存货档案导入 / 导出（设置页）

- 设置页「存货档案（离线数据）」显示当前数据来源（U8 实时数据 / 本地文件）、条数与本地缓存时间
- **导出**：可选「仅勾选类别」或「全部导出」，生成 xlsx（存货编码 / 名称 / 规格型号 / 最新成本）
- **导入**：选择 xlsx 后按编码校验，弹窗选择「新增合并」（同编码覆盖更新）或「替换全部」
- **离线使用**：U8 登录失败或无配置时，自动加载本地缓存 `inventory.tsv`，检索照常可用
- 导入的数据写入本地缓存，不影响 U8 原始数据

## 七、导入 / 导出

- 导出文件名：`项目编码_项目名称_时间.xlsx`
- 导出：生成 2 个工作表——「汇总表」在前（存货编码、名称、规格、单价、数量、金额，末行为总成本），「原始数据表」在后（按工位分块）。
  项目名称/编码会写入表格信息区和工作簿属性；手工录入的物料整行橙色标识。
- 导入：读取「原始数据表」，**无存货编码的手工行也会完整导入**（标记为手工行）
- 原导入：读取「原始数据表」，导入前会询问是否先导出备份；导入会清空当前所有工位与物料。
  文件中的项目信息与当前不一致时会弹窗询问是否覆盖。

## 八、常见问题

1. 检索不到存货：确认 U8 配置正确、网络可达；软件每次启动时读取一次存货档案，
   运行中 U8 新增的存货需重启软件后才会出现。
2. 忘记密码/换电脑：配置文件无法跨用户解密，删除 `u8.json` 后重新配置即可。
3. 数据异常：先备份 `bom.db`，再联系维护人员；日志目录中可查看错误详情。

## 九、在线升级

1. **自动检查**：启动器每次启动会联网检查新版本（3 秒超时，失败静默跳过），发现新版本弹出升级窗口；主程序启动后也会静默检查一次，有新版本时左下角「检查更新」按钮旁显示徽标。
2. **手动检查**：点击左下「检查更新」打开更新窗口，可查看新版本号、大小与更新说明，选择「立即升级并重启」或「稍后」；「跳过此版本」后该版本不再提示。
3. **安全性**：更新清单使用 RSA-2048 数字签名，下载的安装包再校验 SHA256，任一校验失败都不会安装。
4. **回退机制**：新版本连续两次启动失败（未写入启动成功标记）时，启动器自动回退到上一个可用版本；升级过程失败只提示错误，不影响当前版本运行。
5. **目录与数据**：程序版本解压在 `%LOCALAPPDATA%\VisionBomTool\app\<版本>_<哈希>\`，保留最近两个版本；`config\` 与 `data\bom.db` 不会被升级改动。
6. **发布端**：更新源为 Cloudflare Pages（`https://bom-updates.pages.dev/stable/manifest.json`）；发布流程见 `scripts\publish-update.ps1`，签名私钥由维护方单独保管。
