edgeone-pages-website-skeleton

Website Skeleton Skill — EdgeOne Pages 全栈网站骨架

Scaffold and deploy a production-ready full-stack website on EdgeOne Pages from a single natural language request.

When to use this skill

• User wants to start a new full-stack website (e-commerce, AI chatbot, SaaS admin) with zero config
• User mentions: e-commerce, shopping cart, payment, AI chat, admin dashboard, login/register, or similar
• User wants Edge Functions + Cloud Functions + KV + MySQL on EdgeOne Pages

Do NOT use for:

• Adding a single API/function to an existing project → use edgeone-pages-dev
• Deploying an already-built project → use edgeone-pages-deploy
• Pure static sites or blogs without business logic

⛔ Critical Rules (never skip)

1. ALWAYS ask the user to confirm the scenario first. Three built-in templates are available:
2. E-commerce (🛒)：Auth + Cart + Payment (WeChat/Alipay) + Orders + Admin
3. AI Assistant (🤖)：Auth + AI Chat (SSE streaming) + Admin
4. SaaS Admin (📊)：Auth + RBAC Admin + Subscription Payments
5. Never fabricate the user's requirements. If information is missing, ask clarifying questions before generating code.
6. Respect EdgeOne Pages platform constraints:
7. KV is only accessible from Edge Functions (not Cloud Functions)
8. Cloud Functions directory must be named cloud-functions/
9. bcrypt must run inside Cloud Functions
10. AI SSE streaming must be implemented in Cloud Functions (Edge cannot use waitUntil)
11. Payment idempotency is mandatory. Use Edge putIfNotExists with 24h TTL (< WeChat retry window of 72h).
12. Never commit .env.local or any real API keys. Ensure .gitignore covers it.
13. Always verify EdgeOne Pages CLI is installed before deployment.

Main Flow

Step 1 — Confirm scenario

Use ask_followup_question to ask:

你想要建什么类型的网站？ - 🛒 电商站 — 登录注册、购物车、微信/支付宝支付、订单管理 - 🤖 AI 客服站 — 登录注册、AI 对话（SSE 流式）、访客留言 - 📊 SaaS 管理后台 — 登录注册、RBAC 权限、数据看板 - ⚙️ 自定义 — 自由组合模块

Branch:

• E-commerce → use references/templates.md § "电商模板"
• AI Assistant → use references/templates.md § "AI助手模板"
• SaaS Admin → use references/templates.md § "管理后台模板"
• Custom → confirm which modules are needed

Step 2 — Collect requirements

Read references/templates.md and confirm with user:

1. Site name / domain
2. Which modules to enable (Auth always required)
3. Payment providers (WeChat / Alipay / Both / None)
4. AI provider (if AI Chat enabled)

Output: a Spec object

{
  "scenario": "e-commerce | ai-assistant | saas-admin | custom",
  "siteName": "...",
  "modules": ["auth", "cart", "payment", "ai-chat", "admin"],
  "paymentProviders": ["wx", "ali"],
  "aiProvider": "openai | hunyuan | none",
  "envVars": ["JWT_SECRET", "DATABASE_URL", ...]
}

Show the Spec back and ask for confirmation.

Step 3 — Generate project structure

Based on the selected template, generate the following directory tree:

<project>/
├── client/                     # Next.js frontend (SPA)
│   ├── app/ (pages: login, register, cart, checkout, orders, admin/*)
│   ├── lib/ (api client, auth service, cart service, SSE client)
│   └── middleware (optional, for pure SPA)
├── edge-functions/            # Edge Functions (V8 + KV)
│   ├── _middleware.js         # JWT check + KV session + rate limit
│   └── api/
│       ├── auth/login.js     # JWT issue + KV session
│       ├── auth/me.js        # KV session read
│       ├── auth/refresh.js   # RT rotation with KV version lock
│       ├── auth/logout.js
│       ├── internal/idempotency.js  # Edge atomic idempotency lock ← P0
│       ├── products/list.js  # KV cache + MySQL fallback
│       ├── cart/*.js         # KV cart
│       ├── orders/list.js    # MySQL read
│       └── ai/history.js     # KV AI session history
├── cloud-functions/          # Cloud Functions (Node.js + MySQL)
│   ├── api/
│   │   ├── auth/register.js  # bcrypt cost=12 ← P0
│   │   ├── pay/create-order.js
│   │   ├── pay/wx-notify.js  # Edge idempotency lock ← P0
│   │   ├── pay/ali-notify.js
│   │   ├── order/create.js   # SELECT FOR UPDATE ← P0
│   │   ├── order/cancel.js
│   │   ├── admin/products.js
│   │   └── ai/chat-stream.js  # SSE streaming ← AI module
│   └── utils/
│       ├── db.js             # MySQL pool (mysql2/promise)
│       └── payment-sdk.js    # WeChat V3 / Alipay SDK
├── db/
│   ├── migrations/001_init.sql  # users, products, orders, order_items
│   └── seed.sql
├── docs/
│   └── env-vars.md           # Environment variable matrix
└── references/
    └── auth-module.md / payment-module.md / ai-chat-module.md / kv-storage.md

Generate each file according to references/ documents.

Step 4 — Environment variables

Read references/env-setup.md (or inline from SKILL.md § Environment Variables) and:

1. List all required env vars for the selected modules
2. Ask user to provide values (or provide placeholder examples)
3. Remind: never commit .env.local

Step 5 — Local verification

Guide user to run locally:

npm run dev   # Next.js on http://localhost:3000

Verify:

• Homepage renders
• Auth signup/login works
• Selected modules (cart / payment / AI chat) are functional

Step 6 — Deploy to EdgeOne Pages

6.1 — Check edgeone-pages-deploy skill

Check if ~/.codebuddy/skills/edgeone-pages-deploy/ exists (or Windows equivalent). If yes → go to 6.2. If no → go to 6.3.

6.2 — Hand off to deploy skill

✅ 项目已就绪，本地跑通后随时可以部署。 告诉 AI 「部署到 EdgeOne Pages」，会自动加载 edgeone-pages-deploy skill 完成上线。

6.3 — Manual deploy

# Install CLI (first time)
npm install -g edgeone@latest

# Login
edgeone login --site china

# Deploy
cd <project>
edgeone pages deploy -n <project-name>

⚠️ The final URL contains eo_token / eo_time query params — must be kept, removing them causes 401.

Routing

| Step | Read | |------|------| | Scenario confirmation + module matrix | [references/templates.md](references/templates.md) | | Auth module (JWT, KV session, bcrypt, RT) | [references/auth-module.md](references/auth-module.md) | | Payment module (idempotency, WeChat/Alipay, callbacks) | [references/payment-module.md](references/payment-module.md) | | AI Chat module (SSE, history, streaming) | [references/ai-chat-module.md](references/ai-chat-module.md) | | KV Storage strategy (single query, layered access) | [references/kv-storage.md](references/kv-storage.md) |

Quick Reference

Demo: https://geek-mall-demo-4qaxvmeh.edgeone.cool

Platform constraints:

• KV → Edge Functions only
• bcrypt → Cloud Functions only
• AI SSE → Cloud Functions only
• Platform Middleware → CORS, CSP, Bearer check, Payment callback IP whitelist (direct return)

P0 Security (all implemented):

• Payment idempotency: Edge putIfNotExists (24h TTL)
• Order atomicity: SELECT FOR UPDATE + optimistic lock + MySQL CHECK
• RT concurrency: KV version optimistic lock (409 retry)
• Price integrity: Server-side MySQL (never trust frontend price)
• Payment callback isolation: Platform Middleware direct return
• Password: bcrypt cost ≥ 12

Template repos: https://github.com/TencentEdgeOne/edgeone-pages-skills

⚠️ 安全与合规说明

1. 部署确认机制

AI Agent 部署前会显示待部署文件清单和变更概要，请求用户确认后执行部署。

2. 支付安全

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

3. 数据保留策略

| 数据类型 | 存储位置 | 保留期限 | |---------|---------|---------| | KV Session | EdgeOne KV | 7 天 TTL | | AI 聊天历史 | EdgeOne KV | 30 天 TTL | | 审计日志 | EdgeOne KV | 90 天 TTL | | 订单数据 | MySQL | 永久（业务必需）|

4. Cron 定时任务

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

5. 使用建议

• 在测试项目中验证全部功能
• 使用测试/沙箱商户号
• 部署前审查生成的代码和环境变量
• 启用真实支付前完成签名验证测试