smart-crop-ui/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

这是一个基于 React + Vite + TypeScript 的智慧农业生产管理系统，包含7个主要功能模块：

• 智能农机管理系统 (machinery)
• 地块管理系统 (field)
• 农事管理系统 (operation)
• 资产管理系统 (asset)
• AI模型系统 (ai-model)
• 灌溉控制系统 (irrigation)
• 配置管理系统 (config)

开发命令

基础命令

• npm i - 安装依赖
• npm run dev - 启动开发服务器 (端口 3000)
• npm run build - 构建生产版本

包管理

• 使用 npm 作为包管理工具
• 建议使用 uv 管理 Python 环境（如果需要）

代码质量

• 使用 ruff 进行代码格式化
• 遵循 PEP 8 指南和 Python 最佳实践
• 提交信息需符合 Conventional Commits 规范

项目架构

技术栈

• 前端框架: React 18 + TypeScript
• 构建工具: Vite + SWC
• UI库: Radix UI + Tailwind CSS
• 状态管理: React Context (AuthContext)
• 路由: 自定义基于路径的路由系统
• 图表: Recharts
• 工具库: date-fns, clsx, lucide-react

目录结构

src/
├── components/           # 组件目录
│   ├── ui/              # 基础UI组件 (shadcn/ui)
│   ├── auth/            # 认证相关组件
│   ├── dashboard/       # 各模块主页面组件
│   ├── machinery/       # 农机管理组件
│   ├── field/           # 地块管理组件
│   └── ...              # 其他业务模块组件
├── types/               # TypeScript 类型定义
│   ├── auth.ts          # 认证相关类型
│   ├── navigation.ts    # 导航菜单类型
│   └── ...              # 其他业务类型
├── lib/                 # 工具函数
│   └── authStorage.ts   # 认证存储管理
├── App.tsx              # 主应用组件
├── main.tsx             # 应用入口
└── index.css            # 全局样式

核心架构模式

路由系统

• 基于路径字符串的自定义路由系统
• 使用 activePath 状态管理当前页面
• 路径格式: /module/submodule/page

状态管理

• 认证状态: 通过 AuthContext 管理用户登录状态
• 页面状态: 每个模块组件接收 activePath prop 来渲染对应页面
• 导航状态: 通过 activeTab 和 activePath 管理导航

组件结构

• 模块组件: 每个业务模块有一个主组件，根据 activePath 渲染具体页面
• UI组件: 基于 shadcn/ui 的可复用组件库
• 业务组件: 封装具体业务逻辑的组件

类型系统

• 完整的 TypeScript 类型定义
• 按业务模块组织类型文件
• 严格的类型检查

认证系统

• 基于 JWT token 的认证机制
• 自动 token 刷新机制
• 支持默认管理员账号自动登录 (admin/admin123)
• 认证信息存储在 localStorage

菜单系统

• 层级化菜单结构，支持多级子菜单
• 菜单配置集中定义在 types/navigation.ts
• 动态菜单渲染和权限控制

开发指南

添加新页面

1. 在对应的模块组件中添加路径判断
2. 创建页面组件文件
3. 在 types/navigation.ts 中添加菜单项

添加新模块

1. 创建模块组件目录和文件
2. 在 App.tsx 中添加模块路由
3. 在 types/navigation.ts 中定义菜单结构
4. 添加对应的类型定义

UI组件使用

• 优先使用 src/components/ui/ 中的组件
• 遵循 shadcn/ui 的设计规范
• 使用 Tailwind CSS 进行样式定制

状态管理

• 简单状态使用 React useState
• 复杂状态考虑使用 useReducer 或 Context
• 避免过度抽象

原始设计

项目基于 Figma 设计开发，原始设计文件：https://www.figma.com/design/8DbZHcVGcWEyLOjz1PF57B/智慧农业生产管理系统