开始上线：一步一步发布陪跑 →
新增：官网、Android / iOS 与按端发布操作说明 →
DWZ COMMERCE / 2026-10-16 / v0.7.0

微信商城
部署与运营操作手册

给第一次配置服务器的 DWZ 经营者。按顺序执行，每一阶段都有明确的完成标志。

当前为可本地验证的开发初版。本地测试与网页流程验证不代表微信真机、支付商户、吉客云企业接口或服务器已经验收。真实凭证尚未在本项目配置；阿里云购买、Docker运行、微信开发者工具编译和正式发布均待执行。不要直接向消费者开放收款。

01 / 你得到的系统

首期按你已确认的范围开发：已有公司小程序账号、支付商户号和备案域名；面向中国大陆，人民币结算，快递发货；会员提供资料、等级和积分，不做储值。

组成作用在哪里
原生微信小程序商品、规格、购物袋、结算、支付、订单、售后、会员、客服、隐私授权miniapp/，在微信开发者工具导入
运营后台上传图片、多规格和价格、品牌页头和会员卡、首页活动、订单售后、会员、客服工单、同步异常、账号权限运行后访问 /admin
商城服务与数据库服务端定价、事务库存、会话权限、支付验签、积分流水、ERP队列与读回src/、持久数据 data/
网页预览方便经营者在电脑上操作演示流程，与后台使用同一数据本地 /preview；正式环境关闭
部署工具Docker编排、HTTPS、配置生成、备份检查、小程序配置及预检compose.yaml、deploy/、scripts/
谁来负责：你负责实名账号、经营规则、商品资料和最终发布；技术人员负责私密凭证、服务器和联调；仓库负责吉客云库存及发货；客服负责接待、退货和隐私申请。本手册可交给受托技术人员逐项执行。

02 / 先在自己的电脑上体验

  1. 打开 DWZ/dwz-commerce 文件夹，双击 启动DWZ商城.command。首次可能需要在系统设置中允许你明确检查过的本地脚本运行。脚本启动后，请保留终端窗口。
  2. 浏览器打开 本地入口。选择“体验商城”或“管理后台”。这里的 127.0.0.1 代表当前电脑，不是公网服务器地址。
  3. 仅本地默认账号为 admin，默认演示密码为 DWZ-local-demo-2026!。生产配置工具会另外生成随机长密码，禁止沿用本地密码。
  4. 商城中选择演示商品→加入购物袋→前往结算→填写测试信息→提交订单→模拟支付。后台“订单与售后”会看到同一订单。
  5. 后台打开该订单→填写演示物流单号→提交演示发货。商城订单刷新后确认演示收货。若要验证积分，先在后台“商城设置”开启赠送积分，再新建订单；已有订单保留原积分比例。
  6. 在商城“我的”查看订单、会员等级、积分；“咨询与售后”提交测试工单。后台客服工作台回复后，商城刷新工单即可看到回复。

完成标志：你能在商城创建订单，并在后台查看、发货；客服能双向回复。这里不会扣真实微信款项，也不会生成真实吉客云单据。

关闭终端窗口或按 Ctrl+C 可停止本地服务。再次启动会保留本地数据。请不要把本地 data/ 复制到正式环境；正式环境从空库建立真实商品与账号。

技术人员本地运行

node scripts/init-env.mjs
node --env-file=.env src/server.mjs
# 另开终端进行检查
node scripts/check.mjs
node --test --test-concurrency=1 tests/*.test.mjs

需要Node.js 24。本机Codex已有可用运行时，启动脚本会自动寻找；换到其他电脑时请安装对应版本。

03 / 开发前已经核对的微信规则

规则本项目的对应做法上线时你要做的事
通讯域名需预配置，HTTPS及有效证书，不能把AppSecret放客户端小程序只请求商城API，微信服务由后台调用配置request/downloadFile合法域名；域名指向服务器，保持证书有效
微信登录code由服务端换取身份，session_key不得下发后端换取OpenID，自建有效期会话核对真实AppID和AppSecret归属；真机验证登录
处理个人信息应声明用途并进行所需授权主动登录与下单同意，手机号隐私授权组件，保留政策版本与同意记录公众平台声明与后台正文保持一致，披露ERP和物流的必要处理
支付由服务端下单、验签并查询最终状态APIv3签名、通知验签解密、商户/币种/金额/用户检查，查单与关单绑定商户与AppID，私密配置密钥，验证支付和退款
交易类小程序按适用要求接入发货管理ERP发货→微信录入；官方收货组件后再查状态核对发货管理开通状态、物流编码与结算流程
原生客服使用微信指定入口open-type="contact"，另有商城工单公众平台添加客服人员，验证接待
类目、认证、小程序备案与代码审核需完整商家政策与备案可配置，不伪造资质域名备案不等于小程序备案；按实际商品核对类目

官方来源见末尾。开发者工具临时跳过域名检查只适合开发；真机和上线验收须正常校验。支付使用官方仍支持的普通商户共享下单接口，不擅自切换未对该商户开放的新能力。

04 / 系统如何连接，数据以谁为准

顾客小程序 → HTTPS商城服务 → 数据库与同步队列 → 微信支付 / 吉客云

员工使用浏览器后台，顾客无需接触后台。服务器全天运行，因此关掉你的电脑不会影响已部署商城。

数据主要来源原则
商品图文、售价、上架商城后台SKU映射真实ERP货品、规格、条码；编码保留前导零
收款与退款最终结果微信支付前端提示不作为凭证；重复通知不重复扣库存、推单或记积分
分仓库存、实际发货指定ERP仓库与店铺本地额度与ERP快照取保守上限；快照超120秒暂停该SKU销售
订单商城网店订单号 + ERP销售单号已支付才推单；查重、读回；未知结果先查单，不盲目重建
会员商城编号 + ERP客户ID独立编号映射，不按手机号直接合并；等级使用明确ID映射
积分商城流水为本期拟采用主账，ERP保留确认值完成赠送、退款撤回；绝对余额更新仅限确认单写方范围
库存与积分边界：查询库存不等于跨渠道原子锁库存。同仓被其他平台抢占时，需要ERP可验证的预占策略或商城独立额度。crm.customer.edit 可改绝对积分余额，不能据此声称支持并发安全的跨渠道增减。多个系统改同一会员积分时，先约定主账与原子更新/幂等机制；本项目默认关闭积分写入。

首版为单服务器、单Node进程、SQLite WAL架构，适合先验证独立商城流程；未经负载测试不承诺高并发。没有实现RDS切换、多实例或多仓分批发货。大规模投放前需要容量测试并评估数据库迁移。

05 / 上线前整理资料

你已有关键账号，先核实状态和归属。密钥仅在公司认可的密码管理器、服务器密钥目录或安全配置界面录入。

资料找谁 / 去哪里完成标志
小程序AppID、主体、认证、小程序备案公众平台→设置/基本设置、备案主体正确、认证有效、备案通过、管理员能扫码
商户号、AppID绑定、商户API序列号/私钥、APIv3密钥、微信验签公钥ID/文件商户平台→产品中心/开发配置、账户中心/API安全同一商户授权，私钥不发聊天
域名与DNS权限、网站备案归属域名与备案负责人能增加api子域；换接入商核实接入备案
ERP企业、店铺ID/名、仓库编码/名、应用订阅吉客云管理员/客户经理一个已知SKU/订单完成限定范围只读核对
等级ID、积分规则与唯一写入方运营 + 吉客云实施确认主账、门槛、跨渠道规则
正式商品、客服及政策商品、仓库、客服负责人图文价格与库存核实；服务、售后、开票、隐私声明一致
演示等级为探索者（0元）、行路者（累计完成消费1000元）、远行者（3000元），演示比例为每完整1元商品金额1积分。这些不是已确认的DWZ经营政策，赠分默认关闭。上线前按公司规则修改并核对ERP等级ID。

06 / 购买阿里云服务器

步骤1：选账号与地域

  1. 使用公司拥有的阿里云账号，完成企业实名，开启MFA，保留公司管理员，避免唯一所有权落在外包个人账号。
  2. “云服务器ECS”→创建实例。按主营用户与运营地点选择中国大陆地域，例如杭州或上海；应用与备份资源统一规划。
  3. 起步可用 2核CPU / 4GiB内存 / 80GiB ESSD系统盘，按商品图片和实测压力调整。这是工程起步估算，不是官方性能承诺。
  4. 选择 Ubuntu 24.04 LTS、x86_64，分配公网IPv4或EIP；Linux版吉客云CLI须同架构。
  5. 购买页逐项核对实例、系统盘、公网带宽/流量、备份费用；以当天控制台报价为准，不采用固定促销价。先验证实际负载再决定长期配置。

步骤2：安全组与登录

端口来源用途
80/TCP公网跳转与证书验证
443/TCP公网小程序API、支付通知、后台HTTPS
22/TCP管理员固定公网IP，或用WorkBench/云助手维护，不长期对所有公网开放
8787与数据库端口不对公网开放Docker私网由Caddy转发

采用密钥对登录，为维护人员分配明确权限。443需给顾客访问，后台另用办公室IP白名单限制。参见阿里云安全组说明。

完成标志：实例运行、公网地址已记录，WorkBench或SSH可登录，权限在公司控制内。

07 / 上传程序、域名与HTTPS

步骤3：安装Docker

按阿里云Docker与Compose安装指引选择Ubuntu页签逐条执行，不混用其他发行版命令。完成后检查：

docker --version
docker compose version

两条均返回版本才继续。

步骤4：上传代码包

本机项目运行 node scripts/package.mjs，通过WorkBench上传或受控SFTP把不含数据/密钥的压缩包传到服务器，例如/tmp目录。服务器执行：

sudo mkdir -p /opt/dwz-commerce
sudo chown "$USER":"$USER" /opt/dwz-commerce
cd /opt/dwz-commerce
tar -xzf /tmp/DWZ商城源代码_2026-10-16.tar.gz
mkdir -p data backups secrets/wechat secrets/jky tools
sudo chown -R 1000:1000 data backups secrets/wechat secrets/jky
chmod 700 data backups secrets secrets/wechat secrets/jky

下文服务器命令均在 /opt/dwz-commerce 执行；不上传本地演示数据。

步骤5：添加域名解析

  1. 现有DNS控制台→添加A记录，主机记录api，值为ECS公网IPv4。例如拥有example.com，得到api.example.com；这是格式示例。
  2. 核对已有AAAA记录是否真能访问正确IPv6，避免部分手机访问错误地址。
  3. 核对备案主体及接入服务商，按备案控制台确认是否需接入备案。小程序备案在公众平台单独核实。

步骤6：生成正式配置

使用临时Node容器生成.env，将示例域名替换为你拥有的真实域名：

docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/work" -w /work \
  node:24-bookworm-slim node scripts/init-env.mjs --production --domain api.example.com

用安全编辑器打开.env。随机后台密码与数据密钥只存入权限600文件，不会打印。数据密钥需独立备份；后续不得重新生成，否则旧收货信息和客服正文无法解密。

配置填写
PUBLIC_DOMAIN仅域名，不带协议或路径
PUBLIC_ORIGIN同域名完整HTTPS地址，不带末尾斜杠
ADMIN_ALLOWED_CIDRS办公室公网IP加/32；多个CIDR用空格分隔并保持引号。文档示例203.0.113.10/32须替换
CHECKOUT_ENABLED初期false，限定体验联调阶段再开启
WECHAT_MODE / JKY_MODEWECHAT_MODE=live；首次基础部署 JKY_MODE=disabled，ERP 联调阶段再切换 live；不复制模拟配置
JKY_WRITES_ENABLED初期false，先限定范围只读核对

修改ADMIN_PASSWORD只影响空库首次建账号；已有后台账号改密需专用重置脚本。

首次生产配置会设置 SMS_MODE=disabled、TRUSTED_PROXY=true，并关闭官网/App 支付。仅在使用随项目的 Caddy 且后端不对公网开放时信任代理。基础部署检查使用 docker compose exec api node scripts/preflight.mjs --stage infrastructure；完整业务配置检查仍使用默认 preflight，按各端进度联调。

步骤7：启动HTTPS服务

docker compose build
docker compose up -d
docker compose ps
docker compose logs --tail=50 api
docker compose logs --tail=50 web

Caddy在DNS正确且80/443可达时申请续期证书。访问 https://API域名/healthz 应显示 {"ok":true}；办公室IP访问/admin有登录页，其他IP受限。证书失败查DNS、安全组、CAA及Caddy日志。

healthz正常只表示进程可响应。当前未实际运行Docker，首次部署必须验证镜像、Linux CLI和编排。正式发布前固定已验证的Node/Caddy镜像版本和摘要，并保留升级记录。

08 / 微信登录、支付及原生小程序

步骤8：私密配置凭证

  1. 管理员核对小程序AppID，将AppSecret私密写入.env的WECHAT_APP_SECRET。
  2. 商户管理员核对AppID绑定与支付权限，填WECHAT_MCH_ID、WECHAT_MCH_SERIAL和32字节WECHAT_API_V3_KEY。
  3. 商户私钥放 secrets/wechat/apiclient_key.pem；微信验签公钥放 secrets/wechat/wechatpay_public_key.pem，对应ID填WECHAT_PAY_PUBLIC_KEY_ID。也可用已核实的当前平台证书及序列号，必须与文件一致，不能拿商户证书当微信验签公钥。
  4. 私钥由运行用户1000可读，权限400/600，只读挂载；禁止放public、miniapp、Git或交付包。
  5. 支付通知为 /api/hooks/wechat/pay，退款通知为 /api/hooks/wechat/refund，程序随请求提交完整HTTPS地址，公网不得加后台IP限制。
  6. 本实现固定一个微信验签标识。轮换时安排维护窗口，核对新公钥和ID、重启并补查期间订单；当前无自动证书轮换器。

步骤9：公众平台配置

“小程序后台→开发→开发管理/开发设置→服务器域名”加入API域名到request和downloadFile。当前商品图使用同域名；浏览器后台上传不要求顾客侧uploadFile。以后改OSS/CDN需同步配置和验证。

隐私指引按真实情况声明：微信身份、会员昵称、主动授权手机号、收货姓名/电话/地址、订单和咨询；说明用途、公司联系渠道及吉客云/承运方处理必要履约信息。手填地址同样是个人信息，不能因未调用微信地址接口就漏声明。

步骤10：导入微信开发者工具

# 本地源码目录，仅填写公开信息
node scripts/configure-miniapp.mjs --appid wx真实AppID --api https://api.你的域名
  1. 从微信官方入口安装开发者工具，用有开发权限的微信号登录。
  2. 导入 dwz-commerce/miniapp，核对真实AppID，小程序模式。
  3. 保持域名检查开启，编译并查看控制台。默认api.example.invalid不能连接，必须先配置。
  4. 真机预览至少覆盖iOS、Android，测试隐私同意/拒绝、登录、图片、支付取消/成功、收货、客服和工单。

已提供12页及隐私组件，目前仅通过代码结构与JS语法检查，未完成微信开发者工具编译及真机验收，网页预览不能替代它们。

09 / 吉客云ERP、会员与积分

步骤11：限定企业和接口

  1. 管理员在官方开放平台建专用自研应用，核实企业、店铺、仓库、权限与订阅。先准备一个已知SKU和一笔已知订单作只读样本。
  2. 从官方CLI页下载匹配ECS架构的Linux版，核对来源、版本与可获得的发布校验资料，放到tools/jky-cli。本机只验证过官方v1.0.0帮助，不代表Linux版已验收。
  3. 管理员私密运行configure。业务参数以权限600临时文件传递、调用后删除，不放进命令行或普通日志。
chmod 755 tools/jky-cli
# configure期间临时可写，日常服务仍只读
docker compose run --rm --no-deps \
  -v "$PWD/secrets/jky:/home/node/.jky-cli:rw" \
  --entrypoint /opt/jackyun/jky-cli api configure

按CLI真实提示操作，核对凭证确实写入挂载目录并仅运行用户可读。若版本使用别的安全存储，先由官方确认路径再调整；不猜环境变量，不打印配置。

目的官方方法核验重点
货品规格erp-goods.goods.getforqimen分页从0开始，编码/规格/条码一致；后台逐SKU配置，未批量迁入整租户
分仓库存erp-stock.stock.skulist限定货品/规格/条码/仓库，可用口径、延迟、扣减时点
推单读回oms.trade.ordercreate / oms.trade.fullinfoget网店号唯一、店铺ID/名、金额单位、付款语义、默认审核
会员与等级crm.customer.list / add / edit、crm.vipLevel.list响应形状、精确过滤、等级ID、空字段修改行为
积分crm.available.integral.balance、crm.integral.log；customer.edit含integralBalance可用与总分不同；绝对余额更新及其他渠道并发

逐方法契约成功码为200，CLI说明有0的不同表述。程序严格按逐方法核验；封装不一致时阻断，不把0全局视为成功。

步骤12：映射与只读核对

.env填JKY_TENANT_LABEL、JKY_SHOP_ID/NAME、JKY_WAREHOUSE_CODE/NAME，来源必须是本企业实际系统。后台商品填写每个SKU的条码和ERP货品/规格码；在数据中心拉取库存，和已知样本逐项比对。空或多行不能冒充零库存或随便合计。

核实专用仓/商城额度后设置JKY_STOCK_SCOPE_CONFIRMED=true。低金额实测确认金额为元或分后填JKY_MONEY_UNIT=yuan或cent；公开schema的integer和例子不足以证明单位。

步骤13：等级、期初积分与主账

# 仅格式示例，L1等换成本企业真实等级ID
JKY_LEVEL_MAPPING={"探索者":"L1","行路者":"L2","远行者":"L3"}
# ERP和微信物流编码不同，按两边清单填写
JKY_LOGISTICS_MAPPING={"ERP物流编码":"微信物流编码"}

会员使用独立DWZ编号保存ERP客户ID，不按手机号自动合并。已有会员迁入须另行去重、验证身份和期初对账，目前无自动迁移。

JKY_POINTS_WRITES_ENABLED与JKY_POINTS_SINGLE_WRITER默认false。仅当这些商城会员由商城独占改分，且ERP不按销售单再次赠分，才可开启。首次ERP积分需核实为零；非零期初将阻断，需另做迁入方案。

写前比对上次确认值，写后读回；资料同步不会把外部积分变动偷偷当新基线。门店/其他系统也会改分时，当前方案不足以保证并发，应与吉客云确认原子增减/幂等接口或改为ERP主账再扩展。未解决前不得宣布全渠道积分完全打通。

步骤14：受控实单写入

业务负责人确认店铺、仓库、样本和影响后开启JKY_WRITES_ENABLED，重建API容器。先一笔允许范围内的低金额单，核对金额、支付单号、ERP销售单、地址和每条SKU，再测发货回读。程序不自动调用ERP审核、过账或仓库发货，企业自身ERP是否自动审核需提前核实。

事件为“未知”只做读回核查；查不到唯一单据仍保持未知，人工查订单与日志后再决定，禁止重复新建或换单号规避不确定性。

新增：首页装修、六种尺寸板块、文字与按钮拖动、商品合集、限时活动价与到期恢复。详细步骤见首页装修与活动价操作说明。本版数据库为版本6；升级时前后端一起更新，旧客户端无法提供结算报价令牌时会要求重新核价。
本次新增帽子、鱼竿、眼镜定制及后台逐项开关，详见定制商品操作说明。配镜核对单在商家核对后才开放支付。

10 / 日常运营

商品上架

  1. 后台→商品管理→新建，填名称、分类、系列和准确介绍，沿用已确认DWZ品牌口径。
  2. 上传JPG/PNG/WebP，单张≤8MB，最多10张，首张主图；持久保存到服务器图片卷。
  3. 每个颜色/尺寸设独立SKU，填元售价、商城额度、安全库存及ERP映射；不用演示数值。
  4. 先草稿核对，拉ERP快照后改在售。有交易的SKU不换编码或ERP映射，新建规格；编辑遇并发冲突重新加载。

订单与退款

待支付预占15分钟；到期查支付并关单后释放。请求结果不明先保留占用。支付后推ERP，仓库按ERP流程发货；系统回读后录入微信。

首期支持整单全额原路退款。所有者批准前完成ERP拦截发货或验收退货，填写业务记录号并核实金额。退款不自动加回实物库存，实际回仓由仓库验收与ERP入库决定。部分退款、换货自动编排、拆单和多包裹尚需扩展。

客服

公众平台添加客服人员，使用微信官方工具接待contact会话；商城工作台保存独立工单，按订单查证、回复、解决后关闭。工单不是完整微信聊天历史镜像。配置真实客服电话和服务时间。

岗位权限

角色操作
所有者账号、配置、ERP控制、退款批准、审计
运营商品、订单、工单；实际发货在ERP
客服受控订单详情和工单，不能改价/退款
审计经营与脱敏列表、审计，不能读完整地址/私密工单正文

读取个人信息留审计，后台会话8小时。员工独立账号，离职停用；未集成SSO或MFA，后台保持IP白名单和长密码。

11 / 真实联调验收

先配置主体、隐私、售后和会员规则。在仅体验者可见的版本，用经允许的测试SKU、库存额度、店铺和一笔低金额订单验证。真实支付及ERP写入影响业务数据；验收完成前不向消费者开放。
检查操作通过标准
预检docker compose exec api node scripts/preflight.mjs配置存在性通过，同时记录不代表凭证或业务有效
原生开发者工具编译，真机iOS/Android页面、图片、域名、隐私组件正常
登录/隐私同意/拒绝，切换体验者浏览不强制登录，拒绝不采集手机号，账号隔离
价格/库存重复提交、超库存、过期取消后台定价，幂等一单，库存非负，取消只释放占用
支付真机支付成功/取消，查商户平台与通知金额/商户/用户一致，服务端确认状态
ERP核网店号、店仓、SKU、单价、运费、总额唯一已付款销售单，读回金额一致，记录单位
异常隔离环境超时、重启未知不重复建单，查单后读回
发货ERP实际发货→微信通知→收货组件物流匹配，微信录入成功，再查收货状态才完成
会员/积分资料更新、完成、刷新、ERP核对、退款唯一会员、等级ID正确、一次赠分/撤回，差异不覆盖
退款实际拦截/验收证据→批准→查微信原路全额成功，状态一致，不自动加库存
客服微信即时会话及工单分别测试官方工具收到，工单双向可见
权限/备份客服尝试越权，隔离恢复备份拒绝越权，脱敏正确，原密钥可解密订单

用 docs/验收记录模板.csv 记录环境、时间、脱敏编号与真实结果，不把模拟测试冒充外部验收。日常由财务人工比较微信交易/退款账单、商城金额和ERP单据；当前没有自动微信T+1账单下载与对账任务。异常退款在商户平台按官方流程处理，不重复发起普通退款。

12 / 提审与发布

  1. 归档DEMO商品，录入核实资料，排除演示价、示意图、占位域名、测试联系方式。
  2. 确认主体、类目、认证、网站备案、小程序备案；政策经公司核实并在后台确认。
  3. 开启已验证的ERP配置，积分仍须满足单写方条件；CHECKOUT_ENABLED=true后先在仅体验者版本完成真实联调。
  4. 配置预检、全部测试及真机通过后，开发者工具上传版本号和说明。
  5. 公众平台→版本管理→开发版本→提交审核，按实际商品类目补资质和体验路径，不公开密钥。
  6. 审核通过，由有权限管理员确认客服、仓库、财务就绪后发布。
  7. 发布后普通账号复测入口与交易，首日关注通知、ERP异常、库存快照、工单和磁盘。

有任一支付、会员或积分联调未完成，就保留体验阶段并记录未完成项；“live”只是配置值，不能代替验收。

13 / 备份、恢复和升级

每天备份

内容办法注意
数据库docker compose exec api node scripts/backup.mjsSQLite在线备份、完整性与SHA256；不只拷运行中的主库漏掉WAL
图片data/media目录副本与数据库快照一起保留
密钥/配置公司密码管理器或独立加密备份不和公开代码混放，丢失无法解密
代码/镜像私有版本库和发布归档保留已验证摘要与回退说明

同一ECS磁盘备份无法抵御整机/磁盘损坏。可用公司OSS私有桶或备份服务保存异机副本，禁止公开读写，规划费用与生命周期。自动上传和告警渠道目前未配置，需技术人员在公司授权下实施。需要每日定时备份时由技术人员创建系统任务并监测退出状态；本次没有替你创建后台定时任务。

恢复演练

  1. 隔离环境执行 node scripts/verify-backup.mjs 备份.sqlite，核摘要与完整性。
  2. 使用对应的原数据密钥恢复数据库/图片，关闭对外下单与真实微信/ERP。先做只读解密检查，不能把生产同步队列直接启动到真实服务。
  3. 生产恢复先暂停下单、备份现状、停API，保留事故目录，再按选定快照恢复；不能留下新WAL/SHM与旧主库混用。
  4. 旧快照可能缺失后续交易，必须对微信支付/退款和ERP补账，核对前不开放支付推单。

更新程序

cd /opt/dwz-commerce
docker compose exec api node scripts/backup.mjs
# 把备份复制到异机，再按版本说明更新代码
# 保留.env、secrets、data、backups；升级仍要先备份
docker compose build api
docker compose up -d --force-recreate api
docker compose ps
docker compose logs --tail=50 api

环境变量变化需重建容器，单纯restart不会加载新的Compose环境。代码回退不等于真实业务回退，不能撤回退款或已发货。

密码重置

有权管理员通过私密标准输入使用scripts/reset-admin.mjs 用户名，设置至少20位新密码并注销全部会话；不把新密码写到命令行参数、历史、工单或截图。

14 / 常见问题

现象检查及处理
本地打不开启动窗口是否关闭、8787占用；保持一个服务进程，区分电脑与公网地址
后台403办公室公网IP变化；管理员SSH更新白名单并重建web，保留限定范围
HTTPS失败A/AAAA/CAA、安全组80/443及Caddy日志；修正配置，不绕过安全警告
小程序域名错误request/downloadFile、证书链、公开API地址；正常校验下复测
上传图看不到持久卷、文件权限、图片域名；保存商品后刷新
有库存不能买映射、120秒快照、商城额度、预占、安全库存；核对单SKU，不盲目加额度
说已付但本地未付查微信真实支付单、商户、通知验签；不凭截图改状态
ERP未知在限定店铺按网店号人工查单，读回核查；不重复新建
积分不同步单写方、等级、期初与外部变化，核对流水及主账，不覆盖消差
退款待核查查退款号和最终状态，ABNORMAL在商户平台按官方异常流程处理
微信客服没接待公众平台客服权限、工具登录、服务时间；商城工单不能替代即时会话
恢复不能解密找回对应DATA_ENCRYPTION_KEY，不反复换随机密钥或删库

报错提供请求编号、时间、页面、脱敏业务号及现象；不发密钥、Cookie、完整地址或原始个人信息日志。

15 / 当前范围与待办

已实现且有本地验证路径

原生页面/API、后台商品图片SKU、订单售后、权限与隐私、会员等级积分、工单、微信APIv3连接器、ERP限定方法与未知处理、部署和备份工具。

必须真实验证

原生编译、iOS/Android、凭证、真实收退款、微信收发货、ERP租户字段与金额、积分语义、Linux CLI/Docker、域名证书及发布审核。

本期不含储值、积分抵现、营销券、自动整租户货品导入、自动合并会员、部分退款、多仓多包裹编排、自动微信账单对账、自动证书轮换、SSO、多实例高可用。遇到业务需扩展测试，不以占位界面假装已支持。

商品、会员及订单列表目前最多200项，工单/审计也有限量；大规模运营前补分页、历史搜索和归档，轮询需容量验证。正式投放还需要独立安全审查、告警渠道及长期维护安排。

图片素材备份补充

备份图片时，请同时保留数据目录中的 media/（展示图片）与 media-originals/（私有原图和取景记录）。后者只应由已登录的所有者或运营管理员通过后台读取，不要配置为公开静态目录。只恢复展示图片仍能正常展示，但会失去从原图重新取景的能力。数据库备份命令不会代替这两个目录的文件备份。

16 / 官方资料

2026-10-16实际获取核对；微信部分页面由公开HTTP下载读取，因检索工具无法直接展示全文。docs/research保存获取记录和接口契约；未调用企业真实API。

服务器规格、数据归属及上线顺序为本项目工程判断；接口开放、资质、菜单和费用以你们实际账号与操作时官方平台为准。

17 / 定制功能上线补充

本次还增加商品管理 → 定制资格 / 邀请：入口显示/隐藏、当前商城积分门槛、指定会员的一次性定制链接。链接在一笔定制订单成功提交后核销。设置步骤与微信正式链接条件见入口与邀请操作说明。v0.7.0开发阶段的92项全量测试通过，真实链接生成及微信真机跳转待联调。

请按定制操作说明核对Logo尺寸、实际节数/编号、色卡及配镜接单范围，填写加价，并在后台逐项开放。三角主Logo用于正式品牌界面，W小人用于会员和客服。配镜资料先由商家核对再付款，核对单24小时过期，核对后付款期限15分钟。

数据库已增加版本6迁移（包含定制资格、一次性邀请、首页内容、活动成交快照和多端发布），升级前按第13节备份。程序自动增加列并保留历史订单。ERP定制备注读回和实际加工单验收完成前，保持JKY_CUSTOMIZATION_VERIFIED=false；正式定制下单还要求商品工艺确认。默认色号、尺寸、价格及接单范围只是演示。

多端支付补充

微信、支付宝、银行卡与手机钱包的当前进度和逐步申请要求，见支付开通指南。源码部署需先安装根目录锁定依赖 npm ci --omit=dev --ignore-scripts。升级支付模块前备份数据库；schema 8 记录原始支付通道、商户和环境。