# 乡村农产品销售系统

**Repository Path**: dm_team/Rural-Agricultural-Products-Sales-System

## Basic Information

- **Project Name**: 乡村农产品销售系统
- **Description**: 乡村农产品销售系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-09
- **Last Updated**: 2026-08-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 乡村农产品销售系统

本项目是一个可运行的助农销售演示系统，覆盖农户协同、商品上架、订单履约、发运签收、农户结算、售后服务、用户管理和业务类别管理。系统已经把原来写死在代码里的少量类别扩展为数据库维护的类别字典，目前内置 **21 个类别分组、190 个类别项**，管理员可以在页面上继续新增、编辑、停用或删除类别。

## 一、技术栈和环境要求

| 项目 | 说明 |
| --- | --- |
| 前端 | React 18.3.1、Vite 6.2.0、Ant Design 5.24.8、Recharts 2.15.1 |
| 后端 | Node.js、Express 4.21.2、better-sqlite3 11.8.1 |
| 数据库 | SQLite，本项目不需要安装 MySQL、SQL Server 或 Redis |
| 推荐 Node.js | Node.js 18.20 及以上，推荐 Node.js 20 LTS；本机验证使用 Node.js 22.12.0 |
| 前端端口 | `5180` |
| 后端端口 | `9018` |
| 数据库文件 | `backend\data\rural-agricultural-product-sales-system.db` |

## 二、目录结构

```text
08-rural-agricultural-product-sales-system
├─ backend                  后端接口服务
│  ├─ src
│  │  ├─ server.js          Express 主服务
│  │  ├─ categorySeed.js    21 个类别分组、190 个默认类别项
│  │  └─ categoryService.js 类别字典服务
│  ├─ test                  后端测试
│  └─ data                  SQLite 数据库运行目录，已在 .gitignore 中排除
├─ frontend                 React 前端
│  └─ src
│     ├─ App.jsx            页面入口和菜单
│     └─ views              各业务页面
├─ database
│  ├─ init.sql              建表脚本
│  └─ sample_data.sql       演示数据脚本
├─ docs                     项目说明文档
└─ start-project.bat        Windows 快速启动脚本
```

## 三、首次运行步骤（Windows 新手版）

1. 安装 Node.js  
   到 [Node.js 官网](https://nodejs.org/) 下载并安装 Node.js 20 LTS。安装完成后重新打开命令提示符，执行：

   ```bat
   node -v
   npm -v
   ```

   如果能看到版本号，说明安装成功。

2. 进入项目目录  

   ```bat
   cd /d D:\Ten-Projects\08-rural-agricultural-product-sales-system
   ```

3. 安装后端依赖  

   ```bat
   cd backend
   npm install
   ```

4. 启动后端服务  

   ```bat
   npm run start
   ```

   看到类似下面内容表示后端启动成功：

   ```text
   乡村农产品销售系统 backend is running on http://127.0.0.1:9018
   ```

5. 新开一个命令提示符窗口，安装并启动前端  

   ```bat
   cd /d D:\Ten-Projects\08-rural-agricultural-product-sales-system\frontend
   npm install
   npm run dev
   ```

6. 打开浏览器访问：

   ```text
   http://127.0.0.1:5180
   ```

运行到这里后，浏览器会打开登录页。可直接使用下面账号登录：

- 管理员: `agri_admin` / `Pass@123`
- 运营人员: `agri_user` / `Pass@123`

建议第一次演示或检查时先使用管理员账号，因为管理员可以看到类别管理、用户管理和完整业务功能。
## 四、登录账号

| 角色 | 账号 | 密码 | 说明 |
| --- | --- | --- | --- |
| 管理员 | `agri_admin` | `Pass@123` | 可维护类别、用户和全部业务数据 |
| 运营人员 | `agri_user` | `Pass@123` | 可使用商品、农户、订单、发运、结算、售后等业务功能 |

## 五、类别管理说明

老师所说的“类太少”，在这套系统里可以理解为业务分类、状态、类型、渠道、单位等可扩展字典。系统现在新增了“类别管理”页面，管理员登录后可以维护以下类别：

- 商品品类、计量单位、商品状态、商品品级
- 供货能力、农户状态、冷链等级
- 订单渠道、配送方式、支付状态、订单状态、发运状态
- 结算状态、售后状态、售后问题类型
- 线路类型、包装类型、认证类型、促销类型
- 用户状态、操作类型

当前默认类别数量为 **190 项**。新增或停用类别后，相关页面的下拉框会读取最新数据，例如商品中心的“商品品类”、订单页面的“销售渠道”、售后页面的“问题类型”。

注意：订单流转里的核心状态，例如“待付款、待分拣、待发运、运输中、已完成、待装车、待打款”等，会被代码流程使用。可以新增展示用状态，但不要随意删除这些默认核心状态，否则会影响演示流程。

## 六、数据库说明

本项目使用 SQLite，第一次启动后端时会自动创建数据库文件：

```text
D:\Ten-Projects\08-rural-agricultural-product-sales-system\backend\data\rural-agricultural-product-sales-system.db
```

如果想恢复到初始演示数据，可以先关闭后端服务，然后删除上面的 `.db` 文件，再重新运行：

```bat
cd /d D:\Ten-Projects\08-rural-agricultural-product-sales-system\backend
npm run start
```

系统会重新执行 `database\init.sql` 和 `database\sample_data.sql`，并自动写入 21 个类别分组和 190 个类别项。

## 七、常用命令

后端：

```bat
cd /d D:\Ten-Projects\08-rural-agricultural-product-sales-system\backend
npm install
npm run start
node --test test/categoryService.test.js
```

前端：

```bat
cd /d D:\Ten-Projects\08-rural-agricultural-product-sales-system\frontend
npm install
npm run dev
npm run build
```

## 八、上传到 Gitee 的注意事项

本项目已经通过 `.gitignore` 排除了以下运行产物：

- `backend/node_modules`
- `frontend/node_modules`
- `frontend/dist`
- `backend/data`
- `*.db`

上传到 Gitee 时提交源代码、`database`、`docs`、`README.md` 即可，不要提交 `node_modules` 和本机数据库文件。别人下载项目后，按本文“三、首次运行步骤”重新执行 `npm install` 和启动命令即可生成自己的数据库。

## 九、常见问题

1. 前端页面打不开  
   先确认前端命令窗口里 `npm run dev` 没有报错，并访问 `http://127.0.0.1:5180`。

2. 页面提示接口连接失败  
   说明后端没有启动，进入 `backend` 目录运行 `npm run start`。

3. 端口被占用  
   后端默认用 `9018`，前端默认用 `5180`。如果提示端口占用，先关闭旧的命令行窗口或在任务管理器结束对应 Node.js 进程。

4. 类别下拉框没有新增项  
   新增类别后要保持“是否启用”为启用状态；如果页面已经打开，刷新页面或重新登录即可读取最新类别。

5. better-sqlite3 安装失败  
   优先使用 Node.js 20 LTS 重新安装依赖。如果之前安装过失败依赖，可以删除 `backend\node_modules` 后再次执行 `npm install`。