易搭衣橱 · API 与技术栈文档

1项目架构总览

「易搭衣橱」由三个端构成，共用同一套 Koa 后端与 MySQL 数据库：

• 用户端 easyClothing-plus-front：Vue 3 + Vant 4 的移动端 H5 应用，运行于 http://127.0.0.1:8080，承载商品浏览、穿搭技巧、社区发帖、消息、AI 穿搭助手等全部 C 端功能。
• 管理端 easyClothing-admin：React 19 + TypeScript 的运营后台，运行于 http://127.0.0.1:8081，承载数据概览与用户 / 帖子 / 商品 / 技巧 / 评论 / 反馈 / 公司站点的审核与管理。
• 后端 easyClothing-plus-backend：Koa 2 服务，监听 http://127.0.0.1:3033，提供全部 REST API，数据存储使用 MySQL（库名 baijiahao），热点数据走 Redis 缓存。

┌─────────────┐   ┌─────────────┐   ┌──────────────────┐
│  用户端 H5   │   │   管理端     │   │   对外静态站点     │
│ Vue3+Vant4  │   │ React+AntD  │   │ 官网 /docs 文档站  │
│  :8080      │   │  :8081      │   │ 后端 public 托管   │
└──────┬──────┘   └──────┬──────┘   └────────┬─────────┘
       │  vite proxy      │  CORS + token    │  静态托管
       ▼                 ▼                 ▼
┌─────────────────────────────────────────────────────┐
│              Koa 2 后端服务  :3033                  │
│  路由 / 鉴权 / 上传 / 业务模型 / AI 多模型调度       │
├──────────────────────┬──────────────────────────────┤
│  MySQL(baijiahao)    │  Redis(热点缓存)             │
└──────────────────────┴──────────────────────────────┘

2技术栈清单

3基础地址与响应格式

后端统一基础地址：http://127.0.0.1:3033。所有接口返回统一 JSON 结构：

{ "code": 0, "msg": "success", "data": { ... } }

• code = 0：成功，业务数据在 data 中。
• code = -1：业务失败，msg 为错误提示（HTTP 状态通常仍为 200；管理端未登录返回 HTTP 401）。

列表类接口统一分页参数：page（页码，从 1 开始）、limit（每页条数），返回 { total, list }；关键词过滤统一使用 keyword。

4鉴权方式

管理端与用户端均使用自定义 Token 头：

authentication: "<token>"      // 注意：值带英文双引号（后端会去除后校验）

• 用户端：登录 / 注册接口返回 token，请求封装在 src/request/axios.js 中统一注入。
• 管理端：POST /admin/login 获取 token，存于 localStorage（zustand persist）；axios 请求拦截器自动携带；后端重启后 token 失效，前端自动跳转登录页。

5前端 API 封装

用户端（Vue3 + Vant4）

统一封装位于 src/request/axios.js（导出 _service）：

• GET 请求第二参数传 { params: {...} }；
• 拦截器判断 res.code === 0 为成功，否则提示 msg 并 reject；
• 自动注入 authentication 请求头；
• 开发环境经 vite proxy 将接口转发到 3033。

import { _service } from "@/request/axios.js";
_service.get("/cloth/index", { params: { page: 1, limit: 10 } });   // 商品列表
_service.post("/user/login", { username, password });               // 登录

管理端（React + TS）

请求封装位于 src/api/http.ts，接口函数位于 src/api/admin.ts：

• axios 实例 baseURL 直连 http://127.0.0.1:3033（后端已开启 CORS）；
• 响应拦截器在 code === 0 时直接返回 data；HTTP 401 时清除 token 并跳转登录页；
• 请求拦截器读取 localStorage.admin_token 并注入 authentication 头。

import { getUsers, toggleUser } from '../api/admin';
const d = await getUsers({ page: 1, limit: 10, keyword: '' });   // d = { total, list }
await toggleUser(id, 0);                                         // 封禁用户

6用户与关注

7商品与穿搭技巧

8帖子与互动（社区）

9AI 穿搭助手 AI

AI 推荐降级链路

读取对话历史
  → 尝试 Claude      ├─ 成功 → 返回（保存对话 / 记录推荐）
  → 尝试 DeepSeek    ├─ 失败 → 下一个
  → 尝试通义千问     ├─ 失败 → 下一个
  → 尝试 Kimi        ├─ 成功 → 返回
                     └─ 全部失败 → 返回"全部不可用"错误
  （每次调用写入 ai_llm_log 日志表）

10搜索

搜索页三栏：商品 / 穿搭技巧 / 帖子，分别对接 /cloth/search、/match/search、/article/search。

11消息

12管理端接口 需登录

管理端接口统一前缀 /admin，需在 authentication 头携带管理员 token（POST /admin/login 获取）。

13公司站点与核心团队

公司信息存储于 company_info（key-value 配置表），团队成员存储于 team_member；官网（/site/）与本文档（/docs/）由后端 koa-static 托管，属于 SEO 友好的静态页面。