# xlxumu 畜牧管理系统 API 文档 ## 概述 本文档描述了 xlxumu 畜牧管理系统的 RESTful API 接口。系统提供用户认证、牛只管理、财务管理、交易管理、商城管理和政府监管等功能。 ## 基础信息 - **基础URL**: `http://localhost:8889/api/v1` - **认证方式**: JWT Token - **数据格式**: JSON - **字符编码**: UTF-8 ## 通用响应格式 ### 成功响应 ```json { "success": true, "data": { // 具体数据内容 }, "message": "操作成功" } ``` ### 错误响应 ```json { "success": false, "message": "错误描述", "code": "ERROR_CODE" } ``` ## 认证接口 (/auth) ### 用户注册 - **URL**: `POST /auth/register` - **描述**: 用户注册 - **请求体**: ```json { "username": "string", "email": "string", "phone": "string", "password": "string", "real_name": "string", "user_type": "farmer|government|bank|insurance" } ``` - **响应**: ```json { "success": true, "data": { "user": { "id": 1, "username": "testuser", "email": "test@example.com", "user_type": "farmer" }, "token": "jwt_token_string" } } ``` ### 用户登录 - **URL**: `POST /auth/login` - **描述**: 用户登录 - **请求体**: ```json { "username": "string", "password": "string" } ``` ### 刷新Token - **URL**: `POST /auth/refresh` - **描述**: 刷新访问令牌 - **请求头**: `Authorization: Bearer ` ### 用户登出 - **URL**: `POST /auth/logout` - **描述**: 用户登出 - **请求头**: `Authorization: Bearer ` ## 用户管理接口 (/users) ### 获取用户信息 - **URL**: `GET /users/profile` - **描述**: 获取当前用户信息 - **请求头**: `Authorization: Bearer ` ### 更新用户信息 - **URL**: `PUT /users/profile` - **描述**: 更新用户信息 - **请求头**: `Authorization: Bearer ` - **请求体**: ```json { "real_name": "string", "phone": "string", "avatar_url": "string" } ``` ### 修改密码 - **URL**: `PUT /users/password` - **描述**: 修改用户密码 - **请求头**: `Authorization: Bearer ` - **请求体**: ```json { "old_password": "string", "new_password": "string" } ``` ## 牛只管理接口 (/cattle) ### 获取牛只列表 - **URL**: `GET /cattle` - **描述**: 获取牛只列表 - **请求头**: `Authorization: Bearer ` - **查询参数**: - `page`: 页码 (默认: 1) - `limit`: 每页数量 (默认: 10) - `breed`: 品种筛选 - `status`: 状态筛选 - `health_status`: 健康状态筛选 ### 添加牛只 - **URL**: `POST /cattle` - **描述**: 添加新牛只 - **请求头**: `Authorization: Bearer ` - **请求体**: ```json { "ear_tag": "string", "name": "string", "breed": "string", "gender": "male|female", "birth_date": "YYYY-MM-DD", "color": "string", "weight": 500.5, "farm_location": "string", "notes": "string" } ``` ### 获取牛只详情 - **URL**: `GET /cattle/:id` - **描述**: 获取指定牛只详情 - **请求头**: `Authorization: Bearer ` ### 更新牛只信息 - **URL**: `PUT /cattle/:id` - **描述**: 更新牛只信息 - **请求头**: `Authorization: Bearer ` ### 删除牛只 - **URL**: `DELETE /cattle/:id` - **描述**: 删除牛只记录 - **请求头**: `Authorization: Bearer ` ### 牛只统计 - **URL**: `GET /cattle/statistics` - **描述**: 获取牛只统计信息 - **请求头**: `Authorization: Bearer ` ## 财务管理接口 (/finance) ### 获取财务记录 - **URL**: `GET /finance/records` - **描述**: 获取财务记录列表 - **请求头**: `Authorization: Bearer ` - **查询参数**: - `page`: 页码 - `limit`: 每页数量 - `type`: 类型 (income|expense) - `category`: 分类 - `start_date`: 开始日期 - `end_date`: 结束日期 ### 添加财务记录 - **URL**: `POST /finance/records` - **描述**: 添加财务记录 - **请求头**: `Authorization: Bearer ` - **请求体**: ```json { "type": "income|expense", "category": "string", "amount": 1000.00, "description": "string", "record_date": "YYYY-MM-DD" } ``` ### 财务统计 - **URL**: `GET /finance/statistics` - **描述**: 获取财务统计信息 - **请求头**: `Authorization: Bearer ` - **查询参数**: - `period`: 统计周期 (month|quarter|year) ## 交易管理接口 (/trading) ### 获取交易列表 - **URL**: `GET /trading/transactions` - **描述**: 获取交易记录列表 - **请求头**: `Authorization: Bearer ` - **查询参数**: - `page`: 页码 - `limit`: 每页数量 - `status`: 交易状态 - `product_type`: 产品类型 ### 创建交易 - **URL**: `POST /trading/transactions` - **描述**: 创建新交易 - **请求头**: `Authorization: Bearer ` - **请求体**: ```json { "seller_id": 1, "product_type": "cattle", "product_id": 1, "quantity": 10, "unit_price": 8500.00, "notes": "string" } ``` ### 获取交易详情 - **URL**: `GET /trading/transactions/:id` - **描述**: 获取交易详情 - **请求头**: `Authorization: Bearer ` ### 更新交易状态 - **URL**: `PUT /trading/transactions/:id/status` - **描述**: 更新交易状态 - **请求头**: `Authorization: Bearer ` - **请求体**: ```json { "status": "pending|confirmed|completed|cancelled", "payment_status": "pending|paid|refunded", "delivery_status": "pending|shipped|delivered" } ``` ## 商城管理接口 (/mall) ### 获取产品列表 - **URL**: `GET /mall/products` - **描述**: 获取商城产品列表 - **查询参数**: - `page`: 页码 - `limit`: 每页数量 - `category_id`: 分类ID - `keyword`: 搜索关键词 - `min_price`: 最低价格 - `max_price`: 最高价格 ### 获取产品详情 - **URL**: `GET /mall/products/:id` - **描述**: 获取产品详情 ### 添加产品 - **URL**: `POST /mall/products` - **描述**: 添加新产品 - **请求头**: `Authorization: Bearer ` - **请求体**: ```json { "name": "string", "description": "string", "category_id": 1, "price": 100.00, "stock_quantity": 50, "images": ["url1", "url2"], "specifications": {} } ``` ### 获取订单列表 - **URL**: `GET /mall/orders` - **描述**: 获取订单列表 - **请求头**: `Authorization: Bearer ` ### 创建订单 - **URL**: `POST /mall/orders` - **描述**: 创建新订单 - **请求头**: `Authorization: Bearer ` - **请求体**: ```json { "items": [ { "product_id": 1, "quantity": 2, "price": 100.00 } ], "shipping_address": "string", "notes": "string" } ``` ## 政府监管接口 (/government) ### 获取农场监管列表 - **URL**: `GET /government/farms/supervision` - **描述**: 获取农场监管信息 - **请求头**: `Authorization: Bearer ` - **查询参数**: - `page`: 页码 - `limit`: 每页数量 - `region`: 地区 - `status`: 监管状态 ### 获取监管统计 - **URL**: `GET /government/statistics` - **描述**: 获取监管统计数据 - **请求头**: `Authorization: Bearer ` - **响应示例**: ```json { "success": true, "data": { "overview": { "total_farms": 1250, "total_cattle": 45680, "active_farms": 1180, "compliance_rate": 94.4 }, "by_region": [ { "region": "华北地区", "farms": 320, "cattle": 12500, "compliance_rate": 96.2 } ], "by_type": [ { "type": "肉牛养殖", "count": 680, "percentage": 54.4 } ], "monthly_trend": [ { "month": "2024-01", "new_registrations": 25, "inspections": 156, "violations": 8 } ] } } ``` ## 系统接口 ### 健康检查 - **URL**: `GET /health` - **描述**: 系统健康检查 - **响应**: ```json { "status": "ok", "timestamp": "2024-01-20T10:30:00Z", "database": "connected", "version": "1.0.0" } ``` ### 数据库状态 - **URL**: `GET /database/status` - **描述**: 数据库连接状态 ### 数据库表信息 - **URL**: `GET /database/tables` - **描述**: 获取数据库表信息 ## 错误码说明 | 错误码 | 描述 | |--------|------| | VALIDATION_ERROR | 请求参数验证失败 | | UNAUTHORIZED | 未授权访问 | | FORBIDDEN | 禁止访问 | | NOT_FOUND | 资源未找到 | | DATABASE_ERROR | 数据库操作失败 | | INTERNAL_SERVER_ERROR | 服务器内部错误 | ## 认证说明 大部分API接口需要在请求头中包含JWT Token： ``` Authorization: Bearer ``` Token可通过登录接口获取，有效期为24小时。 ## 分页说明 支持分页的接口使用以下参数： - `page`: 页码，从1开始 - `limit`: 每页数量，默认10，最大100 分页响应格式： ```json { "success": true, "data": { "items": [...], "pagination": { "total": 100, "page": 1, "limit": 10, "pages": 10 } } } ``` ## 开发环境 - **服务器地址**: http://localhost:8889 - **数据库**: SQLite (开发环境) - **日志级别**: DEBUG ## 注意事项 1. 所有时间格式使用 ISO 8601 标准 2. 金额字段使用 DECIMAL 类型，保留2位小数 3. 文件上传大小限制为 10MB 4. API请求频率限制：每15分钟100次请求 5. 开发环境下会返回详细的错误信息，生产环境下会隐藏敏感信息