# 🧑‍💻 编程经验库 — 兮楠女装商城 (Next.js)

> 2026-06-08 | Next.js 16 + FastAPI(SQLite) + CDN

---

## 一、项目位置

| 内容 | 路径 |
|:-----|:------|
| **4号生产** | `/data/xinan-fashion/` (PM2: `shop-frontend`, 端口3000) |
| **本地备份** | `/media/zhengjie/WORKSPACE/003/郑杰资产包/4号服务器网站备份_20260606/xinan-fashion/` |
| **后端** | FastAPI 端口8891 (nginx `/api/v1/` → 8891) |
| **DB** | `/data/xinan-fashion/data/fashion.db` (SQLite) |
| **CDN** | `img.hunanningyuan.cloud` (COS) |
| **网站** | `shop.hunanningyuan.cloud` |

**⚠️ PM2 shop-frontend 当前 errored 状态，需排查。**

## 二、技术栈

```
Next.js 16 (breacking changes多! 改前查 node_modules/next/dist/docs/)
React 19
TailwindCSS v4 (PostCSS插件模式)
@react-spring/web + @use-gesture/react (滑动交互)
FastAPI + SQLAlchemy (后端8891)
SQLite (fashion.db)
```

## 三、关键页面与组件

| 路由 | 文件 | 说明 |
|:-----|:------|:------|
| `/` | `page.tsx` | DesktopHome/MobileHome分流(<768px) |
| `/products` | `products/page.tsx` | 左分类导航+右5列网格 分页200条 |
| `/product/[style_no]` | `product/[style_no]/page.tsx` | SSR详情 全屏大图+搭配推荐+尺码选择 |
| `/swipe` | `swipe/SwipeFeed.tsx` | **核心交互** 滑动选品(右滑喜欢/左滑跳过/上滑加购/长按520ms进详情) |
| `/cart` | `cart/page.tsx` | 购物车(clientId/token双模式) |
| `/checkout` | `checkout/page.tsx` | ⚠️ 无真实支付，仅alert |

### SwipeFeed 核心逻辑（写滑动页必看）
```typescript
// 3种手势
右滑喜欢(x>150)  → addFavorite()  → 卡片飞出右侧
左滑跳过(x<-150) → skip()        → 卡片飞出左侧
上滑加购(y<-100) → addToCart()   → 卡片飞出上方
双击/捏合        → 放大查看
长按520ms        → router.push(/product/[id])
```
- 只展示有AI图(`/generated/`)的商品
- 每商品最多4张AI图，展开为连续卡片
- Fisher-Yates乱序，sessionStorage保持进度
- 左下角原图缩略图，点击全屏对比

## 四、API速查（后端FastAPI 8891）

| 路径 | 说明 |
|:-----|:------|
| `GET /api/v1/products` | 商品列表(review_status=shelf过滤) |
| `GET /api/v1/products/{sn}/detail` | SSR详情(含AI标签/scene_images) |
| `GET /api/v1/recommend?style_no=X&limit=4` | 搭配推荐 |
| `POST /api/v1/cart` | 加购 |
| `POST /api/v1/favorites` | 收藏 |
| `POST /api/v1/orders` | 下单(无真实支付) |

**价格公式**: `¥{retail_price * 0.35}` (折扣价) + `¥{retail_price}` (原价划线)

## 五、设计系统

```css
/* 桌面端(globals.css) */
--color-primary: #2d2926;    /* 深棕 */
--color-accent: #c4a882;     /* 金色 */
--color-bg: #f5f0eb;         /* 米白暖底 */
--color-card: #ebe5dd;
--color-border: #e5dfd8;

/* 移动端深色模式 */
--bg: #141414;               /* 深黑 */
--gold: #c4a882;
--text-warm: #e8e0d4;        /* 暖白 */
/* 毛玻璃胶囊按钮 */
.btn-glass {
  backdrop-filter: blur(16px);
  border: 1px solid rgba(196,168,130,0.3);
}
```

字体: `Noto Serif SC` + `Noto Sans SC` + `Playfair Display`
动画: `react-spring` 弹簧物理 / CSS `cubic-bezier(0.22, 1, 0.36, 1)`

## 六、常踩的坑

- **Next.js 16 有breaking changes**，改前必须查 `node_modules/next/dist/docs/`
- **PM2 shop-frontend errored** — 原因不明，待排查
- **图片URL替换**: API返回COS直链，前端统一替换为 `img.hunanningyuan.cloud` CDN
- **无真实支付**: checkout页仅 `alert('下单成功！')`
- **后端端口混淆**: nginx配8891，ecosystem配8892，需确认实际端口
- **SwipeFeed**: 用了16个 `useSpring` + `animated.div`，性能敏感，改动画参数先测
- **color字段是价格**: 数据库设计缺陷，改的时候别信字段名