SuperAPI AI 工具集

edgeone-pages-website-skeleton

编程与开发

查看项目

更新于 10-16 08:24

技能介绍

用途

Website Skeleton Skill 用于在 EdgeOne Pages 上从一句自然语言请求,脚手架并部署一个可直接投产的全栈网站。适用于用户想要零配置新建全栈站点(电商、AI 客服、SaaS 管理后台),或提到电商、购物车、支付、AI 对话、管理后台、登录注册等需求时。

不适合的场景:为已有项目添加单个 API/函数(应使用 edgeone-pages-dev)、部署已构建完成的项目(应使用 edgeone-pages-deploy)、不含业务逻辑的纯静态站点或博客。

主要能力

内置三类模板:

  • 电商(🛒):Auth + Cart + Payment(微信/支付宝)+ Orders + Admin
  • AI 助手(🤖):Auth + AI Chat(SSE 流式)+ Admin
  • SaaS 管理后台(📊):Auth + RBAC Admin + 订阅支付

同时支持自定义,自由组合所需模块(Auth 始终必需)。

生成的项目目录结构包含:

  • client/:Next.js 前端 SPA(页面、lib 中的 API 客户端/鉴权/购物车/SSE 客户端)
  • edge-functions/:Edge Functions(V8 + KV),含 _middleware 及各 API,如登录、会话读取、刷新、登出、幂等锁、商品列表、购物车、订单列表、AI 历史
  • cloud-functions/:Cloud Functions(Node.js + MySQL),含注册、支付下单、微信/支付宝回调、订单创建/取消、后台商品、AI 流式对话、数据库连接池与支付 SDK 工具
  • db/:migrations 与 seed.sql
  • docs/:环境变量矩阵
  • references/:各模块参考文档

使用方式

技能按以下主流程执行:

  1. 确认场景:通过提问让用户选择电商 / AI 客服 / SaaS 后台 / 自定义。
  2. 收集需求:确认站点名/域名、启用模块、支付渠道(微信/支付宝/两者/无)、AI 服务商(如启用 AI Chat),输出一个 Spec 对象(含 scenario、siteName、modules、paymentProviders、aiProvider、envVars)并回显确认。
  3. 生成项目结构:依据所选模板生成上述目录树,并参照 references 中对应文档生成每个文件。
  4. 环境变量:列出所选模块所需的全部环境变量,请用户提供值或给出占位示例,并提醒不要提交 .env.local。
  5. 本地验证:npm run dev(Next.js 运行在 http://localhost:3000),验证首页渲染、注册登录、所选模块(购物车/支付/AI 对话)可用。
  6. 部署到 EdgeOne Pages:检测是否存在 edgeone-pages-deploy 技能,存在则交接部署;否则手动部署:
# 首次安装 CLI
npm install -g edgeone@latest

# 登录
edgeone login --site china

# 部署
cd <project>
edgeone pages deploy -n <project-name>

部署后最终 URL 携带 eo_token / eo_time 查询参数,必须保留,移除会导致 401。

平台约束与安全实现

平台约束:

  • KV 只能从 Edge Functions 访问(Cloud Functions 不可访问)
  • Cloud Functions 目录必须命名为 cloud-functions/
  • bcrypt 必须在 Cloud Functions 中运行
  • AI SSE 流式必须在 Cloud Functions 中实现(Edge 无法使用 waitUntil)
  • 支付幂等为强制要求,使用 Edge putIfNotExists 并设 24h TTL(小于微信 72h 重试窗口)
  • 不得提交 .env.local 或任何真实 API 密钥,需确保 .gitignore 覆盖
  • 部署前必须确认 EdgeOne Pages CLI 已安装

P0 安全实现(均已实现):

  • 支付幂等:Edge putIfNotExists(24h TTL)
  • 订单原子性:SELECT FOR UPDATE + 乐观锁 + MySQL CHECK
  • RT 并发:KV 版本乐观锁(409 重试)
  • 价格完整性:价格以服务端 MySQL 为准,不信任前端价格
  • 支付回调隔离:平台中间件直接返回
  • 密码:bcrypt cost ≥ 12

支付安全:回调实现 HMAC-SHA256 签名验证(微信官方算法)、校验 appid/mchid 商户身份一致性、校验回调金额与订单金额完全匹配、仅接受 result_code=SUCCESS 的交易状态、KV 幂等锁防止重复回调处理。

平台中间件:CORS、CSP、Bearer 检查、支付回调 IP 白名单(直接返回)。

数据保留策略

  • KV Session:EdgeOne KV,7 天 TTL
  • AI 聊天历史:EdgeOne KV,30 天 TTL
  • 审计日志:EdgeOne KV,90 天 TTL
  • 订单数据:MySQL,永久(业务必需)

定时任务(Cron)

  • PENDING 超时 30 分钟 → CANCELLED
  • SHIPPED 超过 7 天 → COMPLETED
  • 提供一键禁用脚本 cloud-functions/cron/disable-cron.js

适用场景与限制

适用:快速从零搭建带业务逻辑的全栈站点,尤其是电商、AI 客服、SaaS 后台三类场景,并希望直接部署到 EdgeOne Pages。

限制与注意事项:只适用于新建项目而非改造既有项目;部署确认机制要求 AI Agent 在部署前显示待部署文件清单与变更概要并请求用户确认;建议先在测试项目中验证全部功能,使用测试/沙箱商户号,部署前审查生成的代码和环境变量,启用真实支付前完成签名验证测试。

参考资料

  • Demo:https://geek-mall-demo-4qaxvmeh.edgeone.cool
  • 模板仓库:https://github.com/TencentEdgeOne/edgeone-pages-skills
  • 其他信息:暂未提供