# 🧑‍💻 编程经验库 — 兮楠女装小程序

> 2026-06-08 | 原生微信小程序 + Express.js(SQLite)后端 + 微信云函数

---

## 一、项目位置

| 内容 | 路径 |
|:-----|:------|
| **前端源码** | `/media/zhengjie/WORKSPACE/003/projects/xinan-miniprogram/miniprogram-xinan-fashion/` |
| **后端源码** | `/media/zhengjie/WORKSPACE/003/projects/xinan-miniprogram/miniapp/` |
| **4号部署** | `/data/xinan-miniapp/` (PM2: `xinan-miniapp`, 端口3003) |
| **Nginx配置** | `shop.hunanningyuan.cloud` → `/api/miniapp/` → `127.0.0.1:3003` |
| **DB文件** | `miniapp/db/miniapp.db` (SQLite, better-sqlite3) |

## 二、架构要点（写代码必看）

### 双通道数据
```
商品/收藏/用户 → 自建API (services/request.js → shop.hunanningyang.cloud)
AI穿搭/试衣   → 微信云函数 (wx.cloud.callFunction)
```
API 域名是 `ningyang` 不是 `ningyuan`，别写错。

### 数据库关键表 (`tenant_products`)
```sql
cover_url      TEXT   -- AI封面图(优先)
scene_images   TEXT   -- JSON数组(AI场景图)
ai_description TEXT   -- AI描述
image_url      TEXT   -- 原厂图(兜底)
color          TEXT   -- ⚠️ 实际存的是价格(分)，不是颜色
retail_price   REAL   -- 原价
```

### 图片优先级
```
cover_url > image_url > scene_images
```
前端 `transformProduct()` 最终数组: `[AI封面, ...AI场景图, 原图]` 去重后。

### 当前模式: 收藏模式
- Tab显示"收藏夹"不是"购物车"
- 商品加入收藏，咨询店员下单
- 可通过 `/api/miniapp/admin/features` 切换为购物模式

### AI功能开关
```js
app.globalData.aiEnabled  // false时不显示AI功能
```

## 三、关键文件速查

### 前端
| 路径 | 职责 |
|:-----|:------|
| `services/request.js` | API封装(核心) |
| `services/ai/ai.js` | AI穿搭服务(双写策略: 本地缓存+云函数) |
| `utils/cloudImageHandler.js` | cloud:// → HTTPS 转换 |
| `utils/imageOptimizer.js` | WebP检测+CDN参数+缓存 |
| `components/goods-card/` | 商品卡片(cover_image→thumb→primaryImage三级回退) |
| `components/webp-image/` | WebP图片组件 |
| `packageAI/` | AI功能子包(穿搭/试衣/海报) |
| `packageGoods/pages/details/` | 商品详情(AI图轮播) |
| `packageAdmin/` | 管理后台(11页) |

### 后端
| 路径 | 职责 |
|:-----|:------|
| `server.js` | Express入口, 端口3003 |
| `db.js` | SQLite连接(better-sqlite3) |
| `routes/goods.js` | 商品CRUD(含AI图字段) |
| `routes/recommend.js` | ⚠️ 用`ORDER BY RANDOM()`性能差 |
| `ecosystem.config.js` | PM2配置 |

### 云函数(34个)
| 名称 | 用途 |
|:-----|:------|
| `ai-outfit-recommend` | 混元Lite+Kimi推荐 |
| `aliyun-virtual-tryon` | 阿里云aitryon-plus试衣 |
| `qwenvl-fashion-tagger` | 通义千问VL打标 |
| `aliyun-image-gen` | 通义万相生图 |
| `generateOutfit` / `outfit-feedback` | 搭配生成/反馈 |

## 四、常踩的坑

- **API域名** `ningyang` 不是 `ningyuan`
- **color字段** 存的是价格不是颜色，别被字段名骗了
- **后端推荐** 用 `ORDER BY RANDOM()` 全表扫描，性能差
- **PM2进程名** 是 `xinan-miniapp`，在 `/data/xinan-miniapp/`
- **双写策略**: `saveOutfitHistory()` 先写本地缓存，再静默写云函数
- **Nginx**: 路径是 `/api/miniapp/` 不是 `/api/v1/`（那个是商城的）