FlamePOS 配置手册
1. 本手册的用途
本手册说明 FlamePOS 1.1.0-VSMS-1.0.0 所需的管理配置，涵盖商户资料、用户、商品数据、税务、 付款方式、打印机、数据库连接、VSMS 设置与税务小票配置。
2. 配置责任
配置应由获授权的管理员或实施人员执行。税务相关的配置必须在正式营业前验证通过。 对税务、小票模板、付款方式映射、SDC 地址、签名方类型、PIN、PAC 或证书设置的改动， 都可能影响税务合规。
3. 商户与终端资料
打开后台 > 配置 > 商户。"商户"页取代了原来的"餐厅"标签， 因此同一套配置同时适用于餐饮、餐厅、零售与杂货等场景。
| 设置项 | 用途 |
|---|---|
| 商户名称 | 用于本地小票抬头与对内报表的纳税人或商号名称。 |
| 门店名称 | 可选的本地分店／门店标识，用于非税务的品牌展示。它不会覆盖 SDC 的税务场所名称。 |
| 地址与电话 | 打印在小票抬头与面向顾客的单据上。 |
| 纳税人识别号 | 在辖区要求时用于税务识别。 |
| 终端编号 | 在小票输出与税务记录中标识该 POS 终端。 |
| 小票页脚 | 可选的、显示在小票上的顾客留言。 |
修改本地商户名称或门店名称后，请保存并重启 FlamePOS。在税务发票上，FlamePOS 打印的是所选 SDC 返回的、
已签名的 businessName 与 locationName。这两个值由 TaxCore 证书与开发者场所决定，
不受本地品牌设置控制。
4. 用户与角色配置
请按岗位职能配置用户：
- 收银员：开单、录入商品、收款、打印小票。
- 主管：批准作废、折扣、退货及其他受限操作。
- 经理：运行报表、管理钱箱操作、复核销售。
- 管理员：配置系统设置、用户、打印机、数据库、税务与 VSMS 设置。
每位用户都应有独立的登录账号。应避免共用收银账号，因为税务与经营活动必须能追溯到负责的操作员。
5. 商品与菜单配置
5.1 把菜单搬到另一台收银机
在一台 FlamePOS 上建好的菜单，可以用表格文件搬到另一台上。第二台收银机、更换的机器， 或者第二家门店，都可以用这个办法拿到同样的商品，不必重新录入。
在已有菜单的那台机器上
- 打开后台 → 产品 → 导出商品到表格。
- 选择保存位置。默认文件名为
menu-items.csv。 - FlamePOS 会提示写入了多少个商品。把该文件复制到另一台机器上。
文件共五列，每个商品一行：
Category,Group,Item,Price,Barcode Drinks,Soft Drinks,Coca-Cola 330ml,150,9300675024235 Drinks,Soft Drinks,Bottled Water 600ml,100, Food Cupboard,Rice and Flour,"Rice, long grain 5kg",1200,
这是一个普通的 UTF-8 CSV 文件，导入之前可以用任何表格软件编辑——一次改五十个价格，
这也是最快的办法。名称中含有逗号的，要像上面最后一行那样用引号括起来。
空行以及以 # 开头的行会被忽略。
在要接收菜单的那台机器上
- 打开后台 → 产品 → 从表格导入商品，选择该文件。
- FlamePOS 会读取文件，并说明读到了多少个商品、接下来会做什么。此时还没有改动任何数据。
- 确认后，FlamePOS 会报告新增了多少商品、更新了多少，以及新建了多少个类别与分组。
导入会做什么，不会做什么
- 它是合并，不是覆盖。该分组中已存在的商品会保留自己的图片、打印机路由、 附加项与排序，只更新价格和条码。
- 文件中出现的类别与分组，如果接收方没有，会被自动创建。
- 新商品会设为可见，并在该机器所设经营模式对应的销售模式下销售。
- 要么全部导入，要么一个都不导入。只要有任何一行有问题，就什么都不会导入， 并会列出出错的行号，因此绝不会留下导入了一半的菜单。
- 下列情况该行会被拒绝：列数少于四列；类别、分组或商品名称为空；价格不是数字或小于零。
税类
表格中没有税类这一列，而没有税类的商品无法售卖。改由接收方机器询问一次， 并把它赋给这次导入新建的每一个商品：
- 如果该机器只有一个税类，直接使用，不再询问。
- 如果有多个，FlamePOS 会在导入开始之前询问新商品应使用哪一个。 关闭该询问会中止本次导入。
- 如果一个都没有，商品仍会导入，确认信息会说明它们没有税类。 在产品录入中补上之前，这些商品无法售卖。
文件中与接收方已有商品对应上的，保留它们原有的税类；只有新建的商品才会使用这里选定的税类。
只有五列是有意为之。图片、打印机路由、附加项分组、班次价格与订单类型都不随表格搬运， 因为这些是商家在少数几个商品上设置一次的东西，而不是要重复三百次的东西—— 而且它们在不同机器上本来就不一样。
5.2 录入与修改商品（产品录入）
后台 → 产品 → 产品录入把每个商品列为表格中的一行， 是录入或修正一批到货最快的方式。列就是日常要用的字段：编号、名称、价格、条码、库存、分组、税类、 排序、按钮色与字体色，以及图片。
- 在单元格中输入后继续下一格；离开单元格时该行即被写入。
- 最上面的空白行用于录入新商品。它的第一格会显示这一行还缺什么——
needs name（缺名称）、needs group（缺分组）、needs price（缺价格）、needs tax（缺税类）——齐了则显示Enter to add。在此之前不会写入任何内容，因此绝不会产生一个只填了一半的商品。 - 按 Enter，或点第一格，即可加入该商品。随后会出现一个新的空白行， 可以直接接着录下一个。
- 分组与税类是从列表中选择的，不是打字输入的。
- 颜色与图片单元格会打开取色器与文件选择框。
表格中没有的内容——订单类型、打印机分组、描述、班次价格、附加项分组——都在该商品自己的 编辑窗口中，表格并不取代它。
5.3 税类是必填的
本版本之前创建的商品可能仍然没有税类。升级后管理员应把商品清单检查一遍， 给所有缺税类的商品补上。
5.4 以多种形式售卖的商品
按尺寸、按饼底或按其他任何一组形式售卖的商品，就是一个附带了必选附加项分组的普通商品：
- 按最便宜的那种形式的价格创建该商品。
- 为这个选择创建一个附加项分组，并在其中为每一种形式各建一个附加项。 每个附加项带的是该形式与商品自身价格之间的差额，因此最便宜的那种形式加价为零。
- 把该分组挂到商品上，最少与最多都设为一。正是这一点让收银机在商品一被按下时就要求作出选择。
顾客支付的价格等于商品价格加上所选附加项的价格。两者都会出现在小票上，也都会被申报， 因此各自的税额是分别计算、分别取整的。
正式营业前应先配置好商品数据：
- 创建商品分组与类别。
- 创建商品，填写名称、价格、税类与订单类型行为。
- 有 GTIN 时，把商品的 GTIN 填入条码 / GTIN 字段。
- 为商品可选的选项创建附加项分组与附加项，需要时再创建烹饪要求选项。 以多种形式售卖的商品——按尺寸、按饼底、按份量——配置为带必选附加项分组的商品， 而不是另立一类。
- 如有使用，按终端或班次配置商品的可售性。
- 正式营业前先测试有代表性的商品。
| 商品字段 | 税务上的用途 |
|---|---|
| 商品名称 | 作为 TaxCore 发票的商品名称发送。 |
| 条码 / GTIN | 存放该商品的全球贸易项目代码。长度 8 至 14 位的值会在商品税务化时
放入 TaxCore 发票行的 gtin 字段。 |
| 价格 | 作为含税单价发送，并用于计算税务合计。 |
| 税类 | 映射到该商品当前生效的 TaxCore 税标。 |
商品的改动必须由获授权的用户控制。商品价格、税标与名称的改动会影响税务发票的内容；
条码 / GTIN 的改动会影响发送给 TaxCore 的 gtin 值。这些改动应由商户记录在案。
录入销售时，操作员先选所配置的类别，再选所配置的商品分组，然后按带名称的商品按钮。 按钮上显示的就是此处配置的商品名称。按下即把该商品或服务加入当前单据； 扫描 GTIN 条码是另一种选择方式，按名称选择时并不需要它。
5.5 取价与两位小数取整
选中一个商品或服务时，FlamePOS 会取用适用的订单类型价格、班次价格或商品基础价格，
并立即用 ROUND_HALF_UP 把该单价取整到两位小数。第三位小数决定结果：
0 到 4 舍去，5 到 9 进一。整数与一位小数的价格显示为两位小数。
| 取价得到的价格 | FlamePOS 使用的价格 | 原因 |
|---|---|---|
| 10.124 | 10.12 | 第三位小数是 4，舍去。 |
| 10.125 | 10.13 | 第三位小数是 5，进一。 |
| 25.675 | 25.68 | 第三位小数是 5，进一。 |
| 10 | 10.00 | 货币输出使用两位小数。 |
FlamePOS 同样以两位小数、四舍五入的方式处理商品小计、折扣、税额、行合计、单据合计、 已付与应付金额，以及序列化进 TaxCore 发票请求的金额。因此，单据上显示的取整后单价， 就是用于税务发票计算与提交的单价。
6. 税务配置
FlamePOS 直接从所选 SDC 获取当前生效的税率与税标。在程序初始化时，以及每次构建税务发票之前，
它都会用 E-SDC PIN 激活或 V-SDC 客户端证书／PAC 作认证，发起
GET /api/v3/status 请求，读取 currentTaxRates，
并用返回的税率组替换内存中的生效税率缓存。本地定义的默认税率或税标不会被使用。
| 税务设置 | 运行规则 |
|---|---|
| 税率来源 | 所选 SDC 的 /api/v3/status 应答中的 currentTaxRates 字段。 |
| 税类关联 | 每条本地税务记录都在内部关联到生效 SDC 税率组中稳定的税标。 |
| 自动同步 | FlamePOS 会用该 SDC 税标当前返回的税率覆盖本地计算百分比，无需管理员操作。 |
| 校验 | 若关联的税标不存在、应答无效，或某个税类无法唯一确定， FlamePOS 会中止初始化或税务化并显示错误。 |
| 刷新时机 | 在程序启动时，以及每一次普通、预收款、形式发票、培训、退款与副本的 税务请求之前，同步生效税率组与本地计算缓存。 |
| 价格含税 | 本版本中商品价格按含税配置，测试时须使用含税的合计值。 |
| 商品税类 | 管理员为商品指定适用的税类；FlamePOS 从 SDC 获取该税类当前的百分比与税标。 |
本地的 TAX.RATE 值是同步得来的计算缓存，而不是税务配置的来源。
若该百分比被手工修改或被导入数据改动，下一次自动同步会把它重置为 SDC 为关联税标返回的当前值。
启用 VSMS 时，税率浏览器为只读，并会说明税率由生效的 SDC 配置自动管理。
6.1 随时查看当前生效的税率
具有后台管理权限的用户可以随时取回并查看所选 SDC 当前生效的税率组：
- 用获授权的管理员账号登录 FlamePOS。
- 打开后台。
- 选择 Admin > Active TaxCore Tax Rates。
- 等待 FlamePOS 向所配置的 SDC 发起一次新的认证请求。
- 查看生效税率组的 ID、生效日期／时间、税类、税类类型、百分比与税标。
- 按 Refresh 可再次请求当前列表。表格下方显示的取回时间， 说明所显示的这份快照是何时获得的。
- 查看完毕后按 Close。
此界面为只读，只显示 SDC 返回的值，不能用来新建或修改税率。若取回失败， FlamePOS 会显示错误，且不会改用本地配置的值。
7. 付款方式配置
FlamePOS 支持 TaxCore 发票请求模型中的每一种付款类型。现金、刷卡与礼券可直接在收款界面选择；
支票、电汇、手机支付与其他，则是通过 OTHER 按钮打开的自定义付款选项。
所选的自定义付款名称会保留在 POS 交易上，并映射到对应的 TaxCore PaymentType。
| FlamePOS 付款方式 | TaxCore 税务付款类型 | 配置键 |
|---|---|---|
| 其他 | Other | vsms.payment.OTHER |
| 现金 | Cash | vsms.payment.CASH |
| 刷卡，含外部／手工授权 | Card | vsms.payment.CREDIT_CARD 与 vsms.payment.DEBIT_CARD |
| 支票 | Check | vsms.payment.CHECK 与 vsms.payment.CHEQUE |
| 电汇或银行转账 | WireTransfer | vsms.payment.WIRE_TRANSFER 与 vsms.payment.BANK_TRANSFER |
| 礼券或代金券 | Voucher | vsms.payment.GIFT_CERTIFICATE 与 vsms.payment.VOUCHER |
| 手机支付 | MobileMoney | vsms.payment.MOBILE_MONEY 与 vsms.payment.MOBILE_PAYMENT |
7.1 必需的自定义付款记录
数据库的创建与升级过程会在下列自定义付款选项不存在时把它们装上。管理员可在 后台 > 浏览器 > 自定义付款中查看。
| 自定义付款名称 | 凭据要求 |
|---|---|
| CHECK | 必填：支票号 |
| WIRE TRANSFER | 必填：转账凭据号 |
| MOBILE MONEY | 必填：手机交易凭据号 |
| OTHER | 可选的付款凭据号 |
在没有同时添加对应的 vsms.payment.<规范化名称> 映射之前，不要改这些记录的名称。
改动付款名称或税务配置之后，请把七种付款类型全部测试一遍。
7.2 一张发票上的多种付款方式
FlamePOS 把每一笔部分结算都记为一条独立的 POS 交易。若一张单据用两种以上方式付款，
该单据会在应付金额归零前一直保持打开。最终税务化时，会把该单据所有正向的收款交易作为
TaxCore Payment 数组中的独立条目一并提交，这些条目之和必须等于该发票的金额。
请至少用两种不同方式（例如现金与刷卡）测试此配置，确认所存的请求 JSON 与税务小票中 同时包含两种付款方式及各自的金额。
8. VSMS / TaxCore 配置
把 vsms.sdc_type 设为且仅设为一个生效签名方：ESDC 或 VSDC。
两种模式的设置都可以安全地保留在配置中，但只有被选中的那一种会被使用。更改签名方后请重启 FlamePOS。
系统不会在两个签名方之间自动回退。
| 设置项 | 说明 |
|---|---|
| vsms.sdc_type | ESDC 或 VSDC；决定一次发票尝试所使用的唯一签名方。 |
| vsms.esdc.base_url | 用于状态与发票请求的本地或开发 E-SDC 地址。 |
| vsms.esdc.pin | 分配的 E-SDC 卡 PIN，仅发送到 /api/v3/pin，绝不会作为 PAC 头发送。 |
| vsms.vsdc.base_url | 用于认证状态与发票请求的 HTTPS V-SDC 地址。 |
| vsms.vsdc.certificate.path | V-SDC 双向 TLS 所用 PKCS#12 客户端证书的路径。 |
| FLAMEPOS_VSMS_VSDC_CERTIFICATE_PASSWORD | 受保护的运行时环境变量，存放 V-SDC 客户端证书密码。 它会覆盖同名的配置属性，且不会写入公开的配置文件。 |
| FLAMEPOS_VSMS_VSDC_PAC | 受保护的运行时环境变量，存放仅用于 V-SDC 请求的 PAC 头值， 它会覆盖同名的配置属性。 |
| 环境 | Sandbox 用于测试；production 用于正式税务营业。 |
| 超时 | 显示错误之前等待所选 SDC 应答的最长时间。 |
| POS 身份 | 1083/1.1.0-VSMS-1.0.0 内嵌于发行版中，作为 TaxCore
InvoiceNumber 发送并打印为 POS 号。它不可由客户配置，也不会在"激活与维护"中显示。 |
| 失败处理 | 若所选 SDC 不可用或拒绝该请求，FlamePOS 会显示错误， 既不会改用另一个签名方重试，也不会为该次尝试保存一张成功的税务发票。 |
vsms.enabled=true vsms.sdc_type=ESDC vsms.esdc.base_url=http://<esdc-host> vsms.esdc.pin=<assigned-pin> # 保留下来、供获授权时切换到 V-SDC 的非机密设置： vsms.vsdc.base_url=https://<vsdc-host> vsms.vsdc.certificate.path=/secure/path/client.pfx # V-SDC 的机密项通过受保护的进程环境提供： FLAMEPOS_VSMS_VSDC_PAC=<protected PAC> FLAMEPOS_VSMS_VSDC_CERTIFICATE_PASSWORD=<protected PFX password>
填好 VSMS 设置后请重启 FlamePOS。初始化过程中，FlamePOS 会取回所选 SDC 的状态， 把每个本地税类关联到一个生效的返回税标，并同步其计算百分比；每次税务请求之前都会重复这一过程。 若状态／税率同步失败、某个商品税类无法解析到生效的返回税标，或者没有收到并保存有效的税务应答， 这笔销售都不得完成。
9. 小票模板配置
小票模板决定税务发票如何打印。税务小票模板必须包含全部必需的税务字段，包括发票号、发票计数器、
税务日期／时间、税标、合计金额、付款金额、验证二维码，以及副本／退款标记。纳税人商号与场所名称
直接取自已签名的 SDC 应答。对于所提交的总部开发者场所，这两个值都是 Wok & Flame，
因此两行必需的标识行有意写着相同的文字。POS 号为 1083/1.1.0-VSMS-1.0.0。
验证网址会被保存以备审计，但不会打印。二维码下方会打印结束行
END OF FISCAL INVOICE。副本小票必须显示 TaxCore 副本发票类型、
Copy/Sale 或 Copy/Refund 交易类型，以及原始／引用发票信息。
若修改了模板，请打印测试小票，确认所有必需文字与二维码字段都能放进小票纸并保持清晰可读。
10. 打印机配置
税务小票模板宽 226 点（约 79.7 毫米），按 80 毫米热敏纸卷配置， 落在门户的 57 毫米至 80 毫米纸卷类别内。本配置不包含在 57 毫米以内的纸卷 或 A4 纸上进行税务打印。
- 先在操作系统中配置好打印机。
- 在 FlamePOS 中选择该小票打印机。
- 如有使用，配置厨房与报表打印机。
- 打印一张测试小票。
- 确认二维码可以扫出。确认验证网址没有作为小票文字被打印出来。
11. 数据库与备份配置
数据库连接在安装时配置。数据库存放单据、交易、用户、商品、配置与税务审计记录。 备份流程应保护经营与税务记录不致丢失。
- 每日备份数据库，或按商户的留存策略备份。
- 每次经批准的改动之后，备份小票模板与配置文件。
- 妥善保护含有税务记录与凭据的备份。
12. 变更控制
下列方面的改动应受控并经过测试，因为它们会影响发送给税务机关的内容：
- 税务化请求的生成。
- 税标与税率映射。
- 小票版式、二维码打印、POS 号、SDC 商户／场所字段，以及结束行的位置。
- 退款与副本的处理。
- 付款类型映射。
- 版本号与发行包。
- E-SDC PIN 处理、V-SDC 证书／PAC 处理、签名方选择与地址设置。
13. 配置完成后建议的验证
- 在程序中确认版本为 1.1.0-VSMS-1.0.0。
- 如适用，确认非税务品牌处的本地商户名称与门店名称。
- 确认税务小票打印的是所选 SDC 的 businessName 与 locationName。 对于所提交的总部场所，两行都读作 Wok & Flame。
- 确认所显示的签名方正是预期的 E-SDC 或 V-SDC，且其状态检查成功。
- 配置至少一个带有效条码 / GTIN 的测试商品，确认它能被所选 SDC 的发票请求接受。
- 做一笔普通销售，并扫描验证二维码。
- 针对该笔销售做一次退货。
- 打印一张小票副本，确认生成并保存了 TaxCore 副本发票，且打印出了原始／引用发票信息。
- 运行一次日销售报表，并与税务发票核对。