|
|
|
@ -2,6 +2,43 @@ |
|
|
|
|
|
|
|
> 关联项目：健康AI问询助手 |
|
|
|
> 开发顺序：在健康AI问询助手项目完成后开发 |
|
|
|
> **实现状态**: 后端API已完成，前端待开发 |
|
|
|
|
|
|
|
--- |
|
|
|
|
|
|
|
## 实现进度 |
|
|
|
|
|
|
|
### 后端开发状态 ✅ 已完成 |
|
|
|
|
|
|
|
| 模块 | 状态 | 说明 | |
|
|
|
|------|------|------| |
|
|
|
| 会员系统 | ✅ 完成 | 会员等级(普通/银卡/金卡/钻石)、积分、折扣 | |
|
|
|
| 商品模块 | ✅ 完成 | 分类、商品列表、详情、SKU、搜索 | |
|
|
|
| 购物车 | ✅ 完成 | 增删改查、批量操作、库存检查 | |
|
|
|
| 收货地址 | ✅ 完成 | 地址管理、默认地址 | |
|
|
|
| 订单系统 | ✅ 完成 | 订单创建、支付、取消、确认收货 | |
|
|
|
| 体质推荐 | ✅ 完成 | 基于用户体质的商品推荐 | |
|
|
|
| 用户共享 | ✅ 完成 | 与健康AI共用用户表和JWT认证 | |
|
|
|
|
|
|
|
### 前端开发状态 |
|
|
|
|
|
|
|
| 平台 | 状态 | 说明 | |
|
|
|
|------|------|------| |
|
|
|
| Web (Vue3) | ✅ 完成 | 独立 `mall/` 项目（10个页面 + 布局 + API层 + 状态管理） | |
|
|
|
| React Native | 📋 待开发 | APP端商城界面 | |
|
|
|
|
|
|
|
### 前端项目架构 |
|
|
|
|
|
|
|
``` |
|
|
|
healthApps/ |
|
|
|
├── web/ → 健康AI助手前端 (端口 5173) |
|
|
|
├── mall/ → 健康商城前端 (端口 5174) ← 独立项目 |
|
|
|
└── backend/ → 共享后端 (端口 8080) |
|
|
|
``` |
|
|
|
|
|
|
|
- `web/` 和 `mall/` 为独立 Vue 3 项目，各自有 `package.json` |
|
|
|
- 共享同一后端 API 和 JWT Token（通过 localStorage） |
|
|
|
- 通过环境变量配置双向跳转 URL |
|
|
|
|
|
|
|
--- |
|
|
|
|
|
|
|
@ -36,11 +73,16 @@ |
|
|
|
|------|----------|------| |
|
|
|
| Web前端 | Vue 3 + TypeScript + Vite | 与健康AI项目保持一致 | |
|
|
|
| APP端 | React Native + TypeScript | 与健康AI项目保持一致 | |
|
|
|
| 后端服务 | Go + Gin + GORM | 与健康AI项目保持一致 | |
|
|
|
| 后端服务 | Go + go-zero + GORM | 与健康AI项目保持一致（已迁移） | |
|
|
|
| 数据库 | SQLite / PostgreSQL | 支持切换，与健康AI共享用户表 | |
|
|
|
| 支付对接 | 微信支付 / 支付宝 | 预留接口 | |
|
|
|
| 对象存储 | 阿里云OSS / 本地存储 | 产品图片存储 | |
|
|
|
|
|
|
|
> **框架说明**: 后端使用 go-zero 微服务框架，保持与健康AI后端一致。 |
|
|
|
> - API定义: 使用 .api 文件定义接口 |
|
|
|
> - ORM: 继续使用 GORM 进行数据库操作 |
|
|
|
> - 认证: 使用 go-zero 内置 JWT 中间件 |
|
|
|
|
|
|
|
### 2.2 系统架构图 |
|
|
|
|
|
|
|
``` |
|
|
|
@ -87,6 +129,46 @@ |
|
|
|
| 体质信息获取 | 商城 ← 健康AI | 商城调用健康AI接口获取用户体质，优化推荐排序 | |
|
|
|
| 购买记录同步 | 商城 → 健康AI | 用户购买保健品后，同步到健康AI用于AI问诊参考 | |
|
|
|
|
|
|
|
### 2.4 会员系统设计 (已实现) |
|
|
|
|
|
|
|
#### 会员等级体系 |
|
|
|
|
|
|
|
| 等级 | 升级条件 | 折扣 | 积分倍率 | 包邮门槛 | |
|
|
|
|------|----------|------|----------|----------| |
|
|
|
| 普通用户 | 默认 | 无 | 1.0x | ￥99 | |
|
|
|
| 银卡会员 | 累计消费≥￥500 | 98折 | 1.2x | ￥69 | |
|
|
|
| 金卡会员 | 累计消费≥￥2000 | 95折 | 1.5x | ￥49 | |
|
|
|
| 钻石会员 | 累计消费≥￥5000 | 92折 | 2.0x | 全场包邮 | |
|
|
|
|
|
|
|
#### 积分规则 |
|
|
|
|
|
|
|
- **获取**: 订单支付后按实付金额 × 等级倍率获得积分 |
|
|
|
- **使用**: 100积分 = 1元，单笔订单最多抵扣20% |
|
|
|
- **有效期**: 获得后1年过期 |
|
|
|
|
|
|
|
#### 数据模型 (已实现) |
|
|
|
|
|
|
|
```go |
|
|
|
// User 扩展字段 |
|
|
|
type User struct { |
|
|
|
// ... 基础字段 |
|
|
|
MemberLevel string // normal/silver/gold/diamond |
|
|
|
TotalSpent float64 // 累计消费 |
|
|
|
Points int // 当前积分 |
|
|
|
MemberSince *time.Time // 首次消费时间 |
|
|
|
} |
|
|
|
|
|
|
|
// 积分变动记录 |
|
|
|
type PointsRecord struct { |
|
|
|
UserID uint |
|
|
|
Type string // earn/spend/expire/adjust |
|
|
|
Points int // 变动积分（正负） |
|
|
|
Balance int // 变动后余额 |
|
|
|
Source string // order/activity/system |
|
|
|
ReferenceID uint // 关联订单ID |
|
|
|
} |
|
|
|
``` |
|
|
|
|
|
|
|
--- |
|
|
|
|
|
|
|
## 三、功能模块 |
|
|
|
@ -473,6 +555,132 @@ POST /api/favorites # 添加收藏 |
|
|
|
DELETE /api/favorites/:product_id # 取消收藏 |
|
|
|
``` |
|
|
|
|
|
|
|
### 5.7 go-zero API 定义示例 |
|
|
|
|
|
|
|
```api |
|
|
|
// mallapi.api - 商城API定义文件 |
|
|
|
|
|
|
|
syntax = "v1" |
|
|
|
|
|
|
|
info( |
|
|
|
title: "保健品商城API" |
|
|
|
desc: "健康AI配套商城服务" |
|
|
|
author: "healthApps" |
|
|
|
version: "1.0" |
|
|
|
) |
|
|
|
|
|
|
|
// ==================== 类型定义 ==================== |
|
|
|
|
|
|
|
type ( |
|
|
|
// 产品 |
|
|
|
Product { |
|
|
|
ID uint `json:"id"` |
|
|
|
Name string `json:"name"` |
|
|
|
Category string `json:"category"` |
|
|
|
MainImage string `json:"main_image"` |
|
|
|
SalePrice float64 `json:"sale_price"` |
|
|
|
OriginalPrice float64 `json:"original_price,omitempty"` |
|
|
|
SalesCount int `json:"sales_count"` |
|
|
|
Stock int `json:"stock"` |
|
|
|
} |
|
|
|
|
|
|
|
ProductListReq { |
|
|
|
Category string `form:"category,optional"` |
|
|
|
Page int `form:"page,default=1"` |
|
|
|
PageSize int `form:"page_size,default=20"` |
|
|
|
Sort string `form:"sort,optional"` // price_asc, price_desc, sales |
|
|
|
} |
|
|
|
|
|
|
|
ProductListResp { |
|
|
|
List []Product `json:"list"` |
|
|
|
Total int64 `json:"total"` |
|
|
|
} |
|
|
|
|
|
|
|
// 购物车 |
|
|
|
CartItem { |
|
|
|
ID uint `json:"id"` |
|
|
|
ProductID uint `json:"product_id"` |
|
|
|
SkuID uint `json:"sku_id,omitempty"` |
|
|
|
Name string `json:"name"` |
|
|
|
Image string `json:"image"` |
|
|
|
Price float64 `json:"price"` |
|
|
|
Quantity int `json:"quantity"` |
|
|
|
Selected bool `json:"selected"` |
|
|
|
} |
|
|
|
|
|
|
|
AddCartReq { |
|
|
|
ProductID uint `json:"product_id"` |
|
|
|
SkuID uint `json:"sku_id,omitempty"` |
|
|
|
Quantity int `json:"quantity,default=1"` |
|
|
|
} |
|
|
|
|
|
|
|
// 订单 |
|
|
|
CreateOrderReq { |
|
|
|
AddressID uint `json:"address_id"` |
|
|
|
CartIDs []uint `json:"cart_ids"` |
|
|
|
Remark string `json:"remark,optional"` |
|
|
|
} |
|
|
|
|
|
|
|
OrderResp { |
|
|
|
OrderNo string `json:"order_no"` |
|
|
|
Status string `json:"status"` |
|
|
|
TotalAmount float64 `json:"total_amount"` |
|
|
|
PayAmount float64 `json:"pay_amount"` |
|
|
|
} |
|
|
|
) |
|
|
|
|
|
|
|
// ==================== 公开接口（无需认证）==================== |
|
|
|
|
|
|
|
@server( |
|
|
|
prefix: /api/mall |
|
|
|
) |
|
|
|
service mallapi-api { |
|
|
|
@doc "产品列表" |
|
|
|
@handler GetProductList |
|
|
|
get /products (ProductListReq) returns (ProductListResp) |
|
|
|
|
|
|
|
@doc "产品详情" |
|
|
|
@handler GetProduct |
|
|
|
get /products/:id returns (Product) |
|
|
|
|
|
|
|
@doc "产品搜索" |
|
|
|
@handler SearchProducts |
|
|
|
get /products/search returns (ProductListResp) |
|
|
|
|
|
|
|
@doc "分类列表" |
|
|
|
@handler GetCategories |
|
|
|
get /categories returns ([]Category) |
|
|
|
} |
|
|
|
|
|
|
|
// ==================== 需要认证的接口 ==================== |
|
|
|
|
|
|
|
@server( |
|
|
|
prefix: /api/mall |
|
|
|
jwt: Auth |
|
|
|
) |
|
|
|
service mallapi-api { |
|
|
|
@doc "获取购物车" |
|
|
|
@handler GetCart |
|
|
|
get /cart returns ([]CartItem) |
|
|
|
|
|
|
|
@doc "添加到购物车" |
|
|
|
@handler AddToCart |
|
|
|
post /cart (AddCartReq) returns (CartItem) |
|
|
|
|
|
|
|
@doc "创建订单" |
|
|
|
@handler CreateOrder |
|
|
|
post /orders (CreateOrderReq) returns (OrderResp) |
|
|
|
|
|
|
|
@doc "订单列表" |
|
|
|
@handler GetOrders |
|
|
|
get /orders returns ([]OrderResp) |
|
|
|
|
|
|
|
@doc "体质推荐产品" |
|
|
|
@handler GetRecommendProducts |
|
|
|
get /recommend returns (ProductListResp) |
|
|
|
} |
|
|
|
``` |
|
|
|
|
|
|
|
--- |
|
|
|
|
|
|
|
## 六、项目目录结构 |
|
|
|
@ -512,39 +720,45 @@ healthMall/ |
|
|
|
│ │ └── utils/ |
|
|
|
│ └── package.json |
|
|
|
│ |
|
|
|
├── server/ # 后端服务 |
|
|
|
│ ├── cmd/ |
|
|
|
│ │ └── main.go |
|
|
|
│ ├── internal/ |
|
|
|
│ │ ├── api/ |
|
|
|
│ │ │ ├── handler/ |
|
|
|
│ │ │ │ ├── product.go |
|
|
|
│ │ │ │ ├── cart.go |
|
|
|
│ │ │ │ ├── order.go |
|
|
|
│ │ │ │ ├── payment.go |
|
|
|
│ │ │ │ └── address.go |
|
|
|
│ │ │ ├── middleware/ |
|
|
|
│ │ │ └── router.go |
|
|
|
│ │ ├── model/ |
|
|
|
│ │ │ ├── product.go |
|
|
|
│ │ │ ├── cart.go |
|
|
|
│ │ │ ├── order.go |
|
|
|
│ │ │ ├── payment.go |
|
|
|
│ │ │ └── address.go |
|
|
|
│ │ ├── repository/ |
|
|
|
│ │ ├── service/ |
|
|
|
│ │ │ ├── product.go |
|
|
|
│ │ │ ├── cart.go |
|
|
|
│ │ │ ├── order.go |
|
|
|
│ │ │ └── payment.go |
|
|
|
│ │ ├── database/ |
|
|
|
│ │ └── config/ |
|
|
|
│ ├── pkg/ |
|
|
|
│ │ ├── payment/ # 支付SDK封装 |
|
|
|
│ │ │ ├── wechat.go |
|
|
|
│ │ │ └── alipay.go |
|
|
|
│ │ └── logistics/ # 物流查询 |
|
|
|
│ └── go.mod |
|
|
|
├── backend/ # 后端服务 (go-zero) |
|
|
|
│ └── mallapi/ # 商城API服务 |
|
|
|
│ ├── mallapi.go # 主入口 |
|
|
|
│ ├── mallapi.api # API定义文件 |
|
|
|
│ ├── etc/ |
|
|
|
│ │ └── mallapi-api.yaml # 配置文件 |
|
|
|
│ ├── internal/ |
|
|
|
│ │ ├── config/ |
|
|
|
│ │ │ └── config.go # 配置结构 |
|
|
|
│ │ ├── handler/ # 请求处理器 (goctl生成) |
|
|
|
│ │ │ ├── product_handler.go |
|
|
|
│ │ │ ├── cart_handler.go |
|
|
|
│ │ │ ├── order_handler.go |
|
|
|
│ │ │ ├── payment_handler.go |
|
|
|
│ │ │ ├── address_handler.go |
|
|
|
│ │ │ └── routes.go |
|
|
|
│ │ ├── logic/ # 业务逻辑 |
|
|
|
│ │ │ ├── product_logic.go |
|
|
|
│ │ │ ├── cart_logic.go |
|
|
|
│ │ │ ├── order_logic.go |
|
|
|
│ │ │ ├── payment_logic.go |
|
|
|
│ │ │ └── address_logic.go |
|
|
|
│ │ ├── model/ # GORM模型 |
|
|
|
│ │ │ ├── product.go |
|
|
|
│ │ │ ├── cart.go |
|
|
|
│ │ │ ├── order.go |
|
|
|
│ │ │ ├── payment.go |
|
|
|
│ │ │ └── address.go |
|
|
|
│ │ ├── svc/ |
|
|
|
│ │ │ └── service_context.go # 服务上下文 |
|
|
|
│ │ ├── types/ |
|
|
|
│ │ │ └── types.go # 请求/响应类型 (goctl生成) |
|
|
|
│ │ └── database/ |
|
|
|
│ │ └── database.go # 数据库初始化 |
|
|
|
│ └── pkg/ |
|
|
|
│ ├── payment/ # 支付SDK封装 |
|
|
|
│ │ ├── wechat.go |
|
|
|
│ │ └── alipay.go |
|
|
|
│ └── logistics/ # 物流查询 |
|
|
|
│ |
|
|
|
├── config.yaml # 配置文件 |
|
|
|
└── README.md |
|
|
|
@ -599,14 +813,28 @@ healthMall/ |
|
|
|
|
|
|
|
### 8.2 开发任务清单 |
|
|
|
|
|
|
|
**后端开发：** |
|
|
|
1. 项目初始化（共用健康AI的基础架构） |
|
|
|
**后端开发（go-zero）：** |
|
|
|
1. 项目初始化 |
|
|
|
- 使用 goctl 生成项目骨架：`goctl api new mallapi` |
|
|
|
- 编写 mallapi.api 定义文件 |
|
|
|
- 配置与健康AI共享的数据库和JWT密钥 |
|
|
|
2. 产品模块（详情、SKU、库存） |
|
|
|
- GORM 模型定义 |
|
|
|
- 产品列表、详情、搜索接口 |
|
|
|
3. 购物车模块 |
|
|
|
- 添加、修改、删除购物车 |
|
|
|
4. 地址管理模块 |
|
|
|
- CRUD 地址接口 |
|
|
|
5. 订单模块（创建、状态流转） |
|
|
|
- 订单创建、列表、详情 |
|
|
|
- 订单状态机实现 |
|
|
|
6. 支付模块（微信/支付宝） |
|
|
|
7. 健康AI对接（用户认证、体质推荐、订单同步） |
|
|
|
- 支付SDK封装 |
|
|
|
- 回调处理 |
|
|
|
7. 健康AI对接 |
|
|
|
- JWT Token 共享认证 |
|
|
|
- 体质推荐产品接口 |
|
|
|
- 购买记录同步接口 |
|
|
|
|
|
|
|
**Web前端开发：** |
|
|
|
1. 项目初始化 |
|
|
|
@ -630,21 +858,38 @@ healthMall/ |
|
|
|
|
|
|
|
### 9.1 用户认证集成 |
|
|
|
|
|
|
|
商城与健康AI共享同一套JWT认证，使用相同的 AccessSecret： |
|
|
|
|
|
|
|
```yaml |
|
|
|
# mallapi-api.yaml 配置（与健康AI保持一致） |
|
|
|
Auth: |
|
|
|
AccessSecret: health-ai-secret-key-change-in-production |
|
|
|
AccessExpire: 86400 |
|
|
|
``` |
|
|
|
|
|
|
|
```go |
|
|
|
// 商城服务验证Token时，调用健康AI的JWT验证 |
|
|
|
func ValidateToken(token string) (*UserClaims, error) { |
|
|
|
// 使用相同的JWT密钥验证 |
|
|
|
// 或调用健康AI的 /api/auth/validate 接口 |
|
|
|
// go-zero 内置 JWT 中间件自动验证 |
|
|
|
// 在 .api 文件中使用 jwt:Auth 标记需要认证的路由 |
|
|
|
@server( |
|
|
|
prefix: /api/mall |
|
|
|
jwt: Auth |
|
|
|
) |
|
|
|
service mallapi-api { |
|
|
|
@handler GetCart |
|
|
|
get /cart returns (CartResp) |
|
|
|
} |
|
|
|
``` |
|
|
|
|
|
|
|
### 9.2 体质推荐集成 |
|
|
|
|
|
|
|
```go |
|
|
|
// 商城首页获取用户体质推荐产品 |
|
|
|
func GetConstitutionRecommend(userID uint) ([]Product, error) { |
|
|
|
// 1. 调用健康AI接口获取用户体质 |
|
|
|
// GET http://health-ai-server/api/constitution/result |
|
|
|
// internal/logic/recommend_logic.go |
|
|
|
func (l *RecommendLogic) GetConstitutionRecommend() (*types.RecommendResp, error) { |
|
|
|
userID, _ := logic.GetUserIDFromCtx(l.ctx) |
|
|
|
|
|
|
|
// 1. 从共享数据库获取用户体质 |
|
|
|
var assessment model.ConstitutionAssessment |
|
|
|
l.svcCtx.DB.Where("user_id = ?", userID).Order("assessed_at DESC").First(&assessment) |
|
|
|
|
|
|
|
// 2. 根据体质查询推荐产品 |
|
|
|
// SELECT * FROM products p |
|
|
|
@ -873,6 +1118,47 @@ storage: |
|
|
|
|
|
|
|
--- |
|
|
|
|
|
|
|
> **文档版本**: v1.0 |
|
|
|
## 附录B：后端API汇总 (已实现) |
|
|
|
|
|
|
|
### 商城公开接口 (/api/mall) |
|
|
|
|
|
|
|
| 方法 | 路径 | 说明 | |
|
|
|
|------|------|------| |
|
|
|
| GET | /categories | 获取商品分类 | |
|
|
|
| GET | /products | 商品列表 | |
|
|
|
| GET | /products/:id | 商品详情 | |
|
|
|
| GET | /products/search | 搜索商品 | |
|
|
|
| GET | /products/featured | 推荐商品 | |
|
|
|
|
|
|
|
### 商城认证接口 (/api/mall，需JWT) |
|
|
|
|
|
|
|
| 方法 | 路径 | 说明 | |
|
|
|
|------|------|------| |
|
|
|
| GET | /member/info | 获取会员信息 | |
|
|
|
| GET | /member/points/records | 积分变动记录 | |
|
|
|
| GET | /cart | 获取购物车 | |
|
|
|
| POST | /cart | 添加到购物车 | |
|
|
|
| PUT | /cart/:id | 更新购物车项 | |
|
|
|
| DELETE | /cart/:id | 删除购物车项 | |
|
|
|
| POST | /cart/batch-select | 批量选中 | |
|
|
|
| DELETE | /cart/clear | 清空购物车 | |
|
|
|
| GET | /addresses | 地址列表 | |
|
|
|
| POST | /addresses | 创建地址 | |
|
|
|
| PUT | /addresses/:id | 更新地址 | |
|
|
|
| DELETE | /addresses/:id | 删除地址 | |
|
|
|
| PUT | /addresses/:id/default | 设为默认 | |
|
|
|
| GET | /orders | 订单列表 | |
|
|
|
| GET | /orders/:id | 订单详情 | |
|
|
|
| POST | /orders/preview | 订单预览 | |
|
|
|
| POST | /orders | 创建订单 | |
|
|
|
| POST | /orders/:id/pay | 支付订单 | |
|
|
|
| POST | /orders/:id/cancel | 取消订单 | |
|
|
|
| POST | /orders/:id/receive | 确认收货 | |
|
|
|
| GET | /products/constitution-recommend | 体质推荐商品 | |
|
|
|
|
|
|
|
--- |
|
|
|
|
|
|
|
> **文档版本**: v1.3 |
|
|
|
> **更新日期**: 2026-02-07 |
|
|
|
> **创建日期**: 2026-02-01 |
|
|
|
> **关联项目**: 健康AI问询助手 |
|
|
|
|
