# wagon

**Repository Path**: fei88/wagon

## Basic Information

- **Project Name**: wagon
- **Description**: 可以与金蝶KIS专业版对接的地磅称重软件
- **Primary Language**: C#
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 13
- **Created**: 2021-12-27
- **Last Updated**: 2021-12-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 金磅称重客户端帮助文档

- [金磅简介](#金磅简介)
- [版本更新记录](#版本更新记录)
- [功能概述](#功能概述)
- [启动连接](#启动连接)
- [在线登录](#在线登录)
- [离线登录](#离线登录)
- [退出登录](#退出登录)
- [系统使用状况](#系统使用状况)
- [认识主界面](#认识主界面)
- [配置](#配置)
- [新增基础资料](#新增基础资料)
- [车辆皮重管理](#车辆皮重管理)
- [上传离线基础资料](#上传离线基础资料)
- [下载基础资料](#下载基础资料)
- [打印模板设置](#打印模板设置)
- [入库称重操作](#入库称重操作)
- [出库称重操作](#出库称重操作)
- [虚拟开单操作](#虚拟开单操作)
- [作废称重流水](#作废称重流水)
- [基础资料录入方式](#基础资料录入方式)
- [查询已完成列表](#查询已完成列表)
- [地磅编码](#地磅编码)


## 金磅简介

金磅称重软件对接金蝶KIS专业版、旗舰版，金蝶K/3 WISE，金蝶K/3 Cloud（金蝶云），可将称重数据自动生成金蝶软件出入库单据，免去操作人员重复录单的辛苦，提高了工作效率和准确率，节省了人力。
1. 支持在线、离线模式无缝切换，登录后掉线，可以继续离线开单，等恢复联网后，自动在后台向服务器同步数据；
2. 支持局域网和互联网应用，互联网应用时需具有固定公网IP或域名；
3. 支持**虚拟开单** ，此功能仅管理员可用，且在离线时不可用；
4. 支持净重调整；
5. 支持多个打印模板。<br/>

- **登录用户和密码**：与金蝶账套里建立的用户名和密码一致。
- **基础资料**:登录成功后服务器返回客户端供应商、客户、部门、职员、仓库、物料列表。
- **运行环境**：需要.Net Framework 4.5环境支持。

## 功能概述

金磅称重客户端直接从地磅表头读取称重数据，经过两次称重后（车辆有皮重信息的情况下，可以一次称重），自动同步生成金蝶出入库单据。

## 版本更新记录

|  日期   | 更新记录  |
|  ----  | ----  |
| 2020-04-16  | 增加车辆皮重批量导入功能 |
| 2020-04-14  | 增加多打印模板支持，可以切换不同的打印模板作为默认模板 |


## 启动连接

**简要描述：** 客户端启动时，会向服务器发送`Hello`信息，等待服务器回复。如果收到回复信息，说明与服务端网络连接畅通，此时客户端将向服务端请求账套信息。

**账套信息：** 账套信息以AES256方式加密后返回客户端，客户端接收后按约定算法解密，提取出账套信息。然后将账套信息填充到登录窗口并显示。服务器端必须开启金蝶系统管理，否则会报错。

## 在线登录

**简要描述：** 在线登录到金蝶KIS专业版。

**详细描述：** 操作人员录入用户名、密码，选择要登录的账套，然后点击登录。
1. 客户端将用户名、密码和账套信息以AES256加密后，提交到服务器进行验证；
2. 服务器接收信息后解密，验证金蝶用户名和密码是否有效；
3. 将验证结果返回客户端；
4. 客户端根据验证结果，成功则进入称重主控台，并缓存来自服务器的最新基础资料及其他相关数据；失败则显示具体信息；  
    > 登录成功后，客户端将：
    > + 从服务端获取金蝶账套内最新的供应商、客户、部门、职员、仓库、物料信息。
    > + 获取车辆及平均皮重信息。
    > + 并将上述信息缓存到本地。  
    > + 将本次登录用户信息缓存到本地。  
    > + 检查本地是否有离线数据，上传至服务器同步。
5. 连续3次登录失败则自动退出客户端。<br/>

## 离线登录

**简要描述：** 离线登录。

**详细描述：** 在没有网络或无法连接到服务器时，客户端自动转为离线登录。
1. 离线登录不显示登录账套；
2. 离线登录时只能录入在本地曾经在线登录过的用户，未在本地登录过的用户无法离线登录；
    > 离线登录时，必须在此前至少成功在线登录过一次，否则没有缓存信息是无法离线登录的；
3. 离线登录后如果恢复在线，则强制要求重新登录，以便及时上传离线数据；
4. 连续3次登录失败则自动退出客户端。<br/>

## 退出登录

**简要描述：** 客户端退出时，自动向服务器发出退出消息，服务器收到消息后将删除该客户端令牌Token。  

## 系统使用状况

**简要描述：** 用于处理异常掉线后，如突然停电导致的客户端异常退出，未向服务器发送退出信息，从而该客户端令牌一直存在，导致不允许重新登录的情况。

**详细描述：** 

1. 在线登录时，在登录界面录入管理员账号和密码，然后点击“系统使用状况”；
2. 依次点击主控台菜单“配置-系统使用状况”，录入管理员账号和密码，然后点击确定；
3. 系统使用状况窗口显示当前登录的用户名、地磅编码、登录时间等信息，可以选择踢出；
4. 被踢出的用户会在5秒内自动退出客户端，如果将自己踢出，则客户端自动退出；
5. 本功能只有管理员可用，且需二次验权；
6. 即使普通用户登录的客户端，也可以按步骤2，录入管理员账号和密码后进入本功能。<br/>

## 认识主界面

**简要描述：** 主界面分为主菜单区、称重数据区、仪表显示区、功能操作区和状态栏区。

**详细描述：** 

1. 主菜单区：配置、基础资料、打印设置、帮助、退出；
2. 称重数据区：未完成、已完成列表；作废、刷新是针对未完成列表的；上传、重新打印、打印预览是针对已完成列表的；导出适用于两个列表。已完成查询条件，自动记忆；列表列宽自动记忆；
3. 仪表显示区显示为0说明连接COM失败，如果正确连接通讯的话，会显示表头实际数据。表头数据为0时显示为0.00；
4. 功能操作区：入库和出库称重作业操作区域；
5. 状态区：显示客户端一些状态信息，其中右下角的显示信息最为重要，它会实时显示一些操作的运行状态。依次是公司名称、账套名称、列表数据数量、当前登录用户、地磅编码、与服务器连接状态、与地磅表头COM口通讯状态、程序激活状态、其他信息和本程序运行状态信息。当前登录用户为管理员时，显示为“用户名-[管理员]”，普通用户只显示用户名；
6. 只有管理员用户，功能操作区才会显示“虚拟”复选框，普通用户不显示。也就是说只有管理员才可以开虚拟单。<br/>

## 配置

**简要描述：** 对客户端进行一些参数设置，用来连接服务端App、地磅表头和缓存数据库。

**详细描述：** `配置-配置`   
1. 服务程序地址设置，为地磅服务端App的URL，但是不需要录入http://，结尾必须为api/；
2. 地磅表头与计算机串口通讯设置，请参照地磅说明书提供的参数填入；  
    > 如果软件显示串口已连接，但未能成功获取地磅表头数据，请在参数里调整波特率，一般是从1200-9600之间。具体需要参照地磅说明书提供的参数。
3. 地磅表头计重单位设置。地磅表头默认计重单位一般为Kg，但有时会被设置为吨。此处要指定计量单位与地磅表头计重单位保持一致；
4. 本地缓存数据库连接设置，用来指定连接本地缓存数据库的实例名、用户名、密码，以及缓存库的名称。
    > + 数据库须为SQL Server 2008或更高版本，完整版或Express版均可。推荐使用最新版SQL Server 2019 Express。  
    > + 如果指定的缓存数据库不存在，则需手工点击“建库”，此时将创建缓存库、缓存库的表、视图和存储过程。请等待提示“成功”后再进行其他操作。  

**手工操作：** 专业人士也可手工直接修改配置文件。配置文件存储在`~\etc\config.json`，为json格式的文本文件，可以用记事本或其他文本编辑器打开，推荐使用`vscode`或`notepad++`。手工修改配置文件风险较高，可能会导致金磅客户端无法正常运行，请慎重！！！

## 新增基础资料

**简要描述：** 在金磅客户端增加金蝶KIS专业版的供应商、客户、部门、职员四项基础资料。

**通用规范：** 
1. 直接输入名称，系统自动按照“年月日时分秒毫秒”形式编码；
2. 可以在金蝶软件里修改编码；  

**操作描述：** `基础资料-新增XX`   
1. 客户：
    - 点击主控台菜单 `基础资料-新增客户`，在弹出窗口里录入 客户名称 ；
    - 点击确定，则数据：
        1. 缓存到本地；
        2. 如在线，上传至服务器同步到金蝶软件；如离线，则等待恢复在线或下次在线登录时自动上传；
            > 上传后服务器会判定名称是否重复，并按照编码规则在服务端重新编码，不以客户端编码为准。
    - 点取消，则退出本次操作。
2. 供应商：同上。
3. 部门：同上。
4. 职员：同上。


## 车辆皮重管理

**简要描述：** 提供导入功能，可将用户整理的车辆皮重信息Excel表批量导入服务端和客户端。

**操作描述：** `基础资料-车辆皮重管理-批量导入`  
1. 在打开文件对话框里，指定要导入的Excel文件。
     + Excel文件格式必须为2007及以上版。  
     + 要导入的内容只能在Excel的第一个工作表。
     + 表内只能有两列，且列标题分别为“车牌号”，“皮重”。
     + 点“取消”则退出导入过程。  

|  车牌号   | 皮重  |
|  ----  | ----  |
| 豫AXXXXX  | 5978.5 |
| 豫AXXXXY  | 7597.6 |

2. 选定文件后，如果符合格式要求，此时：
     + 导入到本地车辆缓存；
     + 如在线，将车辆信息批量上传至服务器进行同步；
     + 如不在线，等下次在线登录时，这些信息将被服务端信息清空并覆盖。
     + **因此我们建议在线时进行导入操作。**  


*离线模式下导入的车辆皮重信息，如果在离线称重时使用了，则恢复网络或重新在线登录后，车辆皮重信息会上传到服务器。则这部分车辆皮重信息不会被覆盖。*

## 上传离线基础资料

**简要描述：** 在离线环境下创建的供应商、客户、部门、职员数据，默认情况下会在下次在线登录时自动后台上传。或者在线登录后才离线，离线操作产生的数据会在恢复在线后自动后台上传。此菜单用来手工上传离线基础资料，不过估计应该用不上。

**操作描述：** `基础资料-上传离线基础资料`  


## 下载基础资料

**简要描述：** 从服务器获取供应商、客户、部门、职员、仓库、物料、车辆的最新数据。为避免频繁访问服务器，金磅客户端默认只是在登录时请求服务器，根据服务器返回数据更新本地基础资料缓存。如果在客户端登录后，金蝶操作人员在金蝶软件里增加了某些基础资料后，客户端并不能及时获取这些更新。此时需手工点击下载菜单，以更新客户端数据。

**操作描述：** `基础资料-下载全部基础资料`，`基础资料-下载XX`  
 1. 下载全部基础资料是将供应商、客户、部门、职员、仓库、物料、车辆资料全部下载。  
 2. 下载XX则是只下载对应的单项基础资料。
 3. 从服务器下载的车辆皮重数据为历次皮重数据的**平均数**，因此可能会和某次称的皮重数据有差异。


## 打印模板设置

**简要描述：** 按预先设定的打印模板格式打印称重磅单。

**通用规范：** 
1. 模板为Excel文件，可以使用Microsoft Excel编辑修改。  
2. 活动文本为{}包含起来的字符，活动文本不可修改。
    > 可调整格式、字体、颜色等。也可以挪动位置，从一个单元格挪到另一个单元格。  

*注意：不能用WPS替代Excel。*  

**操作描述：** `打印设置-打印模板设置`  

点击菜单后，出现“打印模板管理”窗口。在此窗口，您可以：  
1. 新增打印模板。  
     + 点击“新增”后，给新模板命名。名称不得与已有模板重名。
     + 名称通过后，以当前默认模板为源模板创建新模板，并自动调用Office打开。
     + 修改后保存。
2. 编辑打印模板。  
     + 在模板列表，鼠标单击选择某个模板，然后点击“编辑”。
     + 自动调用Excel打开，修改后保存。
3. 删除打印模板。  
     + 在模板列表，鼠标单击选择某个模板，然后点击“删除”。
     + **当前使用的默认模板不可以删除。**
4. 指定某个模板为默认模板。
     + 在模板列表，鼠标单击选择某个模板，然后点击“设为默认”。
     + 默认模板在列表里以蓝色显示。
     + 每次完成称重后，将自动调用默认模板格式进行打印。

## 入库称重操作

**简要描述：** 入库称重操作。  

**业务流程：** 称毛重 -> 称皮重  

**操作步骤：** 称毛重  
1. 勾选“入库称重”单选钮。
2. 选择往来单位。有以下三种方法：    
    > + 点击右侧下拉箭头，从列表中选择；
    > + 在框内输入单位名称，按<kbd>Enter</kbd>进行模糊搜索，自动定位到第一条符合搜索条件的往来单位；
    > + 鼠标双击往来单位框，从弹出的往来单位列表里搜索、选择。    
    > 往来单位：当称重类型为“入库称重”时，关联**供应商**信息；当称重类型为“出库称重”时，关联**客户**信息。
3. 选择物料。*操作方法同上。*
4. 录入或选择车辆。*操作方法同上。*
5. 录入司机姓名。*此项为非必录项，可以不录。*
6. 选择仓库。*此项有默认仓库，如一致可跳过此步骤。*
7. 调整重量。
    > 调整范围为0-1000。入库时用来调减净重，即 **调整后净重=实际净重-调整重量**。出库时用来调增净重，即 **调整后净重=实际净重+调整重量**。  
8. 录入单价。*此项为非必录项，可以不录。*  
9. 指定部门及经办人。*操作方法同往来单位。非必录项，可以不指定。*
10. 等待地磅数据稳定后，点击“称毛重”按钮。此时，客户端将：
     + 数据存储到本地缓存；
     + 添加到未完成列表；
     + 如果在线，上传数据到服务器。  

**操作步骤：** 称皮重  
待车辆卸货后，空车上磅称皮重。  
1. 从左侧未完成列表鼠标单击选择对应车辆的称重记录。  
2. 点击上下箭头调整“调整重量”的值，范围为0-1000。0为不调整，扣减实际净重。  
3. 此时也可录入单价、工程项目，也可重新指定部门、经办人，以本次指定的为准。  
4. 等地磅数字稳定后，点击“称皮重”。此时，客户端将：  
     + 按照“显示重量=毛重-皮重-调整重量”，“金额=显示重量*单价”计算;
     + 保存称重流水记录到本地缓存;
     + 如果在线，同步到服务器，并请求服务器同步为金蝶采购入库单；
     + 等待服务器返回信息，显示并记录同步的金蝶单据内码、编号及同步时间;
     + 无论同步是否成功，均自动打印磅单；
     + 如果离线，则下次在线登录时自动后台同步，不再打印磅单。  

**操作步骤：** 一次完成称毛重  
此项前提为系统中记录有该车辆的历史皮重信息，即该车辆至少曾上磅称重过一次。如称重过多次，则每次皮重信息均记录。通过客户端参数可选择使用平均皮重数据或是最近一次的皮重数据。
当车辆有皮重信息时，录入或选择车牌号，会自动在皮重栏携带出皮重数据。  
此时只需录入一些必要的信息，等地磅数字稳定后，直接点击“直接称毛重”来完成本次称重。  

## 出库称重操作

**简要描述：** 出库称重操作。  

**业务流程：** 称皮重 -> 称毛重 ； 也可一次完成称重。

## 虚拟开单操作

**简要描述：** 虚拟出入库业务。  

**业务流程：** 必须、只能一次完成称重。  

1. 只有系统管理员用户才可以进行虚拟开单操作。普通用户登录无“虚拟”复选框;
2. 在功能操作区，勾选“虚拟”。此时：  
    + “称皮重”、“称毛重”按钮变成灰色不可点击状态；
    + 出现“虚拟开单”按钮;
    + 皮重栏和毛重栏由灰色变成白色可输入状态，手工输入皮重和毛重数据;
    + 注意毛重必须大于皮重，不然不允许保存;
    + 虚拟开单时，一定要选择一个专门约定的虚拟仓库，不可选择正常业务使用的仓库;
3. 其余操作同正常开单；
4. 必要信息指定和录入完毕后，点击“虚拟开单”。 

**注意：**   
1. *离线登录时，因无法判定登录用户是否管理员身份，因此不可虚拟开单。*  
2. *虚拟开单时车辆皮重信息不具备真实性，所以不予保存。*

## 作废称重流水  

**业务情景：** 只能作废未完成的称重流水。应用场景为：入库满车称重后，我方突然决定不买了，对方车辆未卸货即返回；出库称完皮重后，客户突然不买了，直接空车返回。  
**操作步骤：**  
1. 从未完成列表里，鼠标左键单击选择要作废的记录；  
2. 点击称重数据区工具栏“作废”按钮；此时：
    + 该称重记录移出未完成列表；
    + 作废本地流水记录和服务器上对应的流水记录。  

3. *可以在已完成列表里通过过滤条件查询。*

## 基础资料录入方式

列表型基础资料，包括往来单位、部门、职员、物料、仓库，有以下三种方法录入：    
1. 点击右侧下拉箭头，从列表中选择；
2. 在框内输入单位名称，按<kbd>Enter</kbd>进行模糊搜索，自动定位到第一条符合搜索条件的基础资料；
3. 鼠标双击，从弹出的列表里搜索、选择。  

录入型基础资料，包括车牌号、司机、工程项目，有以下两种方式录入：
1. 手工录入；
2. 鼠标双击，从弹出的列表里搜索、选择。  

## 查询已完成列表  

默认情况下，查询数据是按地磅、按用户进行隔离的，即每台地磅只能查询到本地磅的数据，每个用户也只能查询到自己的数据。

1. 设定查询日期区间;  
    > 注意截止日期，假如要查询2020-03-01至2020-03-31的称重流水，则必须将截止日期设置为2020-04-01。因为称重时间是精确到毫秒的，因此2020-03-31当天的称重流水日期时间信息是日期+时间，是大于2020-03-31 00:00:00:000的。所以设置为2020-03-31是查询不到当天的数据，必须向后延长1天。  
2. 往来单位是录入编码，而不是名称。可以手工录入，也可双击在弹出的列表里选择；
    > 只有在称重类型里选择“入库”或“出库”后才能双击调出往来单位列表。入库时调出供应商列表，出库时调出客户列表。如果是全部，则无法调出。只能手工录入编码或者留空。留空意味着查询全部往来单位。  
3. 虚拟和作废复选框，均为三态选择。
    > 当为对号时，代表只查询虚拟和（或）作废记录；  
	> 当为空白时，代表只查询真实和（或）未作废记录；  
	> 当为黑色方块时，代表查询全部。  
4. 下拉框用来设定查询入库、出库或全部称重记录；设定已同步、未同步或全部称重记录；设定已生成金蝶单据、未生成金蝶单据或全部称重记录；
5. 设定完毕查询条件后，点击：
    + **查询：** 按条件查询本地称重流水数据，此时只能查询到这台地磅的当前登录用户的数据。  
    + **本地查询：** 同“查询”。  
    + **服务端查询：** 此时将从服务器请求称重流水数据，只有管理员才可以进行此操作，此时将查询全部符合条件的数据，可以看到所有地磅、所有用户的数据。不再进行数据隔离。
6. *查询条件自动记忆，下次再次打开已完成页签时，会自动载入最近一次查询条件。*  

## 地磅编码

每台地磅在软件里都有其唯一编码，这个编码是金磅软件自动生成的，不可修改。