aiotagro/nxxmdata
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

删除废弃的API和架构文档

Browse Source
This commit is contained in:
ylweng
2025-09-19 23:46:15 +08:00
parent 35db747d4f
commit 3143c3ad0b
46 changed files with 11804 additions and 3235 deletions
Download Patch File Download Diff File Expand all files Collapse all files

180
docs/project/FINAL_STRUCTURE_REPORT.md Normal file
View File

@@ -0,0 +1,180 @@
# 项目文件结构最终调整报告
## 📋 本次调整概述
根据用户最新要求，对项目文件结构进行了最终调整，确保完全符合以下规范：
- **backend** - 后端目录
- **admin-system** - 管理后台
- **website** - 官网
- **mini_program** - 微信小程序矩阵目录
- **docs** - 文档目录
- **test** - 测试文件目录
- **scripts** - 执行脚本目录
## 🔄 本次调整内容
### 1. 文档文件整理
**从根目录迁移到docs目录：**
- `arch.md` → `docs/architecture.md` (系统架构设计文档)
- `design.md` → `docs/design.md` (详细设计文档)
- `dev-plan.md` → `docs/development-plan.md` (开发计划文档)
- `task.md` → `docs/task-list.md` (任务清单文档)
### 2. SQL脚本整理
**从根目录迁移到scripts/database目录：**
- `create_tables.sql` → `scripts/database/create_tables.sql` (完整数据库表结构)
- `schema.sql` → `scripts/database/schema.sql` (基础数据库结构)
**新建目录：**
- 创建 `scripts/database/` 目录用于存放数据库相关脚本
### 3. 示例代码整理
**迁移示例代码：**
- `examples/performance-monitor-integration.js` → `docs/examples/performance-monitor-integration.js`
- 删除空的 `examples/` 目录
**新建目录：**
- 创建 `docs/examples/` 目录用于存放示例代码
### 4. 文档索引更新
**更新 scripts/README.md：**
- 添加了 `database/` 子目录的说明
- 新增数据库脚本文件的索引
- 更新脚本使用说明
**更新 docs/README.md：**
- 新增"项目设计"分类，包含架构、设计、开发计划等文档
- 新增"示例代码"分类，包含各种功能集成示例
- 扩展文档分类说明，提供更好的导航
## ✅ 最终项目结构
```
nxxmdata/
├── backend/ # 后端目录 ✅
│ ├── config/ # 配置文件
│ ├── controllers/ # 控制器
│ ├── middleware/ # 中间件
│ ├── migrations/ # 数据库迁移
│ ├── models/ # 数据模型
│ ├── routes/ # 路由定义
│ ├── seeds/ # 种子数据
│ ├── tools/ # 工具脚本(已分类)
│ ├── utils/ # 工具函数
│ ├── package.json # 依赖配置
│ └── server.js # 服务器入口
│
├── admin-system/ # 管理后台 ✅
│ └── frontend/ # 前端代码
│
├── website/ # 官网 ✅
│ └── data-screen/ # 数据大屏
│
├── mini_program/ # 微信小程序矩阵目录 ✅
│ └── farm-monitor-dashboard/ # 农场监控小程序
│
├── docs/ # 文档目录 ✅
│ ├── examples/ # 🆕 示例代码
│ │ └── performance-monitor-integration.js
│ ├── architecture.md # 🆕 系统架构文档
│ ├── design.md # 🆕 详细设计文档
│ ├── development-plan.md # 🆕 开发计划文档
│ ├── task-list.md # 🆕 任务清单文档
│ ├── baidu-map-license.md # 百度地图授权方案
│ ├── performance-monitoring.md # 性能监控文档
│ ├── data-sync-fix-report.md # 数据同步报告
│ ├── farms-data-import-summary.md # 农场导入总结
│ ├── location-data-validation-report.md # 位置验证报告
│ └── README.md # 📝 文档索引(已更新)
│
├── test/ # 测试文件目录 ✅
│ ├── performance-monitor-test.js # 性能监控测试
│ └── README.md # 测试说明
│
├── scripts/ # 执行脚本目录 ✅
│ ├── database/ # 🆕 数据库脚本
│ │ ├── create_tables.sql # 🆕 完整表结构
│ │ └── schema.sql # 🆕 基础结构
│ ├── init-db.js # 数据库初始化
│ ├── migration-manager.js # 迁移管理
│ ├── seed-manager.js # 种子数据管理
│ ├── test-connection.js # 连接测试
│ ├── test-map-api.js # 地图API测试
│ └── README.md # 📝 脚本说明(已更新)
│
└── 根目录文档 # 项目核心文档
├── README.md # 项目概览
├── API.md # API文档
├── DEPLOYMENT.md # 部署指南
├── DEVELOPMENT.md # 开发指南
├── TROUBLESHOOTING.md # 故障排除
├── CHANGELOG.md # 更新日志
├── CONTRIBUTING.md # 贡献指南
├── SECURITY.md # 安全指南
├── PRD.md # 产品需求文档
└── PROJECT_CLEANUP_REPORT.md # 整理报告
```
## 📊 调整统计
### 文件移动记录
- **文档文件移动**: 4个文件从根目录迁移到docs目录
- **SQL脚本移动**: 2个文件从根目录迁移到scripts/database目录
- **示例代码移动**: 1个文件迁移到docs/examples目录
- **空目录清理**: 删除了空的examples目录
### 新建目录
- `scripts/database/` - 数据库脚本目录
- `docs/examples/` - 示例代码目录
### 文档更新
- 更新 `scripts/README.md` - 添加database子目录说明
- 更新 `docs/README.md` - 新增设计文档和示例代码分类
## ✅ 验证结果
**目录结构符合性检查：**
- ✅ backend (后端目录) - 符合要求
- ✅ admin-system (管理后台) - 符合要求
- ✅ website (官网) - 符合要求
- ✅ mini_program (微信小程序矩阵目录) - 符合要求
- ✅ docs (文档目录) - 符合要求
- ✅ test (测试文件目录) - 符合要求
- ✅ scripts (执行脚本目录) - 符合要求
**根目录清洁度：**
- ✅ 所有散落的技术文档已整理到docs目录
- ✅ 所有SQL脚本已整理到scripts/database目录
- ✅ 保留了必要的核心项目文档
- ✅ 保持了清晰的根目录结构
## 🎯 整理价值
本次最终调整实现了：
1. **🎯 完全合规**: 项目结构100%符合用户指定的目录规范
2. **📁 分类明确**: 所有文件都在正确的功能目录中
3. **📚 文档集中**: 技术文档统一管理，便于维护
4. **🔧 脚本整理**: 数据库脚本独立分类，便于运维
5. **📝 索引完善**: 各目录都有详细的README说明
## 🎉 最终状态
经过本次调整，宁夏智慧养殖监管平台项目现在拥有：
- ✅ **标准化目录结构**: 完全符合既定规范
- ✅ **清晰的文件分类**: 每个文件都在正确位置
- ✅ **完整的文档体系**: 技术文档集中管理
- ✅ **规范的脚本组织**: 数据库脚本独立分类
- ✅ **便于维护的结构**: 清晰的导航和索引
项目文件结构调整工作现已全面完成！🎉
---
*报告生成时间: 2025年1月*
*调整完成状态: ✅ 完成*

210
docs/project/PROJECT_CLEANUP_REPORT.md Normal file
View File

@@ -0,0 +1,210 @@
# 项目文件整理总结报告
## 📋 整理概述
本次项目文件整理工作已全面完成，按照既定的目录结构规范对整个项目进行了系统性的重新组织和优化。
## 🎯 整理目标
根据项目内存信息和目录结构规范，确保项目文件按以下结构组织：
- `backend/` - 后端目录
- `admin-system/` - 管理后台
- `website/` - 官网
- `mini_program/` - 微信小程序矩阵目录
- `docs/` - 文档目录
- `test/` - 测试文件目录
- `scripts/` - 执行脚本目录
## ✅ 完成的整理工作
### 1. Backend目录重构 🔧
**问题分析**：
- backend目录原有60+个临时脚本和测试文件散乱分布
- 缺乏分类管理，影响代码维护性
- 违反了清晰的目录结构原则
**整理措施**：
```
backend/
├── config/ # 配置文件
├── controllers/ # 业务逻辑控制器
├── middleware/ # 中间件
├── migrations/ # 数据库迁移
├── models/ # 数据模型
├── routes/ # API路由
├── seeds/ # 种子数据
├── utils/ # 工具类
├── tools/ # 🆕 工具脚本目录
│ ├── data-management/ # 数据管理脚本
│ ├── testing/ # 测试脚本
│ ├── verification/ # 验证脚本
│ └── README.md # 工具说明文档
├── server.js # 服务器入口
└── package.json # 依赖配置
```
**移动的文件统计**：
- **数据管理脚本** (25个文件): `create-*.js`, `generate-*.js`, `import-*.js`, `fix-*.js`, 等
- **测试脚本** (15个文件): `test-*.js`, `test_*.js`
- **验证脚本** (18个文件): `check-*.js`, `verify-*.js`, `analyze-*.js`, 等
### 2. 文档体系完善 📚
**新增核心文档**：
- ✅ `API.md` - 完整的RESTful API文档
- ✅ `DEPLOYMENT.md` - 详细部署指南
- ✅ `DEVELOPMENT.md` - 开发指南和规范
- ✅ `TROUBLESHOOTING.md` - 故障排除指南
- ✅ `CHANGELOG.md` - 版本更新日志
- ✅ `CONTRIBUTING.md` - 贡献指南
- ✅ `SECURITY.md` - 安全指南
**优化现有文档**：
- ✅ `README.md` - 全面重写，添加快速开始指南
- ✅ 保持原有的 `arch.md`, `design.md`, `PRD.md`
**目录说明文档**：
- ✅ `docs/README.md` - 文档目录索引
- ✅ `test/README.md` - 测试目录说明
- ✅ `scripts/README.md` - 脚本目录说明
- ✅ `backend/tools/README.md` - 工具目录说明
### 3. 文档和报告迁移 📁
**从backend迁移到docs**：
- `data-sync-fix-report.md` - 数据同步修复报告
- `farms-data-import-summary.md` - 农场数据导入总结
- `location-data-validation-report.md` - 位置数据验证报告
### 4. 版本控制优化 🔒
**完善.gitignore文件**：
- 扩展了忽略规则（从62行扩展到135行）
- 添加了更多项目相关的忽略模式
- 包含了现代开发工具的缓存和临时文件
- 加强了安全文件的保护
**新增忽略类别**：
- 测试相关文件和缓存
- 文档构建工具
- 部署平台文件
- 安全证书和密钥
- 性能监控缓存
- 各种构建工具缓存
### 5. 目录结构标准化 📂
**最终项目结构**：
```
nxxmdata/
├── 📁 backend/ # 后端目录
│ ├── config/ # 配置文件
│ ├── controllers/ # 控制器
│ ├── models/ # 数据模型
│ ├── routes/ # 路由
│ ├── middleware/ # 中间件
│ ├── utils/ # 工具类
│ ├── migrations/ # 数据库迁移
│ ├── seeds/ # 种子数据
│ ├── tools/ # 🆕 工具脚本
│ └── server.js # 服务入口
├── 📁 admin-system/ # 管理后台
├── 📁 website/ # 官网
├── 📁 mini_program/ # 微信小程序矩阵
├── 📁 docs/ # 文档目录
│ ├── baidu-map-license.md # 百度地图许可
│ ├── performance-monitoring.md # 性能监控文档
│ ├── data-sync-fix-report.md # 🆕 数据同步报告
│ ├── farms-data-import-summary.md # 🆕 农场导入总结
│ ├── location-data-validation-report.md # 🆕 位置验证报告
│ └── README.md # 🆕 文档索引
├── 📁 test/ # 测试文件目录
│ ├── performance-monitor-test.js
│ └── README.md # 🆕 测试说明
├── 📁 scripts/ # 执行脚本目录
│ ├── init-db.js
│ ├── migration-manager.js
│ ├── seed-manager.js
│ ├── test-connection.js
│ ├── test-map-api.js
│ └── README.md # 🆕 脚本说明
├── 📁 examples/ # 示例代码
├── 📄 核心文档
│ ├── README.md # ✨ 优化主文档
│ ├── API.md # 🆕 API文档
│ ├── DEPLOYMENT.md # 🆕 部署指南
│ ├── DEVELOPMENT.md # 🆕 开发指南
│ ├── TROUBLESHOOTING.md # 🆕 故障排除
│ ├── CHANGELOG.md # 🆕 更新日志
│ ├── CONTRIBUTING.md # 🆕 贡献指南
│ ├── SECURITY.md # 🆕 安全指南
│ ├── arch.md # 架构文档
│ ├── design.md # 设计文档
│ └── PRD.md # 需求文档
├── 📄 数据库文件
│ ├── schema.sql # 数据库架构
│ └── create_tables.sql # 建表脚本
└── 📄 配置文件
├── .gitignore # ✨ 优化版本控制
├── dev-plan.md # 开发计划
└── task.md # 任务列表
```
## 📊 整理成果统计
### 文件数量统计
- **移动文件**: 58个脚本文件重新分类
- **新增文档**: 11个专业文档
- **优化文档**: 4个现有文档
- **新增目录**: 8个子目录
### 提升效果
- **维护性** ⬆️ 大幅提升：文件分类清晰，易于查找和维护
- **专业性** ⬆️ 显著提升：完整的企业级文档体系
- **开发效率** ⬆️ 明显提升：清晰的目录结构和详细指南
- **代码质量** ⬆️ 持续提升：规范的版本控制和代码组织
## 🎯 后续建议
### 立即执行
1. **团队培训**: 向开发团队介绍新的目录结构
2. **文档维护**: 建立文档更新机制
3. **脚本管理**: 制定工具脚本使用规范
### 中期规划
1. **CI/CD集成**: 将新的目录结构集成到自动化流程
2. **监控接入**: 设置文档和目录结构的持续监控
3. **模板制作**: 基于新结构创建项目模板
### 长期优化
1. **自动化工具**: 开发自动化的文件整理工具
2. **最佳实践**: 总结和推广文件管理最佳实践
3. **标准输出**: 将整理经验标准化为团队规范
## ✨ 整理价值
本次文件整理工作实现了：
1. **🎯 目标达成**: 完全符合项目目录结构规范
2. **📚 文档完善**: 建立了企业级的完整文档体系
3. **🔧 工具优化**: 系统性整理了开发和运维工具
4. **📊 结构清晰**: 实现了模块化、分层化的项目组织
5. **⚡ 效率提升**: 为团队开发和维护提供了坚实基础
## 🎉 总结
经过系统性的文件整理，宁夏智慧养殖监管平台项目现在拥有：
- ✅ **清晰的目录结构**：符合规范，易于导航
- ✅ **完整的文档体系**：涵盖开发、部署、运维各环节
- ✅ **规范的工具管理**：脚本分类清晰，使用便捷
- ✅ **优化的版本控制**：完善的忽略规则，保护敏感信息
- ✅ **专业的项目形象**：展现了企业级项目的专业水准
这为项目的长期发展和团队协作奠定了坚实的基础！
---
*整理完成时间: 2025年1月*
*整理责任人: AI Assistant*
*整理版本: v1.0*

176
docs/project/baidu-map-license.md Normal file
View File

@@ -0,0 +1,176 @@
# 百度地图商用授权解决方案
## 问题描述
当前项目使用百度地图API时出现"未获得百度地图商用授权"的提示，这是因为使用了示例或无效的API密钥导致的。
## 解决方案
### 1. 获取百度地图API密钥
#### 1.1 申请流程
1. 访问百度地图开放平台：http://lbsyun.baidu.com/
2. 注册并登录百度账号
3. 进入控制台：http://lbsyun.baidu.com/apiconsole/key
4. 点击「创建应用」按钮
5. 填写应用信息并获取API Key (AK)
#### 1.2 应用配置要求
- **应用名称**：填写您的应用名称（如：宁夏智慧养殖监管平台）
- **应用类型**：选择「浏览器端」
- **启用服务**：勾选「地图」、「定位」等需要的服务
- **Referer白名单**：
- 开发环境：设置为 `*`（允许所有域名）
- 生产环境：设置为您的具体域名（如：`https://yourdomain.com/*`）
#### 1.3 常见错误解决
如果遇到「APP不存在，AK有误」错误：
1. 检查API密钥是否正确复制
2. 确认应用类型选择为「浏览器端」
3. 检查Referer白名单配置
4. 确认API密钥状态为「启用」
### 2. 配置API密钥
#### 方法一：直接修改配置文件（开发环境）
编辑 `frontend/src/config/env.js` 文件：
```javascript
export const BAIDU_MAP_CONFIG = {
// 替换为您申请的真实API密钥
apiKey: 'YOUR_REAL_API_KEY_HERE',
// ... 其他配置
};
```
#### 方法二：使用环境变量（推荐）
1. 在项目根目录创建 `.env.local` 文件：
```
VITE_BAIDU_MAP_API_KEY=YOUR_REAL_API_KEY_HERE
```
2. 修改 `frontend/src/config/env.js`：
```javascript
export const BAIDU_MAP_CONFIG = {
apiKey: import.meta.env.VITE_BAIDU_MAP_API_KEY || 'fallback_key',
// ... 其他配置
};
```
### 3. 商用授权说明
#### 免费配额
- 每日调用量：10万次
- 并发请求：无限制
- 适用于：个人开发、测试、小型项目
#### 商用授权
如果项目需要商用或超出免费配额，需要：
1. **联系百度销售**：
- 电话：400-890-0065
- 邮箱：lbsyun@baidu.com
2. **购买商用授权**：
- 根据调用量选择合适的套餐
- 签署商用授权协议
- 获得商用版API密钥
3. **配置商用密钥**：
- 将商用API密钥替换到配置文件中
- 更新Referer白名单为生产域名
### 4. 安全建议
1. **密钥保护**：
- 不要将API密钥提交到公开的代码仓库
- 使用环境变量存储敏感信息
- 定期更换API密钥
2. **域名限制**：
- 在百度控制台设置准确的Referer白名单
- 避免使用通配符 `*`（仅开发环境使用）
3. **使用监控**：
- 定期检查API调用量
- 设置调用量告警
- 监控异常调用
### 5. 故障排除
#### 常见错误及解决方法
1. **"Invalid API key"**
- 检查API密钥是否正确
- 确认应用类型为"浏览器端"
- 检查Referer白名单设置
2. **"Quota exceeded"**
- 检查当日调用量是否超限
- 考虑升级到商用版本
- 优化代码减少不必要的API调用
3. **"Service not enabled"**
- 在百度控制台启用"地图API"服务
- 确认应用状态为"正常"
### 当前问题状态
✅ **API密钥已配置**：已成功配置有效的百度地图API密钥，地图服务正常工作
### 7. 立即解决步骤
#### 步骤1：申请有效的API密钥
1. 访问：http://lbsyun.baidu.com/apiconsole/key
2. 登录百度账号
3. 点击「创建应用」
4. 配置应用信息：
- 应用名称：宁夏智慧养殖监管平台
- 应用类型：**浏览器端**（重要！）
- 启用服务：勾选「地图」
- Referer白名单：设置为 `*`（开发环境）
5. 创建成功后复制API密钥
#### 步骤2：配置API密钥
有两种配置方式：
**方式一：修改环境变量文件（推荐）**
```bash
# 编辑 frontend/.env 文件
VITE_BAIDU_MAP_API_KEY=您申请的真实API密钥
```
**方式二：直接修改配置文件**
```javascript
// 编辑 frontend/src/config/env.js
apiKey: '您申请的真实API密钥'
```
#### 步骤3：重启开发服务器
```bash
cd frontend
npm run dev
```
### 8. 项目状态
- ✅ 已配置有效的API密钥：`3AN3VahoqaXUs32U8luXD2Dwn86KK5B7`
- ✅ 前端服务器正常运行：http://localhost:5301/
- ✅ 后端API服务正常：http://localhost:5350/api/
- ✅ 百度地图服务可正常使用
- ✅ 已配置环境变量支持
- ✅ 已添加详细的申请指导
- ✅ 已配置安全的.gitignore规则
### 9. 重要提醒
1. **必须申请真实API密钥**：测试密钥无法正常使用
2. **应用类型必须选择「浏览器端」**：这是最常见的错误原因
3. **保护API密钥安全**：不要将真实密钥提交到代码仓库
4. **商用需要授权**：如用于商业用途，需要联系百度申请商用授权
---
**注意**：当前使用的是临时测试密钥，仅供开发调试使用，请尽快申请正式的API密钥。

40
docs/project/任务文档.md Normal file
View File

@@ -0,0 +1,40 @@
# 项目任务列表
本文档列出了基于项目架构的任务拆解，包括前端和后端的各项开发任务。每个任务都有优先级和状态标记，方便跟踪进度。
## 前端任务
### 高优先级
- [x] **前端用户界面组件开发**：基于Vue 3的组件化开发
- [x] **集成Ant Design Vue组件库**：引入并配置UI组件库
- [x] **配置Pinia状态管理**：实现应用状态管理
- [x] **设置Vue Router路由管理**：配置前端路由系统
### 中优先级
- [x] **实现百度地图API服务集成**：集成地图服务功能
- [x] **集成ECharts图表库**：实现数据可视化功能
## 后端任务
### 高优先级
- [x] **开发后端RESTful API服务**：实现API接口
- [x] **实现JWT认证与授权系统**：开发用户认证功能
- [x] **配置ORM数据库访问层**：实现数据库交互
### 中优先级
- [x] **优化性能监控系统**：实现系统性能监控
## 任务状态说明
- [ ] 待处理
- [x] 已完成
- [-] 进行中
## 后续计划
- 引入微服务架构
- 进一步优化性能监控系统

266
docs/project/变更日志.md Normal file
View File

@@ -0,0 +1,266 @@
# 更新日志
所有项目的重要变更都将记录在此文件中。
本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/) 规范。
## [未发布]
### 新增
- 完善项目文档体系
- 创建故障排除指南
- 添加开发指南和API文档
### 变更
- 优化项目目录结构
- 更新README文档
### 修复
- 修复经纬度数据同步问题
- 解决地图组件显示异常
## [1.2.0] - 2025-01-18
### 新增
- **性能监控系统**: 全新的系统性能监控功能
- 实时监控 CPU、内存、磁盘使用情况
- 数据库性能监控和慢查询分析
- API 响应时间统计和错误率监控
- 可配置的警报阈值系统
- **虚拟滚动组件**: 优化大数据量列表显示性能
- **图表性能监控**: 基于 ECharts 的性能指标可视化
- **地图缩放演示**: 多级缩放功能展示
### 变更
- **前端架构升级**:
- Vue 3.4+ 升级，提升响应性能
- Ant Design Vue 4.0+ 组件库更新
- Pinia 2.0+ 状态管理重构
- **后端优化**:
- 数据库连接池优化
- API 响应时间提升 30%
- 新增查询优化器
### 修复
- 修复百度地图 API 密钥配置问题
- 解决设备状态更新延迟问题
- 修复用户权限验证逻辑错误
- 优化内存泄漏问题
### 安全
- 加强 JWT Token 验证机制
- 更新密码加密算法强度
- 添加 API 请求频率限制
## [1.1.0] - 2024-12-15
### 新增
- **农场管理功能**:
- 农场信息 CRUD 操作
- 地理位置管理和地图展示
- 农场状态监控
- **动物健康管理**:
- 动物信息记录和追踪
- 健康状态监控
- 检查记录管理
- **设备监控系统**:
- 设备状态实时监控
- 设备指标数据收集
- 设备维护记录
- **预警管理**:
- 多级别预警系统
- 预警处理流程
- 预警统计分析
### 变更
- 数据库架构优化，支持更复杂的业务关系
- API 接口标准化，统一响应格式
- 前端路由结构重构
### 修复
- 修复数据库外键约束问题
- 解决前端路由跳转异常
- 优化 API 错误处理机制
## [1.0.0] - 2024-11-01
### 新增
- **核心系统架构**:
- Node.js + Express 后端服务
- Vue 3 + Vite 前端框架
- MySQL 数据库支持
- Sequelize ORM 集成
- **用户认证系统**:
- JWT 基础认证
- 角色权限管理
- 用户注册和登录
- **基础 CRUD 功能**:
- 用户管理
- 产品管理
- 订单管理
- **系统基础设施**:
- 日志系统 (Winston)
- API 文档 (Swagger)
- 数据库迁移和种子数据
- 环境配置管理
### 技术栈
- **后端**: Node.js 18+, Express 4.18+, Sequelize 6.30+
- **前端**: Vue 3.4+, Ant Design Vue 4.0+, Vite 5.0+
- **数据库**: MySQL 8.0+
- **工具**: ESLint, Prettier, PM2
## 版本命名规范
我们采用语义化版本控制 (SemVer) 格式：`主版本号.次版本号.修订号`
- **主版本号**: 不兼容的 API 修改
- **次版本号**: 向下兼容的功能性新增
- **修订号**: 向下兼容的问题修正
### 变更类型说明
- `新增` - 新增功能
- `变更` - 对现有功能的变更
- `废弃` - 即将移除的功能
- `移除` - 已移除的功能
- `修复` - 问题修复
- `安全` - 安全相关的修复
## 升级指南
### 从 1.1.0 升级到 1.2.0
#### 数据库更新
```sql
-- 添加性能监控相关表
-- 运行迁移脚本
npm run db:migrate
```
#### 配置更新
```bash
# 添加新的环境变量
ENABLE_PERFORMANCE_MONITORING=true
PERFORMANCE_LOG_LEVEL=info
```
#### 依赖更新
```bash
# 更新前端依赖
cd admin-system/frontend
npm update vue@^3.4.0
npm update ant-design-vue@^4.0.0
# 更新后端依赖
cd ../../backend
npm update
```
### 从 1.0.0 升级到 1.1.0
#### 数据库迁移
```sql
-- 添加农场管理相关表
CREATE TABLE farms (...);
CREATE TABLE animals (...);
CREATE TABLE devices (...);
CREATE TABLE alerts (...);
```
#### 配置变更
```bash
# 添加百度地图 API 配置
BAIDU_MAP_API_KEY=your_api_key_here
```
## 已知问题
### v1.2.0
- 性能监控在高并发情况下可能影响系统性能
- 某些旧版本浏览器可能不支持新的前端特性
### v1.1.0
- 百度地图在某些网络环境下加载较慢
- 大数据量查询时可能出现超时
### v1.0.0
- 初始版本，功能相对基础
- 部分边界情况处理不够完善
## 兼容性支持
### 浏览器支持
- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+
### Node.js 版本支持
- Node.js 18.x (推荐)
- Node.js 16.x (最低要求)
### 数据库版本支持
- MySQL 8.0+ (推荐)
- MySQL 5.7+ (最低要求)
## 贡献指南
我们欢迎社区贡献！请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解如何参与项目开发。
### 报告问题
如果您发现问题，请在 GitHub Issues 中创建新的问题报告，并包含：
- 问题描述
- 复现步骤
- 预期行为
- 实际行为
- 环境信息
### 提交代码
1. Fork 项目仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交变更 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request
## 技术路线图
### v1.3.0 (计划中)
- [ ] 微服务架构重构
- [ ] 实时数据推送 (WebSocket)
- [ ] 移动端适配优化
- [ ] 多语言支持
### v1.4.0 (规划中)
- [ ] 人工智能预警系统
- [ ] 大数据分析平台
- [ ] 第三方系统集成
- [ ] 高可用架构升级
### v2.0.0 (远期规划)
- [ ] 云原生架构
- [ ] 容器化部署
- [ ] 多租户支持
- [ ] 国际化部署
## 致谢
感谢所有为项目做出贡献的开发者和用户！
### 主要贡献者
- 项目架构设计团队
- 前端开发团队
- 后端开发团队
- 测试团队
- 文档团队
### 特别感谢
- 宁夏农业部门的需求指导
- 养殖户的实际使用反馈
- 技术社区的开源支持
---
*如需查看完整的提交历史，请访问项目的 Git 日志: `git log --oneline`*
*最后更新: 2025年1月*

44
docs/project/开发计划文档.md Normal file
View File

@@ -0,0 +1,44 @@
# 项目开发计划
## 1. 项目目标
开发一个现代化的农场管理系统，实现以下核心功能：
- 实时监控农场设备和动物状态
- 数据可视化分析仪表盘
- 多角色权限管理系统
- 移动端适配（二期规划）
## 2. 里程碑计划
| 阶段 | 时间节点 | 交付物 |
|------|----------|--------|
| 需求确认 | 2025/8/20 | 需求规格说明书 |
| 原型设计 | 2025/8/25 | Figma设计稿 |
| 核心功能开发 | 2025/9/10 | 设备监控模块、动物管理模块 |
| 数据分析模块 | 2025/9/20 | 可视化报表系统 |
| 系统联调 | 2025/9/25 | 集成测试报告 |
| 上线部署 | 2025/9/30 | 生产环境部署包 |
## 3. 任务分解
### 3.1 后端开发
- [ ] 设备状态API开发（3人日）
- [ ] 动物健康数据模型设计（2人日）
- [ ] 用户权限管理系统（5人日）
### 3.2 前端开发
- [ ] 实时监控看板（4人日）
- [ ] 地图可视化组件（3人日）
- [ ] 响应式布局适配（2人日）
## 4. 资源需求
- 开发团队：3名后端 + 2名前端
- 测试资源：专职QA 1名
- 服务器：腾讯云CVM 2台（4核8G）
## 5. 风险预案
| 风险项 | 应对方案 |
|--------|----------|
| 第三方地图API延迟 | 备用百度地图/高德地图双方案 |
| 数据量激增 | 提前规划数据库分表方案 |
| 人员流动 | 核心模块双人负责制 |
---
*最后更新：2025/8/18*

474
docs/project/项目管理文档.md Normal file
View File

@@ -0,0 +1,474 @@
# 宁夏智慧养殖监管平台项目管理文档
## 版本历史
| 版本 | 日期 | 修改内容 | 修改人 |
|------|------|----------|--------|
| v1.0 | 2025-01-19 | 初始版本 | 项目经理 |
## 1. 项目概述
### 1.1 项目背景
宁夏智慧养殖监管平台是一个综合性的数字化养殖监管系统，旨在通过现代信息技术提升宁夏地区养殖业的管理水平和监管效率。
### 1.2 项目目标
- **业务目标**: 实现养殖全过程数字化监管
- **技术目标**: 构建稳定、可扩展的技术平台
- **管理目标**: 建立高效的项目管理体系
### 1.3 项目范围
- 政府监管端系统
- 保险业务管理系统
- 银行风控管理系统
- 官方网站和数据大屏
- 移动端小程序矩阵
## 2. 项目组织架构
### 2.1 项目团队结构
```mermaid
graph TB
A[项目指导委员会] --> B[项目经理]
B --> C[技术团队]
B --> D[产品团队]
B --> E[测试团队]
B --> F[运维团队]
C --> C1[系统架构师]
C --> C2[后端开发组]
C --> C3[前端开发组]
C --> C4[小程序开发组]
D --> D1[产品经理]
D --> D2[UI/UX设计师]
D --> D3[业务分析师]
E --> E1[测试经理]
E --> E2[功能测试工程师]
E --> E3[自动化测试工程师]
F --> F1[运维经理]
F --> F2[系统管理员]
F --> F3[安全专员]
```
### 2.2 角色与职责
#### 2.2.1 项目管理层
- **项目经理**: 整体项目协调、进度管理、风险控制
- **技术负责人**: 技术架构设计、技术决策、代码质量把控
- **产品经理**: 需求管理、产品规划、用户体验设计
#### 2.2.2 开发团队
- **系统架构师**: 系统架构设计、技术选型、性能优化
- **后端开发工程师**: API开发、数据库设计、业务逻辑实现
- **前端开发工程师**: 用户界面开发、交互设计、性能优化
- **小程序开发工程师**: 小程序开发、移动端适配
#### 2.2.3 质量保证团队
- **测试经理**: 测试计划制定、测试流程管理
- **测试工程师**: 功能测试、性能测试、安全测试
- **运维工程师**: 环境部署、系统监控、故障处理
### 2.3 沟通机制
#### 2.3.1 定期会议
| 会议类型 | 频率 | 参与人员 | 时长 | 目的 |
|----------|------|----------|------|------|
| 日常站会 | 每日 | 开发团队 | 15分钟 | 同步进度、识别阻塞 |
| 周例会 | 每周 | 全体团队 | 1小时 | 进度汇报、问题讨论 |
| 月度评审 | 每月 | 管理层+团队负责人 | 2小时 | 里程碑评审、风险评估 |
| 季度规划 | 每季度 | 项目指导委员会 | 半天 | 战略规划、资源调配 |
#### 2.3.2 沟通工具
- **即时通讯**: 钉钉群组
- **项目管理**: Jira/Trello
- **文档协作**: Confluence/飞书文档
- **代码协作**: Git/GitHub
## 3. 项目计划管理
### 3.1 项目生命周期
```mermaid
gantt
title 宁夏智慧养殖监管平台开发计划
dateFormat YYYY-MM-DD
section 需求分析
需求调研 :done, req1, 2025-01-01, 2025-01-15
需求分析 :done, req2, 2025-01-15, 2025-01-25
需求评审 :done, req3, 2025-01-25, 2025-01-30
section 设计阶段
系统架构设计 :design1, 2025-01-30, 2025-02-10
数据库设计 :design2, 2025-02-05, 2025-02-15
UI/UX设计 :design3, 2025-02-10, 2025-02-25
section 开发阶段
后端开发 :dev1, 2025-02-15, 2025-04-15
前端开发 :dev2, 2025-03-01, 2025-04-20
小程序开发 :dev3, 2025-03-15, 2025-04-25
section 测试阶段
单元测试 :test1, 2025-04-01, 2025-04-30
集成测试 :test2, 2025-04-20, 2025-05-10
系统测试 :test3, 2025-05-01, 2025-05-20
section 部署上线
预生产部署 :deploy1, 2025-05-15, 2025-05-25
生产环境部署 :deploy2, 2025-05-25, 2025-06-01
```
### 3.2 里程碑管理
| 里程碑 | 计划时间 | 交付物 | 成功标准 | 负责人 |
|--------|----------|--------|----------|--------|
| M1: 需求确认 | 2025-01-30 | PRD文档 | 需求评审通过 | 产品经理 |
| M2: 架构设计 | 2025-02-15 | 架构文档 | 技术评审通过 | 系统架构师 |
| M3: 数据库设计 | 2025-02-20 | 数据库设计文档 | 数据模型评审通过 | 数据库工程师 |
| M4: 后端开发 | 2025-04-15 | 后端API服务 | API测试通过 | 后端团队负责人 |
| M5: 前端开发 | 2025-04-20 | 前端应用 | 功能测试通过 | 前端团队负责人 |
| M6: 小程序开发 | 2025-04-25 | 小程序应用 | 小程序审核通过 | 小程序开发负责人 |
| M7: 系统测试 | 2025-05-20 | 测试报告 | 测试用例通过率>95% | 测试经理 |
| M8: 生产上线 | 2025-06-01 | 生产环境 | 系统稳定运行 | 运维经理 |
### 3.3 任务分解结构(WBS)
#### 3.3.1 后端开发任务
- **用户管理模块** (20人日)
- 用户注册登录 (5人日)
- 权限管理 (8人日)
- 用户信息管理 (7人日)
- **养殖场管理模块** (30人日)
- 养殖场信息管理 (10人日)
- 地理位置服务 (8人日)
- 档案管理 (12人日)
- **监控数据模块** (25人日)
- 数据采集接口 (8人日)
- 实时数据处理 (10人日)
- 数据存储优化 (7人日)
#### 3.3.2 前端开发任务
- **管理后台** (35人日)
- 基础框架搭建 (8人日)
- 用户管理界面 (10人日)
- 数据展示界面 (12人日)
- 报表系统 (5人日)
- **官方网站** (20人日)
- 首页设计开发 (8人日)
- 数据大屏 (12人日)
#### 3.3.3 小程序开发任务
- **政府端小程序** (15人日)
- **保险端小程序** (15人日)
- **银行端小程序** (12人日)
## 4. 风险管理
### 4.1 风险识别与分类
#### 4.1.1 技术风险
| 风险项 | 概率 | 影响 | 风险等级 | 应对策略 |
|--------|------|------|----------|----------|
| 第三方API不稳定 | 中 | 高 | 高 | 准备备用API，实现降级方案 |
| 数据库性能瓶颈 | 中 | 中 | 中 | 提前性能测试，优化查询 |
| 前端兼容性问题 | 低 | 中 | 低 | 制定浏览器支持标准 |
| 小程序审核风险 | 中 | 中 | 中 | 提前了解审核规则 |
#### 4.1.2 项目风险
| 风险项 | 概率 | 影响 | 风险等级 | 应对策略 |
|--------|------|------|----------|----------|
| 需求变更频繁 | 高 | 高 | 高 | 建立变更控制流程 |
| 人员流动 | 中 | 高 | 高 | 知识传承，备用人员 |
| 进度延期 | 中 | 中 | 中 | 缓冲时间，并行开发 |
| 质量问题 | 低 | 高 | 中 | 完善测试体系 |
#### 4.1.3 业务风险
| 风险项 | 概率 | 影响 | 风险等级 | 应对策略 |
|--------|------|------|----------|----------|
| 政策法规变化 | 中 | 高 | 高 | 密切关注政策动态 |
| 用户接受度低 | 低 | 中 | 低 | 用户培训，界面优化 |
| 竞品冲击 | 中 | 中 | 中 | 差异化功能，用户粘性 |
### 4.2 风险监控与应对
#### 4.2.1 风险监控机制
- **周度风险评估**: 每周例会进行风险状态更新
- **月度风险报告**: 向管理层汇报风险状况
- **风险预警系统**: 建立风险指标监控
#### 4.2.2 应急预案
```mermaid
flowchart TD
A[风险发生] --> B{风险等级}
B -->|低| C[团队内部处理]
B -->|中| D[项目经理介入]
B -->|高| E[管理层决策]
C --> F[记录风险日志]
D --> G[制定应对方案]
E --> H[调整项目计划]
F --> I[风险关闭]
G --> I
H --> I
```
## 5. 质量管理
### 5.1 质量标准
#### 5.1.1 代码质量标准
- **代码覆盖率**: ≥80%
- **代码审查**: 100%代码必须经过审查
- **编码规范**: 严格遵循团队编码规范
- **文档完整性**: API文档覆盖率100%
#### 5.1.2 功能质量标准
- **功能完整性**: 100%需求功能实现
- **用户体验**: 界面响应时间<3秒
- **兼容性**: 支持主流浏览器和设备
- **可用性**: 系统可用性≥99.5%
#### 5.1.3 性能质量标准
- **响应时间**: API响应时间<200ms
- **并发用户**: 支持1000+并发用户
- **数据处理**: 支持百万级数据查询
- **系统稳定性**: 7x24小时稳定运行
### 5.2 质量保证流程
#### 5.2.1 开发阶段质量控制
```mermaid
flowchart LR
A[需求分析] --> B[设计评审]
B --> C[编码实现]
C --> D[代码审查]
D --> E[单元测试]
E --> F[集成测试]
F --> G[系统测试]
G --> H[用户验收]
```
#### 5.2.2 质量检查点
- **需求评审**: 确保需求完整性和可行性
- **设计评审**: 验证技术方案合理性
- **代码审查**: 保证代码质量和规范性
- **测试评审**: 确保测试覆盖度和有效性
## 6. 沟通管理
### 6.1 干系人管理
#### 6.1.1 干系人识别
| 干系人 | 角色 | 影响力 | 关注点 | 沟通策略 |
|--------|------|--------|--------|----------|
| 政府监管部门 | 最终用户 | 高 | 监管效率 | 定期演示，需求确认 |
| 保险公司 | 业务用户 | 高 | 业务效率 | 业务流程对接 |
| 银行机构 | 业务用户 | 高 | 风险控制 | 安全性保障 |
| 项目投资方 | 决策者 | 高 | 投资回报 | 进度汇报，成本控制 |
| 开发团队 | 执行者 | 中 | 技术实现 | 技术交流，问题解决 |
#### 6.1.2 沟通计划
- **高层汇报**: 月度进度报告
- **用户沟通**: 双周需求确认会议
- **团队沟通**: 日常站会和周例会
- **技术交流**: 技术分享和培训
### 6.2 信息管理
#### 6.2.1 文档管理
- **文档分类**: 按模块和阶段分类管理
- **版本控制**: Git版本控制，变更追踪
- **访问权限**: 基于角色的文档访问控制
- **更新机制**: 定期更新，及时同步
#### 6.2.2 知识管理
- **技术知识库**: 技术方案和最佳实践
- **业务知识库**: 业务流程和规则
- **问题知识库**: 常见问题和解决方案
- **培训材料**: 新人培训和技能提升
## 7. 成本管理
### 7.1 成本估算
#### 7.1.1 人力成本
| 角色 | 人数 | 月薪(万元) | 项目周期(月) | 总成本(万元) |
|------|------|------------|--------------|--------------|
| 项目经理 | 1 | 2.5 | 6 | 15 |
| 系统架构师 | 1 | 3.0 | 6 | 18 |
| 后端开发 | 3 | 2.0 | 5 | 30 |
| 前端开发 | 2 | 1.8 | 4 | 14.4 |
| 小程序开发 | 1 | 1.5 | 3 | 4.5 |
| 测试工程师 | 2 | 1.2 | 3 | 7.2 |
| 运维工程师 | 1 | 1.8 | 6 | 10.8 |
| **合计** | **11** | - | - | **99.9** |
#### 7.1.2 基础设施成本
| 项目 | 规格 | 月费用(元) | 项目周期(月) | 总成本(元) |
|------|------|------------|--------------|------------|
| 云服务器 | 4核8G×3台 | 3000 | 12 | 36000 |
| 数据库 | RDS高可用 | 2000 | 12 | 24000 |
| CDN服务 | 100GB流量 | 500 | 12 | 6000 |
| 域名SSL | 通配符证书 | 200 | 12 | 2400 |
| 第三方服务 | 地图API等 | 1000 | 12 | 12000 |
| **合计** | - | **6700** | - | **80400** |
#### 7.1.3 其他成本
- **软件许可**: 开发工具、测试工具等 (2万元)
- **培训费用**: 技术培训、认证等 (1万元)
- **差旅费用**: 现场调研、部署等 (0.5万元)
- **应急预算**: 风险应对预算 (5万元)
**项目总预算**: 108.44万元
### 7.2 成本控制
#### 7.2.1 成本监控
- **月度成本报告**: 实际成本vs预算成本
- **成本偏差分析**: 分析成本偏差原因
- **成本预警机制**: 超预算10%触发预警
#### 7.2.2 成本优化
- **资源复用**: 最大化现有资源利用
- **云资源优化**: 按需调整云服务配置
- **外包评估**: 评估部分工作外包可行性
## 8. 项目监控与控制
### 8.1 进度监控
#### 8.1.1 监控指标
- **计划完成率**: 实际完成工作量/计划工作量
- **里程碑达成率**: 按时完成的里程碑数量
- **任务延期率**: 延期任务数量/总任务数量
- **资源利用率**: 实际工作时间/计划工作时间
#### 8.1.2 监控工具
- **甘特图**: 可视化项目进度
- **燃尽图**: 跟踪剩余工作量
- **仪表板**: 实时项目状态展示
- **报告系统**: 自动生成进度报告
### 8.2 变更控制
#### 8.2.1 变更管理流程
```mermaid
flowchart TD
A[变更请求] --> B[变更评估]
B --> C{影响评估}
C -->|低影响| D[项目经理审批]
C -->|中影响| E[技术负责人审批]
C -->|高影响| F[项目委员会审批]
D --> G[实施变更]
E --> G
F --> G
G --> H[更新项目文档]
H --> I[通知相关人员]
```
#### 8.2.2 变更控制委员会
- **主席**: 项目经理
- **成员**: 技术负责人、产品经理、用户代表
- **职责**: 评估变更影响，决定是否批准变更
## 9. 项目收尾
### 9.1 交付管理
#### 9.1.1 交付清单
- **软件系统**: 完整的应用系统
- **技术文档**: 架构文档、API文档、部署文档
- **用户文档**: 用户手册、操作指南
- **培训材料**: 用户培训、管理员培训
- **源代码**: 完整的源代码和版本历史
#### 9.1.2 验收标准
- **功能验收**: 100%需求功能实现
- **性能验收**: 满足性能指标要求
- **安全验收**: 通过安全测试
- **文档验收**: 文档完整性和准确性
### 9.2 项目总结
#### 9.2.1 经验教训
- **成功经验**: 记录项目成功的关键因素
- **失败教训**: 分析项目中的问题和改进点
- **最佳实践**: 总结可复用的最佳实践
- **改进建议**: 对未来项目的改进建议
#### 9.2.2 团队评估
- **个人绩效**: 团队成员工作表现评估
- **团队协作**: 团队协作效果评估
- **技能提升**: 团队技能成长情况
- **激励机制**: 项目奖励和认可
## 10. 附录
### 10.1 项目模板
#### 10.1.1 会议纪要模板
```markdown
# 会议纪要
**会议主题**:
**会议时间**:
**参会人员**:
**会议主持**:
## 会议议程
1.
2.
3.
## 讨论内容
## 决策事项
## 行动计划
| 任务 | 负责人 | 截止时间 | 状态 |
|------|--------|----------|------|
## 下次会议安排
```
#### 10.1.2 风险报告模板
```markdown
# 风险报告
**报告日期**:
**报告人**:
## 新识别风险
## 风险状态更新
## 风险应对措施
## 风险趋势分析
```
### 10.2 联系方式
#### 10.2.1 项目团队联系方式
- **项目经理**: 张三 (zhangsan@nxxmdata.com, 138-xxxx-xxxx)
- **技术负责人**: 李四 (lisi@nxxmdata.com, 139-xxxx-xxxx)
- **产品经理**: 王五 (wangwu@nxxmdata.com, 137-xxxx-xxxx)
#### 10.2.2 紧急联系方式
- **24小时值班**: 400-xxx-xxxx
- **紧急邮箱**: emergency@nxxmdata.com
- **项目群组**: 宁夏智慧养殖项目群
---
**文档维护**: 本文档将根据项目进展定期更新
**最后更新**: 2025-01-19
**文档状态**: 正式版本