建站骨架 (EdgeOne Pages)

一句话说需求，AI 生成完整前后端网站并自动部署到 EdgeOne Pages。支持电商栈（Auth/购物车/支付）、AI 栈（SSE 流式对话）、管理后台。触发词：帮我建网站、建一个电商网站、做 AI 客服站、建管理后台、EdgeOne Pages 建站

# 建站 Skill — EdgeOne Pages 全栈网站骨架

> **版本：** 2.3 · **日期：** 2026-05-04 · **安全强化更新**
> **一句话描述：** 用户说一句话，AI 生成完整前后端网站，自动部署到 EdgeOne Pages。

---

## 一、核心设计理念

```
一次设计，无限复用 = 5 个模块 × 3 个场景 × 1 个部署平台
```

将"建站"拆解为 **Layer 0 基础设施** + **Layer 1 能力栈** + **Layer 2 可选增强**：

| 层级 | 内容 | 性质 |
|------|------|------|
| **Layer 0**（Core） | SPA 骨架 + Auth + Middleware + EventBus | 必选，不可裁剪 |
| **Layer 1**（Stack） | 🛒 电商栈 · 🤖 AI 栈 · 📊 管理栈 | 按需组合，互不依赖 |
| **Layer 2**（Addon） | SEO · Analytics · i18n | 可选增强 |

**场景模板优先**：用户选"电商"、"AI 助手"或"管理后台"场景，不选模块——模块由模板自动组合。

---

## 二、技术架构

### 2.1 EdgeOne Pages 双运行时

```
┌──────────────────────────────────────────────────────────────┐
│  Platform Middleware（middleware.js）                        │
│  ① CORS 预检（OPTIONS）                                     │
│  ② CSP Header 注入                                          │
│  ③ 轻量 Bearer 检查（公开路径放行）                           │
│  ④ 支付回调 IP 白名单 → 直接 return，不进 Edge Middleware     │
└──────────────────────────────────────────────────────────────┘
                              ↓（非回调路径）
┌──────────────────────────────────────────────────────────────┐
│  Edge Functions Middleware（V8 + KV）                      │
│  ⑤ JWT 详细校验（crypto.subtle）                             │
│  ⑥ KV session 验证                                          │
│  ⑦ KV 限流计数器（滑动窗口）                                   │
└──────────────────────────────────────────────────────────────┘
```

### 2.2 运行时职责边界

| 运行时 | 存储 | 职责 | 说明 |
|--------|------|------|------|
| **Edge Functions**（V8） | KV | Auth 登录/me、Products 公开读、Cart、Orders 读、AI History 读、幂等锁 | 延迟敏感、无密钥 |
| **Cloud Functions**（Node） | MySQL | Auth 注册/bcrypt、Payment 创建/回调、Admin CRUD、Orders 创建/取消、AI SSE 流 | 密钥操作、复杂事务 |

> ⚠️ **平台约束（EdgeOne Pages）：**
> - KV 仅 Edge Functions 可用，Cloud Functions 无法访问
> - Cloud Functions 目录名必须为 `cloud-functions/`
> - bcrypt 必须在 Cloud Functions 中执行

### 2.3 分层目录结构

```
website-skeleton/
├── SKILL.md                    # 本文件，Skill 核心指令
│
├── templates/                  # 场景预设模板
│   ├── e-commerce.json         # 🛒 电商场景
│   ├── ai-assistant.json       # 🤖 AI 助手场景
│   └── saas-admin.json         # 📊 SaaS 管理后台场景
│
├── sharing/                    # 跨运行时共享（构建时同步）
│   ├── types.ts               # User/Product/Cart/Order/AISession 接口
│   ├── constants.ts           # OrderStatus/UserRole/APIPaths 枚举
│   ├── validators.ts           # 共享输入校验
│   └── kv-keys.ts             # KV key 命名（含租户前缀占位）
│
├── client/                     # 前端 SPA
│   ├── index.html
│   └── src/
│       ├── app.js             # 启动 + History API 路由
│       ├── utils/
│       │   ├── event-bus.js   # 全局事件总线（P0）
│       │   ├── router.js      # History API 路由 + AuthGuard
│       │   ├── escape-html.js # XSS 防护
│       │   └── storage.js      # localStorage 封装
│       ├── services/
│       │   ├── api.js          # 统一客户端 + 拦截器
│       │   ├── auth.js         # 内存 AuthService
│       │   ├── cart.js         # 双模式购物车
│       │   └── ai.js           # SSE 流式 AI
│       └── components/         # 组件清单
│
├── middleware.js               # Platform Middleware
│
├── db/                         # 数据库迁移
│   ├── migrations/
│   │   └── 001_init.sql        # 建表脚本
│   └── seed.sql                # 测试数据
│
├── docs/
│   └── env-vars.md             # 环境变量矩阵
│
├── edge-functions/             # Edge Functions（V8 + KV）
│   ├── _middleware.js          # JWT 校验 + KV session + 限流
│   ├── api/
│   │   ├── auth/login.js       # JWT 签发（Cookie） + KV session
│   │   ├── auth/me.js          # KV session 读取
│   │   ├── auth/refresh.js     # RT 轮换（KV version 乐观锁）
│   │   ├── auth/logout.js      # 清除 Cookie + KV session
│   │   ├── internal/idempotency.js  # Edge 原子幂等锁
│   │   ├── products/list.js   # KV 缓存 + Cloud MySQL 回源
│   │   ├── products/[id].js
│   │   ├── products/categories.js
│   │   ├── cart/*.js           # KV 购物车
│   │   ├── orders/list.js      # MySQL 订单读取
│   │   ├── orders/[id].js
│   │   └── ai/history.js       # KV 读取 AI 会话历史
│   └── utils/
│       ├── kv-helper.js
│       ├── jwt-helper.js       # crypto.subtle HS256
│       ├── rate-limit.js        # KV 滑动窗口限流
│       └── response.js
│
├── cloud-functions/            # Cloud Functions（Node.js）
│   ├── api/
│   │   ├── auth/register.js   # bcrypt cost=12 + MySQL
│   │   ├── pay/create-order.js # 微信/支付宝预下单
│   │   ├── pay/wx-notify.js   # Edge 幂等锁 → 业务处理
│   │   ├── pay/ali-notify.js
│   │   ├── pay/query.js
│   │   ├── pay/close.js
│   │   ├── admin/products.js   # MySQL CRUD（含 version 乐观锁）
│   │   ├── admin/orders.js    # MySQL 查询
│   │   ├── admin/users.js     # MySQL CRUD
│   │   ├── admin/stats.js     # MySQL 聚合统计
│   │   ├── order/create.js    # SELECT FOR UPDATE + 事务 + 指数退避
│   │   ├── order/detail.js
│   │   ├── order/cancel.js    # 状态机 + version 校验
│   │   └── ai/chat-stream.js  # SSE 流式（主力实现）
│   └── utils/
│       ├── db.js               # MySQL 连接池（mysql2/promise）
│       ├── payment-sdk.js      # 微信V3/支付宝 SDK 封装
│       ├── admin-guard.js
│       └── notification-hooks.js  # 通知钩子空壳
│
├── references/                  # 能力参考文档
│   ├── auth-module.md           # ✅ JWT RS256 + HS256 兼容 + KV Session
│   ├── cart-module.md
│   ├── payment-module.md
│   ├── ai-chat-module.md
│   ├── admin-module.md          # ✅ RBAC + CRUD + 运营统计 + 审计日志
│   ├── notification-module.md   # Layer 2：邮件/微信/钉钉通知
│   ├── order-state-machine.md   # ✅ 6状态 + 权限矩阵 + 库存联动 + 审计日志
│   ├── edge-functions.md        # ✅ Edge Middleware + KV API + 限流
│   ├── cloud-functions.md       # ✅ MySQL 事务 + bcrypt + 支付 SDK + SSE
│   ├── kv-storage.md
│   ├── middleware.md            # ✅ Platform + Edge 双层 + CSP + 支付 bypass
│   └── deployment.md            # ✅ 完整部署流程 + Cron + 回滚
│
└── scripts/
    ├── init-site.js             # 交互式初始化（模板优先）
    ├── sync-sharing.js          # 构建时 shared → edge/cloud 同步
    └── sample-data.js
```

---

## 三、Auth 模块（Layer 0，Core）

### API 路由

| 方法 | 路径 | 运行时 | 说明 |
|------|------|--------|------|
| POST | `/api/auth/login` | Edge（KV） | JWT 签发 + KV session |
| GET | `/api/auth/me` | Edge（KV） | KV session 读取 |
| POST | `/api/auth/refresh` | Edge（KV） | RT 轮换（version 乐观锁） |
| POST | `/api/auth/logout` | Edge（KV） | 清除 Cookie + KV session |
| POST | `/api/auth/register` | Cloud（MySQL） | bcrypt cost=12 + MySQL |

### JWT 安全设计

```
Access Token：短期 JWT（15min）+ HttpOnly Cookie（Secure + SameSite=Strict）
Refresh Token：7天 TTL，存 KV rt:{userId}:meta（含 version）
算法：Phase 1 用 HS256 + 短期 TTL，Phase 2 迁移 RS256
```

### 【v2.1 Critical 修复】RT 并发安全

两个请求并发携带同一 RT，只有第一个能成功写入新 version，第二个收到 409 → 客户端稍等重试。

```javascript
// edge-functions/api/auth/refresh.js
export async function onRequest(context) {
  const { RT } = await getTokens(context.request);
  const { KV } = context.env;
  const payload = parseJWT(RT);
  const userId = payload.sub;
  if (!userId) return new Response('Invalid', { status: 401 });

  const current = await KV.get(`rt:${userId}:meta`);
  const { version: oldVersion, token: oldToken } = JSON.parse(current || '{"version":0,"token":""}');

  if (oldToken !== RT) {
    return new Response('Token already rotated', { status: 409 });
  }

  const newVersion = oldVersion + 1;
  const newToken = signRT(userId, newVersion);

  const ok = await KV.put(
    `rt:${userId}:meta`,
    JSON.stringify({ version: newVersion, token: newToken }),
    { expirationTtl: 604800 }
  );

  if (!ok) return new Response('Concurrent rotation', { status: 409 });

  return new Response(JSON.stringify({ refreshToken: newToken }), {
    headers: { 'Content-Type': 'application/json' }
  });
}
```

---

## 四、Cart 模块（Layer 1，电商栈）

**双模式同步：**
```
未登录：localStorage（30d TTL 自动清理）
登录时：localStorage → 服务端 KV（syncOnLogin()）
已登录：服务端 KV（唯一数据源）
```

---

## 五、Payment 模块（Layer 1，电商栈）

### 独立回调路径

```
/api/pay/wx-notify   ← 微信支付回调（IP 白名单后直接 return，不进 Edge Middleware）
/api/pay/ali-notify  ← 支付宝回调（独立路径）
```

### 【v2.1 Critical 修复】支付幂等原子锁

微信支付平台会在回调超时后重试（最长 72h），KV 查→判→写三步非原子。解决方案：Edge Function `putIfNotExists` 原子幂等锁。

```javascript
// ===== Edge Function（唯一可访问 KV 的路径）=====
// edge-functions/api/internal/idempotency.js