面向宠物零售与到店服务的一体化智能生活平台
Mobile Commerce · Service Booking · AI Shopping Assistant · Operations Console
PetLife 将移动端商城、到店服务预约、会员优惠、智能导购与运营后台整合在同一套业务系统中。项目不是仅用于展示界面的静态原型：商品库存、购物车、优惠券、订单、宠物档案、预约容量与后台履约均由真实 API 和 SQLite 数据驱动。
| 3 独立子系统 |
2 端到端业务闭环 |
19 持久化数据表 |
224 当前版本通过用例 |
- 移动端用户应用：商品浏览、规格选择、购物车、优惠券、订单、服务预约、宠物档案、AI 导购与拍照搜商品。
- 桌面端运营后台：分类、商品、服务、门店、时段、优惠券、订单与预约管理，以及 AI 运营内容生成。
- Node.js 服务端：统一 REST API、会话鉴权、业务事务、图片上传、数据持久化与受控 AI 接入。
Tip
可直接访问 在线 Demo，点击「微信登录（测试）」进入体验。移动端建议使用手机访问，或将浏览器视口调整为约 430 × 932。
品牌首页 商品与服务统一分流 |
商品详情 规格与购买决策 |
拍照搜商品 多源特征融合排序 |
AI 售前咨询 真实目录约束推荐 |
运营概览 · 商品、服务与履约指标 |
AI 运营助手 · 生成内容先入表单、校验后保存 |
商品零售：浏览 / 搜索 → 规格选择 → 购物车 → 优惠券 → 下单 → 库存扣减 → 后台履约
到店服务：服务选择 → 门店 / 日期 / 时段 → 宠物档案 → 优惠券 → 预约 → 容量校验 → 后台处理
两条链路共享用户、会员与优惠体系，但分别维护库存和时段容量等业务边界，避免将不同领域逻辑耦合在页面状态中。
PetLife 没有把 AI 作为装饰性聊天窗口，而是将其用于购买决策、视觉检索和运营提效：
- 目录约束型 AI 导购：服务端向模型提供当前商品上下文和真实商品目录，要求结构化 JSON；模型返回的商品 ID 会再次回查数据库，并过滤不存在、下架或售罄商品。
- 混合式视觉搜索：浏览器侧使用 TensorFlow.js / MobileNet 完成本地识别，服务端补充视觉语义；最终融合 AI 相似度、识别相似度与图片相似度，并展示可解释的推荐理由。
- 结构化运营内容生成：后台可生成商品标签、摘要、适用说明、规格 JSON 与服务资料；输出需经过字段长度、数组数量和 JSON 结构校验，只回填表单，不绕过人工确认直接写库。
- 可降级设计：模型调用具备超时、重试与错误转换；云端视觉服务不可用时仍保留本地识别和目录匹配能力，核心商城与预约流程不依赖 AI 密钥。
| 场景 | 工程处理 |
|---|---|
| 创建订单 | 在 SQLite 事务中写入订单与明细、扣减库存、核销优惠券并清理已结算购物车项。 |
| 取消订单 | 校验订单状态后回补对应商品库存，避免库存与履约状态不一致。 |
| 创建预约 | 校验宠物类型、服务、门店、时段和容量，并在事务内完成预约与优惠券核销。 |
| 历史数据 | 订单保存商品、规格、价格和收货信息快照；预约保存宠物、服务、门店和时段快照。 |
| 身份边界 | 用户接口采用 Bearer Token 会话；后台接口使用 x-admin-key；同时支持微信公众号 OAuth 与本地演示登录。 |
服务端遵循 routes → controllers → services → repositories → db 的职责划分：控制器处理 HTTP，服务层承载领域规则，仓储层集中封装 SQL。移动端和后台分别独立构建、独立路由，同时共享一致的 API 契约。
前端还封装了设计 Token、通用业务组件和 GSAP 动效组合式函数；动效使用作用域上下文自动清理，并尊重 prefers-reduced-motion，在视觉表现与可访问性之间保持平衡。
flowchart LR
User["养宠用户"] --> Mobile["移动端 Web<br/>Vue 3 · Router · Pinia · GSAP"]
Operator["运营人员"] --> Admin["运营后台<br/>Vue 3 · Router · Pinia"]
Mobile --> Routes
Admin --> Routes
Mobile -. "本地视觉推理" .-> MobileNet["TensorFlow.js<br/>MobileNet"]
subgraph Backend["Node.js / Express"]
Routes["Routes<br/>public · auth · user · admin · wechat"] --> Controllers["Controllers"]
Controllers --> Services["Domain Services<br/>订单 · 预约 · 优惠券 · AI"]
Services --> Repositories["Repositories"]
end
Repositories --> SQLite[("SQLite")]
Services --> Uploads["File Uploads"]
Services -. "受控 JSON 调用" .-> LLM["OpenAI-compatible LLM<br/>文本 / 视觉模型"]
| Namespace | 职责 |
|---|---|
/api/public |
商品、分类、服务、门店时段、AI 咨询与视觉搜索。 |
/api/auth |
演示登录、微信公众号 OAuth、会话查询与退出。 |
/api/user |
用户资料、地址、宠物、购物车、优惠券、订单与预约。 |
/api/admin |
运营资料 CRUD、图片上传、发券与履约状态管理。 |
/api/wechat |
微信公众号服务器校验和事件消息处理。 |
| 领域 | 移动端用户应用 | 运营管理后台 |
|---|---|---|
| 商品 | 首页推荐、分类筛选、关键字搜索、图搜、详情、规格选择 | 分类与商品增删改查、上下架、库存、图集 |
| 交易 | 购物车、优惠券、确认订单、订单列表与详情、取消订单 | 订单检索、详情查看、履约状态流转 |
| 服务 | 服务列表与详情、门店 / 日期 / 时段选择、预约确认 | 服务、门店、时段容量与预约状态管理 |
| 用户 | 微信身份、个人资料、地址、宠物档案、会员权益 | 用户优惠券发放与状态维护 |
| AI | 通用导购、商品上下文咨询、拍照搜商品 | 商品介绍、规格 JSON、服务资料生成 |
| 层级 | 技术 | 用途 |
|---|---|---|
| 移动端 | Vue 3、Vite、Vue Router、Pinia、GSAP | 组件化页面、路由、业务状态与动效系统。 |
| 管理端 | Vue 3、Vite、Vue Router、Pinia | 独立桌面端 SPA、登录守卫、表格与表单管理。 |
| 服务端 | Node.js、Express、Multer | REST API、鉴权、中间件、图片上传与领域服务。 |
| 数据层 | SQLite、better-sqlite3 | 文件型部署、同步事务、迁移与种子数据。 |
| 智能能力 | OpenAI-compatible Chat API、TensorFlow.js、MobileNet | AI 咨询、结构化草稿、视觉识别与相似度排序。 |
| 质量保障 | Vitest、Vue Test Utils、Supertest、Playwright | 单元 / 组件 / API 测试与真实页面验收。 |
petlife/
├── src/ # 移动端用户应用
│ ├── views/ # 页面与业务流程
│ ├── components/ # 通用 UI / 业务组件
│ ├── stores/ # Pinia 状态
│ ├── api/ # HTTP 与会话客户端
│ ├── lib/ # AI、图搜、价格等领域工具
│ └── tests/ # 移动端测试
├── admin/ # 独立运营后台
│ └── src/{views,components,stores,api,tests}
├── server/ # Express 服务端
│ ├── src/routes/ # 路由定义
│ ├── src/controllers/ # HTTP 输入输出
│ ├── src/services/ # 领域规则与事务边界
│ ├── src/repositories/ # 数据访问
│ ├── src/db/ # SQLite 迁移与种子数据
│ └── tests/ # API / 业务测试
├── public/ # 公共图片与本地 MobileNet 模型
├── docs/ # 设计记录与 README 展示素材
└── package.json # 根项目脚本
- Node.js
18+（推荐使用当前 LTS） - npm
9+ - 无需单独安装 MySQL、PostgreSQL 或 Redis
git clone https://github.com/yeahnangua/petlife.git
cd petlife
npm ci
npm --prefix admin ci
npm --prefix server cicp .env.example .env核心配置：
| 变量 | 说明 | 默认 / 示例 |
|---|---|---|
PORT |
API 服务端口 | 8787 |
ADMIN_KEY |
本地后台登录密钥 | petlife-admin-demo |
DB_PATH |
SQLite 文件路径 | ./data/petlife.sqlite |
UPLOAD_DIR |
上传目录 | ./uploads |
BASE_URL |
服务端公开地址 | http://127.0.0.1:8787 |
MOBILE_APP_URL |
移动端地址，供 OAuth 回跳 | http://127.0.0.1:5173/ |
VITE_WECHAT_OAUTH_ENABLED |
是否启用真实微信 OAuth | false |
SILICONFLOW_API_KEY |
OpenAI 兼容模型密钥，可选 | 留空时不启用云端 AI |
还可按需配置 SILICONFLOW_MODEL、SILICONFLOW_BASE_URL、IMAGESEARCH_*、VISION_* 与 WECHAT_OFFICIAL_ACCOUNT_*。请勿将真实密钥提交到版本库。
分别打开三个终端：
# Terminal 1 · API
npm run dev:server
# Terminal 2 · 移动端
npm run dev:client
# Terminal 3 · 运营后台
npm run dev:admin| 应用 | 本地地址 | 说明 |
|---|---|---|
| 移动端 | http://127.0.0.1:5173 | 点击「微信登录（测试）」进入。 |
| 运营后台 | http://127.0.0.1:5174 | 使用 .env 中的 ADMIN_KEY。 |
| API | http://127.0.0.1:8787 | 提供 /api 与 /uploads。 |
服务端启动时会自动执行数据库迁移；全新数据库会自动装填演示数据和优惠券，无需额外准备数据库服务。
项目针对组件交互、状态管理、用户鉴权、商品目录、订单事务、预约容量、优惠券规则、AI 结构化输出和异常降级建立了三端测试。当前版本实测 224 个用例通过，移动端与管理端均可完成生产构建。
# 三端自动化测试
npm run test:client
npm run test:admin
npm run test:server
# 生产构建
npm run build
npm run build:admin测试分层包括：
- 移动端：组件、Store、路由守卫、购物车 / 下单 / 预约流程和图搜排序。
- 管理端：登录会话、侧栏导航、商品 / 服务表单、优惠券运营与上传组件。
- 服务端：使用 Supertest 验证 API、鉴权、事务、状态机和 AI 异常边界。
- 页面验收：使用 Playwright 分别按移动端
430 × 932和桌面端1440 × 900视口走查核心页面。
- SQLite 而非独立数据库服务：降低作品演示与本地复现成本，同时利用同步事务保证课程项目规模下的数据一致性。
- 前后台独立 SPA：用户体验与运营体验分别设计、分别构建，避免在同一应用内堆叠权限和布局分支。
- 服务端代理 AI：密钥不进入浏览器；模型输出统一在服务层解析、裁剪、校验并映射真实业务数据。
- 快照而非历史回查：订单和预约保留创建时语义，后台后续修改商品、价格、宠物或门店资料不会污染历史记录。
- 渐进增强：AI、视觉服务和微信 OAuth 均是可选增强能力，基础交易与预约链路可以独立运行。
- 接入正式支付、退款、物流追踪与售后流程。
- 将后台密钥升级为 RBAC、短期令牌、操作审计与权限分级。
- 引入对象存储、生产级数据库、监控告警与可观测性链路。
- 持续补强并发库存、预约容量竞争和端到端自动化测试。
Built with product thinking, explicit transaction boundaries, and restrained AI integration.