aiotagro/aijianhua
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新项目文档，完善需求和技术细节

Browse Source
This commit is contained in:
ylweng
2025-09-01 02:35:41 +08:00
parent e1647902e2
commit ad20888cd4
57 changed files with 961 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files

454
docs/API接口文档.md Normal file
View File

@@ -0,0 +1,454 @@
# 爱鉴花小程序后端API接口文档
## 概述
本文档详细描述了爱鉴花小程序后端RESTful API接口规范，基于OpenAPI 3.0标准。
## 基础信息
- **Base URL**: `http://localhost:3200/api/v1`
- **认证方式**: Bearer Token (JWT)
- **响应格式**: JSON
## 认证接口
### 用户注册
**POST** `/auth/register`
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| username | string | 是 | 用户名 |
| password | string | 是 | 密码（最少6位） |
| phone | string | 是 | 手机号 |
| email | string | 否 | 邮箱 |
| user_type | string | 否 | 用户类型（farmer/buyer/admin） |
**响应示例**:
```json
{
"code": 201,
"message": "注册成功",
"data": {
"user_id": 1,
"username": "testuser",
"phone": "13800138000",
"email": "user@example.com",
"user_type": "farmer",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
}
```
### 用户登录
**POST** `/auth/login`
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| login | string | 是 | 用户名/手机号/邮箱 |
| password | string | 是 | 密码 |
**响应示例**:
```json
{
"code": 200,
"message": "登录成功",
"data": {
"user_id": 1,
"username": "testuser",
"phone": "13800138000",
"email": "user@example.com",
"user_type": "farmer",
"avatar_url": "/uploads/avatars/avatar.jpg",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
}
```
## 用户接口
### 获取用户信息
**GET** `/users/me`
**请求头**:
```
Authorization: Bearer <token>
```
**响应示例**:
```json
{
"code": 200,
"message": "获取成功",
"data": {
"id": 1,
"username": "testuser",
"phone": "13800138000",
"email": "user@example.com",
"user_type": "farmer",
"avatar_url": "/uploads/avatars/avatar.jpg",
"created_at": "2023-01-01T00:00:00Z",
"last_login": "2023-01-01T00:00:00Z"
}
}
```
### 更新用户信息
**PUT** `/users/{id}`
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| email | string | 否 | 邮箱 |
| real_name | string | 否 | 真实姓名 |
| avatar_url | string | 否 | 头像URL |
## 商品接口
### 获取商品列表
**GET** `/products`
**查询参数**:
| 参数名 | 类型 | 说明 |
|--------|------|------|
| page | integer | 页码（默认1） |
| limit | integer | 每页数量（默认12） |
| category_id | integer | 分类ID |
| keyword | string | 搜索关键词 |
| min_price | number | 最低价格 |
| max_price | number | 最高价格 |
| sort_by | string | 排序字段（name/price/created_at/stock） |
| sort_order | string | 排序方向（asc/desc） |
**响应示例**:
```json
{
"code": 200,
"message": "获取成功",
"data": {
"products": [
{
"id": 1,
"name": "玫瑰花",
"category_id": 1,
"price": 29.9,
"stock": 100,
"image": "/uploads/products/rose.jpg",
"description": "新鲜玫瑰花，香气浓郁",
"category_name": "鲜花"
}
],
"pagination": {
"page": 1,
"limit": 12,
"total": 50,
"pages": 5
}
}
}
```
### 获取商品详情
**GET** `/products/{id}`
## 订单接口
### 创建订单
**POST** `/orders`
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| items | array | 是 | 商品列表 |
| shipping_address | string | 是 | 收货地址 |
**items数组结构**:
```json
[
{
"product_id": 1,
"quantity": 2
}
]
```
## 花卉识别接口
### 花卉识别
**POST** `/identifications/identify`
**请求格式**: `multipart/form-data`
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| image | file | 是 | 植物图片文件 |
| user_id | integer | 否 | 用户ID（记录识别历史） |
**响应示例**:
```json
{
"code": 200,
"message": "识别成功",
"data": {
"identification_id": 1,
"plant_name": "玫瑰花",
"scientific_name": "Rosa rugosa",
"family": "蔷薇科",
"confidence": 0.92,
"care_tips": "喜阳光，需要充足水分",
"related_products": [
{
"id": 1,
"name": "玫瑰花束",
"price": 29.9,
"image": "/uploads/products/rose.jpg"
}
],
"created_at": "2024-01-15T10:30:00Z"
}
}
```
### 获取识别历史
**GET** `/identifications/history`
**查询参数**:
| 参数名 | 类型 | 说明 |
|--------|------|------|
| user_id | integer | 用户ID |
| page | integer | 页码（默认1） |
| limit | integer | 每页数量（默认10） |
**响应示例**:
```json
{
"code": 200,
"message": "获取成功",
"data": {
"identifications": [
{
"id": 1,
"plant_name": "玫瑰花",
"image_url": "/uploads/identifications/rose_123.jpg",
"confidence": 0.92,
"created_at": "2024-01-15T10:30:00Z"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 15,
"pages": 2
}
}
}
```
## 推广奖励接口
### 生成推广链接
**POST** `/promotions/generate-link`
**请求头**:
```
Authorization: Bearer <token>
```
**响应示例**:
```json
{
"code": 200,
"message": "生成成功",
"data": {
"promotion_link": "https://aijianhua.com/register?ref=ABC123",
"qr_code_url": "/uploads/qrcodes/ABC123.png",
"expires_at": "2024-02-15T10:30:00Z"
}
}
```
### 获取推广数据
**GET** `/promotions/stats`
**查询参数**:
| 参数名 | 类型 | 说明 |
|--------|------|------|
| start_date | string | 开始日期（YYYY-MM-DD） |
| end_date | string | 结束日期（YYYY-MM-DD） |
**响应示例**:
```json
{
"code": 200,
"message": "获取成功",
"data": {
"total_referrals": 50,
"successful_orders": 25,
"pending_rewards": 250.00,
"withdrawn_rewards": 500.00,
"available_balance": 250.00,
"daily_stats": [
{
"date": "2024-01-15",
"referrals": 5,
"orders": 3,
"rewards": 30.00
}
]
}
}
```
### 申请提现
**POST** `/promotions/withdraw`
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| amount | number | 是 | 提现金额（≥50元） |
| bank_account | string | 是 | 银行账号 |
| bank_name | string | 是 | 银行名称 |
**响应示例**:
```json
{
"code": 200,
"message": "提现申请已提交",
"data": {
"withdrawal_id": 1,
"amount": 100.00,
"status": "pending",
"estimated_arrival": "2024-01-16T10:30:00Z"
}
}
```
### 获取提现记录
**GET** `/promotions/withdrawals`
**查询参数**:
| 参数名 | 类型 | 说明 |
|--------|------|------|
| page | integer | 页码（默认1） |
| limit | integer | 每页数量（默认10） |
| status | string | 状态（pending/completed/rejected） |
**响应示例**:
```json
{
"code": 200,
"message": "获取成功",
"data": {
"withdrawals": [
{
"id": 1,
"amount": 100.00,
"status": "completed",
"bank_account": "****1234",
"bank_name": "中国银行",
"created_at": "2024-01-15T10:30:00Z",
"completed_at": "2024-01-16T10:30:00Z"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 5,
"pages": 1
}
}
}
```
## 错误码规范
| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 200 | 成功 | 请求成功 |
| 201 | 创建成功 | 资源创建成功 |
| 400 | 参数错误 | 请求参数验证失败 |
| 401 | 未授权 | 需要登录认证 |
| 403 | 禁止访问 | 权限不足 |
| 404 | 资源不存在 | 请求的资源不存在 |
| 409 | 资源冲突 | 资源已存在或状态冲突 |
| 500 | 服务器内部错误 | 服务器内部处理错误 |
| 1001 | 识别失败 | 植物识别处理失败 |
| 1002 | 图片格式不支持 | 上传的图片格式不支持 |
| 2001 | 推广奖励不足 | 可提现余额不足50元 |
| 2002 | 提现频率限制 | 24小时内只能提现一次 |
| 3001 | 库存不足 | 商品库存不足 |
| 3002 | 订单状态异常 | 订单状态不允许此操作 |
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| image | file | 是 | 花卉图片文件 |
**响应示例**:
```json
{
"code": 200,
"message": "识别成功",
"data": {
"identification_id": 1,
"image_url": "/uploads/identifications/identify-123.jpg",
"results": [
{
"name": "玫瑰",
"confidence": 0.95,
"scientificName": "Rosa rugosa",
"description": "玫瑰是蔷薇科蔷薇属的植物，具有浓郁的芳香和美丽的花朵。"
}
],
"best_result": {
"name": "玫瑰",
"confidence": 0.95,
"scientificName": "Rosa rugosa",
"description": "玫瑰是蔷薇科蔷薇属的植物，具有浓郁的芳香和美丽的花朵。"
}
}
}
```
### 获取识别历史
**GET** `/identifications`
## 安全要求
1. 所有敏感接口必须使用HTTPS
2. JWT token有效期7天
3. 密码使用bcrypt加密存储
4. 文件上传限制10MB
5. 支持CORS跨域访问
## 版本历史
- v1.0.0 (2024-03-15): 初始版本发布
- 包含用户认证、商品管理、订单管理、花卉识别等核心功能

49
docs/CHANGELOG.md Normal file
View File

@@ -0,0 +1,49 @@
# 变更日志
爱鉴花项目遵循[语义化版本](https://semver.org/lang/zh-CN/)。
## [未发布]
### 新增
- 初始化项目结构和文档
- 创建微信小程序、后端服务、后台管理系统、官方网站四个子项目
- 完善需求文档、详细设计文档、项目总览文档
- 添加数据库配置和连接工具
- 创建部署指南和贡献指南
### 变更
- 优化项目文档结构和内容
- 统一技术栈和开发规范
- 完善开发环境配置说明
### 修复
- 文档中的错误和遗漏信息
- 开发环境配置问题
- 数据库用户表缺少last_login字段的问题
- 密码哈希值存储和验证问题
- bcrypt版本不匹配导致的密码验证失败
## 版本规范
### 版本格式
`主版本号.次版本号.修订号`
- **主版本号**: 不兼容的API修改
- **次版本号**: 向下兼容的功能性新增
- **修订号**: 向下兼容的问题修正
### 发布周期
- 主版本号: 重大功能更新或架构调整
- 次版本号: 每月或每季度发布
- 修订号: 根据需要随时发布
## 版本历史
### v0.1.0 - 2024-01-01
- 项目初始版本
- 基础框架搭建完成
- 核心文档编写完成
- 开发环境配置就绪
---
*变更日志格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)*

171
docs/CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,171 @@
# 贡献指南
欢迎参与爱鉴花项目的开发！本文档将指导您如何为项目做出贡献。
## 🎯 开发流程
### 1. 环境准备
- 确保已安装 Node.js 16.0.0+
- 安装 Git 版本控制工具
- 配置开发工具（HBuilderX、VSCode等）
### 2. 获取代码
```bash
git clone https://github.com/your-username/aijianhua.git
cd aijianhua
```
### 3. 分支管理
我们使用 Git Flow 工作流：
- `main` - 主分支，用于生产环境
- `develop` - 开发分支，集成所有功能
- `feature/*` - 功能开发分支
- `bugfix/*` - bug修复分支
- `release/*` - 发布分支
### 4. 开发步骤
1. 从 `develop` 分支创建功能分支
2. 在分支上开发新功能或修复bug
3. 提交代码并推送到远程仓库
4. 创建 Pull Request 到 `develop` 分支
5. 代码审查通过后合并
## 📝 代码规范
### JavaScript/TypeScript
- 使用 ESLint + Prettier 进行代码格式化
- 遵循 Airbnb JavaScript 风格指南
- 使用 async/await 代替回调函数
- 添加必要的注释和文档
### Vue/uni-app
- 使用 Composition API
- 组件命名使用 PascalCase
- Props 定义使用 TypeScript 类型
- 使用 Vue Router 进行路由管理
### Node.js
- 使用 Express.js 框架
- 中间件使用统一的错误处理
- API 响应格式标准化
- 使用 Winston 进行日志记录
## 🔧 提交规范
### Commit Message 格式
```
<type>(<scope>): <subject>
<body>
<footer>
```
### Type 类型
- `feat`: 新功能
- `fix`: bug修复
- `docs`: 文档更新
- `style`: 代码格式调整
- `refactor`: 代码重构
- `test`: 测试相关
- `chore`: 构建过程或辅助工具变动
### 示例
```
feat(user): 添加用户注册功能
- 实现用户注册API接口
- 添加手机号验证功能
- 完善错误处理机制
Closes #123
```
## 🧪 测试要求
### 单元测试
- 后端API接口需要编写单元测试
- 测试覆盖率要求达到80%以上
- 使用 Jest 测试框架
### 集成测试
- 主要业务流程需要集成测试
- 测试数据库操作和API调用
- 模拟各种边界情况
### E2E测试
- 关键用户流程需要端到端测试
- 使用 Cypress 或 Puppeteer
- 覆盖主要业务场景
## 📖 文档要求
### 代码注释
- 公共方法和复杂逻辑需要添加注释
- 使用 JSDoc 格式注释
- 注释说明参数、返回值、异常情况
### API文档
- 使用 Swagger/OpenAPI 规范
- 文档需要与代码同步更新
- 包含请求示例和响应示例
### 项目文档
- README 文件需要保持最新
- 添加必要的配置说明
- 更新部署和运维指南
## 🐛 Issue 报告
### Bug报告格式
```
## 问题描述
清晰描述遇到的问题
## 重现步骤
1. 第一步
2. 第二步
3. 第三步
## 预期行为
期望的正常表现
## 实际行为
实际发生的异常表现
## 环境信息
- 操作系统:
- 浏览器:
- 版本:
```
### 功能请求格式
```
## 功能描述
详细描述请求的功能
## 使用场景
在什么情况下需要这个功能
## 解决方案建议
如果有的话，提供实现建议
## 附加信息
任何其他相关信息
```
## 🤝 行为准则
- 尊重其他贡献者
- 建设性的代码审查
- 及时响应问题和请求
- 遵守开源协议
## 📞 联系方式
如有问题可以通过以下方式联系：
- GitHub Issues
- 项目邮箱: aijianhua@example.com
- 开发者微信群
感谢您的贡献！🎉

459
docs/PRD_爱鉴花小程序.md Normal file
View File

@@ -0,0 +1,459 @@
# 爱鉴花小程序 - 产品需求文档
## 版本历史
| 版本 | 日期 | 作者 | 描述 |
|------|------|------|------|
| 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%的可用性保障
- **扩展性**: 支持后续按需扩展架构

28
docs/README.md Normal file
View File

@@ -0,0 +1,28 @@
# 爱鉴花项目文档中心
## 项目介绍
这是爱鉴花项目的完整文档中心，包含所有技术文档、API说明和部署指南。
## 技术栈
- Node.js
- Express.js
- SQLite（开发环境）
- MySQL（生产环境）
- Redis
## 文档结构
- 需求文档: 项目业务需求和功能说明
- 设计文档: 系统架构、数据库设计和详细设计
- API文档: 前后端接口规范和说明
- 部署指南: 环境配置和部署流程
- 开发计划: 项目开发进度和任务安排
## 开发说明
请确保安装了Node.js环境，并使用npm管理依赖。
## 文档
- [开发计划](./开发计划.md)
- [功能模块](./功能模块.md)
- [数据库设计](./数据库设计文档.md)
- [API接口文档](./API接口文档.md)

124
docs/README_DATABASE.md Normal file
View File

@@ -0,0 +1,124 @@
# 数据库配置和使用指南
## 📋 数据库连接信息
### 开发环境 (MySQL)
- **主机**: 129.211.213.226
- **端口**: 9527
- **用户名**: root
- **密码**: aiotAiot123!
- **数据库**: ajhdata
### 生产环境 (MySQL)
- **主机**: 129.211.213.226
- **端口**: 9527
- **用户名**: root
- **密码**: aiotAiot123!
- **数据库**: ajhdata
## 🚀 快速开始
### 1. 安装依赖
```bash
cd backend
npm install
```
### 2. 配置环境变量
复制环境变量模板文件：
```bash
cp .env.example .env.development
```
编辑 `.env.development` 文件，根据实际环境修改配置：
```env
NODE_ENV=development
DB_HOST=192.168.0.240
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=aiot$Aiot123
DB_DATABASE=ajhdata
```
### 3. 验证数据库连接
```bash
# 完整初始化验证
npm run db:init
# 只检查连接状态
npm run db:check
```
## 📁 配置文件说明
### `config/database.js`
主数据库配置文件，根据环境变量自动选择配置：
- 开发环境: `NODE_ENV=development`
- 生产环境: `NODE_ENV=production`
### `.env.example`
环境变量配置模板，包含所有可配置参数。
### `utils/dbConnector.js`
数据库连接工具类，提供：
- 连接池管理
- SQL查询执行
- 事务支持
- 健康检查
### `scripts/initDatabase.js`
数据库初始化脚本，功能：
- 验证数据库连接
- 检查数据库版本
- 执行SQL文件（预留）
## 🔧 可用脚本命令
| 命令 | 描述 |
|------|------|
| `npm run db:init` | 完整数据库初始化验证（脚本位于 `/scripts/backend/` 目录） |
| `npm run db:check` | 只检查数据库连接状态 |
| `npm run db:migrate` | 执行数据库迁移（预留） |
| `npm run db:seed` | 填充初始数据（预留） |
## 🛡️ 安全注意事项
1. **密码保护**: 数据库密码已配置在环境变量中，不要硬编码在代码里
2. **连接池**: 使用连接池避免频繁创建连接
3. **错误处理**: 所有数据库操作都有完整的错误处理
4. **SQL注入**: 使用参数化查询防止SQL注入
## 📊 性能优化
- **连接池配置**: 最大20连接，最小5连接
- **超时设置**: 获取连接超时60秒，空闲连接超时30秒
- **字符编码**: UTF8MB4支持中文和emoji
- **时区设置**: 东八区(+08:00)
## 🔍 故障排除
### 连接失败
1. 检查网络是否能访问数据库服务器
2. 验证用户名密码是否正确
3. 确认数据库服务是否启动
### 权限问题
1. 检查用户是否有数据库访问权限
2. 确认数据库是否存在
### 性能问题
1. 检查连接池配置是否合理
2. 监控数据库服务器负载
## 📝 开发建议
1. 开发环境使用测试数据库配置
2. 生产环境使用生产数据库配置
3. 定期备份重要数据
4. 使用事务保证数据一致性
## 🔗 相关文档
- [MySQL官方文档](https://dev.mysql.com/doc/)
- [mysql2 npm包文档](https://www.npmjs.com/package/mysql2)
- [连接池最佳实践](https://github.com/mysqljs/mysql#pooling-connections)

30
docs/功能模块.md Normal file
View File

@@ -0,0 +1,30 @@
# 爱鉴花后端功能模块
## 1. 植物识别服务
- 接收小程序上传的图片
- 调用AI识别服务
- 返回识别结果
## 2. 用户管理模块
- 用户注册/登录
- 用户信息管理
- 用户权限控制
## 3. 商品管理模块
- 商品信息管理
- 商品分类管理
- 库存管理
## 4. 订单管理模块
- 订单创建
- 订单状态管理
- 订单查询
## 5. 支付模块
- 支付接口集成
- 支付状态回调处理
## 6. 数据统计模块
- 用户行为统计
- 销售数据统计
- 识别数据统计

285
docs/后台管理系统API文档.md Normal file
View File

@@ -0,0 +1,285 @@
# 爱鉴花后台管理系统 API 接口文档
基于 OpenAPI 3.0 规范
## 基础信息
- **Base URL**: `http://localhost:3200/api/v1`
- **认证方式**: Bearer Token (JWT)
- **响应格式**: JSON
## 统一响应格式
所有接口都遵循以下响应格式：
```json
{
"code": 200,
"message": "操作成功",
"data": {}
}
```
## 认证接口
### 管理员登录
**POST** `/auth/login`
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| login | string | 是 | 用户名/手机号/邮箱 |
| password | string | 是 | 密码 |
**响应示例**:
```json
{
"code": 200,
"message": "登录成功",
"data": {
"user_id": 1,
"username": "admin",
"user_type": "admin",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
}
```
## 用户管理接口
### 获取用户列表
**GET** `/users`
**权限要求**: 管理员
**查询参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | number | 否 | 页码，默认1 |
| limit | number | 否 | 每页数量，默认10 |
| keyword | string | 否 | 搜索关键词 |
| user_type | string | 否 | 用户类型过滤 |
**响应示例**:
```json
{
"code": 200,
"message": "获取成功",
"data": {
"users": [
{
"id": 1,
"username": "testuser",
"phone": "13800138000",
"email": "test@example.com",
"user_type": "farmer",
"created_at": "2024-01-01T00:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 100,
"pages": 10
}
}
}
```
### 获取用户详情
**GET** `/users/{id}`
**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | number | 是 | 用户ID |
### 删除用户
**DELETE** `/users/{id}`
**权限要求**: 管理员
## 商品管理接口
### 获取商品列表
**GET** `/products`
**查询参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | number | 否 | 页码，默认1 |
| limit | number | 否 | 每页数量，默认10 |
| category_id | number | 否 | 分类ID过滤 |
| min_price | number | 否 | 最低价格 |
| max_price | number | 否 | 最高价格 |
| status | number | 否 | 状态过滤 |
### 创建商品
**POST** `/products`
**权限要求**: 管理员
**请求体**:
```json
{
"name": "玫瑰花",
"category_id": 1,
"price": 29.9,
"stock": 100,
"image": "/uploads/roses.jpg",
"description": "新鲜玫瑰花束"
}
```
## 订单管理接口
### 获取订单列表
**GET** `/orders`
**权限要求**: 管理员
**查询参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | number | 否 | 页码，默认1 |
| limit | number | 否 | 每页数量，默认10 |
| status | number | 否 | 订单状态过滤 |
| start_date | string | 否 | 开始日期 |
| end_date | string | 否 | 结束日期 |
### 更新订单状态
**PUT** `/orders/{id}/status`
**权限要求**: 管理员
**请求体**:
```json
{
"payment_status": 1,
"shipping_status": 2
}
```
## 识别记录管理接口
### 获取识别记录列表
**GET** `/identifications`
**权限要求**: 管理员
**查询参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | number | 否 | 页码，默认1 |
| limit | number | 否 | 每页数量，默认10 |
| start_date | string | 否 | 开始日期 |
| end_date | string | 否 | 结束日期 |
| min_confidence | number | 否 | 最低置信度 |
## 数据统计接口
### 获取系统统计概览
**GET** `/admin/statistics/overview`
**权限要求**: 管理员
**响应示例**:
```json
{
"code": 200,
"message": "获取成功",
"data": {
"total_users": 1000,
"new_users_today": 10,
"total_orders": 500,
"total_revenue": 15000.50,
"total_identifications": 2000,
"active_users_today": 50
}
}
```
### 获取趋势数据
**GET** `/admin/statistics/trend`
**查询参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| days | number | 否 | 天数，默认7 |
| type | string | 否 | 统计类型（users/orders/revenue/identifications） |
## 系统配置接口
### 获取系统配置
**GET** `/admin/config`
**权限要求**: 管理员
### 更新系统配置
**PUT** `/admin/config/{key}`
**权限要求**: 管理员
**请求体**:
```json
{
"value": "new_value"
}
```
## 错误码说明
| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 200 | 成功 | 请求成功 |
| 201 | 创建成功 | 资源创建成功 |
| 400 | 参数错误 | 请求参数验证失败 |
| 401 | 未授权 | 需要登录认证 |
| 403 | 禁止访问 | 权限不足 |
| 404 | 资源不存在 | 请求的资源不存在 |
| 409 | 资源冲突 | 资源已存在或状态冲突 |
| 500 | 服务器内部错误 | 服务器内部处理错误 |
| 1001 | 识别失败 | 植物识别处理失败 |
| 1002 | 图片格式不支持 | 上传的图片格式不支持 |
| 2001 | 推广奖励不足 | 可提现余额不足50元 |
| 2002 | 提现频率限制 | 24小时内只能提现一次 |
| 3001 | 库存不足 | 商品库存不足 |
| 3002 | 订单状态异常 | 订单状态不允许此操作 |
## 安全要求
1. 所有敏感操作需要管理员权限
2. API请求需要携带有效的JWT Token
3. 密码传输需要加密
4. 文件上传需要验证文件类型和大小
---
*文档版本: 1.0.0*
*最后更新: 2024-03-15*

194
docs/开发计划.md Normal file
View File

@@ -0,0 +1,194 @@
# 爱鉴花小程序 - 开发计划
## 版本历史
| 版本 | 日期 | 作者 | 描述 |
|------|------|------|------|
| v1.0 | 2024-01-15 | 项目经理 | 初始版本 |
## 1. 项目里程碑
### 里程碑1：MVP版本上线（4周）
- **目标**：核心功能可用，支持植物识别和基础购物
- **交付物**：小程序v1.0上线，后台管理系统v1.0
- **关键指标**：日活1000+，识别准确率85%+
### 里程碑2：推广功能完善（8周）
- **目标**：完整的推广奖励体系，支付功能
- **交付物**：推广中心v1.0，微信支付集成
- **关键指标**：月GMV 10万+，推广转化率20%+
### 里程碑3：商业化运营（12周）
- **目标**：稳定运营，数据驱动优化
- **交付物**：数据统计平台，运营后台
- **关键指标**：日活1万+，月GMV 50万+
## 2. 详细开发计划
### 第一阶段：基础框架搭建（2周）
| 任务 | 负责人 | 工时 | 优先级 | 依赖 |
|------|--------|------|--------|------|
| 技术选型和环境搭建 | 架构师 | 3人日 | P0 | 无 |
| 数据库设计和建表 | 后端工程师 | 5人日 | P0 | 技术选型 |
| 用户服务基础框架 | 后端工程师 | 4人日 | P0 | 数据库设计 |
| 商品服务基础框架 | 后端工程师 | 4人日 | P0 | 数据库设计 |
| API网关和路由配置 | 后端工程师 | 3人日 | P0 | 服务框架 |
| 小程序基础框架搭建 | 前端工程师 | 5人日 | P0 | 无 |
**本阶段产出**：
- 完整的开发环境
- 数据库Schema v1.0
- 基础服务框架
- 小程序基础页面
### 第二阶段：核心功能开发（4周）
| 任务 | 负责人 | 工时 | 优先级 | 依赖 |
|------|--------|------|--------|------|
| 用户注册登录功能 | 后端工程师 | 5人日 | P0 | 用户服务框架 |
| 植物识别API集成 | 后端工程师 | 8人日 | P0 | 无 |
| 商品管理和展示 | 后端工程师 | 6人日 | P0 | 商品服务框架 |
| 购物车和订单功能 | 后端工程师 | 8人日 | P0 | 用户+商品服务 |
| 小程序首页和识别页 | 前端工程师 | 10人日 | P0 | 基础框架 |
| 商品详情和购物流程 | 前端工程师 | 12人日 | P0 | 首页完成 |
| 用户中心页面 | 前端工程师 | 6人日 | P1 | 登录功能 |
**本阶段产出**：
- 完整的植物识别功能
- 基础电商交易流程
- 小程序核心页面
- API接口v1.0
### 第三阶段：推广奖励功能（3周）
| 任务 | 负责人 | 工时 | 优先级 | 依赖 |
|------|--------|------|--------|------|
| 推广链接生成服务 | 后端工程师 | 5人日 | P0 | 用户服务 |
| 推广数据统计 | 后端工程师 | 6人日 | P0 | 订单服务 |
| 奖励计算和发放 | 后端工程师 | 8人日 | P0 | 推广统计 |
| 提现申请和处理 | 后端工程师 | 6人日 | P1 | 奖励计算 |
| 推广中心页面 | 前端工程师 | 8人日 | P0 | 用户中心 |
| 提现页面和流程 | 前端工程师 | 6人日 | P1 | 推广中心 |
**本阶段产出**：
- 完整的推广奖励体系
- 提现处理流程
- 推广数据统计
- 小程序推广相关页面
### 第四阶段：支付和运营功能（3周）
| 任务 | 负责人 | 工时 | 优先级 | 依赖 |
|------|--------|------|--------|------|
| 微信支付集成 | 后端工程师 | 8人日 | P0 | 订单服务 |
| 支付回调处理 | 后端工程师 | 4人日 | P0 | 支付集成 |
| 订单状态管理 | 后端工程师 | 5人日 | P0 | 支付回调 |
| 数据统计服务 | 后端工程师 | 8人日 | P1 | 所有服务 |
| 支付页面和流程 | 前端工程师 | 6人日 | P0 | 订单页面 |
| 数据统计页面 | 前端工程师 | 8人日 | P1 | 数据服务 |
**本阶段产出**：
- 完整的支付流程
- 订单状态管理系统
- 基础数据统计功能
- 支付相关页面
### 第五阶段：测试和优化（2周）
| 任务 | 负责人 | 工时 | 优先级 | 依赖 |
|------|--------|------|--------|------|
| 单元测试编写 | 测试工程师 | 10人日 | P0 | 功能开发完成 |
| 集成测试 | 测试工程师 | 8人日 | P0 | 单元测试 |
| 性能测试和优化 | 后端工程师 | 6人日 | P1 | 集成测试 |
| 安全漏洞扫描 | 安全工程师 | 4人日 | P1 | 代码完成 |
| 用户体验优化 | 前端工程师 | 6人日 | P1 | 测试反馈 |
**本阶段产出**：
- 测试报告和Bug修复
- 性能优化方案
- 安全评估报告
- 用户体验改进
### 第六阶段：部署上线（1周）
| 任务 | 负责人 | 工时 | 优先级 | 依赖 |
|------|--------|------|--------|------|
| 生产环境部署 | DevOps工程师 | 3人日 | P0 | 测试通过 |
| 域名和SSL配置 | DevOps工程师 | 2人日 | P0 | 部署完成 |
| 监控告警设置 | DevOps工程师 | 3人日 | P1 | 部署完成 |
| 数据迁移和验证 | 后端工程师 | 4人日 | P0 | 生产环境 |
| 小程序提交审核 | 前端工程师 | 2人日 | P0 | 生产环境 |
**本阶段产出**：
- 生产环境正式运行
- 小程序上线发布
- 监控告警系统
- 运维文档
### 第七阶段：运营维护（持续）
| 任务 | 负责人 | 频率 | 优先级 |
|------|--------|------|--------|
| 系统监控和告警处理 | DevOps工程师 | 7×24 | P0 |
| Bug修复和功能优化 | 全团队 | 按需 | P1 |
| 数据分析和业务优化 | 产品经理 | 每周 | P1 |
| 用户反馈收集处理 | 运营团队 | 每日 | P2 |
## 3. 资源分配
### 3.1 团队组成
| 角色 | 人数 | 主要职责 |
|------|------|--------|
| 产品经理 | 1 | 需求分析，产品规划 |
| 架构师 | 1 | 技术架构，技术选型 |
| 后端工程师 | 2 | 服务开发，API实现 |
| 前端工程师 | 2 | 小程序开发，页面实现 |
| 测试工程师 | 1 | 测试用例，质量保证 |
| DevOps工程师 | 1 | 部署运维，监控告警 |
### 3.2 工时估算
| 阶段 | 后端工时 | 前端工时 | 总工时 | 周期 |
|------|---------|---------|--------|------|
| 基础框架 | 19人日 | 5人日 | 24人日 | 2周 |
| 核心功能 | 27人日 | 28人日 | 55人日 | 4周 |
| 推广功能 | 25人日 | 14人日 | 39人日 | 3周 |
| 支付运营 | 25人日 | 14人日 | 39人日 | 3周 |
| 测试优化 | 6人日 | 6人日 | 22人日 | 2周 |
| 部署上线 | 4人日 | 2人日 | 11人日 | 1周 |
| **总计** | **106人日** | **69人日** | **190人日** | **15周** |
## 4. 风险分析
### 4.1 技术风险
| 风险点 | 影响程度 | 应对措施 |
|--------|----------|----------|
| 植物识别准确率低 | 高 | 多模型对比，人工审核备用方案 |
| 高并发性能问题 | 中 | 压力测试，缓存优化，弹性扩容 |
| 支付接口稳定性 | 高 | 备用支付渠道，异常重试机制 |
### 4.2 业务风险
| 风险点 | 影响程度 | 应对措施 |
|--------|----------|----------|
| 用户增长不及预期 | 中 | 加强推广，优化用户体验 |
| 商品供应链问题 | 高 | 多供应商合作，库存预警 |
| 竞争加剧 | 中 | 差异化功能，快速迭代 |
### 4.3 管理风险
| 风险点 | 影响程度 | 应对措施 |
|--------|----------|----------|
| 人员变动 | 中 | 文档规范化，代码审查 |
| 需求变更 | 中 | 敏捷开发，优先级管理 |
| 进度延迟 | 中 | 里程碑跟踪，风险预警 |
## 5. 质量保证
### 5.1 代码质量
- 代码规范检查（ESLint, Prettier）
- 单元测试覆盖率 > 80%
- Code Review流程
- 自动化CI/CD流水线
### 5.2 测试策略
- 单元测试：核心业务逻辑
- 集成测试：服务间调用
- 性能测试：并发压力测试
- 安全测试：漏洞扫描
### 5.3 监控指标
- 系统可用性：99.9%
- API响应时间：< 2秒
- 错误率：< 0.1%
- 业务指标监控：日活，订单量，GMV

144
docs/数据库设计文档.md Normal file
View File

@@ -0,0 +1,144 @@
# 爱鉴花项目数据库设计文档
## 1. 数据库概述
本项目使用MySQL 8.0+作为主数据库，存储用户、商品、订单、识别记录等核心业务数据。
## 2. 数据库表结构
### 2.1 用户表 (users)
| 字段名 | 类型 | 说明 | 约束 |
|--------|------|------|------|
| id | bigint | 用户ID | 主键，自增 |
| username | varchar(50) | 用户名 | 唯一索引 |
| email | varchar(100) | 邮箱 | 唯一索引 |
| phone | varchar(20) | 手机号 | 唯一索引 |
| password | varchar(255) | 密码（bcrypt加密） | 非空 |
| real_name | varchar(50) | 真实姓名 | 可空 |
| avatar_url | varchar(255) | 头像URL | 可空 |
| user_type | enum | 用户类型 | 非空 |
| status | tinyint | 状态 | 默认1 |
| last_login | timestamp | 最后登录时间 | 可空 |
| created_at | timestamp | 创建时间 | 默认当前时间 |
| updated_at | timestamp | 更新时间 | 自动更新 |
### 2.2 商品分类表 (categories)
| 字段名 | 类型 | 说明 | 约束 |
|--------|------|------|------|
| id | int | 分类ID | 主键，自增 |
| name | varchar(100) | 分类名称 | 非空 |
| parent_id | int | 父分类ID | 默认0 |
| sort_order | int | 排序 | 默认0 |
| status | tinyint | 状态 | 默认1 |
| created_at | timestamp | 创建时间 | 默认当前时间 |
| updated_at | timestamp | 更新时间 | 自动更新 |
### 2.3 商品表 (products)
| 字段名 | 类型 | 说明 | 约束 |
|--------|------|------|------|
| id | bigint | 商品ID | 主键，自增 |
| name | varchar(200) | 商品名称 | 非空 |
| category_id | int | 分类ID | 索引 |
| price | decimal(10,2) | 价格 | 非空 |
| stock | int | 库存 | 默认0 |
| image | varchar(255) | 图片URL | 可空 |
| description | text | 商品描述 | 可空 |
| status | tinyint | 状态 | 默认1 |
| created_at | timestamp | 创建时间 | 默认当前时间 |
| updated_at | timestamp | 更新时间 | 自动更新 |
### 2.4 订单表 (orders)
| 字段名 | 类型 | 说明 | 约束 |
|--------|------|------|------|
| id | bigint | 订单ID | 主键，自增 |
| user_id | bigint | 用户ID | 非空，索引 |
| total_amount | decimal(10,2) | 订单总额 | 非空 |
| payment_status | tinyint | 支付状态 | 默认0 |
| shipping_status | tinyint | 配送状态 | 默认0 |
| shipping_address | text | 配送地址 | 可空 |
| created_at | timestamp | 创建时间 | 默认当前时间 |
| updated_at | timestamp | 更新时间 | 自动更新 |
### 2.5 订单商品表 (order_items)
| 字段名 | 类型 | 说明 | 约束 |
|--------|------|------|------|
| id | bigint | 订单项ID | 主键，自增 |
| order_id | bigint | 订单ID | 非空，索引 |
| product_id | bigint | 商品ID | 非空，索引 |
| quantity | int | 数量 | 非空 |
| unit_price | decimal(10,2) | 单价 | 非空 |
### 2.6 识别记录表 (identifications)
| 字段名 | 类型 | 说明 | 约束 |
|--------|------|------|------|
| id | bigint | 记录ID | 主键，自增 |
| user_id | bigint | 用户ID | 非空，索引 |
| image_url | varchar(255) | 图片URL | 非空 |
| result | text | 识别结果 | 可空 |
| confidence | decimal(5,4) | 置信度 | 可空 |
| created_at | timestamp | 创建时间 | 默认当前时间 |
### 2.7 收货地址表 (addresses)
| 字段名 | 类型 | 说明 | 约束 |
|--------|------|------|------|
| id | bigint | 地址ID | 主键，自增 |
| user_id | bigint | 用户ID | 非空，索引 |
| recipient | varchar(100) | 收货人 | 非空 |
| phone | varchar(20) | 手机号 | 非空 |
| address | text | 详细地址 | 非空 |
| is_default | tinyint | 是否默认 | 默认0 |
| created_at | timestamp | 创建时间 | 默认当前时间 |
| updated_at | timestamp | 更新时间 | 自动更新 |
## 3. 索引设计
### 3.1 唯一索引
- users.phone: 手机号唯一索引
- users.email: 邮箱唯一索引
- users.username: 用户名唯一索引
### 3.2 普通索引
- products.category_id: 商品分类索引
- orders.user_id: 订单用户索引
- orders.created_at: 订单时间索引
- identifications.user_id: 识别记录用户索引
- identifications.created_at: 识别时间索引
- addresses.user_id: 地址用户索引
## 4. 测试数据统计
已插入的测试数据：
- 用户数据: 3条
- 商品分类: 7条
- 商品数据: 5条
- 订单数据: 3条
- 订单商品: 4条
- 识别记录: 3条
- 收货地址: 3条
## 5. 数据库变更记录
### 2024-03-15 更新
- 修复用户表缺少last_login字段的问题
- 密码字段使用password，采用bcrypt加密存储
- 增加数据库初始化脚本，包含默认管理员账号（admin/admin123）
## 5. 数据库连接信息
**生产环境**:
- 主机: 129.211.213.226:9527
- 数据库: ajhdata
- 用户名: root
- 密码: aiotAiot123!
**连接池配置**:
- 最大连接数: 200
- 最小连接数: 20
- 超时时间: 30秒
## 6. 字符编码和时区
- 字符编码: UTF8MB4（支持emoji表情）
- 时区设置: 东八区（+08:00）
---
*本文档最后更新: 2024-03-15*
*数据库版本: MySQL 8.0+*

255
docs/系统架构文档.md Normal file
View File

@@ -0,0 +1,255 @@
# 爱鉴花小程序 - 系统架构文档
## 版本历史
| 版本 | 日期 | 作者 | 描述 |
|------|------|------|------|
| v1.0 | 2024-03-15 | 系统架构师 | 初始版本 |
## 1. 架构设计原则
### 1.1 设计原则
- **微服务架构**：模块化设计，服务解耦
- **高可用性**：99.9%可用性目标
- **可扩展性**：支持水平扩展
- **安全性**：端到端数据加密
- **性能优化**：响应时间<2秒
### 1.2 技术选型理由
| 技术栈 | 选型理由 | 替代方案 |
|--------|----------|----------|
| Node.js + Express | 高性能I/O处理，生态丰富 | Python Django, Java Spring Boot |
| MySQL 8.0+ | 事务支持完善，生态成熟 | PostgreSQL, MongoDB |
| Redis Cluster | 高性能缓存，分布式支持 | Memcached, Hazelcast |
| Vue.js 3 + Ant Design | 组件化开发，企业级UI | React + AntD, Angular + Material |
| uni-app | 跨端开发，成本效益高 | Taro, React Native |
## 2. 系统架构图
```mermaid
graph TB
subgraph "客户端层"
A[微信小程序] --> B[后台管理系统]
A --> C[官网系统]
end
subgraph "接入层"
D[API网关 - Nginx] --> E[负载均衡]
end
subgraph "应用服务层"
F[用户服务] --> G[认证服务]
H[商品服务] --> I[订单服务]
J[识别服务] --> K[支付服务]
L[推广服务] --> M[统计服务]
end
subgraph "数据层"
N[MySQL 8.0+] --> O[主从复制]
P[Redis Cluster] --> Q[分布式缓存]
R[腾讯云COS] --> S[文件存储]
end
E --> F
E --> H
E --> J
E --> L
F --> N
H --> N
J --> N
L --> N
F --> P
H --> P
J --> P
```
## 3. 微服务架构设计
### 3.1 服务划分
| 服务名称 | 职责 | 技术栈 | 部署方式 |
|----------|------|--------|----------|
| 用户服务 | 用户管理、权限控制 | Node.js + Express | 独立部署 |
| 商品服务 | 商品管理、库存管理 | Node.js + Express | 独立部署 |
| 订单服务 | 订单处理、支付集成 | Node.js + Express | 独立部署 |
| 识别服务 | 植物识别AI集成 | Node.js + TensorFlow.js | 独立部署 |
| 推广服务 | 推广奖励计算 | Node.js + Express | 独立部署 |
| 网关服务 | API路由、认证 | Nginx + Lua | 独立部署 |
### 3.2 服务通信机制
- **同步调用**：RESTful API（HTTP/HTTPS）
- **异步消息**：Redis Pub/Sub（预留RabbitMQ集成）
- **服务发现**：Consul/Nacos（预留）
- **配置中心**：Apollo（预留）
## 4. 数据库设计
### 4.1 数据库架构
```mermaid
erDiagram
USERS ||--o{ ORDERS : "创建"
USERS ||--o{ IDENTIFICATIONS : "发起"
USERS ||--o{ PROMOTIONS : "参与"
PRODUCTS ||--o{ ORDER_ITEMS : "包含"
CATEGORIES ||--o{ PRODUCTS : "分类"
ORDERS ||--o{ ORDER_ITEMS : "包含"
ORDERS ||--o{ PAYMENTS : "关联"
USERS {
bigint id PK
varchar username
varchar password_hash
varchar phone
varchar email
enum user_type
datetime created_at
datetime updated_at
}
PRODUCTS {
bigint id PK
varchar name
text description
decimal price
int stock
bigint category_id FK
varchar image_url
}
```
### 4.2 关键表结构
**用户表 (users)**
```sql
CREATE TABLE users (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
username VARCHAR(50) NOT NULL UNIQUE,
password_hash VARCHAR(255) NOT NULL,
phone VARCHAR(20) NOT NULL UNIQUE,
email VARCHAR(100),
user_type ENUM('consumer', 'gardener', 'merchant', 'creator') DEFAULT 'consumer',
avatar_url VARCHAR(255),
real_name VARCHAR(50),
promotion_balance DECIMAL(10,2) DEFAULT 0.00,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_phone (phone),
INDEX idx_email (email)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```
**推广记录表 (promotion_records)**
```sql
CREATE TABLE promotion_records (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
promoter_id BIGINT NOT NULL,
referred_id BIGINT NOT NULL,
reward_amount DECIMAL(10,2) DEFAULT 0.00,
reward_type ENUM('registration', 'first_order') NOT NULL,
status ENUM('pending', 'completed', 'rejected') DEFAULT 'pending',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
completed_at TIMESTAMP NULL,
FOREIGN KEY (promoter_id) REFERENCES users(id),
FOREIGN KEY (referred_id) REFERENCES users(id),
INDEX idx_promoter (promoter_id),
INDEX idx_referred (referred_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```
## 5. 部署架构
### 5.1 生产环境部署
```mermaid
graph LR
subgraph "负载均衡层"
A[阿里云SLB] --> B[Nginx集群]
end
subgraph "应用服务器集群"
C[用户服务 2台] --> D[MySQL主从]
E[商品服务 2台] --> D
F[订单服务 2台] --> D
G[识别服务 2台] --> D
end
subgraph "缓存层"
H[Redis哨兵模式] --> I[3节点集群]
end
subgraph "存储层"
J[腾讯云COS] --> K[CDN加速]
L[MySQL主库] --> M[MySQL从库]
end
B --> C
B --> E
B --> F
B --> G
C --> H
E --> H
F --> H
G --> H
```
### 5.2 监控告警体系
- **应用监控**：Prometheus + Grafana
- **日志收集**：ELK Stack
- **链路追踪**：Jaeger
- **告警通知**：钉钉/邮件/SMS
## 6. 安全架构
### 6.1 安全防护措施
- **网络层**：VPC隔离，安全组规则
- **应用层**：JWT认证，RBAC权限控制
- **数据层**：字段级加密，SQL注入防护
- **传输层**：HTTPS加密，TLS 1.3
### 6.2 敏感数据处理
- 密码：bcrypt加密存储
- 手机号：AES加密存储
- 支付信息：PCI DSS合规处理
- 日志数据：脱敏处理
## 7. 性能优化策略
### 7.1 数据库优化
- 索引优化：覆盖索引，联合索引
- 查询优化：避免SELECT *，分页查询
- 连接池：最大200连接，超时30秒
### 7.2 缓存策略
- **Redis缓存**：热点数据缓存，TTL设置
- **本地缓存**：Node.js内存缓存
- **CDN加速**：静态资源加速
### 7.3 异步处理
- 耗时操作异步化
- 消息队列削峰填谷
- 批量处理优化
## 8. 容灾备份方案
### 8.1 数据备份
- **每日全量备份**：mysqldump + binlog
- **实时增量备份**：MySQL主从复制
- **异地备份**：OSS冷备存储
### 8.2 故障恢复
- **数据库故障**：主从切换，30分钟恢复
- **服务故障**：健康检查，自动重启
- **网络故障**：多可用区部署
## 9. 扩展性设计
### 9.1 水平扩展
- 无状态服务，支持弹性伸缩
- 数据库分库分表方案
- 缓存集群扩展
### 9.2 功能扩展
- 插件化架构设计
- API版本管理
- 灰度发布机制

73
docs/详细设计.md Normal file
View File

@@ -0,0 +1,73 @@
# 爱鉴花项目详细设计文档
## 1. 系统架构
爱鉴花项目采用前后端分离的架构，包含以下主要组件：
1. 微信小程序 (uni-app) - 前端用户界面
2. Node.js后端服务 - 提供API接口
3. Vue3后台管理系统 - 管理界面
4. HTML5 Bootstrap官网 - 公司展示
5. 数据库 - 存储用户、商品、订单等数据
6. AI识别服务 - 植物识别
## 2. 模块设计
### 2.1 微信小程序 (uni-app)
- 首页：展示推荐内容和拍照入口
- 识别结果页：显示识别结果和植物信息
- 商城：展示花卉商品
- 配送：下单和配送信息
- 工具：园艺工具
- 个人中心：用户信息和订单管理
### 2.2 后端接口 (Node.js)
- 植物识别接口：接收图片，调用AI服务，返回识别结果
- 用户管理接口：注册、登录、用户信息管理
- 商品管理接口：商品增删改查
- 订单管理接口：订单创建、查询、状态更新
- 支付接口：处理支付请求
### 2.3 后台管理系统 (Vue3)
- 用户管理模块：查看和管理用户
- 商品管理模块：添加和管理商品
- 订单管理模块：查看和处理订单
- 数据统计模块：展示业务数据
### 2.4 官方网站 (HTML5 Bootstrap)
- 首页：公司介绍和产品展示
- 关于我们：公司信息
- 联系我们：联系方式
## 3. 数据流程
1. 用户在小程序拍照上传图片
2. 小程序调用后端植物识别接口
3. 后端服务调用AI识别服务
4. AI服务返回识别结果
5. 后端服务将结果返回给小程序
6. 用户查看识别结果及相关信息
7. 用户可在商城下单购买
8. 订单信息存储在数据库中
9. 后台管理系统可查看和处理订单
## 4. 数据库设计
### 4.1 核心数据表
- **用户表 (users)**: 用户ID、用户名、密码哈希、手机号、邮箱、头像、注册时间、最后登录时间、状态
- **商品表 (products)**: 商品ID、商品名称、分类ID、价格、库存、图片、描述、状态、创建时间
- **商品分类表 (categories)**: 分类ID、分类名称、父分类ID、排序、状态
- **订单表 (orders)**: 订单ID、用户ID、订单金额、支付状态、配送状态、收货地址、创建时间
- **订单商品表 (order_items)**: 订单项ID、订单ID、商品ID、数量、单价
- **识别记录表 (identifications)**: 记录ID、用户ID、图片URL、识别结果、置信度、识别时间
- **收货地址表 (addresses)**: 地址ID、用户ID、收货人、手机号、详细地址、是否默认
### 4.2 数据库技术选型
- **主数据库**: MySQL 8.0+，支持事务和复杂查询
- **缓存数据库**: Redis，用于会话管理、热点数据缓存
- **字符编码**: UTF8MB4，支持emoji表情
- **连接池**: 最大连接数20，最小连接数5，超时时间60秒
### 4.3 索引设计
- 用户表：手机号唯一索引、邮箱唯一索引
- 商品表：分类ID索引、状态索引
- 订单表：用户ID索引、创建时间索引
- 识别记录表：用户ID索引、识别时间索引

371
docs/部署指南.md Normal file
View File

@@ -0,0 +1,371 @@
# 爱鉴花小程序 - 部署操作指南
## 📋 概述
本文档提供「爱鉴花」小程序项目的完整部署指南，涵盖开发、测试、生产环境的部署流程和运维操作。
## 🚀 环境准备
### 1. 系统要求
- **操作系统**: Ubuntu 20.04+ / CentOS 7+
- **Node.js**: 16.0.0+
- **MySQL**: 8.0+
- **Redis**: 6.0+
- **Nginx**: 1.18+
### 2. 依赖安装
#### 后端依赖
```bash
cd backend
npm install
```
#### 前端依赖
```bash
cd mini_program
npm install
```
## 🔧 环境配置
### 1. 数据库配置
#### 创建配置文件
```bash
# 复制环境变量模板
cp backend/.env.example backend/.env.development
# 编辑配置文件
vim backend/.env.development
```
#### 环境变量配置示例
```env
# 应用配置
NODE_ENV=development
PORT=3000
APP_NAME=爱鉴花小程序后端
# 数据库配置（开发环境使用SQLite，生产环境使用MySQL）
DB_TYPE=sqlite # 开发环境使用sqlite，生产环境使用mysql
DB_HOST=192.168.0.240
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=aiot$Aiot123
DB_DATABASE=ajhdata
SQLITE_DB_PATH=./database.sqlite # SQLite数据库文件路径
# Redis配置
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=
# 腾讯云配置
TENCENT_CLOUD_SECRET_ID=your_secret_id
TENCENT_CLOUD_SECRET_KEY=your_secret_key
COS_BUCKET=your_bucket_name
COS_REGION=ap-beijing
# 微信小程序配置
WX_APPID=your_wechat_appid
WX_APPSECRET=your_wechat_appsecret
# JWT配置
JWT_SECRET=your_jwt_secret_key
JWT_EXPIRE=7d
```
### 2. 数据库初始化
```bash
# 验证数据库连接
cd backend
npm run db:check
# 完整数据库初始化
npm run db:init
```
**注意**: 数据库初始化脚本已移动到 `/scripts/backend/` 目录，执行时会自动调用正确路径。
## 🏗️ 构建部署
### 1. 后端服务部署
#### 开发环境启动
```bash
cd backend
npm run dev
```
#### 生产环境构建
```bash
# 安装生产依赖
npm install --production
# 启动生产服务
npm start
```
#### PM2进程管理
```bash
# 安装PM2
npm install -g pm2
# 启动服务
pm2 start app.js --name aijianhua-backend
# 查看服务状态
pm2 status
# 设置开机自启
pm2 startup
pm2 save
```
### 2. 前端小程序部署
#### 开发环境
```bash
cd mini_program
npm run dev:mp-weixin
```
#### 生产构建
```bash
npm run build:mp-weixin
```
#### 微信开发者工具
1. 打开微信开发者工具
2. 导入项目目录 `mini_program`
3. 配置AppID和项目设置
4. 点击"上传"发布体验版
### 3. Nginx配置
#### 创建Nginx配置文件
```nginx
server {
listen 80;
server_name api.aijianhua.com;
# API反向代理
location /api/ {
proxy_pass http://localhost:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
# 静态资源服务
location /static/ {
alias /path/to/static/files/;
expires 30d;
}
# 健康检查
location /health {
access_log off;
return 200 "healthy\n";
}
}
```
#### 启用配置
```bash
# 检查配置语法
nginx -t
# 重新加载配置
nginx -s reload
```
## 📊 监控运维
### 1. 日志管理
#### 查看应用日志
```bash
# PM2日志
pm2 logs aijianhua-backend
# Nginx访问日志
tail -f /var/log/nginx/access.log
# Nginx错误日志
tail -f /var/log/nginx/error.log
```
#### 日志轮转配置
```bash
# 安装logrotate
sudo apt-get install logrotate
# 创建日志轮转配置
sudo vim /etc/logrotate.d/aijianhua
```
### 2. 性能监控
#### 系统监控
```bash
# 查看系统负载
top
htop
# 查看磁盘使用
df -h
# 查看内存使用
free -h
```
#### 应用监控
```bash
# 查看Node.js进程
pm2 monit
# 查看数据库连接
mysql -u root -p -e "SHOW PROCESSLIST;"
```
### 3. 备份恢复
#### 数据库备份
```bash
# 全量备份
mysqldump -u root -p ajhdata > backup_$(date +%Y%m%d).sql
# 压缩备份
gzip backup_$(date +%Y%m%d).sql
```
#### 文件备份
```bash
# 备份重要文件
tar -czf backup_$(date +%Y%m%d).tar.gz /path/to/important/files
```
## 🔒 安全配置
### 1. 防火墙配置
```bash
# 启用防火墙
sudo ufw enable
# 开放必要端口
sudo ufw allow 22 # SSH
sudo ufw allow 80 # HTTP
sudo ufw allow 443 # HTTPS
sudo ufw allow 3000 # Node.js
# 查看防火墙状态
sudo ufw status
```
### 2. SSL证书配置
#### 申请证书
```bash
# 使用Certbot申请SSL证书
sudo apt-get install certbot python3-certbot-nginx
sudo certbot --nginx -d api.aijianhua.com
```
#### 自动续期
```bash
# 测试续期
sudo certbot renew --dry-run
# 设置定时任务
sudo crontab -e
# 添加：0 12 * * * /usr/bin/certbot renew --quiet
```
### 3. 安全加固
#### 数据库安全
```sql
-- 创建专用用户
CREATE USER 'aijianhua'@'localhost' IDENTIFIED BY 'strong_password';
GRANT SELECT, INSERT, UPDATE, DELETE ON ajhdata.* TO 'aijianhua'@'localhost';
FLUSH PRIVILEGES;
```
#### 文件权限
```bash
# 设置正确的文件权限
chmod 600 /path/to/config/file
chmod 700 /path/to/executable
```
## 🚨 故障处理
### 1. 常见问题
#### 端口冲突
```bash
# 查看端口占用
netstat -tlnp | grep :3000
lsof -i :3000
# 杀死进程
kill -9 <PID>
```
#### 服务无法启动
```bash
# 查看错误详情
npm start 2>&1 | tee error.log
# 检查依赖
npm ls --depth=0
```
#### 数据库连接失败
```bash
# 测试数据库连接
mysql -h 192.168.0.240 -P 3306 -u root -p
# 检查MySQL服务状态
sudo systemctl status mysql
```
### 2. 应急响应
#### 服务重启
```bash
# 重启Node.js服务
pm2 restart aijianhua-backend
# 重启Nginx
sudo systemctl restart nginx
# 重启MySQL
sudo systemctl restart mysql
```
#### 回滚部署
```bash
# 回滚到上一个版本
pm2 restart aijianhua-backend --update-env
```
## 📞 支持联系
### 运维团队
- **值班电话**: 138-0013-8000
- **技术支持**: tech@aijianhua.com
- **紧急响应**: emergency@aijianhua.com
### 监控平台
- **应用性能**: NewRelic / Datadog
- **错误监控**: Sentry
- **日志分析**: ELK Stack
- **业务监控**: Grafana
---
*最后更新: 2024-03-15*
*文档版本: v1.0*

127
docs/需求文档.md Normal file
View File

@@ -0,0 +1,127 @@
# 爱鉴花项目需求文档
## 版本历史
| 版本号 | 修订日期 | 修订人 | 修订说明 |
|--------|----------|--------|----------|
| v1.0.0 | 2024-01-20 | 系统 | 初始版本创建 |
| v1.1.0 | 2024-03-15 | 产品经理 | 完善官网功能需求细节 |
| v1.1.1 | 2024-03-15 | 产品经理 | 补充非功能需求技术要求 |
| v1.1.2 | 2024-03-15 | 开发工程师 | 修复数据库设计问题，更新文档一致性 |
## 1. 项目概述
爱鉴花是一款通过AI图片识别植物类型的微信小程序应用，为用户提供花卉相关信息、购买、配送等服务。
## 2. 产品定位
爱鉴花旨在为花卉爱好者提供一个集植物识别、花卉信息查询、购买、配送于一体的综合服务平台。
## 3. 用户群体
- 花卉爱好者
- 园艺爱好者
- 对植物感兴趣的一般用户
## 4. 功能需求
### 4.1 微信小程序 (uni-app)
- **拍照识别植物**: 支持拍照或相册选择图片，AI识别植物种类
- **植物信息展示**: 展示识别结果，包括植物名称、科属、习性、养护方法等
- **花卉商城**: 商品分类浏览、搜索、详情查看、加入购物车
- **花卉配送**: 在线下单、配送地址管理、配送时间选择、订单跟踪
- **园艺工具**: 园艺知识文章、植物养护指南、工具推荐
- **用户个人中心**: 用户信息管理、订单历史、收藏夹、收货地址管理
### 4.2 后端接口 (Node.js)
- **植物识别API**: 接收图片文件，调用AI服务，返回识别结果
- **用户管理API**: 用户注册、登录、信息修改、密码重置
- **商品管理API**: 商品CRUD操作、分类管理、库存管理
- **订单管理API**: 订单创建、状态更新、查询、取消
- **支付接口**: 微信支付集成、支付状态回调处理
- **数据统计API**: 用户行为统计、销售数据统计、识别数据统计
### 4.3 后台管理系统 (Vue3)
- **用户管理**: 用户列表查看、信息编辑、权限管理、封禁操作
- **商品管理**: 商品添加/编辑/删除、分类管理、库存调整、上下架
- **订单管理**: 订单列表查看、状态更新、详情查看、导出功能
- **数据统计**: 用户增长统计、销售报表、识别数据统计、图表展示
- **系统设置**: 系统参数配置、权限角色管理、操作日志查看
### 4.4 官方网站 (HTML5 Bootstrap)
- **首页模块**
- 公司简介展示（品牌标语、核心价值主张）
- 核心功能展示（智能识别、知识库、社区交流三大功能卡片）
- 产品展示区（微信小程序、API服务、企业版三款产品）
- 最新动态展示（最新3条新闻摘要）
- 联系入口（快速联系按钮）
- **关于我们模块**
- 公司详细介绍（成立时间、使命愿景、发展规模）
- 企业文化展示（价值观、企业精神）
- 发展历程时间线（关键里程碑事件）
- 团队介绍（核心团队成员信息、照片、职位）
- **产品介绍模块**
- 产品功能详细说明（各产品功能特点、优势）
- 功能对比表格（三款产品功能差异对比）
- 使用案例展示（真实用户使用场景和效果）
- 客户评价系统（用户评价卡片、星级评分）
- 价格方案展示（各产品定价和套餐）
- **新闻中心模块**
- 公司动态（产品发布、版本更新、活动通知）
- 行业资讯（花卉行业最新趋势和技术）
- 媒体报道（媒体采访、报道文章）
- 分类筛选（按类别查看新闻）
- 搜索功能（关键词搜索新闻内容）
- **联系我们模块**
- 联系表单（姓名、邮箱、电话、消息内容）
- 实时表单验证（前端验证、错误提示）
- 表单提交反馈（成功/失败提示信息）
- 联系信息展示（地址、电话、邮箱、工作时间）
- 在线地图集成（公司位置地图展示）
- 社交媒体链接（微信、微博、GitHub）
- **通用功能**
- 响应式设计（桌面端、平板、手机适配）
- 导航系统（主导航菜单、面包屑导航）
- 页脚信息（版权声明、备案信息、政策链接、友情链接）
- SEO优化（meta标签、结构化数据）
- 性能优化（图片懒加载、资源压缩）
## 5. 非功能需求
### 5.1 性能要求
- **页面加载速度**: 首屏加载时间 ≤ 3秒，完整页面加载时间 ≤ 5秒
- **资源优化**: 图片压缩（WebP格式支持），CSS/JS文件合并压缩
- **缓存策略**: 浏览器缓存优化，CDN加速部署
- **响应时间**: 用户操作响应时间 ≤ 100ms
- **技术栈版本**: Node.js 16.0.0+, MySQL 8.0+, Redis 6.0+, Vue.js 3.0+
### 5.2 可用性要求
- **浏览器兼容性**: 支持 Chrome、Firefox、Safari、Edge 等主流浏览器
- **设备兼容性**: 完美支持桌面端、平板、手机等不同设备尺寸
- **可访问性**: 符合WCAG 2.1 AA标准，支持屏幕阅读器
- **错误处理**: 友好的错误提示和恢复机制
### 5.3 安全性要求
- **表单安全**: 防止XSS攻击，输入内容过滤和转义
- **HTTPS强制**: 全站HTTPS加密传输
- **数据验证**: 前后端双重数据验证机制
- **隐私保护**: 用户数据加密存储，符合GDPR要求
### 5.4 可维护性要求
- **代码规范**: 遵循HTML5、CSS3、ES6+编码规范
- **文档完整**: 完整的代码注释和技术文档
- **模块化设计**: 组件化开发，便于维护和扩展
- **版本控制**: Git版本管理，清晰的commit记录
### 5.5 SEO要求
- **搜索引擎友好**: 合理的URL结构，语义化HTML标签
- **结构化数据**: Schema.org标记，丰富搜索结果展示
- **元数据优化**: 每个页面独立的title、description、keywords
- **站点地图**: XML sitemap自动生成和提交
### 5.6 监控和分析
- **性能监控**: Google Analytics集成，性能指标监控
- **错误监控**: 前端错误日志收集和分析
- **用户行为分析**: 热点图、转化漏斗分析
- **安全监控**: 安全漏洞扫描和预警

60
docs/项目总览.md Normal file
View File

@@ -0,0 +1,60 @@
# 爱鉴花项目总览
## 项目概述
爱鉴花是一款通过AI图片识别植物类型的微信小程序应用，为用户提供花卉相关信息、购买、配送等服务。
## 项目组成
1. **微信小程序 (uni-app)** - 用户端应用，提供植物识别、商城购物、配送服务等功能
2. **后端接口 (Node.js)** - 提供RESTful API服务，包括植物识别、用户管理、商品管理、订单管理等
3. **后台管理系统 (Vue3)** - 管理后台，用于用户管理、商品管理、订单管理、数据统计等
4. **官方网站 (HTML5 Bootstrap)** - 公司展示网站，提供产品介绍、公司信息、联系方式等
5. **项目文档 (docs)** - 包含需求文档、设计文档、API文档、部署指南等
6. **测试目录 (test)** - 包含单元测试、集成测试、端到端测试等测试文件
## 技术架构
- **前端技术栈**: uni-app、Vue3、Element Plus、Bootstrap
- **后端技术栈**: Node.js、Express.js、MySQL（生产环境）、SQLite（开发环境）、Redis
- **开发工具**: HBuilderX、VSCode、Git
- **部署环境**: Nginx、Docker、云服务器
## 项目文档
### 需求文档
- [需求文档](./需求文档.md)
### 详细设计
- [详细设计](./详细设计.md)
### 开发规范
- [贡献指南](./CONTRIBUTING.md)
- [变更日志](./CHANGELOG.md)
### 微信小程序
- [README](./mini_program/README.md)
- [功能模块](./mini_program/功能模块.md)
- [开发计划](./mini_program/开发计划.md)
### 后端接口
- [README](./backend/README.md)
- [功能模块](./backend/功能模块.md)
- [开发计划](./backend/开发计划.md)
### 后台管理系统
- [README](./admin-system/README.md)
- [功能模块](./admin-system/功能模块.md)
- [开发计划](./admin-system/开发计划.md)
### 官方网站
- [README](./website/README.md)
- [功能模块](./website/功能模块.md)
- [开发计划](./website/开发计划.md)
## 开发时间安排
整个项目预计需要16周完成，分为以下阶段：
1. 第一阶段（1-2周）：各项目基础框架搭建
2. 第二阶段（3-6周）：核心功能开发
3. 第三阶段（7-10周）：扩展功能开发
4. 第四阶段（11-12周）：系统集成
5. 第五阶段（13-14周）：测试和优化
6. 第六阶段（15-16周）：部署上线和维护

64
docs/项目说明.md Normal file
View File

@@ -0,0 +1,64 @@
# 爱鉴花项目说明
## 项目结构
```
爱鉴花项目
├── mini_program (微信小程序矩阵目录)
├── backend (后端服务目录)
├── admin-system (管理后台目录)
├── website (官网目录)
├── docs (文档目录)
├── test (测试文件目录)
├── scripts (执行脚本目录)
├── 需求文档.md
├── 详细设计.md
├── 项目总览.md
├── start_project.bat (项目启动脚本)
└── 项目说明.md (本文档)
```
## 启动项目
双击运行 `start_project.bat` 脚本，将会打开所有子项目的文件夹，方便在编辑器中打开。
## 各项目开发环境配置
### 微信小程序 (uni-app)
1. **开发工具**: 安装 HBuilderX (推荐) 或 VSCode + uni-app 插件
2. **环境要求**: Node.js 16+，npm 或 yarn 包管理器
3. **开发步骤**:
- 导入 mini_program 文件夹到开发工具
- 运行 `npm install` 安装依赖
- 配置小程序AppID（需要微信开发者账号）
- 运行开发服务器进行调试
### 后端服务 (Node.js)
1. **环境要求**: Node.js 16+，MySQL 8.0+（生产环境），SQLite（开发环境），Redis
2. **开发步骤**:
- 导入 backend 文件夹
- 运行 `npm install` 安装依赖
- 复制 `.env.example` 为 `.env` 并配置数据库连接
- 运行 `npm run db:init` 初始化数据库（默认使用SQLite，脚本位于 `/scripts/backend/` 目录）
- 运行 `npm start` 启动服务（开发环境使用 `npm run dev`）
### 后台管理系统 (Vue3)
1. **环境要求**: Node.js 16+，npm 或 yarn
2. **开发步骤**:
- 导入 admin-system 文件夹
- 运行 `npm install` 安装依赖
- 配置后端API地址（环境变量或配置文件）
- 运行 `npm run serve` 启动开发服务器
### 官方网站 (HTML5 Bootstrap)
1. **环境要求**: 任意现代浏览器
2. **开发步骤**:
- 可直接在浏览器中打开 index.html 查看效果
- 可使用 Live Server 等工具进行本地开发
- 部署到 Nginx、Apache 或任何静态文件服务器
## 文档说明
- 需求文档：描述项目需求和功能
- 详细设计：描述系统架构和设计
- 项目总览：汇总所有项目信息
- 各子项目中的 README.md：子项目介绍
- 各子项目中的 功能模块.md：子项目功能说明
- 各子项目中的 开发计划.md：子项目开发计划