ECNext：一个部署，一家全球化店铺

ECNext 是面向独立站的电商模板，同时服务零售客户与企业买家。每个部署只对应一个品牌、一个域名、一套 PostgreSQL 数据库以及独立的第三方服务凭据。商务功能只依赖 PostgreSQL：多副本共享的限流状态保存在数据库表中，不需要额外的缓存服务。

为什么坚持单店单部署？

每个品牌都可以独立修改店铺、集成和运营规则，不必让运行时多租户路由侵入商品、价格、库存与订单决策。独立部署也让备份、密钥轮换、故障处理和品牌版本发布更容易审计。

当前可以直接使用的能力

• B2C 商品发现与下单：多语言目录、搜索、筛选、商品详情、规格与库存状态，购物车持久化保存在服务端。访客与已登录买家都可以完成结账：服务端会重新核对商品价格、优惠、配送与税费，写入不可变的订单快照，并且只有在支付通过验证后才预留库存。访客还可获得带令牌的订单状态页与可打印的收据。
• B2B 企业采购：企业成员、指定价目表、数量阶梯、报价、采购单、隔离的买家工作区，以及完整的应收账款台账——授信决策、发票、客户回款、核销、贷项通知单与账龄分析，买家可在采购单详情页查看对账结果。
• 售后履约：创建与取消货件、完整的轨迹状态流转（轨迹事件记录在货件上，而非从承运商接口拉取）、买家在交付后 30 天窗口内发起退货（该窗口由接口强制校验）、仓库收货，以及以商品退款或企业信用额度完成结算。
• 运营后台：商品、库存、企业、定价、采购、订单、履约、应收、经营分析、RBAC、内容、客服与供应商设置。
• 交付基础：PostgreSQL 与经过评审的迁移历史、pnpm stack:up（certs → postgres → migrate → app，并附带通知投递与加密备份工作进程）、无生产密钥镜像构建、多语言 SEO 路由和 GHCR 发布流程。

仍然取决于商家配置的部分

以下都是配置边界，而不是尚未编写的代码。每个交易环节都已实现并有测试覆盖，但都需要只有店铺运营方才能提供的值。

• 支付渠道：结账需要一个已启用的渠道——Stripe、支付宝或微信支付——并在 Admin 设置中填入商家自己的凭据。在启用之前，只有经过验证的零金额订单可以提交，并在内部结算、不创建外部支付会话。
• 退款执行：退款记录在任何情况下都会生成，但把钱通过渠道退回取决于适配器：Stripe、微信支付与 PayPal 适配器支持，支付宝与 Creem 适配器不支持。
• 税费与运费：两者都在结账时依据运营方配置的规则报价——按目的地配置的税率规则（价外税）以及配送区域、方式与费率。系统不调用第三方税务引擎或承运商实时报价接口，因此未配置费率的目的地就没有报价，订单也无法提交。
• 交易类邮件：订单、货件与退货通知会写入发件箱并由投递进程发送，而投递需要商家自己的邮件服务凭据。
• 已发布政策与店铺主体信息：配送、退换货、联系、隐私、条款与 Cookie 页面均以“未经法律审阅的模板”形式提供，并在页面上明确标注。法定名称、地址以及至少一个匿名联系渠道来自 Admin 设置；在填写之前，联系页会提示店铺联系信息尚未发布完整。

有两处区分是刻意保留的，而不是未完成：平台 billingOrder 记录（账号订阅与用量积分）不是商品销售订单；Admin 中的积分记录也不等于已批准的授信额度。

保持这种边界正是目的所在：已完成能力可以直接使用，依赖配置的能力明确标注为依赖配置，不用静态页面伪装交易闭环。

启动开发部署

# package.json 的 `packageManager` 已锁定 pnpm 11.15.0。可通过
# `corepack enable && corepack prepare pnpm@11.15.0 --activate` 激活，
# 或直接独立安装 pnpm 11.15.0。
pnpm install
cp .env.example .env

export COMPOSE_PROJECT_NAME=ecnext-dev
export POSTGRES_PASSWORD="$(openssl rand -hex 32)"
export AUTH_SECRET="$(openssl rand -hex 32)"
export CONFIG_ENCRYPTION_KEY="$(openssl rand -hex 32)"
export DATABASE_URL="postgresql://ecnext:${POSTGRES_PASSWORD}@127.0.0.1:5432/ecnext"

# 只需启动 PostgreSQL，没有额外的缓存服务需要运行。
docker compose -p "$COMPOSE_PROJECT_NAME" up -d --wait postgres
pnpm db:migrate
pnpm dev

容器化方式可用 pnpm stack:up：它会把开发用凭据生成到被 gitignore 的 .env.local，并依次启动 certs → postgres → migrate → app，同时带上通知投递与备份工作进程。

凭据应保留在当前进程或受保护的密钥存储中。店铺名称、描述、Logo、公开 URL 与默认语言等品牌值，是每个独立部署的公开构建输入。