跨境云使用手册

更新日期：2026 年 11 月 6 日。本文对应当前版本。独立 OMS 已完成隔离数据库、真实 HTTP 和浏览器联调，未操作正式数据库；正式运行仍需配置服务器、真实来源数据与发件服务。保存结果以页面成功提示与再次读取为准。

先启动网站

在项目文件夹双击“启动跨境云.cmd”，保持启动窗口运行。普通用户前台地址为 http://127.0.0.1:4173/，总部管理台为 http://127.0.0.1:4173/admin.html。不要双击 index.html 办理登录、导入或订单操作；file:// 只是本地外观预览，不能连接后台同步商品和库存。

需要用手机查看总部后台时，在电脑上双击“手机访问启动.cmd”，手机与电脑连接同一个 Wi‑Fi，然后用启动窗口显示的局域网地址打开 /admin.html。手机端已适配抽屉导航、订单卡片和库存卡片；手机访问只在当前局域网开放，Windows 防火墙若询问请允许“专用网络”。

以后部署到服务器后，把上述地址换成正式网站地址即可。本地地址只在运行网站的这台电脑可用。

当前首页导航与代理流程

总部管理员在顶部“后台管理”菜单选择“打开总部管理台”“可视化编辑”“商品管理”或“编辑首页模块”。这四项仅管理员可见；一级代理仅显示“代理后台”。首页底部不再放总部编辑条。

英国、欧洲、墨西哥站点通过商品列表上方的下拉菜单切换，说明小字跟在下拉菜单后。首页左侧模式只保留“热门品类”和“经营概览”，重复的电商 Skills 入口已删除；资源分享仍从左侧货源目录进入独立资源页 /resources.html。

分销顺序为：注册并申请一级代理 → 总部审核后获取邀请码 → 邀请客户注册 → 客户订单产生分润。审核通过不等于已有客户订单；返佣以实际订单和佣金规则为准。

三种账户

按身份阅读：总部管理员看“总部：入口与日常顺序”；一级代理看“一级代理”；普通用户看“普通用户：选品与库存监控”。

密码不会通过邮件原样发给客户。忘记密码时，用户在登录窗口点“使用邮箱验证码找回”，收到验证码后自行设置新密码。注册验证码和找回密码依赖总部发件邮箱正常工作。

总部：入口与日常顺序

管理台侧栏“使用手册”可打开 /help.html。

新独立管理台地址为 http://127.0.0.1:4173/admin.html。只有管理员可进入。左侧按“待办 → 商品库存 → 订单采购 → 供应商 → 售后对账 → 设置”组织。

旧管理功能仍保留：网站 /#hq-fulfillment 打开“订单与发货”；/#hq-import 打开表格上品；/#hq-data 打开原数据工作台；/#hq-applications 处理代理申请；/#hq-mail 设置总部邮箱。

建议每天先看待办：处理库存未知或过期、确认待发货订单、生成采购任务、核实失败通知，再做财务对账。待办计数来自服务端，尚读取失败时会明确报错，不用空白或示例数字替代真实数据。

表格自动上品

点击“表格上品”或打开 /#hq-import → 下载上品模板 → 选择英国、欧洲或墨西哥站 → 选择填好的 .xlsx → “上传并预检” → 查看逐行错误和新增/更新结果 → 无错误后确认导入。

WPS 与 Excel 均可制作，单批最多 1000 行、文件不超过 30MB。请保留模板标题行，避免合并数据单元格。每行一款商品；同一批次不要重复 SKU。

图片支持普通链接、标准嵌入图片和解析器可读取的 WPS 单元格图片；不支持的 WPS 图片形式会在预检报告标出。链接必须能被服务器读取，不要使用自己电脑上的 C:\… 路径。提交后主图及详情会显示在商品模块和详情图库。

相同 SKU 是更新既有商品，不是另建一件。预检后有人改过该 SKU，系统会要求重新预检。库存不得低于已经预留给订单的数量。预检有错误时整批不提交；请先修正。

自动上品 API 位于导入窗口“自动上品接口”。单独生成受限密钥，仅展示一次。接口 POST /api/integrations/catalog/import 使用 Bearer 密钥，价格以整数分传递。此接口只导入商品，不代替支付、采购或文案制作。

商品库存：五个页签

“商品库存”看网站库存、订单预占、可售数、源头库存及核对状态。“上架热度”统计哪些商品被客户加入已上架清单；这不是平台实际销量。“客户统计”看客户上架/监控数量及风险。“库存核对”查看源头快照。“通知记录”查看邮件状态，失败记录可手动重试。

库存数量必须区分：网站库存是网站自己的记录；已预占是订单占用；可售数由服务端计算；源头数量是供应商给出的核实值。未知数量不等于 0，过期数据不代表仍有货。

真实规格 SKU 建档

商品库存表每行“规格SKU建档”进入编辑器。颜色、尺码有真实资料时可生成矩阵，生成行的库存全部为未知；SKU名称只是待核实草稿，需要逐项改成源头真实SKU后保存。不能把商品总库存平均分给颜色尺码。数量只有核实后才填写；留空表示未知，0表示明确无货。保存替换此商品规格清单，移除既有SKU前应核实其映射与监控影响。

供应商、映射与快照

1. “供应商 → 新增供应商”：填写名称、网址、站点、同步方式、时效和安全库存。
2. “新增商品映射”：选择供应商和网站商品，填写源 SKU；按规格核对时填写网站规格 ID 与源规格 ID。人工比对正确后才勾选已确认。
3. “导入库存快照”：选供应商、填任务编号，粘贴 JSON 数组或 CSV；先预检，再检查结果，最后确认写入。

CSV 标题可用：mappingId,sourceSku,sourceVariantId,quantity,observedAt,evidence。JSON 示例：

[{"sourceSku":"SOURCE-001","quantity":20,"observedAt":"2026-11-06T08:00:00Z","evidence":"供应商后台人工核实"}]

数量未知在 CSV 留空、JSON 填 null；只有明确无货才填 0。核对时间使用完整时间并带时区。不要把商品价格、销量或浏览次数误填库存数量。映射不明确、来源过期或数值错误时应先复核；以预检报告与服务端结果为准。

“API”同步方式只是来源配置，不代表网站已经会自动抓取任意供应商网站。自动采集还需要供应商可用接口、令牌或合法数据来源。创建接入令牌后只显示一次，请妥善保存并限制用途。

客户订单、采购和发货

客户已确认付款的订单才进入总部履约流程。打开旧“订单与发货”或在新台“售后对账 → 客户订单与发货”进入现有订单管理。

“订单采购 → 生成采购任务”把需要处理的订单整理为任务。点击“查看并登记”，选择真实供应商，填写供应商订单号、已采购数量、采购原币实际单价（整数分）、币种与备注，选择草稿、已登记或异常并保存。确认采购时要求供应商、订单号、全部采购数量和每行成本完整；草稿成本未知可以留空，不会自动记作0。采购原币不会自动折算成人民币财务成本，人民币利润仍按财务模块自己的成本口径核算。它是采购登记，不会真的向供应商下单或扣款。

发货请在订单管理登记真实物流信息。登记成功后客户的订单显示已提交发货及相应物流资料。不要把“采购已登记”当成“客户已发货”。

财务、充值与邮件

“售后对账”展示成交、成本、佣金和利润。缺少成本时显示未知，不推算利润。现有毛利口径为商品金额减采购成本与有效佣金，不等同扣除物流、税费、支付手续费后的最终净利润。

线下收款由总部核实后手工入账；不要在未收款时记充值。用户余额与充值记录需通过现有总部资产入口维护。新 OMS 没有新增在线微信支付通道。

“设置 → 总部发件邮箱”可保存 SMTP 授权码并测试。这里填邮箱服务生成的授权码，不是邮箱登录密码。成功收到测试邮件后再检验注册、找回密码与库存通知。发件名称为跨境云。

“设置 → 编辑网站销量榜单”先选择站点，再编辑趋势与排名，保存后公开展示。该榜单是总部发布内容，不能宣称实时成交统计。趋势每行使用“时间标签,非负数字”。

一级代理

普通用户提交代理申请后，总部在代理申请审核中处理。审核通过后重新刷新账户状态。一级代理登录入口为 /#agent-login。

代理后台仅展示通过自己邀请码注册客户的订单和佣金，订单可查看详情但由总部处理。今日、本月与累计佣金按系统计算结果展示；总部设置折扣与佣金规则，客户不能自行改。仅注册不产生佣金，取消、退款等按后台实际规则处理。

代理可在账户菜单进入“已上架商品”，添加自己在店铺经营的商品，设置接收邮箱与库存下限。它是经营清单，不代表本站替你向外部销售平台发布商品。

普通用户：选品与库存监控

1. 注册或登录，验证自己的邮箱。
2. 选正确站点，搜索/按类目查看商品。全部商品页不限首页三排展示数量。
3. 点商品图或名称进入详情，选择已有尺码、颜色；资料缺失时联系总部核实。
4. 点击购物车图标添加商品，再在购物车核对规格、数量与收货地址。
5. 在账户菜单进入“已上架商品” → 添加商品 → 设置库存监控。

监控时填写自己接收提醒的邮箱和整数阈值，选择需要关注的规格；可以全选规格，也可给不同规格设置各自下限。系统只按已保存的库存来源和规格资料判断，不会凭空知道供应商真实库存。

需要监控但没有规格库存时，不能把总库存当成每个颜色/尺码都有货。先联系总部补齐映射和数量。未知库存与实际零库存应分开对待。

邮件提醒的边界

监控设置保存成功不等于邮件已经发出。真实发送需要：总部发件箱配置有效、服务在线、库存更新被系统读取、监控启用且满足下限条件。供应商库存没有同步，网站就无法根据其变化提醒。

可查看“监控中、等待邮件通道、提醒待发送、本轮已发送、发送失败”等状态。邮件可能被服务商延迟或放进垃圾箱。单次库存波动的重复提醒由后台去重规则处理，不保证每次刷新都再发一封。

只有总部有通知失败重试与发件设置权限。用户可暂停或取消自己的监控，修改邮箱和阈值。请勿把未实际收到的邮件说成发送成功。

当前联调与未承诺功能

独立 OMS 已在隔离环境验证管理员六导航、供应商新增、规格 SKU、映射快照、采购登记与销量榜单真实读写，普通用户拒绝进入总部、代理仅查看自己邀请码客户订单、登录库存风险提醒只在显式登录后弹出。正式上线仍须用实际供应商数据和邮件通道验收。

任意供应商网站自动采集、外部平台自动刊登、真实自动采购付款、自动生成跨境物流单、服务器持续在线和生产邮箱投递率，不属于当前页面直接保证的能力。正式上线前应逐项使用测试商品与测试订单验收。

页面同步与库存购买规则

游客在当前标签页累计可见浏览 30 秒后会收到一次注册登录邀请；29 秒不弹，关闭后本标签页刷新也不重复。已登录用户不受该提醒打断。

总部修改商品后，普通网页可通过 CloudCatalogData.refresh() 立即重新读取；切回网页触发焦点刷新，页面可见时每 30 秒再同步一次。不同站点仍各自筛选。网络故障或标签页在后台会影响更新时机，不能当作供应商实时库存抓取。

有多个规格且部分库存未知时，详情按选中 SKU 判断：已核实并有货的规格可加入购物车；未知规格显示“库存待核实”并禁用购买，不显示成 0，也不把总库存分给未知规格。

API 文档与常用总部入口

• 商品库存页“表格上品”：/#hq-import。
• 订单采购页“客户订单与发货”：/#hq-fulfillment。
• 设置页常用入口：代理申请 /#hq-applications；代理折扣返佣 /#hq-agents；线下充值 /#hq-recharge；资源分享管理 /resources.html。
• API 文档入口：/api-docs.html（以当前部署是否提供该页为准）；商品自动上品接口说明同时保留在表格导入窗口内。
• 总部 OMS API 前缀为 /api/admin/oms/，要求管理员会话与 CSRF 校验；外部源头同步令牌按供应商授权，不可用于用户登录或付款。不要把管理员密码放进第三方工具。

资源分享：发布、观看与下载

资源页地址 /resources.html，首页左侧货源目录的“资源分享”和总部设置都可进入。页面自动识别当前会话，普通访客只看到已发布内容。

总部点击“＋ 发布资源”，填写标题、9 个分类之一及介绍。可上传 MP4/WebM 视频（不超过 64MB），或填写 HTTPS 视频链接。资料支持 ZIP/PDF/JSON/TXT 文件（不超过 20MB），或 HTTPS 链接；文件名不能带路径，服务器会校验文件签名和 JSON 内容。服务类资料可补充价格及联系方式。

上传后还须保存。默认是草稿，勾选“发布给用户”才公开；草稿文件匿名访问返回不存在。编辑卡片可以修改、取消发布下线或删除；遇到并发更新提示应先刷新。

用户可按分类或搜索找资源，点击“观看视频/详情”在弹层播放，点击“下载资料”获取文件。视频失败有错误提示，外链可尝试新窗口打开。资源页不要求登录查看已发布资料。隔离环境已验证约 49MB MP4 实际浏览器播放、匿名下载正文和普通用户管理权限拒绝；这不保证第三方外链永不失效。