面向东南亚跨境电商的 WhatsApp 多语言智能订单助手与自动化履约引擎。
Multilingual WhatsApp order assistant & automation engine for Southeast Asia cross-border e-commerce.
SolaFlow AI 专为出海东南亚及本地中小电商卖家打造。产品聚焦独立站订单履约关键生命周期，通过官方 WhatsApp Business Platform（Cloud API）提供合规自动化触达、智能多语言应答与原子人工接管支持。
| 业务场景 | 痛点 | SolaFlow AI 解决方案 | 预期成效 |
|---|---|---|---|
| 场景 A：未支付订单催付 | 东南亚独立站弃单率高，人工难以 24 小时实时跟进 | 订单创建 15 分钟后触发，核验订单、同意记录与静默时段后发出带安全恢复链接的本地化模板 | 提升待支付订单挽回率（内测目标支付率 ≥15%） |
| 场景 B：COD 发货前确认 | 货到付款（COD）拒签与虚假地址导致高额往返物流损失 | 订单创建 5 分钟后触发，向买家核验收货意愿，收集改址/取消诉求并同步商户审核 | 降低无谓发货与拒签率（内测目标下降 5～8 个百分点） |
| 场景 C：夜间多语言咨询 | 跨时区夜间咨询无人应答，本地俚语与缩写识别困难 | 在 24 小时服务窗口内以印尼语（支持常见俚语缩写）及英语自动解答商品与 FAQ | 缩短响应时间，保障夜间流量不流失 |
| 场景 D：原子人工接管 | 机器误答或买家投诉导致客诉升级与账号封禁风险 | 买家申请人工、改址/取消、退款投诉或达消息上限时，原子挂起自动化并进入专属客服队列 | 明确责任边界，保障高风险订单安全 |
| 场景 E：链上服务费结算 | 传统跨境小额支付开户门槛高、手续费贵、结算账期长 | 商户端使用 Solana Pay 原生 USDC 充值软件订阅与自动化 Credits，基于 finalized 交易单次原子入账 | 充值秒级到账，账本流水可核验审计 |
⚠️ 关键业务与资金边界：
- 买家货款与物流款：买家商品货款在商户原有支付网关结算，COD 仍按商户既有物流渠道收款；本系统不介入买家货款交易。
- Solana Pay 独立用途：仅用于商户向 SolaFlow AI 购买软件订阅套餐和充值自动化 Credits。
- 无自动平台改单：系统沉淀买家改址、取消诉求及确认凭证，由商户在原独立站后台核实操作，不擅自越权修改商户电商订单。
根据 PRD v1.1 规划，系统严格界定首发交付边界：
┌────────────────────────┐
│ 首发版本 (MVP) │
│ - WooCommerce 独立站 │
│ - 印尼语 / 英语 │
│ - WhatsApp Cloud API │
│ - 印尼市场 15m 催付/COD │
│ - Solana Devnet/USDC │
└───────────┬────────────┘
│ 验证通过后演进
▼
┌────────────────────────┐
│ 后续扩展路线 │
│ - Shopify 独立站 │
│ - TikTok Shop / Shopee│
│ - 泰语 / 越南语 / 马来语 │
│ - Solana 主网原生结算 │
└────────────────────────┘
| 维度 | 首发版本 (MVP) 包含 | 后续扩展或非目标 |
|---|---|---|
| 电商平台 | WooCommerce（已创建未支付订单、COD 订单） | Shopify、TikTok Shop、Shopee、Lazada |
| 消息通道 | 官方 WhatsApp Business Platform (Cloud API) | Baileys / WPPConnect 扫码接入（仅作技术研究，不承诺交付） |
| 支持语言 | 印尼语（含常见缩写如 bisa COD?、ongkir brp?）、英语、中文商家后台 |
泰语、越南语、马来语、菲律宾市场语言 |
| 发送合规 | 营销模板、24h 客户服务窗口、21:00～09:00 静默时段、买家退订严格停止、滚动 24h 频控（最多 2 次） | 未经授权的主动群发、越过退订限制的补发 |
| 计费单位 | 1 Credit = 同租户、同店铺、同买家在 24h 窗口内的自动化额度（上限 20 条消息） | 任意金额折算、无上限滥用、无底线负余额 |
| 支付结算 | 原生 USDC、Solana Pay 二维码/深链接、基于 finalized 交易原子入账 | 法币代收代付、EURC、自动代扣续费 |
- 全栈框架：Next.js 16.3.8（App Router 架构，强制 React Server Components 优先）
- UI 核心：React 19.2.8 + TypeScript 5（
strict: true） - 样式体系：Tailwind CSS 4 + CSS 变量设计令牌（对齐 UI 设计规范）
- 动效与交互：GSAP 3.15、Motion 14、Three.js 0.186（支持
prefers-reduced-motion降级） - 图标系统：Lucide React
- 链上支付组件：
@solana/kit(v8.4.0)、@solana-program/token、qrcode
严格遵循 AGENTS.md 规定的三层状态流转，避免远端缓存与本地状态混杂：
┌───────────────────────────────────────────────┐
│ UI Presentation │
└───────┬───────────────────────┬───────────────┘
│ │
┌─────────────▼─────────────┐ ┌─────▼─────────────────────────┐
│ React Local Hooks │ │ Zustand Client Store │
│ (useState / useReducer) │ │ (stores/use-app-store.ts) │
│ • 弹窗开关 / 表单本地草稿 │ │ • 跨页筛选偏好 / 全局 UI 状态 │
└───────────────────────────┘ └───────────────────────────────┘
│
┌─────────────▼─────────────────────────────────────────┐
│ TanStack Query (@tanstack/react-query) │
│ • 订单列表 / 财务账本 / 会话消息等服务端数据缓存与失效 │
└───────────────────────────────────────────────────────┘
本项目保持单一 Next.js 16 App Router 全栈代码库，禁止另起独立 NestJS 服务或通过 rewrite 转发后端。服务端架构已在 Next.js 全栈 API 接口契约 中完整定义：
app/
api/v1/**/route.ts # HTTP 薄适配器：解析、鉴权、校验、调用服务、映射响应
(console)/**/page.tsx # Server Components 优先，直接调用服务端服务与数据访问层
lib/server/
auth/ # OTP、会话、CSRF、RBAC 租户鉴权
db/ # PostgreSQL 连接、迁移与事务管理
dal/ # 按租户、角色、店铺范围授权后的数据访问
validation/ # 请求入参和外部数据运行时 Schema 校验
services/ # 订单、会话、工作流、计费、报表领域服务
integrations/
woocommerce/ # WooCommerce API 与凭证适配
whatsapp/ # WhatsApp Cloud API 客户端与模板校验
solana/ # Solana Pay 账单构建与 finalized 校验
webhooks/ # 外部 Webhook 验签、持久化、去重和乱序协调
jobs/ # 异步入队与后台调度任务定义
audit/ # 脱敏审计流水
types/
api/ # 客户端与服务端共享的可序列化 API 契约类型
├── app/ # Next.js App Router 页面、布局与 Route Handlers
│ ├── (marketing)/page.tsx # 官方首页 (Landing Page / ROI 计算器)
│ ├── login/ # 商户登录与模拟认证
│ ├── onboarding/ # 店铺与 WhatsApp 通道开通引导
│ ├── console/ # 商户工作台核心界面
│ │ ├── page.tsx # 工作台总览 Dashboard
│ │ ├── orders/ # 订单流水与多阶段自动化状态
│ │ ├── inbox/ # 统一会话中心与人工接管队列
│ │ ├── workflows/ # 自动化规则、时区与频次控制
│ │ ├── stores/ # 绑定的独立站与 WhatsApp 号码
│ │ ├── knowledge/ # 商户 FAQ 与商品知识库
│ │ ├── billing/ # 订阅套餐、Credits 余额与充值
│ │ └── settings/ # 租户配置、成员角色与审计日志
│ └── api/v1/ # 全栈 Route Handlers (auth, orders, billing 等)
├── components/ # 可复用 UI 组件
│ ├── landing/ # 落地页业务组件 (Hero, ROI, TopoMesh 等)
│ ├── billing/ # 充值与 Solana Pay 交互组件
│ └── ui/ # 基础原子 UI 组件
├── docs/ # 核心业务、设计与工程规范文档
│ ├── PRD.md # 产品需求文档 (v1.1 权威基准)
│ ├── API.md # Next.js 全栈 API 接口契约
│ ├── UI_DESIGN.md # 视觉与交互设计规范
│ ├── whatsapp-integration-guide.md # WhatsApp Cloud API 接入指南
│ ├── channel-feasibility-review.md # 东南亚电商与消息通道可行性
│ └── plans/ # 强制 MVP 计划与执行记录目录
├── lib/ # 客户端工具库与 lib/server/** 服务端领域模块
├── public/ # 静态资源 (Logo、SVG 图标等)
├── stores/ # Zustand 客户端共享状态
├── ui_design/ # UI 原型设计与规范拆分文档
├── package.json # 依赖清单与工程脚本
└── AGENTS.md # 团队与 AI 协作规范 (行数 ≤ 200)
| 路由路径 | 页面定位 | 核心能力与操作 |
|---|---|---|
/ |
官网落地页 | 产品价值传递、动态 3D 网格、交互式 ROI 收益测算器、套餐定价方案 |
/login |
商家认证 | 商家邮箱/工作台登录、租户身份切换演示 |
/onboarding |
接入向导 | WooCommerce 凭证授权验证、WhatsApp Business 通道配置与测试样例验证 |
/console |
经营总览 | 今日自动化订单、COD 挽回率、待人工会话、Credits 余额与快捷动作 |
/console/orders |
订单管理 | 订单同步状态、工作流阶段（已排队/已送达/已停止）、买家意愿标记 |
/console/inbox |
会话与客服 | 多语言双向消息流、AI 自动问答证据、一键人工接管（独占处理权） |
/console/workflows |
自动化工作流 | 15 分钟催付规则、COD 确认规则、静默时段设置、频次上限配置 |
/console/stores |
店铺与通道 | WooCommerce 绑定状态、WhatsApp 模板审批状态、Webhook 连通性 |
/console/knowledge |
知识库 | 商品增量同步状态、商家审核 FAQ、事实冲突标记 |
/console/billing |
财务与支付 | 套餐有效期、Credits 消耗流水、Solana Pay USDC 点数充值与状态追踪 |
/console/settings |
租户设置 | 成员管理与 RBAC 权限（所有者/管理员/客服/财务）、数据保留与脱敏 |
- Node.js：
>= 22.9.0（推荐使用 LTS 版本；pnpm payments:db/pnpm payments:worker依赖--env-file-if-exists） - 包管理器：固定使用
pnpm@11.17.0（仓库严格维护pnpm-lock.yaml，禁止混用 npm/yarn）
# 1. 克隆代码仓库
git clone https://github.com/your-org/solana.git
cd solana
# 2. 安装依赖（遵循严格锁文件）
pnpm install --frozen-lockfile
# 3. 准备本机环境变量（.env 已提供 dev 安全默认值，只需填机密与本机覆盖项）
cp .env.example .env.local
# 然后编辑 .env.local，填入 DATABASE_URL、签名密钥等真实值
# 4. 启动本地开发服务
pnpm dev启动完成后，在浏览器中打开 http://localhost:3000 即可预览落地页与控制台。
环境变量分三层，键位说明与占位符以 .env.example 为准：
| 文件 | 用途 | 是否提交 |
|---|---|---|
.env |
非机密、对所有环境安全的默认值 | 是（禁止写入真实凭证） |
.env.local |
机密与本机覆盖项，优先级高于 .env |
否 |
.env.example |
占位符模板，新人从这里开始 | 是 |
Next.js 按 .env.local → .env 顺序加载（后者覆盖前者）。pnpm payments:db 与 pnpm payments:worker 用 --env-file-if-exists 加载同样的两个文件，需 Node ≥ 22.9.0。
💳 Devnet 支付入口：
/console/billing仅对已登录并已绑定商户租户的账户开放，未登录访客会被拒绝。该入口只写test_credit_ledger，不产生正式权益；主网正式计费保持关闭。本地跑 devnet 需在.env.local中设PAYMENTS_DEVNET_ENABLED=true并提供SOLANA_RECIPIENT。
🔒 安全守则：私钥、WhatsApp Access Token、数据库密码等敏感密钥严禁写入客户端暴露的变量，严禁提交到公共代码仓库；
.env会被提交，任何真实凭证只能写在.env.local或部署平台。
在提交任何代码前，必须执行以下检查门禁：
# 1. ESLint 代码质量检查
pnpm lint
# 2. Next.js 类型生成与 TypeScript 严格检查
pnpm exec next typegen && pnpm exec tsc --noEmit
# 3. 生产环境打包构建
pnpm build
# 4. 启动生产构建服务
pnpm start为了保障业务可靠性、商户数据隐私及资金账本绝对正确，开发过程中必须恪守以下不变量：
- 财务账本绝对精确
- 金额与链上代币数量必须使用最小整数单位（如 USDC 6 位精度下的最小整数）存储。
- 严禁使用浮点数（Float/Double） 计算财务金额。
- Solana Pay 验证与入账单向性
- 不把钱包签名或交易提交当作充值成功。
- 必须通过服务端读取 RPC 节点，确认交易达到
finalized最终确定性，并完整校验网络、Mint、收款方、精确金额与唯一 reference 后，原子入账一次。
- 严格的租户隔离 (RBAC)
- 服务端依据认证会话（Cookie/Session）锁定当前租户，严禁信任前端传入的
tenant_id。 - 客服角色不可访问财务中心，财务角色不可手动无证据增减 Credits。
- 服务端依据认证会话（Cookie/Session）锁定当前租户，严禁信任前端传入的
- 合规自动化与安全熔断
- 主动消息严格遵守 WhatsApp Business 消息政策与获批 Marketing 模板。
- 买家一旦发送退订关键词（如 STOP/UNSUBSCRIBE），立即停止所有主动触达。
- 遭遇未决异常、退款争议或改址取消申请，自动化立即原子转入人工接管。
- 📘 PRD 业务需求文档 (v1.1)：业务定义、KPI 口径、场景规则与验收标准。
- 🔌 Next.js 全栈 API 接口契约：RESTful 契约、数据流转与安全边界。
- 🎨 UI 设计规范 & UI 规范索引：视觉设计语言、色彩令牌、排版系统与交互规范。
- 💬 WhatsApp 官方接入指南：Cloud API 接入流程、模板规则与扣费说明。
- 📊 东南亚电商与通道可行性评审：各渠道接口可行性与市场研究。
本仓库所有功能需求均执行规范的 MVP 迭代闭环（详见 AGENTS.md）：
- 任何需求实施前，必须在
docs/plans/YYYY-MM-DD-<slug>/下建立plan.md明确背景、范围、分阶段测试与验收标准。 - 开发推进过程中，必须同步维护该目录下的
result.md，真实记录各阶段执行结果与遗留问题。 - 未经过独立测试或存在未解决阻塞时，禁止虚报通过。
本项目依据业务规划开发，当前演示环境数据均为 Demo/Mock 仿真。未经过正式商业授权与安全审查前，请勿用于真实资金交易与生产环境短信群发。