# vegetable-query-go-api **Repository Path**: hunua-vegetable-query/vegetable-query-go-api ## Basic Information - **Project Name**: vegetable-query-go-api - **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-14 - **Last Updated**: 2025-05-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 有机蔬菜溯源信息查询系统 - 项目说明文档 (v1.4) ## 1. 项目概述 本项目是一个面向有机蔬菜产业的溯源信息查询系统，旨在实现从种植到销售的全流程信息透明化。系统分为两个主要部分： ### 1.1 后台管理系统（供农户使用） - 农户账号管理 - 蔬菜批次信息管理 - 种植过程记录（施肥、农药使用） ### 1.2 手机App接口（供消费者使用） - 用户注册登录 - 溯源信息查询 - AI智能问答 ## 2. 系统架构 ### 2.1 技术栈 - 后端：Go + Gin + GORM + MySQL - AI服务：Python + Flask/FastAPI - 前端：Vue 3 + Element Plus（后台管理） - 移动端：原生App（调用API） ### 2.2 核心功能模块 #### 2.2.1 农户管理模块 - 功能：农户账号的创建、登录、状态管理、个人资料更新 - 数据表：`farmers` - 关键字段： * `username`：登录用户名 * `farm_name`：农场名称（用于数据隔离） * `status`：账号状态（Active/Pending/Rejected） #### 2.2.2 蔬菜批次管理模块 - 功能：批次信息的录入、修改、查询、删除 - 数据表：`vegetable_batches` - 关键字段： * `batch_id`：唯一批次号（用于生成二维码） * `farm_name`：关联农户 * `vegetable_name`：蔬菜名称 * `planting_date`/`harvest_date`：种植/采摘日期 #### 2.2.3 种植记录模块 - 功能：记录施肥和农药使用情况 - 数据表：`fertilizer_records`和`pesticide_records` - 关键字段： * `batch_id`：关联蔬菜批次 * `record_date`：记录日期 * `description`：详细描述 #### 2.2.4 溯源查询模块 - 功能：消费者通过扫描二维码查询溯源信息 - 接口：`GET /api/app/trace/{batch_id}` - 返回数据：包含批次信息、施肥记录、农药记录等 #### 2.2.5 AI问答模块 - 功能：智能回答消费者关于蔬菜种植的问题 - 接口：`POST /api/ai/ask` - 技术：调用外部AI模型API ## 3. 数据库设计 ### 3.1 表结构详细说明 #### 3.1.1 farmers表（农户账号） ```sql CREATE TABLE farmers ( id INT PRIMARY KEY AUTO_INCREMENT, -- 农户唯一标识 username VARCHAR(50) NOT NULL UNIQUE, -- 登录用户名 password_hash VARCHAR(255) NOT NULL, -- 加密后的密码 farm_name VARCHAR(100) NOT NULL, -- 农场名称（重要：用于数据隔离） phone_number VARCHAR(20), -- 联系电话 status VARCHAR(20) NOT NULL, -- 账号状态：Active/Pending/Rejected created_at TIMESTAMP, -- 创建时间 updated_at TIMESTAMP -- 更新时间 ); ``` #### 3.1.2 users表（App用户） ```sql CREATE TABLE users ( id INT PRIMARY KEY AUTO_INCREMENT, -- 用户唯一标识 username VARCHAR(50) NOT NULL UNIQUE, -- 登录用户名 password_hash VARCHAR(255) NOT NULL, -- 加密后的密码 created_at TIMESTAMP -- 创建时间 ); ``` #### 3.1.3 vegetable_batches表（蔬菜批次） ```sql CREATE TABLE vegetable_batches ( id INT PRIMARY KEY AUTO_INCREMENT, -- 批次记录ID batch_id VARCHAR(100) NOT NULL UNIQUE, -- 批次号（如：VEG-20240520-XYZ123） farm_name VARCHAR(100) NOT NULL, -- 关联farmers表的farm_name vegetable_name VARCHAR(100) NOT NULL, -- 蔬菜名称 seed_info TEXT, -- 种子信息 planting_date DATE, -- 种植日期 harvest_date DATE, -- 采摘日期 qa_report_info TEXT, -- 质检报告信息 remarks TEXT, -- 备注信息 created_at TIMESTAMP, -- 创建时间 updated_at TIMESTAMP -- 更新时间 ); ``` #### 3.1.4 fertilizer_records表（施肥记录） ```sql CREATE TABLE fertilizer_records ( id INT PRIMARY KEY AUTO_INCREMENT, -- 记录ID batch_id VARCHAR(100) NOT NULL, -- 关联vegetable_batches表 record_date DATE, -- 施肥日期 description TEXT NOT NULL, -- 施肥描述 created_at TIMESTAMP -- 创建时间 ); ``` #### 3.1.5 pesticide_records表（农药记录） ```sql CREATE TABLE pesticide_records ( id INT PRIMARY KEY AUTO_INCREMENT, -- 记录ID batch_id VARCHAR(100) NOT NULL, -- 关联vegetable_batches表 record_date DATE, -- 使用日期 description TEXT NOT NULL, -- 使用描述 created_at TIMESTAMP -- 创建时间 ); ``` ### 3.2 索引设计 - `farmers`表：`username`(UNIQUE), `farm_name`(INDEX) - `users`表：`username`(UNIQUE) - `vegetable_batches`表：`batch_id`(UNIQUE), `farm_name`(INDEX) - `fertilizer_records`表：`batch_id`(INDEX) - `pesticide_records`表：`batch_id`(INDEX) ### 3.3 数据关系 1. 农户(`farmers`) 1:N 蔬菜批次(`vegetable_batches`) - 通过`farm_name`字段关联 - 确保数据隔离 2. 蔬菜批次(`vegetable_batches`) 1:N 施肥记录(`fertilizer_records`) - 通过`batch_id`字段关联 - 记录完整的施肥历史 3. 蔬菜批次(`vegetable_batches`) 1:N 农药记录(`pesticide_records`) - 通过`batch_id`字段关联 - 记录完整的农药使用历史 ## 4. API接口设计 ### 4.1 后台管理接口 - 农户相关 * 农户登录：`POST /api/v1/farmer/login` * 农户注册：`POST /api/v1/farmer/register` * 个人资料查询：`GET /api/v1/farmer/profile` * 个人资料更新：`PUT /api/v1/farmer/profile` * 修改密码：`PUT /api/v1/farmer/password` - 批次管理 * 创建批次：`POST /api/v1/farmer/batches` * 批次列表：`GET /api/v1/farmer/batches` * 批次详情：`GET /api/v1/farmer/batches/{batch_id}` * 更新批次：`PUT /api/v1/farmer/batches/{batch_id}` * 删除批次：`DELETE /api/v1/farmer/batches/{batch_id}` - 施肥记录 * 添加记录：`POST /api/v1/farmer/batches/{batch_id}/fertilizer` * 查询记录：`GET /api/v1/farmer/batches/{batch_id}/fertilizer` * 删除记录：`DELETE /api/v1/farmer/batches/{batch_id}/fertilizer/{record_id}` - 农药记录 * 添加记录：`POST /api/v1/farmer/batches/{batch_id}/pesticide` * 查询记录：`GET /api/v1/farmer/batches/{batch_id}/pesticide` * 删除记录：`DELETE /api/v1/farmer/batches/{batch_id}/pesticide/{record_id}` ### 4.2 App接口 - 用户注册：`POST /api/v1/user/register` - 用户登录：`POST /api/v1/user/login` - 溯源查询：`GET /api/v1/trace/{batch_id}` ### 4.3 AI问答接口 - 智能问答：`POST /api/v1/ai/ask` ## 5. 部署说明 ### 5.1 环境要求 - Go >= 1.18 - MySQL >= 8.0 - Python >= 3.8（AI服务） - Redis >= 6.0（可选，用于缓存） ### 5.2 部署步骤 1. 克隆项目代码 2. 安装依赖 3. 配置数据库 4. 初始化数据库表 5. 启动Go服务 6. 启动Python AI服务 ## 6. 开发规范 ### 6.1 代码规范 - Go代码遵循标准项目布局 - 使用golangci-lint进行代码检查 - 遵循RESTful API设计规范 - 统一错误处理和响应格式 ### 6.2 文档规范 - 所有API接口必须有详细文档 - 数据库表结构变更需要更新文档 - 重要功能需要编写测试用例 ## 7. 项目进度 ### 7.1 已完成功能 - 项目基础架构搭建 - 数据库设计与实现 - 农户管理模块（注册、登录、个人资料） - 蔬菜批次管理模块（创建、查询、更新、删除） - 种植记录模块（施肥记录和农药记录） ### 7.2 待开发功能 - 农户注册认证流程优化 - 移动端适配优化 - 系统监控和告警 - 数据导出功能 - AI问答模块集成 ## 8. 维护说明 ### 8.1 日常维护 - 定期数据库备份 - 日志监控和分析 - 性能优化 - 安全更新 ### 8.2 问题处理 - 建立问题反馈机制 - 制定应急预案 - 定期系统检查 ## 9. 更新日志 ### v1.4 (当前版本) - 优化了施肥记录和农药记录的控制器层功能 - 将种植记录相关功能从batch.go抽离到独立的planting_record.go文件 - 改进了错误处理和响应格式 - 完善了API接口文档 ### v1.3 - 实现了基础的农户管理功能 - 实现了蔬菜批次的基本CRUD操作 - 添加了施肥记录和农药记录功能 - 完成了数据库表设计和索引优化