# 爱鉴花小程序 - 产品需求文档

## 版本历史
| 版本 | 日期 | 作者 | 描述 |
|------|------|------|------|
| v1.0 | 2024-01-15 | 产品经理 | 初始版本 |

## 1. 项目概述

### 1.1 项目背景
"爱鉴花"是一款集植物识别、鲜花配送、植物商城、园艺花卉于一体的综合性小程序，旨在为用户提供一站式的植物相关服务。

### 1.2 项目目标
- 打造国内领先的植物识别+电商平台
- 为用户提供准确的植物识别服务
- 构建完整的植物相关商品供应链
- 建立园艺爱好者社区

### 1.3 成功标准
- 3个月内实现日活用户10,000+
- 植物识别准确率达到90%以上
- 月GMV达到50万元
- 用户满意度评分4.5/5.0

## 2. 用户角色与用例

### 2.1 用户角色
1. **普通消费者**：购买鲜花、盆栽的普通用户
2. **园艺爱好者**：对植物种植有浓厚兴趣的用户
3. **花店商家**：入驻平台的鲜花零售商
4. **内容创作者**：分享园艺知识的KOL

### 2.2 核心用例
- 植物识别查询
- 鲜花在线订购
- 园艺商品购买
- 知识内容学习
- 社区交流互动

## 3. 功能需求

### 3.1 植物识别模块
**用户故事**：作为用户，我想要通过拍照识别植物，以便了解植物信息和养护方法

**验收标准**：
- Given 用户打开小程序
- When 用户点击"拍照识别"按钮
- Then 系统调用摄像头并允许用户拍照
- When 用户拍摄植物照片
- Then 系统在3秒内返回识别结果
- And 显示植物名称、科属、养护方法等信息
- And 准确率不低于85%

### 3.2 电商交易模块
**用户故事**：作为消费者，我想要在线购买鲜花并配送到家，以便表达情感或装饰家居

**验收标准**：
- Given 用户浏览商品列表
- When 用户选择商品加入购物车
- Then 系统实时计算总价和配送费
- When 用户提交订单
- Then 系统生成订单并支持微信支付
- And 订单状态实时更新
- And 支持同城2小时配送

### 3.3 植物商城模块
**用户故事**：作为园艺爱好者，我想要购买各种植物盆栽和园艺工具，以便打造自己的花园

**验收标准**：
- Given 用户进入商城页面
- When 用户按品类筛选商品
- Then 系统显示相关商品列表
- When 用户查看商品详情
- Then 显示商品规格、养护说明、用户评价
- And 支持收藏和分享功能

### 3.4 内容社区模块
**用户故事**：作为内容创作者，我想要分享园艺知识，以便帮助其他用户并建立个人影响力

**验收标准**：
- Given 用户登录账号
- When 用户发布园艺教程
- Then 系统支持图文混排编辑
- And 内容自动保存草稿
- And 发布后显示在社区首页

### 3.5 用户推广奖励模块
**用户故事**：作为用户，我想要通过推广小程序获得奖励，以便赚取额外收入和优惠

**验收标准**：
- Given 用户完成实名认证
- When 用户进入推广中心
- Then 系统生成专属推广二维码和链接
- When 新用户通过推广链接注册
- Then 推广人获得10元现金奖励
- And 新用户获得5元新人优惠券
- When 被推广用户完成首单消费
- Then 推广人获得订单金额10%的额外奖励

**用户故事**：作为推广员，我想要查看我的推广业绩和收益，以便了解推广效果

**验收标准**：
- Given 用户登录账号
- When 用户查看推广数据
- Then 系统显示累计推广人数、成功订单数
- And 显示可提现余额和已提现金额
- And 支持按时间筛选统计数据

**用户故事**：作为推广员，我想要提现我的推广收益，以便将奖励转化为实际收入

**验收标准**：
- Given 用户有可提现余额
- When 用户申请提现
- Then 系统验证提现金额≥50元
- And 提现申请提交后24小时内到账
- And 提现记录可追溯查询

## 4. 非功能需求

### 4.1 性能需求
- 页面加载时间：< 2秒
- 识别响应时间：< 3秒
- 订单处理延迟：< 1秒

### 4.2 安全需求
- 用户数据加密存储
- 支付接口符合PCI DSS标准
- 防止SQL注入和XSS攻击

### 4.3 可靠性需求
- 系统可用性：99.9%
- 数据备份：每日自动备份
- 故障恢复：30分钟内恢复

## 5. 原型说明

### 5.1 主要界面
1. **首页**：搜索栏、植物识别入口、热门商品推荐
2. **识别页面**：摄像头界面、拍照按钮、图库选择
3. **商城页面**：商品分类、商品列表、筛选排序
4. **我的页面**：订单管理、收藏夹、设置

### 5.2 交互流程
- 识别流程：首页 → 拍照 → 识别结果 → 相关商品推荐
- 购买流程：商品详情 → 加入购物车 → 填写地址 → 支付 → 订单跟踪

## 6. 技术架构

### 6.1 客户端层
- **微信小程序**：基于uni-app开发，提供用户端功能
- **后台管理系统**：基于Vue.js 3 + Ant Design开发，提供管理功能
- **官网系统**：基于HTML5 + Bootstrap开发，提供企业宣传功能

### 6.2 接入层
- **API网关**：基于Nginx + Node.js，提供统一的API接入和路由分发

### 6.3 后端技术栈
- **API服务**：Node.js + Express.js + TypeScript + RESTful API
- **数据库**：MySQL 8.0 主数据库
  - **测试环境**：192.168.0.240:3306 (用户名: root, 密码: aiot$Aiot123, 数据库: ajhdata)
  - **生产环境**：129.211.213.226:9527 (用户名: root, 密码: aiotAiot123!, 数据库: ajhdata)
  - **连接池配置**：最大连接数200，最小连接数20，超时时间30秒
  - **字符编码**：UTF8MB4（支持emoji表情）
  - **时区设置**：东八区（+08:00）
- **缓存系统**：Redis Cluster 分布式缓存 + Node.js内置本地缓存
- **消息队列**：暂不开启（预留RabbitMQ集成能力）
- **文件存储**：腾讯云对象存储COS
- **实时通信**：WebSocket（用于大屏数据推送和实时通知）
- **API文档**：Swagger

### 6.4 数据库配置文件结构

项目已创建以下数据库相关配置文件：

1. **`backend/config/database.js`** - 数据库连接配置
2. **`backend/.env.example`** - 环境变量配置模板
3. **`backend/utils/dbConnector.js`** - 数据库连接工具类
4. **`scripts/backend/initDatabase.js`** - 数据库初始化脚本
5. **`backend/package.json`** - 项目依赖管理

配置支持多环境自动切换，通过 `NODE_ENV` 环境变量区分开发和生产环境。

#### 数据库管理脚本命令：
- `npm run db:init` - 初始化数据库连接验证（脚本位于 `/scripts/backend/` 目录）
- `npm run db:check` - 只检查数据库连接状态
- `npm run db:migrate` - 执行数据库迁移（预留）
- `npm run db:seed` - 填充初始数据（预留）

### 6.4 前端技术栈
- **小程序框架**：uni-app
- **开发语言**：JavaScript/TypeScript
- **UI框架**：WeUI
- **状态管理**：Redux
- **构建工具**：Webpack
- **包管理**：npm/yarn

### 6.5 官网技术栈
- **核心技术**：HTML5 + Bootstrap
- **开发语言**：JavaScript
- **构建工具**：Webpack
- **包管理**：npm/yarn

### 6.6 第三方服务集成
- 微信支付接口
- 腾讯地图LBS服务
- 物流配送API
- 内容安全审核机制
- 植物识别AI服务

## 7. 项目里程碑

### 7.1 第一阶段（1个月）
- ✅ 基础框架搭建
- ✅ 植物识别功能开发
- ✅ 用户系统实现

### 7.2 第二阶段（2个月）
- ✅ 电商功能完整实现
- ✅ 支付系统集成
- ✅ 内容社区搭建

### 7.3 第三阶段（1个月）
- ✅ 性能优化
- ✅ 商家入驻功能
- ✅ 正式上线运营

## 8. 风险与应对

### 8.1 技术风险
- 植物识别准确率不足 → 接入多个识别API备用
- 高并发处理能力 → 使用负载均衡和缓存
- 数据库性能瓶颈 → 单MySQL数据库优化方案（详见附录C）
- 第三方服务不可用 → 降级策略和备用方案

### 8.2 运营风险
- 商品供应链不稳定 → 建立多供应商体系
- 用户增长缓慢 → 设计裂变营销活动
- 推广奖励成本控制 → 设置提现门槛和奖励上限
- 推广作弊风险 → 建立反作弊监控系统

## 9. API接口规范

### 9.1 通用规范
- 采用RESTful API设计风格
- 请求和响应格式为JSON
- 使用HTTPS加密传输
- 接口版本控制：/api/v1/

### 9.2 认证授权
- JWT Token认证机制
- Token有效期7天
- 接口权限分级控制

### 9.3 响应格式
```json
{
  "code": 200,
  "message": "成功",
  "data": {},
  "timestamp": 1640995200000
}
```

### 9.4 错误码规范
- 200: 成功
- 400: 参数错误
- 401: 未授权
- 403: 禁止访问
- 404: 资源不存在
- 500: 服务器错误

## 10. 数据字典

### 10.1 核心数据表
- **users**: 用户表（用户ID、手机号、密码、推广码等）
- **plants**: 植物信息表（植物ID、名称、科属、养护方法等）
- **products**: 商品表（商品ID、名称、价格、库存等）
- **orders**: 订单表（订单ID、用户ID、金额、状态等）
- **promotions**: 推广记录表（推广人ID、被推广人ID、奖励金额等）

### 10.2 重要字段说明
- 用户ID: 雪花算法生成
- 订单号: 时间戳+随机数
- 金额字段: 单位分存储
- 时间字段: Unix时间戳

## 11. 测试策略

### 11.1 测试类型
- 单元测试: 代码逻辑测试
- 集成测试: 接口联调测试
- 性能测试: 压力负载测试
- 安全测试: 漏洞扫描测试

### 11.2 测试环境
- 测试数据库: 192.168.0.240:3306/ajhdata_test
- 测试域名: test.aijianhua.com
- 测试账号: 预置测试用户数据

### 11.3 自动化测试
- Jest单元测试框架
- Postman接口测试
- JMeter性能测试
- SonarQube代码质量检测

## 12. 部署方案

### 12.1 环境划分
- **开发环境**: 内网访问，用于日常开发
- **测试环境**: 外网可访问，用于测试验证
- **预发布环境**: 生产环境镜像，用于最终测试
- **生产环境**: 正式线上环境

### 12.2 部署流程
1. 代码提交到Git仓库
2. 自动触发CI/CD流水线
3. 执行自动化测试
4. 构建Docker镜像
5. 部署到对应环境
6. 健康检查和服务发现

### 12.3 监控告警
- 应用性能监控(APM)
- 错误日志监控
- 业务指标监控
- 短信/邮件告警机制

## 13. 运维管理

### 13.1 日志管理
- 访问日志记录
- 错误日志收集
- 日志分级存储
- 日志查询分析

### 13.2 数据备份
- 每日全量备份
- 实时增量备份
- 异地灾备方案
- 备份恢复演练

### 13.3 安全运维
- 定期安全扫描
- 漏洞修复流程
- 访问权限控制
- 操作审计日志

---
*本文档将持续更新，请关注最新版本*

## 附录

### 附录A: 项目成员及职责
- 产品经理: 需求分析和产品设计
- 前端开发: 小程序和后台管理系统开发
- 后端开发: API服务和数据库开发
- 测试工程师: 质量保证和测试验证
- 运维工程师: 系统部署和运维保障

### 附录B: 相关文档链接
- [技术设计文档](./详细设计.md)
- [数据库设计文档](./backend/README_DATABASE.md)
- [API接口文档](http://api.aijianhua.com/docs)
- [部署操作手册](./部署指南.md)

### 附录C: 数据库性能优化方案

#### C.1 单MySQL数据库架构

**架构设计**
```
应用服务器 → MySQL数据库（读写合一）
```

**配置优化**
1. **连接池配置**
   - 最大连接数: 200
   - 最小连接数: 20  
   - 连接超时时间: 30秒
   - 最大空闲时间: 300秒

2. **性能调优**
   - 调整InnoDB缓冲池大小
   - 优化查询缓存配置
   - 合理设置线程缓存
   - 配置适当的日志文件大小

#### C.2 分库分表方案

**分库策略**
- **垂直分库**: 按业务模块拆分
  - 用户库: users, addresses, identifications
  - 商品库: products, categories, inventories  
  - 订单库: orders, order_items, payments
  - 推广库: promotions, rewards

- **水平分库**: 按数据量拆分
  - 用户数据: 按用户ID范围分库
  - 订单数据: 按时间范围分库
  - 识别记录: 按用户ID哈希分库

**分表策略**
- **用户表**: 按用户ID取模分表（1024张表）
- **订单表**: 按创建时间分表（每月一张表）
- **识别记录表**: 按用户ID和日期分表
- **商品表**: 按分类ID分表

**分片键选择**
- 用户相关表: user_id
- 订单相关表: order_id + create_time
- 商品相关表: product_id + category_id
- 识别记录: user_id + identify_time

#### C.3 实施路线图

**第一阶段（立即实施）**
- 优化现有SQL查询性能
- 添加合适的数据库索引
- 调整数据库连接池配置
- 配置数据库性能监控

**第二阶段（3个月后）**
- 根据业务增长评估分库分表需求
- 准备数据迁移方案
- 优化数据库硬件配置（如需要）

**第三阶段（6个月后）**
- 根据实际数据量决定是否实施分库分表
- 如需要，实施垂直分库按业务模块拆分
- 完善数据备份和容灾方案

#### C.4 监控和运维

**性能监控指标**
- 数据库连接数和使用率
- 查询响应时间（P95、P99）
- 主从复制延迟时间
- 慢查询数量和详情
- 锁等待和死锁情况

**告警机制**
- 数据库连接池耗尽告警
- 主从复制延迟超过阈值告警
- 慢查询数量激增告警
- 磁盘空间不足告警

**备份恢复**
- 每日全量备份 + 实时增量备份
- 跨机房灾备方案
- 定期恢复演练
- 备份数据加密存储

#### C.5 预期效果

- **读写性能**: 提升2-3倍（通过查询优化和索引）
- **并发能力**: 支持200+并发连接
- **数据容量**: 支持TB级数据存储
- **可用性**: 99.5%的可用性保障
- **扩展性**: 支持后续按需扩展架构