# EasyBand

**Repository Path**: secondriver/easy-band

## Basic Information

- **Project Name**: EasyBand
- **Description**: EasyBand 是一套AI完成的可本地跑通、可容器演示的健康手环品牌官网 + 轻量商城：逛首页与产品、注册登录、账号绑定购物车、管理收货地址、选址下单与模拟支付，以及健康生态、服务支持（含保修查询）与个人中心。
- **Primary Language**: JavaScript
- **License**: Apache-2.0
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-23
- **Last Updated**: 2026-10-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EasyBand 健康手环

EasyBand 是一套可本地跑通、可容器演示的健康手环**品牌官网 + 轻量商城**：逛首页与产品、注册登录、账号绑定购物车、管理收货地址、选址下单与模拟支付，以及健康生态、服务支持（含保修查询）与个人中心。视觉参考 [小米官网 mi.com](https://www.mi.com/)，主色 `#FF6700`，背景 `#F5F5F5`。

技术栈上，前端为 **Ant Design Pro / Umi Max**（`frontend/`），业务 API 由 **FastAPI + SQLite** 提供（`backend/`），开发态经 `/api` proxy 联调；生产侧可用 Docker Compose 挂到 443（`deploy/`）。需求以 Spec（PRD / Story）归档在 `spec/`，按 Story 迭代与验收。

演示账号：`demo` / `demo1234`（后端首次启动自动种子）。

## 功能介绍

- 官网首页：Hero 轮播、促销条、热门手环、健康卖点
- 产品商城：分类筛选、关键词搜索、产品详情
- 账号：注册、登录、找回密码、退出登录（JWT）；个人中心改资料 / 改密码
- 购物车：与账号绑定，加购 / 删改数量 / 结算（需登录，SQLite 按 `user_id`）
- 收货地址：增删改查、设默认（需登录）
- 下单与支付：选址下单、模拟微信/支付宝、订单列表与详情、待支付可取消
- 健康生态 / 服务支持（含保修查询）/ 关于品牌

| 路径 | 说明 |
|------|------|
| `/` | 首页 |
| `/products` | 全部产品（`?category=` / `?keyword=`） |
| `/product/:id` | 产品详情 |
| `/cart` | 购物车（需登录） |
| `/checkout` | 确认订单（选地址下单，需登录） |
| `/pay/:orderId` | 模拟支付 |
| `/health` `/support` `/about` | 健康、服务、关于 |
| `/login` `/register` `/forgot-password` | 登录 / 注册 / 找回密码 |
| `/account` | 个人中心（默认进资料，需登录） |
| `/account/profile` | 个人信息 |
| `/account/orders` | 我的订单 |
| `/account/orders/:orderId` | 订单详情 |
| `/account/addresses` | 收货地址 |

## 仓库结构

```
easyband/
├── README.md          # 本文件：功能、运行、效果展示
├── frontend/          # 前端（Umi Max + Ant Design）
├── backend/           # 服务端（Python ≥3.14 + FastAPI + SQLite，uv）
├── deploy/            # Docker Compose 部署（HTTPS 443）
├── spec/              # 需求与规范（PRD + Story-0…9）
└── docs/              # 实践复盘等文档（非运行必需）
```

- 需求索引：[`spec/PRD.md`](./spec/PRD.md)
- 后端说明：[`backend/README.md`](./backend/README.md)
- 演示部署：[`deploy/README.md`](./deploy/README.md)（Compose + 自签 HTTPS）

## 开发运行

需本机具备 **Python ≥ 3.14**、[uv](https://github.com/astral-sh/uv)、**Node.js**、[pnpm](https://pnpm.io/)，并同时启动后端与前端。

### 1. 后端（端口 8001）

```bash
cd backend
uv sync
uv run easyband-backend
```

- 服务：http://127.0.0.1:8001
- OpenAPI：http://127.0.0.1:8001/docs
- 健康检查：http://127.0.0.1:8001/api/health

首次启动会建表并写入种子数据（含演示账号）。本地库文件：`backend/data/easyband.db`。

### 2. 前端（端口 8000）

```bash
cd frontend
pnpm install
pnpm dev
```

浏览器打开 [http://localhost:8000](http://localhost:8000)。  
`frontend/config/config.ts` 已设置 `mock: false`，并将 `/api` 代理到 `http://127.0.0.1:8001`。

| 命令（frontend/） | 说明 |
|------|------|
| `pnpm dev` | 开发 |
| `pnpm build` | 生产构建 |
| `pnpm screenshots` | 重新截取效果图（需本机已起前端） |

## 生产 / 演示部署（Docker）

```bash
cd deploy
cp .env.example .env   # 至少修改 JWT_SECRET
sh scripts/gen-certs.sh    # Windows: .\scripts\gen-certs.ps1
docker compose up -d --build
```

访问 https://localhost/ （自签证书需在浏览器确认继续；HTTP 80 会跳转 HTTPS）。  
API 健康检查：https://localhost/api/health  

更完整的目录约定、环境变量与常用命令见 [`deploy/README.md`](./deploy/README.md)。

## 展示效果图

图片位于 [`frontend/docs/screenshots/`](./frontend/docs/screenshots/)。可用 `pnpm screenshots`（在 `frontend/`）重新截取。

### 首页

![首页](./frontend/docs/screenshots/home.png)

### 全部产品

![全部产品](./frontend/docs/screenshots/products.png)

### 产品详情

![产品详情](./frontend/docs/screenshots/product-detail.png)

### 购物车

![购物车](./frontend/docs/screenshots/cart.png)

### 健康生态

![健康生态](./frontend/docs/screenshots/health.png)

## API 摘要

统一响应：`{ success: boolean, data: T, errorMessage?: string }`  
鉴权：`Authorization: Bearer <token>`（需登录接口）。完整说明见 [`backend/README.md`](./backend/README.md)。

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/health` | 进程健康检查 |
| GET | `/api/home` | 首页聚合 |
| GET | `/api/categories` | 分类 |
| GET | `/api/products` | 产品列表（`category` / `keyword`） |
| GET | `/api/products/:id` | 产品详情 |
| GET | `/api/search` | 搜索（`q`） |
| GET | `/api/support` | 服务与 FAQ |
| POST | `/api/warranty/query` | 保修查询 |
| POST | `/api/auth/register` 等 | 注册 / 登录 / 找回密码 / me / 改资料 / 改密码 / 退出 |
| GET/POST/PUT/DELETE | `/api/cart` | 购物车（需登录；另有按 `product_id` 改删） |
| GET/POST/PUT/DELETE | `/api/addresses` | 收货地址（需登录；可设默认） |
| GET/POST | `/api/orders` | 订单列表 / 下单（需登录，下单需 `addressId`） |
| GET | `/api/orders/:id` | 订单详情 |
| POST | `/api/orders/:id/pay` | 模拟支付 |
| POST | `/api/orders/:id/cancel` | 取消待支付订单 |

订单与支付细节见 [`spec/Story-7.md`](./spec/Story-7.md)。