庭院健康管家小程序功能需求文档

一、项目概述

1.1 项目背景

面向家庭园艺爱好者及别墅业主，解决庭院养护中环境监测不精准、植物管理混乱、病虫害识别困难等问题。通过物联网+AI技术实现科学养护，降低管理门槛。

1.2 技术架构

1.3 技术栈

模块	技术方案
后端框架	FastAPI + Uvicorn（异步高性能）
数据存储	MySQL（关系数据）+ MongoDB（日志/图片）
文件存储	阿里云OSS
AI服务	PyTorch 1.12 + OpenCV 4.5
任务调度	Celery + Redis
蓝牙通信	Bleak 0.19（跨平台蓝牙库）
PDF生成	ReportLab + WeasyPrint

二、核心功能详细设计

2.1 庭院基础管理

2.1.1 多庭院档案

# 数据库模型示例（SQLAlchemy）
class Garden(Base):
    __tablename__ = 'gardens'
    id = Column(Integer, primary_key=True)
    user_id = Column(String(32))  # 微信OpenID
    name = Column(String(50))
    area = Column(Float)  # 面积(㎡)
    create_time = Column(DateTime)
    layout_img = Column(String(255))  # OSS存储路径

2.1.2 成员共享

实现流程：

生成带时效的邀请码（JWT加密）
微信服务通知推送邀请
被邀请人扫码绑定关系

# 共享关系表
class GardenMember(Base):
    garden_id = Column(Integer)
    member_openid = Column(String(32))
    permission = Column(Enum('view','edit'))  # 权限控制

2.1.3 三维布局标注

技术方案：

前端使用Three.js渲染模型
标注数据存储结构：

{
            
  "garden_id": 1001,
  "zones": [
    {
            
      "id": "zone1",
      "type": "lawn",
      "points": [ [x1,y1], [x2,y2], ... ],
      "plants": ["rose001", "tree045"]
    }
  ]
}

2.2 环境检测功能

2.2.1 土壤检测

设备通信协议处理：

# 蓝牙数据解析示例（模拟XPH-300设备）
async def parse_soil_data(device_address):
    async with BleakClient(device_address) as client:
        # 读取特征值
        data = await client.read_gatt_char(UUID_SOIL_SENSOR)
        return {
            
            "ph": data[0] + data[1]*0.1,
            "nitrogen": data[2],
            "moisture": data[3] 
        }

健康评分算法：

def soil_health_score(params):
    weights = {
            'ph':0.3, 'nitrogen':0.25, 'phosphorus':0.25, 'moisture':0.2}
    score = 0
    # pH值评分曲线
    ph_score = 100 - 20*abs(params['ph'] - 6.5)  
    # 氮含量分段计算
    if params['nitrogen'] > 30:
        n_score = 100
    else:
        n_score = params['nitrogen'] * 3.33
    # 综合加权计算
    return min(100, int(ph_score*weights['ph'] + n_score*weights['nitrogen'] + ...))

2.2.2 水质分析

泳池水标准判断逻辑：

def check_pool_water(quality):
    # 国标GB 37488-2019
    return all([
        6.5 <= quality['ph'] <= 8.5,
        quality['cl_remain'] >= 0.3, 
        quality['turbidity'] <= 1
    ])

2.2.3 光照分析

日照计算实现：

from astral import LocationInfo
from astral.sun import sun

def calculate_sunlight(garden_id):
    garden = get_garden(garden_id)
    loc = LocationInfo(latitude=garden.lat, longitude=garden.lng)
    s = sun(loc.observer, date=datetime.today())
    # 计算有效日照时长（小时）
    return (s['sunset'] - s['sunrise']).seconds / 3600

2.3 植物管理系统

2.3.1 养护提醒引擎

2.4 AI智能识别模块

2.4.1 病虫害识别架构

请求流程：
小程序图片上传 → 阿里云OSS临时存储 → 
触发AI处理任务(Celery) → 
加载PyTorch模型预测 → 
结果存入MongoDB → 
返回诊断报告

2.4.2 锦鲤病症识别模型

# YOLOv8 检测示例
from ultralytics import YOLO

def detect_koi_disease(img_path):
    model = YOLO('models/koi_v8n.pt') 
    results = model.predict(source=img_path)
    # 解析检测结果
    diseases = []
    for box in results[0].boxes:
        cls_id = int(box.cls[0])
        diseases.append({
            
            "name": model.names[cls_id],
            "confidence": float(box.conf[0]),
            "position": box.xyxy[0].tolist()
        })
    return diseases

2.5 报告系统

2.5.1 PDF生成技术

from weasyprint import HTML

def generate_pdf_report(data):
    # 使用Jinja2模板引擎
    html_template = render_template('report.html', data=data)
    # 转换为PDF
    pdf = HTML(string=html_template).write_pdf()
    # 上传OSS
    oss_path = f"reports/{
              uuid4()}.pdf"
    oss_client.put_object(oss_path, pdf)
    return oss_path

三、非功能性需求

3.1 性能指标

场景	要求
图片识别响应	< 3s (90%请求)
蓝牙设备连接	< 5s
高峰期并发	支持1000+ TPS

3.2 安全设计

数据加密：

敏感数据AES-256加密存储
通信使用HTTPS+WSS

权限控制：

# 操作权限装饰器
def garden_permission(required_role):
    def decorator(func):
        @wraps(func)
        async def wrapper(garden_id: int, user: User = Depends(get_current_user)):
            if not check_permission(user, garden_id, required_role):
                raise HTTPException(403, "操作禁止")
            return await func(garden_id, user)
        return wrapper
    return decorator

3.3 兼容性要求

微信版本：支持iOS/Android微信客户端8.0.20+
蓝牙设备：兼容主流土壤检测仪（XPH-300/TP-700系列）

四、部署架构

4.1 云服务配置

服务	规格	数量
应用服务器	4核8G GPU(T4)	2台
MySQL	高可用版 8C32G	主从
Redis	集群版 16G	3节点
对象存储	标准存储	5TB

4.2 监控体系

日志采集：ELK Stack（Elasticsearch+Logstash+Kibana）
性能监控：Prometheus + Grafana
错误追踪：Sentry

五、开发计划

5.1 里程碑

阶段	周期	交付物
核心框架	4周	账户系统+基础管理API
环境监测	6周	设备对接+数据分析服务
AI模块	8周	训练模型+诊断接口
全量测试	3周	测试报告+性能优化