附录 速查
本附录沉淀手册正文里需要随时翻查的速查内容：名词表、状态速查、单据关系、权限码、FAQ、录入规范、历史数据导入。
附录A 名词术语表（按拼音排序）
| 拼音 | 名词 | 英文 | 一句话 |
|---|---|---|---|
| B | 品牌 | Brand | 商品所属品牌，可设年度目标 |
| B | 品牌类别 | Brand Category | 品牌下的细分类目 |
| C | 分类 | Category | 商品品类归属 |
| D | 冻结 / 销售占用 | Frozen / Sales Occupied | 销售订单锁定、不可再售的库存 |
| G | 供应链订单 | Supply Chain Order | 向供应商采购的单据（10 态） |
| G | 供应链结算 | Supply Chain Settlement | 确认采购成本、分摊运费（状态9） |
| H | 货位（货架位） | Shelf Position | 库存五维之一，仓内具体货位 |
| J | 加载测算 | Loading Calculation | 按箱型与容积测算装柜量 |
| J | 体积 | Volume (m³) | SKU 单件体积，运费分摊与装载基础 |
| K | 可用库存 | Available Stock | 实物 − 占用，可接单的量 |
| K | 库存 | Stock | 仓库实际在库货物 |
| K | 库存五维 | Five-dimension Stock | SKU×仓库×过期日×供应链订单×货架位 |
| P | 品牌 | — | 见 B |
| S | 商家采购门户 | Merchant Purchase Portal | 下游商户自助选购入口 |
| S | 商户 | Merchant / Store | 下游买家，销售订单对象 |
| S | 商品（SPU） | Product | 产品，系统以 SKU 为最小单元 |
| S | 实物库存 | Physical Stock | 仓库实际物理数量 |
| S | 快照 | Snapshot | 下单时冻结的商品信息副本 |
| S | 规格（SKU） | SKU | 最小可买卖单元，带唯一编码 |
| T | 退货单 | Return Order | 销售退货单据（4 态） |
| X | 销售订单 | Sale Order | 向商户销售单据（7 态） |
| X | 销售结算 | Sale Settlement | 确认收入、生成分析（状态6） |
| Y | 运费分摊 | Freight Allocation | 运费按体积占比摊到各 SKU 成本 |
| Y | 应付 | Accounts Payable | 欠供应商的钱 |
| Y | 应收 | Accounts Receivable | 商户欠我们的钱 |
| Z | 状态机 | State Machine | 单据状态的有序流转规则 |
| Z | 周转率 | Turnover Rate | 库存进销快慢 |
| Z | 年化收益 | Annualized Return | 基于周转与利润折算的年收益 |
| Z | 省份税区 | Province Tax Zone | 按地区设税区与税率 |
| Z | 柜号 | Container No. | 海运柜唯一标识 |
| Z | 到港 | Port Arrival | 货柜到目的港 |
| Z | 清关 | Customs Clearance | 海关放行 |
| Z | 转运 | Transit | 清关后运往仓库途中 |
附录B 状态速查表
供应链订单（10 态）
| 码 | 状态 | 可执行操作 |
|---|---|---|
| 0 | 申请 | 编辑、提交审批、作废（未履约） |
| 1 | 待审批 | 审批通过/驳回（审批人） |
| 2 | 审批确定 | 确认下单 |
| 3 | 已下单 | 维护货运、推进发货 |
| 4 | 已发货 | 推进到港 |
| 5 | 已到港 | 推进清关 |
| 6 | 已清关 | 推进转运 |
| 7 | 转运中 | 推进入库 |
| 8 | 已入库 | 供应链结算 |
| 9 | 已结算 | 终态（成本已确认） |
销售订单（7 态）
| 码 | 状态 | 可执行操作 |
|---|---|---|
| 0 | 申请 | 编辑、提交审批、作废（未履约） |
| 1 | 待审批 | 审批通过/驳回 |
| 2 | 审批确定 | 确认下单（冻结库存） |
| 3 | 已下单 | 出库 |
| 4 | 已出库 | 交货、销售结算 |
| 5 | 已交货 | 销售结算 |
| 6 | 已结算 | 终态（已生成分析） |
退货单（4 态）
| 码 | 状态 | 可执行操作 |
|---|---|---|
| 0 | 退货中 | 仓库退库 |
| 1 | 已入库 | 销售侧确认退价 |
| 2 | 已确认价格 | 财务打款 |
| 3 | 已打款 | 终态 |
盘点
盘点无状态机。系统为实时操作：改货架 / 拆分 / 标记销毁，落库存变动记录，不改总库存数量。账实差异用正规单据（入库/出库/销毁）修正。
附录C 单据关系图
下面这张图串起全系统的核心单据：供应链侧（采购→入库→应付）、销售侧（销售→出库→应收→退货）、以及成本从采购到利润的完整链路。
供应链侧（应付线）：
st=>start: 供应商
a=>operation: 供应链订单
b=>inputoutput: 入库单 → 库存(五维)+，采购成本+运费随批次
c=>subroutine: 供应链结算（运费按体积分摊）
d=>operation: 应付 / 付款记录
e=>end: 已结清
st->a->b->c->d->e
销售侧（应收线 + 退货支线）：
st=>start: 商户
a=>operation: 销售订单（快照 + 冻结库存）
b=>inputoutput: 出库单 → 库存扣减·释放占用
c=>subroutine: 销售结算（成本取自供应链批次）
d=>operation: 应收 / 收款记录
ok=>end: 已结清
ret=>condition: 发生退货？
r1=>operation: 退货单 → 退货入库
r2=>operation: 退价确认
r3=>end: 退款（退货财务）
st->a->b->ret
ret(no)->c->d->ok
ret(yes, right)->r1->r2->r3
任意一笔库存变动都能通过「库存变动记录」追到源头单据（入库单/出库单/退库单/移库单/销毁）。
附录D 权限码清单
页面权限（page_*，每个二级菜单一条）
| 权限码 | 名称 |
|---|---|
| page_dashboard_overview | 全览看板 |
| page_supply_board | 供应链看板 |
| page_supplier_manage | 供应商管理 |
| page_supply_order | 供应链订单 |
| page_supply_purchase_board | 供应链采购看板 |
| page_supply_container_loading | 集装箱装柜 |
| page_sale_board | 销售看板 |
| page_sale_order | 销售订单管理 |
| page_sale_return | 销售退货 |
| page_store_manage | 商户管理 |
| page_warehouse_overview | 仓库功能总览 |
| page_warehouse_alert | 仓库预警 |
| page_warehouse_view | 仓库查看 |
| page_warehouse_destroy | 库存销毁 |
| page_warehouse_manage | 仓库管理 |
| page_warehouse_in_out | 入库与出库 |
| page_warehouse_return | 退货 |
| page_warehouse_transfer | 移库 |
| page_warehouse_putaway | 上架管理 |
| page_warehouse_check | 仓库盘点 |
| page_warehouse_stock_record | 库存变动记录 |
| page_stock_import | 库存导入 |
| page_product_image_import | 商品图片导入 |
| page_category_manage | 分类管理 |
| page_product_manage | 商品管理 |
| page_brand_board | 品牌看板 |
| page_brand_manage | 品牌管理 |
| page_finance_board | 财务看板 |
| page_supply_finance | 供应链财务操作 |
| page_sale_finance | 销售财务操作 |
| page_sale_return_finance | 退货财务操作 |
| page_finance_type | 财务类型 |
| page_tax_invoice | 税票管理 |
| page_store_purchase | 选购商品 |
| page_store_purchase_cart | 购物车 |
| page_store_purchase_orders | 销售单查看 |
| page_user_manage | 成员管理 |
| page_province_manage | 省份管理 |
| page_pending_approval | 待审批 |
数据读写权限（集中在供应链与销售侧）
| 权限码 | 名称 |
|---|---|
| supplier_read | 供应商读 |
| supplier_write | 供应商写 |
| supplier_order_read | 供应链订单读 |
| supplier_order_write | 供应链订单写 |
| supplier_order_cost_read | 供应链订单采购价格读 |
| supplier_order_cost_write | 供应链订单采购价格写 |
| supplier_order_status | 供应链订单状态更改 |
| store_read | 商户读 |
| store_write | 商户写 |
| sale_order_read | 销售订单读 |
| sale_order_write | 销售订单写 |
| sale_order_price_write | 销售订单售价及折扣写 |
| sale_order_status | 销售订单状态更改 |
商品 / 品牌 / 仓库 / 财务模块只有页面权限，能进页面即可读写，无更细字段级分化。
附录E FAQ 与异常处理
| 现象 | 可能原因 | 处理 |
|---|---|---|
| 左侧看不到某个菜单 | 没分配对应页面权限 | 找管理员加 page_* 权限 |
成本/采购价显示 * |
无 supplier_order_cost_read 权限 |
申请采购价读权限（服务端脱敏，非 bug） |
| 开销售单提示库存不足 | 可用库存 = 实物 − 占用，被别的订单占用 | 查占用来源（库存变动记录/在途订单） |
| 销售结算点不了 | 订单未出库，或关联供应链订单未结算 | 先出库、先供应链结算（见 11.7） |
| 供应链订单改不了 | 已发货/在途，不支持改单 | 走退货/补单；未履约可作废 |
| 审批列表里没有我的单 | 单子状态不是「待审批」，或不在你的数据范围 | 确认已提交、确认审批人数据范围 |
| 计税不对 | 商户地区税区错，或 SKU 是否含税设错 | 核对省份税率与 SKU has_tax |
| 运费分摊失真 | 各 SKU 体积填错 / 各柜货运分配错 | 核对体积与货运信息分配 |
| 盘点改不平库存 | 盘点不改总库存 | 用入库/出库/销毁修正总量 |
| 临期/缺货预警 | 库存临近过期或低于阈值 | 临期考虑促销/销毁，缺货安排采购 |
附录F 数据录入规范建议
- SKU 编码：一旦使用尽量稳定，它是库存/订单/财务对账的关联键，改名改码会断关联。
- 体积（m³）：必填且真实。单件体积决定了运费分摊与装柜测算，错则全盘失真。可用长/宽/高（cm）反推，但优先直接填 m³。
- 是否含税（has_tax）：按商品真实税务属性设，影响销售计税。
- 原产国 / 海关编码：跨境必备，报关与统计用，建档时一次填准。
- 商户地区（税区）：建商户必选对，决定计税税率。
- 命名：规格名中/繁/英三语分别填，便于多语言团队与商户门户展示。
- 单位 / 计量（uom）：统一口径，避免同一商品不同单位造成混乱。
- 税区/财务类型：上线前先配好「省份与税率」「财务类型」，再开业务单。
附录G 历史数据导入（非日常模块）
仅在上线初始化或数据迁移时使用，日常运营不需要。入口在系统管理相关导入功能。
系统提供三类历史数据导入：
| 导入 | 用途 |
|---|---|
| 历史订单导入 | 把上线前的供应链/销售历史单据批量导入，延续业务连续性 |
| 历史库存导入 | CSV 全覆盖导入：先将当前主账户各维度库存归零，再按 SKU 与仓库写入默认维度数量 |
| 商品图片导入 | 按 SKU 编码批量匹配上传商品图片 |
库存迁入：先明确覆盖范围
管理后台的历史库存导入接收 inventory_stock.csv，按商品编码和仓库编码预览。数量使用 SKU 的库存单位，保留最多两位小数；包装数不会乘到数量上。空值、负数、无效数量和重名编码须修正或明确匹配，勾选哪些行就只写入哪些行。仅在源商品与仓库编码均完整、组合重复时保留最后一行；编码缺失的记录分别保留，明确选择各行的目标。预览和执行结果显示来源行号，便于回到原文件核对。不同源记录若指向同一目标 SKU 和仓库，须先明确重复还是总量的组成，不能直接合并或丢弃。
这是当前主账户的全覆盖操作：确认后先将各货架、批次等维度的库存数量归零，再写入选中行的默认维度库存。CSV 未包含的库存也会归零，已有货架、批次的成本和维度资料保留，库存变动写入流水。存在订单预留或锁定量时会拒绝清零，先处理相关业务再切换；不要用全覆盖覆盖日常经营中的库存。
批次失败会停止，重试覆盖该批全部行，已经成功的批次不重复执行；跳过的批次尚未迁入，不能作为完整迁移结果。离开页面或切换账户会停止后续请求，已发出的请求可能完成，先读取当前库存与流水再继续。清零和各批次是独立请求，整次导入并非一个事务。
Agent 的自由导入采用另一种范围：opening_stock 经 MCP 按 SKU 与仓库设置默认维度期初数量，不执行全账户清零，也不替换所有货架、批次的总库存。目标数量不能低于该行的订单预留与锁定量。先核对现有库存并选择期初快照或历史重放，避免重复累计实存。详见自由导入。
商品图片：预览、导入与重试
图片以 SKU 编码命名，例如 CASE-12.png。解析所选文件，核对匹配商品并勾选要导入的图片。同一 SKU 多张源图或商品匹配不明确时，不加入可导入列表；先为每个 SKU 保留一张图片。确认导入会替换该 SKU 的原图片。
页面逐个上传，在失败项处停止。修正问题后再次确认，会从该项继续，已成功的图片不重复上传。离开页面或切换账户会停止后续上传，并清理本地预览；服务器已经收到的上传可能已完成，结果未知时先核对实际图片再重新操作。
历史订单导入会修改哪些记录
供应链订单导入会创建入库单、增加库存并确认采购成本；销售订单在有足够带采购成本的库存时会创建出库单、扣减库存并核算，不足时保留为已下单。两类导入会创建税票；默认不生成收付款记录，只有提供实际金额与日期才登记真实流水。核对历史单据、库存与实际收付款后再导入。
展开每单预览，可填写实际收付款金额（正数 CAD）和实际日期，也可在订单头 CSV 增加可选列 Paid Amount (CAD)、Payment Date。日期支持 YYYY-MM-DD 或 YYYY/MM/DD，按多伦多业务日期记录。付款外币使用独立的 Paid Currency、Paid Amount (FC)、Paid Exchange Rate 三列，须同时填写，并满足“外币金额 = CAD 金额 × 付款汇率”。这些是 Wholety 的可选扩展列，订单自身的外币金额与汇率不作为付款凭据。
订单关闭、过账日期和到期日不证明已收 / 已付；部分付款也不表示结清。确认弹窗会展示收付款笔数与 CAD 合计，导入结果分别展示登记笔数和未导入收付款的订单数。没有凭据时可先导入订单，随后通过财务模块登记真实流水。
外部单号、重试与取消单
订单头 CSV 的 Internal Number 是外部来源单号。系统为导入订单生成独立 ID，导入结果提供“来源单号与系统订单 ID 对应关系”；后续查看订单、补记收付款或出库须使用系统订单 ID。不同主账户可使用相同外部单号，数据各自隔离。旧历史订单的 ID 和金额保留。
同一主账户内，同类型订单的来源单号只导入一次；修改订单备注后重试仍会跳过，也不会重复增减库存或登记收付款。同一订单头文件含重复单号（包括 500 与 000500）时会阻止提交。来源单号须为正整数，不能使用科学计数法或超过可准确表示范围的数值。
原单 Canceled / Cancelled 的 N 表示正常，Y 表示取消，C 表示冲销；取消与冲销单不能进入普通库存及财务导入，无效标记也会被拦截。Document Status=C 是关闭状态，与取消标记分别判断，正常关闭的单据仍可导入，关闭不证明已付款。历史取消记录若需要保留，应另行处理，不能作为正常收货、出库或收付款依据。该拦截不会自动冲销既有历史库存或流水。
导入金额核对
采购应付按本次商品金额＋订单折扣计算，税额单独登记，货运费用单独核算。销售应收按本次商品金额＋全部优惠（负数）＋税额计算。原单 Document Total 只保留作核对依据，不能直接替代本次应付 / 应收，也不能作为实际付款金额。
展开订单的“导入金额核对（CAD）”，可填写额外订单折扣（负数表示优惠）并调整本次税额。订单头 CSV 也支持 Wholety 可选扩展列 Order Discount (CAD)。销售原单的折前 / 折后单价差额作为行优惠保留，额外订单折扣在行优惠之外分摊；不要重复填写。系统不会把无法解释的总额差异自动认作折扣。
商品 CAD 金额优先来自原单 CAD 行总额与原数量；缺少行总额时按单价与币种汇率换算。导入采用已交付数量（未提供时采用原数量），部分交付只计算本次导入的商品金额及对应税额，额外订单折扣也应填写本次份额。只有订单税额时按商品金额分摊，各行分摊合计保留到分；商品金额为零时按数量分摊。
原单总额、税额或单价与导入金额不一致，以及部分交付时，页面会要求核对并确认差额。修改折扣或税额后须重新核对。销售 CAD 单价精度为两位，采购为六位；原单的单价、币种、数量和行总额另存来源日志。非法数字、超精度金额、优惠超过商品净额等情况会阻止提交，不能通过勾选确认绕过。确认弹窗分别展示采购应付 / 销售应收与实际收付款合计。
主账户可直接操作。子账户除订单导入页面权限外，还须具备相应的**订单写、审批、成本写（采购）或售价写（销售）、供应链或销售财务、出入库、财务看板（税票）**权限；缺少任何一项都会在创建记录前拒绝。页面会显示当前所缺权限。通过 Agent 导入时，API Key 需要写权限。
销售导入的可用量为实物库存减去冻结量和其他订单预留量，仅使用已有采购成本的采购库存。导入可以跨仓库配货，每次实际收货或出库都有独立记录，保留数量、成本和仓库来源。子账户只能导入其可见供应商或商户的订单。
结果会分别显示创建数、已出库数和保留已下单数；未出库的订单会列出缺货或核算失败原因。创建成功不代表已经出库，处理原因后再走正常出库流程；重复导入相同单据会跳过。
通用流程：下载系统模板 → 按模板填数据 → 上传并校验 → 系统批量写入。
⚠️ 模板的列结构（必填字段、格式）以系统内实际下载的模板为准。写入前务必小批量试导并核对，避免脏数据污染主数据。导入属不可逆写入，操作前确认数据正确。 具体模板字段与示例，建议在系统导入界面实际查看后补充到本附录（待截图环节核实）。
附录到此结束。手册正文（第1–12章）+ 附录（A–G）构成完整的使用手册。 系统截图已配齐；英文版（En）正在编写，完成后可在顶栏切换。