# 蔬菜查询系统 **Repository Path**: hhfdj/vegetable-query-system ## Basic Information - **Project Name**: 蔬菜查询系统 - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-05-05 - **Last Updated**: 2025-05-05 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README 有机蔬菜溯源信息查询系统 - 项目说明文档 (v1.2) --- ## 1. 项目目标 本项目旨在开发一个 **简化版** 的有机蔬菜溯源信息查询系统。目标是让最终用户(消费者)能够通过手机App(的接口)查询到特定批次蔬菜的关键溯源信息,并能就相关问题进行AI咨询。同时,系统提供一个后台管理界面,方便 **农户**(管理员)录入和管理自己农场的蔬菜批次信息。 这个项目是作为 "项目训练" 课程的大作业而开发的。 --- ## 2. 项目核心组成 本项目主要由以下几个部分组成: 1. **核心溯源系统 (Go 单体应用)**: * 包含 **后台管理系统** (Web界面,供农户使用) 和 **手机App接口** (API)。 * 负责蔬菜批次信息的管理、用户认证、以及核心的溯源信息查询。 * 采用 **Go** 语言开发。 2. **AI问答服务 (Python 独立服务)**: * 提供一个独立的 **API 接口**。 * 接收来自 App 的关于蔬菜或农业相关的问题。 * 调用外部的生成式 AI 模型接口获取答案,并返回给 App。 * 采用 **Python** 语言开发。 --- ## 3. 技术选型 - **核心溯源系统 (Go)**: * 后端语言: **Go** * Web框架: **Gin** (`github.com/gin-gonic/gin`) * 数据库: **MySQL** * 数据库 ORM (建议): **GORM** (`gorm.io/gorm`) - **AI问答服务 (Python)**: * 语言: **Python** * Web框架: **Flask** 或 **FastAPI** (lx同学可以根据熟悉程度选择) - **代码管理**: **Git** - **代码托管**: **GitHub / Gitee** --- ## 4. 功能详述 ### 4.1 后台管理系统 (Go应用的一部分 - 供农户使用) - **管理员(农户)登录**: * 路径: `/admin/login` * 提供一个简单的登录页面。 * 验证用户名和密码,并检查账号 **status** 是否为 'Active'。 * 成功后,记录用户身份及其管理的 `farm_name`,才能访问后续管理功能。 - **蔬菜批次管理**: * 路径: `/admin/batches` * **重要**: 所有操作(增删改查)都必须基于当前登录农户的 `farm_name` 进行过滤,确保农户只能管理自己农场的数据。 * 功能: * **添加 (Create)**: 录入新的蔬菜批次信息。系统自动关联当前农户的 `farm_name`。需要包含以下字段: * 蔬菜名称 (例如:有机生菜) * 种子信息 (文本描述) * 种植日期 (例如:2024-05-01) * 采摘日期 (可选, 可后续补充) * 质检报告信息 (文本描述或链接) * 备注 (可选) * **查看 (Read)**: 以列表形式展示 **当前农场** 的所有已录入蔬菜批次,并能查看单个批次的详细信息(包括关联的施肥、农药记录)。系统需要为每个成功添加的批次 **自动生成一个全局唯一的批次号 (Batch ID)**,例如 `VEG-20240520-XYZ123`,并在列表和详情中展示。 * **修改 (Update)**: 编辑 **当前农场** 已存在的蔬菜批次信息。`batch_id` 和 `farm_name` 通常不允许修改。 * **删除 (Delete)**: 删除 **当前农场** 的某个蔬菜批次信息(可能需要考虑是否允许删除,或标记为删除)。 - **施肥记录管理**: * 通常集成在 **查看/修改蔬菜批次** 的详情页面中。 * 允许农户为 **当前农场** 的某个批次 **添加** 新的施肥记录(记录日期、描述)。 * 允许 **查看** 该批次的所有施肥记录。 * 可能允许 **删除** 某条错误的施肥记录。 - **农药记录管理**: * 与施肥记录管理类似,集成在批次详情页。 * 允许为 **当前农场** 的批次 **添加**、**查看**、**删除** 农药使用记录。 ### 4.2 手机App接口 (API - Go应用的一部分) 所有API的路径建议以 `/api/app` 开头,返回数据格式为 **JSON**。 - **用户注册**: * 路径: `POST /api/app/register` * 请求体 (JSON): `{ "username": "user1", "password": "password123" }` * 成功响应 (JSON): `{ "code": 0, "message": "注册成功" }` * 失败响应 (JSON): `{ "code": 1, "message": "用户名已存在" }` 或其他错误信息。 - **用户登录**: * 路径: `POST /api/app/login` * 请求体 (JSON): `{ "username": "user1", "password": "password123" }` * 成功响应 (JSON): `{ "code": 0, "message": "登录成功", "data": { "token": "一个长字符串代表用户的身份凭证(JWT)" } }` (这个 **token** 后续请求需要带上) * 失败响应 (JSON): `{ "code": 1, "message": "用户名或密码错误" }` - **溯源信息查询**: * 路径: `GET /api/app/trace/{batch_id}` (例如: `/api/app/trace/VEG-20240520-XYZ123`) * 请求头: 需要包含登录时获取的 **token** 用于身份验证 (例如: `Authorization: Bearer `)。 * **注意**: 消费者通过手机App扫描的二维码,其内容预期为该蔬菜批次的 **`batch_id`** 字符串。 * 成功响应 (JSON): ```json { "code": 0, "message": "查询成功", "data": { "batch_id": "VEG-20240520-XYZ123", "vegetable_name": "有机生菜", "farm_name": "XX有机农场", "seed_info": "XX公司提供的优质抗病种子", "planting_date": "2024-05-01", "harvest_date": "2024-06-15", "qa_report_info": "报告编号XXXX,合格", "remarks": "阳光充足,长势良好", "fertilizer_records": [ {"record_date": "2024-05-10", "description": "施用有机肥A"}, {"record_date": "2024-05-25", "description": "追施有机肥B"} ], "pesticide_records": [ {"record_date": "2024-06-01", "description": "使用生物农药C"} // 如果没有记录,则返回空列表 [] ] } } ``` * 失败响应 (JSON): ```json { "code": 1, "message": "批次号不存在" } // 或 { "code": 2, "message": "未授权或登录超时" } ``` ### 4.3 AI问答接口 (API - 由独立的Python服务提供) - **职责**: 提供一个HTTP API接口,接收App端的问题,调用外部生成式AI API获取答案,并返回。 - **路径**: (由 **lx** 同学最终确定并更新到此处,例如: `POST /api/ai/ask`) - **请求体 (JSON)**: `{ "question": "有机蔬菜怎么施肥比较好?" }` (可能也需要包含用户 **token** 以进行简单的调用频率限制或记录) - **成功响应 (JSON)**: `{ "code": 0, "answer": "有机蔬菜施肥建议使用腐熟的农家肥或者认证的有机肥料..." }` - **失败响应 (JSON)**: `{ "code": 1, "message": "AI服务调用失败" }` 或其他错误。 --- ## 5. 数据库设计 (初步) - 数据库类型: **MySQL** - *** **设想的注册审核流程 (当前版本简化,暂不实现)**: *理想情况下,农户应通过专门的注册页面提交信息(包括用户名、密码、手机号、农场名称及证明材料)。提交后,账号状态为"待审核"。超级管理员通过后台审核材料,决定通过或拒绝。审核通过后,状态变为"已激活",并记录其管理的 `farm_name`;拒绝则通过短信告知原因。* **在当前简化版本中,我们假设 `farmers` 账号由系统管理员预先创建,并直接设置好 `farm_name` 和 `status` 为 'Active'。** *** - 需要以下几张表: 1. **`farmers` 表 (农户账号信息)**: * `id` (INT, 主键, 自增) * `username` (VARCHAR(50), 用户名, **唯一**, 非空) * `password_hash` (VARCHAR(255), 存储加密后的密码, 非空) * `farm_name` (VARCHAR(100), 该农户管理的农场名称, 非空, **建议加索引**) * `phone_number` (VARCHAR(20), 手机号, 可用于接收通知, 可为空) * `status` (VARCHAR(20), 账号状态, 例如: 'Active', 'Pending', 'Rejected', **非空**, 默认 'Active' 或 'Pending') * `created_at` (TIMESTAMP, 默认当前时间) * `updated_at` (TIMESTAMP, 默认当前时间, 更新时自动更新) 2. **`users` 表 (App消费者用户)**: * `id` (INT, 主键, 自增) * `username` (VARCHAR(50), 用户名, **唯一**, 非空) * `password_hash` (VARCHAR(255), 存储加密后的密码, 非空) * `created_at` (TIMESTAMP, 默认当前时间) 3. **`vegetable_batches` 表 (蔬菜批次信息)**: * `id` (INT, 主键, 自增) * `batch_id` (VARCHAR(100), 批次号, **唯一索引**, 非空) * `farm_name` (VARCHAR(100), 农场名称, 非空, **建议加索引**, 关联 `farmers` 表) * `vegetable_name` (VARCHAR(100), 蔬菜名称, 非空) * `seed_info` (TEXT, 种子信息, 可为空) * `planting_date` (DATE, 种植日期) * `harvest_date` (DATE, 采摘日期, 可为空) * `qa_report_info` (TEXT, 质检信息) * `remarks` (TEXT, 备注, 可为空) * `created_at` (TIMESTAMP, 默认当前时间) * `updated_at` (TIMESTAMP, 默认当前时间, 更新时自动更新) 4. **`fertilizer_records` 表 (施肥记录)**: * `id` (INT, 主键, 自增) * `batch_id` (VARCHAR(100), 关联 `vegetable_batches` 表的 `batch_id`, **非空**, **建议加索引**) * `record_date` (DATE, 记录日期) * `description` (TEXT, 施肥描述, 非空) * `created_at` (TIMESTAMP, 默认当前时间) 5. **`pesticide_records` 表 (农药使用记录)**: * `id` (INT, 主键, 自增) * `batch_id` (VARCHAR(100), 关联 `vegetable_batches` 表的 `batch_id`, **非空**, **建议加索引**) * `record_date` (DATE, 记录日期) * `description` (TEXT, 农药使用描述, 非空) * `created_at` (TIMESTAMP, 默认当前时间) - **注意**: 以上字段类型和长度仅为初步建议。`fertilizer_records` 和 `pesticide_records` 表通过 `batch_id` 与 `vegetable_batches` 表关联。`farmers` 表中的 `farm_name` 用于在后台管理时隔离不同农户的数据,建议在 `vegetable_batches` 和 `farmers` 表的 `farm_name` 字段上都添加索引以优化查询。 --- ## 6. 团队分工 (建议) (根据最新的功能调整,分工可能需要微调,请团队成员确认) - **易与杰 (yyj)**: * 负责整体项目架构搭建 (Go项目结构, Gin路由)。 * 核心数据库表 (`vegetable_batches`, `fertilizer_records`, `pesticide_records`) 在MySQL中的设计与Go代码实现 (使用 **GORM**)。 * 后台管理系统的 **蔬菜批次管理** (CRUD) 功能后端逻辑 (包含 `farm_name` 过滤)。 * 后台管理系统的 **施肥/农药记录管理** 功能后端逻辑 (基于批次进行 CRUD)。 * App接口的 **溯源信息查询** (`GET /api/app/trace/{batch_id}`) 功能 (包含关联查询)。 * 关键: 确保 **`batch_id` 的唯一性生成** 逻辑。 * 协调Go服务与Python服务的部署和可能的通信。 - **罗文泽 (lwz)**: * 负责用户认证相关功能 (Go部分): * 后台 **农户登录** (`/admin/login`) 后端逻辑 (含 `status` 检查和 `farm_name` 获取)。 * App **用户注册** (`POST /api/app/register`) API。 * App **用户登录** (`POST /api/app/login`) API (包括 **JWT token** 生成与验证机制)。 * 数据库 **`farmers`** 和 **`users`** 表在MySQL中的设计与Go代码实现 (使用 **GORM**)。 * (可选) 协助 yyj 完成部分后台 CRUD 功能或测试。 - **刘永康 (lyk)**: * **学习**: Go 语言基础, Gin 框架基本使用, MySQL基础SQL语句, Postman API 测试工具, Swagger API 文档。 * **任务**: * 编写 **核心溯源系统** (Go部分) 的 **API 文档** (使用 **Swagger**)。 * 参与 **核心溯源系统 API 功能测试**,使用 **Postman** 验证接口。 * (可选) 尝试编写一些辅助函数或简单的后台管理页面模板(如果后台需要简单页面显示)。 - **刘祥 (lx)**: * **主要任务**: 独立负责 **AI问答服务** 的开发。 * 技术栈: 使用 **Python** 和熟悉的Web框架 (**Flask** 或 **FastAPI**)。 * 功能: 实现接收App问题的API接口 (如 `POST /api/ai/ask`),调用外部生成式AI API (需确定平台并申请Key),处理并返回结果。 * 接口定义: 需要明确定义并告知团队其服务的API路径、请求和响应格式。 * 部署: 负责将这个Python服务独立部署运行起来 (可以使用 **Docker** 简化)。 * **学习**: 如果不熟悉,需要学习所选Python Web框架、如何调用外部HTTP API。 - **潘凯 (pk)**: * **首要任务**: 搭建好所有开发环境 (Go, Python, Git, VS Code, MySQL数据库及客户端工具如 Navicat, Postman)。 * **学习**: **Git** 基本操作 (clone, pull, add, commit, push), Go 最基础语法。 * **任务**: * 学习使用 **Postman** 或类似工具 **测试** 开发完成的 **所有 API 接口** (包括Go的和Python的),并记录测试结果。 * 准备最终的 **项目演示** (需要演示核心溯源后台管理、App接口查询 和 AI问答功能)。 --- ## 7. 后续步骤 1. **环境搭建**: 所有成员完成开发环境的安装与配置,特别是 **MySQL** 数据库的安装和连接。 2. **数据库设计确认与创建**: **yyj** 和 **lwz** 敲定最终的 **MySQL 表结构** (基于本文档),并在数据库中创建好表 (包括添加必要的 **索引**)。 3. **项目初始化**: **yyj** 在 Git 仓库中初始化 Go 项目 (`go mod init`) 和基本的目录结构。**lx** 初始化 Python AI 服务的项目结构。 4. **API Key申请**: **lx** 确定AI问答服务使用的外部AI平台,并完成 **API Key** 的申请。 5. **任务启动**: 各成员根据分工开始学习和开发。 6. **定期沟通**: 保持 **高频、有效** 的沟通(如每日站会),同步进度,暴露问题,确保Go和Python两部分能顺利对接。 --- ## 8. 项目目录结构说明 本 Go 项目 (`go-api`) 主要采用分层架构的思想来组织代码,各个目录的职责如下: ``` go-api/ ├── controller/ # 控制器层 (Handler) ├── dao/ # 数据访问层 (Data Access Object) ├── dto/ # 数据传输对象 (Data Transfer Object) ├── model/ # 数据模型 (数据库实体) ├── server/ # 服务启动与路由配置 ├── tool/ # 工具包 ├── go.mod # Go 模块依赖定义 ├── go.sum # Go 模块依赖校验和 ├── main.go # (通常) 程序主入口文件 └── README.md # 项目说明文档 ``` - **`controller/`**: 负责处理接收到的 HTTP 请求。它们会验证请求参数(通常使用 `dto`),调用下一层(比如未来可能添加的 `service` 层,或者直接调用 `dao` 层)来完成业务逻辑,最后将结果(也可能使用 `dto`)格式化并返回给客户端。 - **`dao/`**: 负责与数据库进行直接交互。这里面会包含所有对数据库进行增、删、改、查(CRUD)操作的代码。通常会使用像 GORM 这样的 ORM 库来简化数据库操作,操作的数据对象一般是 `model/` 中定义的结构体。 - **`dto/`**: 定义用于在不同层之间,特别是 API 接口层面传输数据的结构体。例如,API 请求传入的 JSON 数据对应的结构体、API 返回给前端的 JSON 数据对应的结构体都应该在这里定义。这样做的好处是让 API 的数据格式与数据库内部的 `model` 分离开,更灵活。 - **`model/`**: 定义了与数据库中的表相对应的 Go 结构体(有时也叫 Entity 或 Domain Object)。这些结构体通常包含了数据库字段的映射信息(比如 GORM 的标签)。它们是程序核心数据的载体。 - **`server/`**: 这个目录通常包含启动 Web 服务器(比如 Gin 引擎)、注册 API 路由(将 URL 路径映射到 `controller/` 中的处理函数)、以及可能配置全局中间件(Middleware,比如日志记录、身份验证)的代码。 - **`tool/`**: 存放项目中使用到的各种通用工具函数或工具包。比如,密码加密、JWT Token 生成与解析、唯一ID生成器等这些可以在项目中多处复用的功能代码。 - **`main.go`** (通常在根目录): 这是整个 Go 应用程序的入口点。它负责初始化配置、连接数据库、设置路由、启动服务器等初始设置工作。 - **`go.mod` / `go.sum`**: Go 语言的模块管理文件,用于定义项目依赖的第三方库及其版本。 - **`README.md`**: 就是你现在看到的这个文件,用来详细说明项目情况。 **注意**: 这个结构是一个基础,随着项目变复杂,可能还会引入 `service/` (业务逻辑层)、`config/` (配置加载)、`middleware/` (独立中间件) 等目录来进一步细化分层。 ## 项目结构 ### 前端项目 (vue-admin) ``` vue-admin/ ├── src/ # 源代码目录 │ ├── api/ # API 接口定义 │ ├── assets/ # 静态资源 │ ├── components/ # 公共组件 │ ├── layout/ # 布局组件 │ ├── router/ # 路由配置 │ ├── store/ # Vuex 状态管理 │ ├── styles/ # 全局样式 │ ├── utils/ # 工具函数 │ └── views/ # 页面组件 ├── public/ # 公共资源 └── package.json # 项目依赖配置 ``` ### 后端项目 (go-api) ``` go-api/ ├── main.go # 程序入口文件 ├── configs/ # 配置文件目录 ├── scripts/ # 脚本文件目录 └── internal/ # 内部代码目录 ├── config/ # 配置管理 ├── controller/ # 控制器层,处理 HTTP 请求 ├── dao/ # 数据访问层,处理数据库操作 ├── dto/ # 数据传输对象,定义请求和响应结构 ├── middleware/ # 中间件,如认证、日志等 ├── model/ # 数据模型,定义数据库表结构 ├── router/ # 路由配置 ├── service/ # 业务逻辑层 └── tool/ # 工具函数 ``` ## 技术栈 ### 前端技术栈 - Vue 3 - Element Plus - Vue Router - Vuex - Axios - ECharts ### 后端技术栈 - Go - Gin Web 框架 - GORM - MySQL - Redis - JWT 认证 ## 功能模块 ### 1. 用户管理 - 超级管理员 - 管理所有农户账号 - 审核农户认证 - 查看所有数据 - 农户账号 - 管理自己的农场信息 - 录入蔬菜信息 - 生成二维码 - 查看自己的数据 ### 2. 农场管理 - 农场基本信息维护 - 农场认证状态管理 - 农场与农户关联 ### 3. 蔬菜信息管理 - 蔬菜基本信息录入 - 种植信息记录 - 批次管理 - 二维码生成 ### 4. 数据统计 - 农场数量统计 - 蔬菜种类统计 - 种植面积统计 - 产量统计 ## 数据库设计 ### 1. 农户表 (farmers) ```sql CREATE TABLE farmers ( id BIGINT PRIMARY KEY AUTO_INCREMENT, username VARCHAR(50) NOT NULL UNIQUE, password VARCHAR(255) NOT NULL, phone VARCHAR(20) NOT NULL, status TINYINT NOT NULL DEFAULT 0 COMMENT '0:待审核 1:已通过 2:已拒绝', created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP ); ``` ### 2. 农场表 (farms) ```sql CREATE TABLE farms ( id BIGINT PRIMARY KEY AUTO_INCREMENT, farmer_id BIGINT NOT NULL, name VARCHAR(100) NOT NULL, address TEXT NOT NULL, area DECIMAL(10,2) NOT NULL COMMENT '面积(亩)', status TINYINT NOT NULL DEFAULT 0 COMMENT '0:待审核 1:已通过 2:已拒绝', created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, FOREIGN KEY (farmer_id) REFERENCES farmers(id) ); ``` ### 3. 蔬菜表 (vegetables) ```sql CREATE TABLE vegetables ( id BIGINT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(50) NOT NULL, category VARCHAR(50) NOT NULL, description TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP ); ``` ### 4. 种植记录表 (planting_records) ```sql CREATE TABLE planting_records ( id BIGINT PRIMARY KEY AUTO_INCREMENT, farm_id BIGINT NOT NULL, vegetable_id BIGINT NOT NULL, batch_number VARCHAR(50) NOT NULL COMMENT '批次号', planting_date DATE NOT NULL, expected_harvest_date DATE NOT NULL, actual_harvest_date DATE, area DECIMAL(10,2) NOT NULL COMMENT '种植面积(亩)', expected_yield DECIMAL(10,2) COMMENT '预计产量(kg)', actual_yield DECIMAL(10,2) COMMENT '实际产量(kg)', status TINYINT NOT NULL DEFAULT 0 COMMENT '0:种植中 1:已收获 2:已取消', created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, FOREIGN KEY (farm_id) REFERENCES farms(id), FOREIGN KEY (vegetable_id) REFERENCES vegetables(id) ); ``` ## 二维码设计 - 二维码内容:仅包含批次ID - 扫描后跳转到:`https://vegetable-query.example.com/batch/{batch_id}` - 批次ID格式:`{farm_id}_{timestamp}_{random_number}` ## 开发规范 ### 1. 代码规范 - 前端遵循 Vue 3 官方风格指南 - 后端遵循 Go 标准项目布局 - 使用 ESLint 和 Prettier 进行代码格式化 - 使用 golangci-lint 进行 Go 代码检查 ### 2. Git 提交规范 - feat: 新功能 - fix: 修复问题 - docs: 文档修改 - style: 代码格式修改 - refactor: 代码重构 - test: 测试用例修改 - chore: 其他修改 ### 3. 接口规范 - 遵循 RESTful API 设计规范 - 使用 JWT 进行身份认证 - 统一响应格式 - 详细的接口文档 ## 部署说明 ### 环境要求 - Node.js >= 16 - Go >= 1.18 - MySQL >= 8.0 - Redis >= 6.0 ### 部署步骤 1. 克隆项目 2. 安装依赖 3. 配置环境变量 4. 初始化数据库 5. 启动服务 ## 待实现功能 1. 农户注册时的认证材料上传 2. 超级管理员的审核流程 3. 农户与农场的关联管理 4. 更详细的种植记录 5. 数据导出功能 6. 移动端适配 7. 多语言支持