FarmPro API 合同
使用 FarmPro API 的 API 型安全合同 ts-resst (英语) 财务报告和审定财务报表 佐德语Name。 。 。 .
概览
这个包为所有FarmPro模块提供全面,型式安全的API合同. 这些合同遵循RESTFUL原则,并使用Zod计划进行运行时间验证.
安装
npm install @farmpro/contracts
结构
合同分为以下单元:
src/
├── index.ts # Main exports
├── routes/ # API route definitions
│ ├── index.ts # Main contract combining all routers
│ ├── farms.routes.ts
│ ├── fields.routes.ts
│ ├── tasks.routes.ts
│ ├── inventory.routes.ts
│ ├── finance.routes.ts
│ ├── harvest.routes.ts
│ ├── soil-tests.routes.ts
│ ├── weather.routes.ts
│ ├── team.routes.ts
│ ├── equipment.routes.ts
│ ├── documents.routes.ts
│ ├── suppliers.routes.ts
│ └── analytics.routes.ts
└── schemas/ # Zod schemas
├── common.schemas.ts # Shared schemas (pagination, errors, GeoJSON)
├── farms.schemas.ts
├── fields.schemas.ts
├── tasks.schemas.ts
├── inventory.schemas.ts
├── finance.schemas.ts
├── harvest.schemas.ts
├── soil-tests.schemas.ts
├── weather.schemas.ts
├── team.schemas.ts
├── equipment.schemas.ts
├── documents.schemas.ts
├── suppliers.schemas.ts
└── analytics.schemas.ts
使用量
后端( NestJS)
import { apiContract } from '@farmpro/contracts';
import { TsRestHandler, tsRestHandler } from '@ts-rest/nest';
@Controller()
export class FarmsController {
@TsRestHandler(apiContract.farms)
async handler() {
return tsRestHandler(apiContract.farms, {
listFarms: async ({ query }) => {
// Implementation
},
createFarm: async ({ body }) => {
// Implementation
},
// ... other handlers
});
}
}
前端
import { initClient } from '@ts-rest/core';
import { apiContract } from '@farmpro/contracts';
const client = initClient(apiContract, {
baseUrl: 'http://localhost:3000/api',
baseHeaders: {
'Content-Type': 'application/json',
},
});
// Use the client
const farms = await client.farms.listFarms({ query: { page: 1, limit: 20 } });
const farm = await client.farms.createFarm({ body: { name: 'My Farm', location: 'Kano' } });
API 模块
认证
POST /auth/login- 用电子邮件和密码登录POST /auth/signup- 登记新用户POST /auth/google/initiate- 启动谷歌OAuth流量POST /auth/google/callback- 处理谷歌OAuth召回POST /auth/refresh- 刷新访问标志POST /auth/logout- 登录用户POST /auth/password/reset-request- 请求密码重置POST /auth/password/reset- 重新设定密码POST /auth/password/change- 更改密码(认证)POST /auth/email/verify- 验证电子邮件地址POST /auth/email/resend-verification- 重新发送验证邮件
用户
GET /user/profile- 获取当前用户配置PATCH /user/profile- 更新用户配置
农场
GET /farms- 名单农场POST /farms- 创建农场GET /farms/:id- 去农场PATCH /farms/:id- 更新农场DELETE /farms/:id- 删除农场
字段
GET /farms/:farmId/fields- 列表字段POST /farms/:farmId/fields- 创建字段GET /farms/:farmId/fields/:id- 获得野外PATCH /farms/:farmId/fields/:id- 更新字段DELETE /farms/:farmId/fields/:id- 删除字段
任务
GET /farms/:farmId/tasks- 列出任务POST /farms/:farmId/tasks- 创建任务GET /farms/:farmId/tasks/:id- 得到任务PATCH /farms/:farmId/tasks/:id- 更新任务POST /farms/:farmId/tasks/:id/complete- 完成任务DELETE /farms/:farmId/tasks/:id- 删除任务POST /farms/:farmId/tasks/:id/notes- 添加任务说明
库存
GET /farms/:farmId/inventory- 清单物项POST /farms/:farmId/inventory- 创建库存项目GET /farms/:farmId/inventory/:id- 获得库存物品PATCH /farms/:farmId/inventory/:id- 更新库存项目DELETE /farms/:farmId/inventory/:id- 删除库存项目POST /farms/:farmId/inventory/purchase- 购买日志
财务
- 预算:
GET, (中文(简体) ),POST, (中文(简体) ),PATCH, (中文(简体) ),DELETE /farms/:farmId/budget - 费用:
GET, (中文(简体) ),POST, (中文(简体) ),PATCH, (中文(简体) ),DELETE /farms/:farmId/expenses - 收入:
GET, (中文(简体) ),POST, (中文(简体) ),PATCH, (中文(简体) ),DELETE /farms/:farmId/revenue GET /farms/:farmId/finance/summary- 财务摘要
收获
GET /farms/:farmId/harvests- 清单收成POST /farms/:farmId/harvests- 创造收获GET /farms/:farmId/harvests/:id- 收获吧PATCH /farms/:farmId/harvests/:id- 更新收获情况DELETE /farms/:farmId/harvests/:id- 删除收成
土壤试验
GET /farms/:farmId/soil-tests- 列出土壤试验POST /farms/:farmId/soil-tests- 建立土壤测试GET /farms/:farmId/soil-tests/:id- 进行土壤测试PATCH /farms/:farmId/soil-tests/:id- 更新土壤测试DELETE /farms/:farmId/soil-tests/:id- 删除土壤试验
天气
GET /farms/:farmId/weather- 获取天气数据
团队
GET /farms/:farmId/team- 名单小组成员POST /farms/:farmId/team- 创建团队成员GET /farms/:farmId/team/:id- 叫队员来PATCH /farms/:farmId/team/:id- 更新小组成员DELETE /farms/:farmId/team/:id- 删除小组成员
设备
GET /farms/:farmId/equipment- 清单设备POST /farms/:farmId/equipment- 创建设备GET /farms/:farmId/equipment/:id- 拿设备PATCH /farms/:farmId/equipment/:id- 更新设备DELETE /farms/:farmId/equipment/:id- 删除设备POST /farms/:farmId/equipment/:id/maintenance- 增加维护记录
文档
GET /farms/:farmId/documents- 清单文件POST /farms/:farmId/documents- 创建文档GET /farms/:farmId/documents/:id- 获取文档PATCH /farms/:farmId/documents/:id- 更新文档DELETE /farms/:farmId/documents/:id- 删除文档
供应商
- 供应商:
GET, (中文(简体) ),POST, (中文(简体) ),PATCH, (中文(简体) ),DELETE /farms/:farmId/suppliers - 买家 :
GET, (中文(简体) ),POST, (中文(简体) ),PATCH, (中文(简体) ),DELETE /farms/:farmId/buyers
分析
GET /farms/:farmId/analytics- 获取分析数据
常见特征
倾斜
大多数列表终点支持 pagination :
{
page?: number; // Default: 1
limit?: number; // Default: 20, Max: 100
}
日期范围过滤
许多端点支持日期范围过滤:
{
startDate?: string; // ISO datetime
endDate?: string; // ISO datetime
}
GeoJSON 支持
农场和农田支持GeoJSON几何边界:
{
type: 'Polygon' | 'MultiPolygon' | 'Point' | 'LineString';
coordinates: number[][][] | number[][] | number[];
}
错误回复
所有端点返回标准化错误反应:
{
message: string;
code?: string;
errors?: Array<{
field?: string;
message: string;
}>;
}
类型安全
所有计划导出类型Script 类型 :
import type {
FarmResponse,
CreateFarmInput,
FieldResponse,
TaskResponse,
// ... etc
} from '@farmpro/contracts';
发展
大楼
npm run build
类型检查
npm run type-check
出版
npm run prepublishOnly # Builds and validates
npm publish
许可证
公务员制度委员会