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

2025-09-11 09:23:12 +08:00
parent 7d3e5bde1e
commit 28c7b17767
4 changed files with 464 additions and 6 deletions
--- a/docs/Java后端API接口文档.md
+++ b/docs/Java后端API接口文档.md
@@ -0,0 +1,380 @@
+# 爱鉴花Java后端API接口文档
+
+## 1. 概述
+本文档定义了爱鉴花项目Java后端的所有API接口规范，包括请求方式、参数、响应格式和错误处理等。
+
+## 2. 基础信息
+
+- **Base URL**: `http://localhost:3200`
+- **认证方式**: Bearer Token (JWT)
+- **响应格式**: JSON
+- **字符编码**: UTF-8
+
+## 3. 公共请求头
+
+| 头部名称 | 是否必须 | 说明 |
+|---------|---------|------|
+| Authorization | 是 | Bearer Token，格式为 `Bearer <token>` |
+| Content-Type | 否 | 请求体类型，上传文件时为 `multipart/form-data` |
+
+## 4. 公共响应格式
+
+## 3. 公共响应格式
+
+### 成功响应
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {}
+}
+```
+
+### 分页响应
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "list": [],
+    "pagination": {
+      "page": 1,
+      "limit": 10,
+      "total": 0,
+      "pages": 0
+    }
+  }
+}
+```
+
+### 错误响应
+```json
+{
+  "code": 400,
+  "message": "参数错误",
+  "data": null
+}
+```
+
+## 4. 认证接口
+
+### 用户登录
+**POST** `/api/v1/auth/login`
+
+**请求参数**:
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| username | string | 是 | 用户名 |
+| password | string | 是 | 密码 |
+
+**请求示例**:
+```json
+{
+  "username": "admin",
+  "password": "admin123"
+}
+```
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "登录成功",
+  "data": {
+    "user_id": 1,
+    "username": "admin",
+    "phone": "13800138000",
+    "email": "admin@example.com",
+    "user_type": "admin",
+    "avatar_url": "/uploads/avatar.jpg",
+    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+  }
+}
+```
+
+### 用户注册
+**POST** `/api/v1/auth/register`
+
+**请求参数**:
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| username | string | 是 | 用户名 |
+| password | string | 是 | 密码 |
+| phone | string | 是 | 手机号 |
+| email | string | 否 | 邮箱 |
+| user_type | string | 否 | 用户类型，默认为"user" |
+
+**请求示例**:
+```json
+{
+  "username": "newuser",
+  "password": "password123",
+  "phone": "13800138001",
+  "email": "newuser@example.com"
+}
+```
+
+**响应示例**:
+```json
+{
+  "code": 201,
+  "message": "注册成功",
+  "data": {
+    "user_id": 2,
+    "username": "newuser",
+    "phone": "13800138001",
+    "email": "newuser@example.com",
+    "user_type": "user",
+    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+  }
+}
+```
+
+### 获取当前用户信息
+**GET** `/api/v1/auth/me`
+
+**请求头**:
+```
+Authorization: Bearer <token>
+```
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "user_id": 1,
+    "username": "admin",
+    "phone": "13800138000",
+    "email": "admin@example.com",
+    "user_type": "admin",
+    "avatar_url": "/uploads/avatar.jpg",
+    "created_at": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+## 5. 用户接口
+
+### 获取当前用户信息
+**GET** `/users/me`
+
+**请求头**:
+```
+Authorization: Bearer <token>
+```
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "id": 1,
+    "username": "admin",
+    "email": "admin@example.com",
+    "createdAt": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+### 更新用户信息
+**PUT** `/users/me`
+
+**请求头**:
+```
+Authorization: Bearer <token>
+```
+
+**请求参数**:
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| email | string | 否 | 邮箱 |
+| nickname | string | 否 | 昵称 |
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "更新成功",
+  "data": {
+    "id": 1,
+    "username": "admin",
+    "email": "newemail@example.com",
+    "nickname": "管理员"
+  }
+}
+```
+
+## 6. 文件上传接口
+
+### 上传文件
+**POST** `/api/v1/upload`
+
+**请求头**:
+```
+Authorization: Bearer <token>
+Content-Type: multipart/form-data
+```
+
+**请求参数**:
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| file | file | 是 | 文件 |
+| type | string | 是 | 文件类型(image, document等) |
+
+**请求示例**:
+```bash
+curl -X POST "http://localhost:3200/api/v1/upload" \
+  -H "Authorization: Bearer <token>" \
+  -F "file=@/path/to/image.jpg" \
+  -F "type=image"
+```
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "上传成功",
+  "data": {
+    "id": 1,
+    "url": "/uploads/2024/01/15/abc123.jpg",
+    "filename": "abc123.jpg",
+    "original_name": "image.jpg",
+    "type": "image",
+    "size": 102400,
+    "created_at": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+### 获取上传文件列表
+**GET** `/api/v1/upload`
+
+**请求头**:
+```
+Authorization: Bearer <token>
+```
+
+**查询参数**:
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| page | int | 否 | 页码，默认1 |
+| size | int | 否 | 每页数量，默认10 |
+| type | string | 否 | 文件类型筛选 |
+
+**请求示例**:
+```bash
+curl -X GET "http://localhost:3200/api/v1/upload?page=1&size=10&type=image" \
+  -H "Authorization: Bearer <token>"
+```
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "list": [
+      {
+        "id": 1,
+        "url": "/uploads/2024/01/15/abc123.jpg",
+        "filename": "abc123.jpg",
+        "original_name": "image.jpg",
+        "type": "image",
+        "size": 102400,
+        "created_at": "2024-01-15T10:30:00Z"
+      }
+    ],
+    "pagination": {
+      "page": 1,
+      "size": 10,
+      "total": 1
+    }
+  }
+}
+```
+
+### 删除上传文件
+**DELETE** `/api/v1/upload/{id}`
+
+**请求头**:
+```
+Authorization: Bearer <token>
+```
+
+**路径参数**:
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| id | int | 是 | 文件ID |
+
+**请求示例**:
+```bash
+curl -X DELETE "http://localhost:3200/api/v1/upload/1" \
+  -H "Authorization: Bearer <token>"
+```
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "删除成功"
+}
+```
+
+## 7. 健康检查接口
+
+### 服务健康检查
+**GET** `/health`
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "status": "UP",
+    "timestamp": "2024-01-15T10:30:00Z",
+    "service": "aijianhua-backend"
+  }
+}
+```
+
+## 8. 错误码规范
+
+| 错误码 | 错误信息 | 说明 |
+|--------|----------|------|
+| 200 | 成功 | 请求成功 |
+| 201 | 创建成功 | 资源创建成功 |
+| 400 | 参数错误 | 请求参数验证失败 |
+| 401 | 未授权 | 需要登录认证 |
+| 403 | 禁止访问 | 权限不足 |
+| 404 | 资源不存在 | 请求的资源不存在 |
+| 409 | 资源冲突 | 资源已存在或状态冲突 |
+| 422 | 数据验证失败 | 请求数据格式正确但业务验证失败 |
+| 500 | 服务器内部错误 | 服务器内部处理错误 |
+| 503 | 服务不可用 | 服务暂时不可用 |
+
+## 9. 安全要求
+
+1. 所有敏感接口必须使用HTTPS
+2. JWT token有效期7天
+3. 密码使用bcrypt加密存储
+4. 文件上传限制10MB
+5. 支持CORS跨域访问
+6. 请求频率限制（每分钟最多100次）
+7. 敏感操作需要二次验证
+
+## 10. 版本历史
+
+- v1.0.0 (2024-03-15): 初始版本发布
+- v1.1.0 (2024-03-16): 
+  - 完善认证接口文档
+  - 完善文件上传接口文档
+  - 添加健康检查接口文档
+  - 补充错误码规范
+  - 增强安全要求说明
+
+---
+*本文档最后更新: 2024-03-15*
--- a/docs/数据库设计文档.md
+++ b/docs/数据库设计文档.md
@@ -226,6 +226,12 @@
 - 用户名: root
 - 密码: aiotAiot123!

+**Java后端开发环境**:
+- 主机: 129.211.213.226:9527
+- 数据库: xlxumudata
+- 用户名: root
+- 密码: aiotAiot123!
+
 **连接池配置**:
 - 最大连接数: 200
 - 最小连接数: 20
--- a/docs/部署指南.md
+++ b/docs/部署指南.md
@@ -6,21 +6,33 @@

 ## 🚀 环境准备

-### 1. 系统要求
+### 1. 环境准备
+
+#### 系统要求
 - **操作系统**: Ubuntu 20.04+ / CentOS 7+
 - **Node.js**: 16.0.0+
+- **Java**: 8+
 - **MySQL**: 8.0+
 - **Redis**: 6.0+
 - **Nginx**: 1.18+

 ### 2. 依赖安装

-#### 后端依赖
+#### Node.js后端依赖
 ```bash
 cd backend
 npm install
 ```

+#### Java后端依赖
+```bash
+# 进入Java后端目录
+cd java_backend
+
+# 安装Maven依赖
+mvn clean install
+```
+
 #### 前端依赖
 ```bash
 cd mini_program
@@ -182,6 +194,64 @@ nginx -t
 nginx -s reload
 ```

+### 4. 服务管理
+
+#### PM2管理Node.js服务
+```bash
+# 安装PM2
+npm install -g pm2
+
+# 启动服务
+pm2 start app.js --name aijianhua-backend
+
+# 查看服务状态
+pm2 status
+
+# 重启服务
+pm2 restart aijianhua-backend
+
+# 停止服务
+pm2 stop aijianhua-backend
+
+# 设置开机自启
+pm2 startup
+pm2 save
+```
+
+#### Systemd管理Java服务
+```bash
+# 创建服务文件
+sudo nano /etc/systemd/system/aijianhua-java.service
+
+# 添加以下内容
+[Unit]
+Description=爱鉴花Java后端服务
+After=network.target
+
+[Service]
+Type=simple
+User=www-data
+WorkingDirectory=/path/to/aijianhua-java-backend
+ExecStart=/usr/bin/java -jar target/backend-1.0.0.jar
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+
+# 重新加载systemd
+sudo systemctl daemon-reload
+
+# 启动服务
+sudo systemctl start aijianhua-java
+
+# 设置开机自启
+sudo systemctl enable aijianhua-java
+
+# 查看服务状态
+sudo systemctl status aijianhua-java
+```
+
 ## 📊 监控运维

 ### 1. 日志管理
@@ -260,6 +330,7 @@ sudo ufw allow 22    # SSH
 sudo ufw allow 80    # HTTP
 sudo ufw allow 443   # HTTPS
 sudo ufw allow 3000  # Node.js
+sudo ufw allow 3200  # Java后端

 # 查看防火墙状态
 sudo ufw status
--- a/docs/项目总览.md
+++ b/docs/项目总览.md
@@ -6,10 +6,11 @@
 ## 项目组成
 1. **微信小程序 (uni-app)** - 前端用户界面，提供植物识别、植物知识、商城购物、配送服务等功能
 2. **后端接口 (Node.js)** - 提供RESTful API服务，包括植物识别、用户管理、商品管理、订单管理等
-3. **后台管理系统 (Vue3)** - 管理后台，用于用户管理、商品管理、订单管理、数据统计等
-4. **官方网站 (HTML5 Bootstrap)** - 公司展示网站，提供产品介绍、公司信息、联系方式等
-5. **项目文档 (docs)** - 包含需求文档、设计文档、API文档、部署指南等
-6. **测试目录 (test)** - 包含单元测试、集成测试、端到端测试等测试文件
+3. **后端接口 (Java Spring Boot)** - 新增Java后端，提供文件上传等API服务
+4. **后台管理系统 (Vue3)** - 管理后台，用于用户管理、商品管理、订单管理、数据统计等
+5. **官方网站 (HTML5 Bootstrap)** - 公司展示网站，提供产品介绍、公司信息、联系方式等
+6. **项目文档 (docs)** - 包含需求文档、设计文档、API文档、部署指南等
+7. **测试目录 (test)** - 包含单元测试、集成测试、端到端测试等测试文件

 ## 技术架构
 - **前端技术栈**: uni-app、Vue3、Element Plus、Bootstrap