项目分为嵌入式embedded, 前端frontend, 后端backend, 技术文档请参考对应文件夹的README
如果需要修改, 请创建自己的分支并推送, 提交PR等待通过后再合并到master, 请不要直接修改和直接push到master谢谢喵
有问题可以提交issue! 欢迎提各种意见
前端: 前端技术文档
后端: 后端技术文档
- 后端交互式文档: https://lark.mintlab.top/api/docs
- 后端Redoc文档: https://lark.mintlab.top/api/redoc
嵌入式: 嵌入式技术文档
以下是计划书部分, 进展: 校赛报名中...
方向: 物联网应用与物联网创新实践
随着“孤独经济”的兴起与情感陪伴需求的日益增长，鹦鹉以其高互动性、长寿命、色彩艳丽等特性，逐渐成为新兴热门宠物。数据显示，近年来异宠市场规模持续扩大，其中鸟类宠物增速尤为显著。然而，与市场需求快速膨胀形成鲜明对比的是，相关配套产业与服务发展严重滞后，行业痛点突出：
- 交易端：活体来源不透明，健康状况缺乏保障，消费者难以获取可信赖的购买渠道。
- 养护端：养护方式过度依赖经验，缺乏科学、量化的监测手段，导致疾病发现滞后、死亡率偏高。
- 医疗端：异宠医疗资源稀缺，专业兽医数量有限，诊疗困难且成本高昂。
- 体验端：养护过程缺乏数据化、互动化与社交化的现代体验，难以满足年轻一代用户的数字化需求。
与此同时，物联网传感器、嵌入式系统、AI图像识别与云计算技术日趋成熟，已在智能家居、智慧农业等领域实现规模化应用。但在鸟类精细化养护领域，相关技术的渗透率仍较低，尚未形成系统化、标准化的解决方案。因此，将前沿物联网技术引入异宠养护场景，具有重要的现实意义与广阔的市场空间。
本作品“云雀Lark智慧养殖系统”旨在构建一套集智能硬件、云端平台与健康服务于一体的全生命周期管理系统，其意义体现在以下方面：
1. 提升养护效率与成活率 系统通过实时监测温湿度、空气质量、影像等多维数据，结合智能预警与决策支持，帮助养殖者及时发现异常情况，减少因环境不适或疾病延误导致的死亡风险，显著提高养护成功率。
2. 降低人工管理与专业门槛 传统养宠依赖经验判断，新手用户上手难度大。本系统将专业养宠知识转化为可视化数据与自动化控制策略，降低养护门槛，让更多用户能够轻松享受科学养宠的乐趣。
3. 推动行业数字化转型 系统打通从孵化、养殖到消费终端的全链路数据，实现“设备端+服务端+客户端”一体化管理，推动鹦鹉养护从传统的“经验驱动”模式向科学的“数据驱动”模式迈进，为异宠行业数字化升级提供可复用的解决方案。
4. 增强用户互动与情感连接 通过远程视频监看、数据看板、社交分享等功能，增强用户与宠物之间的互动体验，满足现代消费者对情感陪伴与智能化生活的双重需求。
基于上述背景与需求，本作品采用前后端分离的架构，运用Vue.js、FastAPI、ESP-IDF等技术栈，构建了“设备端 + 服务端 + 客户端”三位一体的智慧养护体系：
- 设备端（基于ESP32）：负责采集温湿度、空气质量、图像等多维环境与生物数据。采用基于FreeRTOS的采集-传输多任务调度技术，优化嵌入式端资源利用；通过基于ESP32 FOTA的远程固件更新技术，实现设备的便捷维护与功能升级。
- 服务端（基于FastAPI）：承担数据分析、异常预警、决策支持及设备管理等核心逻辑。采用基于JWT Token的无状态安全登录验证技术，提升系统可扩展性与安全性；通过基于Redis的多进程共享用户状态处理技术，支撑高并发场景下的服务稳定性。
- 客户端（Web网站）：为用户提供直观的可视化数据看板、远程监控及交互控制服务。采用基于WebSocket的视频流传输双工通信技术，实现低延迟远程监看；结合Vue3、TypeScript与ECharts，构建响应式、数据驱动的交互界面。
该体系通过以下关键技术保障系统的安全性与稳定性：
- 基于挑战-应答机制的设备端验证技术，防范非法设备接入与重放攻击，密钥全程不参与网络传输，从根本上杜绝安全漏洞。
- 基于GitHub Action的前后端自动化部署技术，保障快速迭代与持续交付，提升开发运维效率。
1. 完整的云服务落地与安全防护 项目已完成域名注册与工信部、公安部双重备案，并部署于阿里云轻量应用服务器。通过HTTPS与WSS安全协议保障数据传输安全；利用阿里云边缘安全加速（ESA）实现内容分发、访问加速与请求清洗，有效隐藏源站IP并防御DDoS攻击。全站采用同源访问策略，进一步提升安全性。
2. 高效的数据处理与实时通信能力 利用Redis作为中间件存储用户订阅信息，并通过WebSocket高效转发设备端摄像头数据，实现了流畅的远程实时监看。采用SQLite与SQLAlchemy ORM进行本地数据管理，兼顾开发效率与数据安全性。后端采用Gunicorn多进程管理Uvicorn Worker，结合systemd实现开机自启与崩溃自动恢复，确保服务高可用。
3. 完善的系统生态与开发者友好设计 项目不仅实现了完整的功能闭环，还提供了详尽的后端API交互式文档（Swagger UI）与嵌入式开发文档，极大降低了后期拓展与二次开发的门槛。通过FastAPI中间件实现全请求日志记录与全局异常捕获，崩溃时返回唯一追溯码并与后端日志精确关联，实现精准运维定位。
4. 良好的移动端适配与用户体验优化 前端通过User Agent与屏幕宽度双重检测自动识别移动端环境，采用底部导航栏、卡片式布局、品牌色渐变等移动端设计元素，实现跨端一致的使用体验。同时支持触摸操作与平滑滚动，满足移动端用户的交互习惯。
1. 市场需求持续增长 随着居民生活水平提高和家居智能化趋势不断深化，宠物消费结构正从“基础喂养”向“品质养护”升级。异宠爱好者对于智能化、可视化、数据化的养护工具需求日益迫切，智能鱼缸、智能猫砂盆等产品已获得市场验证，智能鸟笼及配套系统同样具备巨大的潜在市场。
2. 应用场景广泛 本系统不仅适用于家庭个人养宠场景，还可拓展至以下领域：
- 宠物繁育基地：实现规模化、标准化的科学养殖管理，降低人工成本，提升幼鸟成活率。
- 异宠医疗机构：辅助兽医进行远程诊断与健康监测，提升诊疗效率。
- 科普教育场所：作为生命科学、生态教育的互动教具，向公众展示智能养殖技术。
- 商业展示空间：应用于宠物店、主题咖啡馆等场所，提升商业空间的科技感与用户体验。
3. 技术成熟与落地可行性 本项目已完成域名备案、服务器部署与自动化运维体系建设，具备完整的端到端落地能力。前后端分离架构、完善的接口文档与嵌入式开发文档，保证了系统的可维护性与可扩展性，具备良好的商业化推广基础。
综上所述，“云雀Lark智慧养殖系统”顺应了智能化、数据化的时代发展趋势，精准切入异宠养护市场的核心痛点，通过扎实的技术架构与创新的产品设计，实现了从设备端到云端再到客户端的全链路智能化管理，具有明确的社会价值、市场前景与推广潜力。
系统整体设计遵循分层、解耦的原则，划分为设备端（嵌入式）、服务端（后端）和客户端（前端）三个层次，各层次技术选型与方案如下。
1. 硬件设备选型 硬件选型以稳定性、成熟度与快速开发为原则，均采用市面主流模块。
- 主控单元：ESP32-WROOM模块，具备240MHz主频双核处理器，集成4MB Flash与4MB PSRAM，可同时满足图像采集与网络传输任务需求。内置Wi-Fi天线与屏蔽罩，射频性能优异且符合电磁兼容标准。
- 图像采集：OV3660摄像头模组，最高支持300万像素，内置硬件JPEG编码，有效降低算力消耗与网络带宽占用。
- 环境感知：
- SHT40工业级温湿度传感器，I2C接口，体积小、精度高、功耗低。
- MQ135空气质量传感器，用于监测氨气等有害气体浓度，提供数字与模拟输出，驱动电路简洁。
2. 软件实现方案
- 开发框架：基于乐鑫官方ESP-IDF v5.5.4开发环境，原生支持FreeRTOS双核实时调度。
- 开发工具：采用Linux环境下的VSCode作为集成开发环境，配合CMake构建系统。
1. 基础设施
- 云服务器：阿里云轻量应用服务器（2核2GB，40GB系统盘），操作系统为Debian Linux，通过SSH/SFTP进行运维管理。
- 网络与安全：
- 采用阿里云边缘安全加速（ESA），实现内容分发、访问加速与请求清洗，有效隐藏源站IP并防御网络层攻击。
- 注册并备案域名
mintlab.top，将系统部署于lark.mintlab.top域名下，前后端同源访问，提升安全性。
2. 软件架构
- 数据库：选用SQLite与SQLAlchemy ORM进行本地数据管理，兼顾开发效率与数据安全性。
- 应用服务：基于Python FastAPI框架，通过Gunicorn进行多进程部署，并接入systemd系统服务管理器，实现开机自启与崩溃自动恢复。
- 中间件：引入Redis作为进程间共享内存，处理用户状态与订阅信息。
- 运维支持：集成Logging模块实现日志分级与按天轮转；借助Swagger UI自动生成标准化接口文档，便于测试与协作。
1. 技术栈与框架
- 核心框架：Vue 3 + TypeScript，采用Composition API提升代码复用性与可维护性。
- 构建工具：Vite，提供极速的开发热更新体验。
- UI组件库：Element Plus及其图标库，实现美观、一致的用户界面。
- 数据可视化：ECharts 6，用于构建丰富的动态数据图表。
- 网络请求：Axios，封装统一的HTTP请求与响应拦截器。
2. 功能模块设计
- 用户认证模块：支持登录、注册、退出、注销及自动登录功能。
- 总览看板：展示在线/离线设备数量、平均环境参数（温度、湿度、空气质量）、错误日志数量及关键指标的ECharts趋势图。
- 数据管理模块：提供设备历史数据查询、实时监控流展示与多维度数据分析。
- 设备与用户管理模块：支持对IoT设备进行增删改查，以及对平台用户的权限管理。
3. 移动端适配
- 设备识别：通过User Agent与屏幕宽度（<768px）双重检测，自动识别移动端环境。
- 交互优化：
- 采用底部导航栏与顶部标签切换的经典移动端布局。
- 用户管理等页面采用卡片式布局替代传统表格，提升触摸操作体验。
- 登录/注册页面采用品牌色渐变背景，增强视觉吸引力。
- 实现页面切换时的平滑滚动，优化浏览连贯性。
- 网络层防护：通过阿里云边缘安全加速（ESA）隐藏源站真实IP，利用其海量带宽与清洗能力吸收网络层DDoS攻击流量，有效保障源站稳定。
- 传输层加密：全站采用HTTPS/WSS协议，结合服务器证书验证，确保数据在传输过程中的机密性与完整性，抵御中间人攻击。
- 无状态身份认证：基于JWT Token实现用户认证。登录成功后，服务端返回Access Token，Refresh Token存储于客户端Cookie中。为每个用户维护独立密钥集，可实现全局强制下线，有效降低服务端压力与开发复杂度。
- 设备接入认证：采用挑战-应答机制对设备进行身份验证。服务端每次下发随机挑战值，设备使用预置密钥计算应答，验证通过后下发访问令牌。该机制中密钥全程不参与网络传输，且应答报文不可复用，从根本上杜绝了非法设备接入与重放攻击。
- 高可用后端服务：采用Gunicorn多进程管理Uvicorn Worker，结合Redis实现进程间数据共享。单进程崩溃不影响整体服务，配合systemd的自动拉起机制，确保后端服务持续可用。
- 精细化日志与运维：通过FastAPI中间件实现全请求日志记录与全局异常捕获。当系统发生崩溃时，向客户端返回唯一追溯码，并与后端日志精确关联，极大提升了问题定位与精准运维的效率。
- 可靠的数据采集与传输：嵌入式端基于FreeRTOS多任务调度，将传感器数据采集、图像抓取、网络传输等任务进行解耦与优先级管理，避免单一任务阻塞导致系统卡死。同时，利用ESP32的FOTA能力，可实现固件的远程、安全升级，为设备长期稳定运行提供保障。
- 2026-03-27 系统：修复椭圆头像显示 bug、完善移动端登录过期退出流程，继续集成与测试主干新功能。
- 2026-03-26 系统：重构 ws 处理逻辑与稳定性修复，改进后端依赖管理问题，完成文档汉化。
- 2026-03-25 嵌入式：完成 OTA/固件管理接口及自动更新脚本，加入固件版本查询、重启控制，并优化 ws 命令处理与连接管理。
- 2026-03-24 后端：实现 ws 连接图像质量与分辨率控制；添加传感器数据统计接口并完善 Stream 模块错误处理；发布后端 v0.5.1。
- 2026-03-23 后端：完成温湿度数据相关功能（含含量统计、历史曲线）和移动端 ws 连接参数适配。
- 2026-03-22 前端：修复实时直播图片超出页面边框的bug；完善移动端登录页面并补充备案号显示。
- 2026-03-21 整体：完成所有测试与文档更新，初始化项目计划书文档（当前分支状态）
- 2026-03-20 后端：完成日志系统配置，修复日志记录语法错误
- 2026-03-19 后端：修复垃圾回收、logout Cookie删除问题，完成日志配置、WebSocket设置及功能测试
- 2026-03-18 后端：重构数据库增加
devices表，实现设备增删改查接口，修复WebSocket连接key错误
嵌入式：完成设备端与后端联调，待机/直播状态响应测试通过 - 2026-03-17 后端：配置环境变量区分测试/生产，部署GitHub Actions自动构建，完成文档本地托管
前端：增加头像URL修改功能，完善注册/修改信息时的提示 - 2026-03-16 前端：优化登录注册界面，完善数据界面显示逻辑
- 2026-03-15 后端：完成用户认证（登录/注册/注销）、Token与Cookie测试，搭建用户与设备数据库
前端：实现登录/注册界面、个人信息管理、注销账号功能 - 2026-03-14 嵌入式：实现WebSocket通信、JSON解析与摄像头图像传输
前端：完成数据界面（实时/历史/大图模式）功能
后端：提供WebSocket接口，支持设备注册与图片数据接收 - 2026-03-13 嵌入式：完成Wi-Fi联网、HTTPS请求封装与NTP时间同步
前端：完善侧边栏、总览界面交互，修复Header样式问题 - 2026-03-12 完成设备端（ESP32）、服务端（FastAPI）、客户端（Web）工程初始化，搭建基础CORS与设备列表接口
- 2026-03-10 完成项目创建与设备初期选型