Files

aiotagro 3c8648a635 refactor: 重构数据库配置为SQLite开发环境并移除冗余文档

2025-09-21 15:16:48 +08:00

16 KiB

Raw Permalink Blame History

后端开发文档

版本历史

版本	日期	作者	变更说明
1.0	2024-01-20	后端开发团队	初始版本
1.1	2024-09-21	后端开发团队	更新技术栈，与实际项目保持一致

1. 项目概述

1.1 项目介绍

畜牧养殖管理平台后端服务，采用微服务架构，为官网、管理后台、小程序APP提供统一的API服务。

1.2 技术栈

开发语言: Node.js (JavaScript)
Web框架: Express.js
数据库: MySQL 8.0 + Redis (缓存)
认证: JWT
文档: 接口设计文档
测试: 手动测试 + API测试
部署: 云服务器 + PM2
监控: 日志监控

1.3 项目结构

backend/
├── api/                     # API服务
│   ├── routes/             # 路由定义
│   ├── server.js           # 服务器入口
│   ├── package.json        # 依赖管理
│   └── .env.example        # 环境配置示例
├── database/               # 数据库管理
│   ├── init_tables.sql     # 数据库表结构
│   ├── init_data.sql       # 初始数据
│   ├── setup-database.js   # 数据库初始化脚本
│   └── database-manager.js # 数据库管理工具
├── services/               # 业务服务
│   └── README.md
└── utils/                  # 工具类
    └── README.md

2. 开发环境搭建

2.1 环境要求

Node.js >= 16.0.0
npm >= 8.0.0
MySQL >= 8.0
Redis >= 6.0
MongoDB >= 4.4

2.2 安装步骤

# 1. 克隆项目
git clone <repository-url>
cd backend

# 2. 安装依赖
npm install

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，配置数据库连接等信息

# 4. 初始化数据库
npm run db:migrate
npm run db:seed

# 5. 启动开发服务器
npm run dev

2.3 开发工具配置

VSCode插件: TypeScript, ESLint, Prettier, REST Client
代码规范: ESLint + Prettier
Git钩子: Husky + lint-staged
调试工具: VSCode Debugger

3. 开发计划

3.1 第一阶段：基础架构搭建（1-2周）

3.1.1 项目初始化

任务: 搭建基础项目结构 负责人: 架构师工期: 2天 详细任务:

创建项目目录结构
配置TypeScript环境
配置ESLint和Prettier
配置Git钩子和代码规范
创建基础的package.json和依赖管理

3.1.2 数据库设计与连接

任务: 设计数据库结构并建立连接 负责人: 数据库工程师工期: 3天 详细任务:

设计MySQL数据库表结构
配置TypeORM连接和实体模型
设计Redis缓存结构
配置MongoDB连接和集合设计
编写数据库迁移脚本
创建初始化数据种子

3.1.3 基础中间件开发

任务: 开发通用中间件 负责人: 后端工程师A 工期: 3天 详细任务:

开发日志中间件
开发错误处理中间件
开发CORS中间件
开发请求限流中间件
开发参数验证中间件
开发响应格式化中间件

3.1.4 认证授权系统

任务: 实现JWT认证和权限控制 负责人: 后端工程师B 工期: 4天 详细任务:

实现JWT Token生成和验证
开发用户认证中间件
实现基于角色的权限控制(RBAC)
开发微信小程序登录集成
实现Token刷新机制
开发权限验证装饰器

3.2 第二阶段：核心业务模块（3-4周）

3.2.1 用户管理模块

任务: 实现用户相关功能 负责人: 后端工程师A 工期: 5天 详细任务:

用户注册和登录API
用户信息管理API
实名认证功能
用户头像上传
密码重置功能
用户状态管理

接口列表:

POST   /api/auth/register          # 用户注册
POST   /api/auth/login             # 用户登录
POST   /api/auth/wechat/login      # 微信登录
POST   /api/auth/refresh           # 刷新Token
GET    /api/users/profile          # 获取用户信息
PUT    /api/users/profile          # 更新用户信息
POST   /api/users/avatar           # 上传头像
POST   /api/users/verification     # 实名认证
GET    /api/users/verification     # 获取认证状态

3.2.2 养殖场管理模块

任务: 实现养殖场相关功能 负责人: 后端工程师B 工期: 6天 详细任务:

养殖场CRUD操作
养殖场审核流程
养殖场统计数据
养殖场图片管理
养殖场地理位置服务
养殖场权限控制

接口列表:

GET    /api/farms                  # 获取养殖场列表
POST   /api/farms                  # 创建养殖场
GET    /api/farms/:id              # 获取养殖场详情
PUT    /api/farms/:id              # 更新养殖场信息
DELETE /api/farms/:id              # 删除养殖场
GET    /api/farms/:id/statistics   # 获取养殖场统计
POST   /api/farms/:id/approve      # 审核养殖场

3.2.3 动物管理模块

任务: 实现动物档案管理 负责人: 后端工程师C 工期: 7天 详细任务:

动物档案CRUD操作
动物健康记录管理
动物生长记录跟踪
动物疫苗接种管理
动物繁殖记录
动物统计分析

接口列表:

GET    /api/animals                # 获取动物列表
POST   /api/animals                # 添加动物
GET    /api/animals/:id            # 获取动物详情
PUT    /api/animals/:id            # 更新动物信息
DELETE /api/animals/:id            # 删除动物
GET    /api/animals/:id/health     # 获取健康记录
POST   /api/animals/:id/health     # 添加健康记录
GET    /api/animals/:id/growth     # 获取生长记录
POST   /api/animals/:id/growth     # 添加生长记录

3.2.4 交易管理模块

任务: 实现商品交易功能 负责人: 后端工程师D 工期: 8天 详细任务:

商品发布和管理
商品搜索和筛选
订单创建和管理
支付集成(微信支付)
物流跟踪
交易评价系统

接口列表:

GET    /api/products               # 获取商品列表
POST   /api/products               # 发布商品
GET    /api/products/:id           # 获取商品详情
PUT    /api/products/:id           # 更新商品信息
DELETE /api/products/:id           # 删除商品
POST   /api/orders                 # 创建订单
GET    /api/orders                 # 获取订单列表
GET    /api/orders/:id             # 获取订单详情
PUT    /api/orders/:id/status      # 更新订单状态
POST   /api/payments               # 创建支付
GET    /api/payments/:id/status    # 查询支付状态

3.3 第三阶段：高级功能开发（2-3周）

3.3.1 文件上传服务

任务: 实现文件上传和管理 负责人: 后端工程师A 工期: 3天 详细任务:

图片上传接口
文件类型验证
图片压缩和缩略图生成
CDN集成
文件安全检查
批量上传支持

3.3.2 消息通知系统

任务: 实现消息推送功能 负责人: 后端工程师B 工期: 4天 详细任务:

系统消息管理
微信小程序消息推送
短信通知集成
邮件通知功能
消息模板管理
消息统计分析

3.3.3 数据统计分析

任务: 实现数据统计功能 负责人: 后端工程师C 工期: 5天 详细任务:

用户行为统计
养殖数据分析
交易数据统计
财务报表生成
数据可视化接口
定时统计任务

3.3.4 系统管理功能

任务: 实现系统管理接口 负责人: 后端工程师D 工期: 4天 详细任务:

系统配置管理
日志查询接口
系统监控接口
数据备份恢复
系统健康检查
性能监控

3.4 第四阶段：测试与优化（1-2周）

3.4.1 单元测试

任务: 编写单元测试 负责人: 全体后端工程师工期: 3天 详细任务:

编写Service层单元测试
编写Controller层单元测试
编写工具函数测试
编写中间件测试
测试覆盖率达到80%以上

3.4.2 集成测试

任务: 编写集成测试 负责人: 测试工程师工期: 3天 详细任务:

API接口集成测试
数据库操作测试
第三方服务集成测试
端到端测试场景
性能测试

3.4.3 性能优化

任务: 系统性能优化 负责人: 架构师工期: 4天 详细任务:

数据库查询优化
缓存策略优化
接口响应时间优化
内存使用优化
并发处理优化

4. 开发规范

4.1 代码规范

命名规范: 使用驼峰命名法，类名首字母大写
文件命名: 使用kebab-case命名法
注释规范: 使用JSDoc格式注释
代码格式: 使用Prettier自动格式化
代码检查: 使用ESLint进行代码检查

4.2 API设计规范

RESTful设计: 遵循REST API设计原则
HTTP状态码: 正确使用HTTP状态码
响应格式: 统一的JSON响应格式
错误处理: 统一的错误码和错误信息
版本控制: API版本控制策略

4.3 数据库规范

表命名: 使用snake_case命名法
字段命名: 使用snake_case命名法
索引设计: 合理设计数据库索引
外键约束: 正确使用外键约束
数据迁移: 使用迁移脚本管理数据库变更

4.4 Git工作流

分支策略: 使用Git Flow分支策略
提交规范: 使用Conventional Commits规范
代码审查: 所有代码必须经过Code Review
合并策略: 使用Squash and Merge策略

5. 部署配置

5.1 环境配置

// config/database.js
module.exports = {
  development: {
    host: 'localhost',
    port: 3306,
    username: 'root',
    password: 'password',
    database: 'xlxumu_dev'
  },
  production: {
    host: process.env.DB_HOST,
    port: process.env.DB_PORT,
    username: process.env.DB_USERNAME,
    password: process.env.DB_PASSWORD,
    database: process.env.DB_DATABASE
  }
}

5.2 Docker配置

# Dockerfile
FROM node:16-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .

EXPOSE 3000

CMD ["npm", "start"]

5.3 PM2配置

// ecosystem.config.js
module.exports = {
  apps: [{
    name: 'xlxumu-backend',
    script: './dist/app.js',
    instances: 'max',
    exec_mode: 'cluster',
    env: {
      NODE_ENV: 'production',
      PORT: 3000
    }
  }]
}

6. 监控与日志

6.1 日志配置

// config/logger.js
const winston = require('winston');

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.errors({ stack: true }),
    winston.format.json()
  ),
  transports: [
    new winston.transports.File({ filename: 'logs/error.log', level: 'error' }),
    new winston.transports.File({ filename: 'logs/combined.log' })
  ]
});

6.2 性能监控

响应时间监控: 监控API响应时间
错误率监控: 监控API错误率
数据库性能: 监控数据库查询性能
内存使用: 监控应用内存使用情况
CPU使用: 监控CPU使用率

6.3 告警配置

错误告警: API错误率超过阈值时告警
性能告警: 响应时间超过阈值时告警
资源告警: 内存或CPU使用率过高时告警
业务告警: 关键业务指标异常时告警

7. 安全措施

7.1 认证安全

JWT安全: 使用强密钥和合适的过期时间
密码安全: 使用bcrypt加密存储密码
会话管理: 实现安全的会话管理机制
多因素认证: 支持短信验证码等多因素认证

7.2 数据安全

输入验证: 严格验证所有输入参数
SQL注入防护: 使用参数化查询防止SQL注入
XSS防护: 对输出内容进行转义
CSRF防护: 实现CSRF Token验证

7.3 传输安全

HTTPS: 强制使用HTTPS传输
数据加密: 敏感数据加密存储
API限流: 实现API调用频率限制
IP白名单: 关键接口实现IP白名单控制

8. 测试策略

8.1 测试类型

单元测试: 测试单个函数或方法
集成测试: 测试模块间的集成
端到端测试: 测试完整的业务流程
性能测试: 测试系统性能和负载能力
安全测试: 测试系统安全性

8.2 测试工具

Jest: 单元测试框架
Supertest: HTTP接口测试
Artillery: 性能测试工具
OWASP ZAP: 安全测试工具
Postman: API测试工具

8.3 测试数据

测试数据库: 独立的测试数据库环境
Mock数据: 使用Mock数据进行测试
数据清理: 测试后自动清理测试数据
数据隔离: 确保测试数据不影响生产环境

9. 文档管理

9.1 API文档

Swagger: 使用Swagger生成API文档
接口说明: 详细的接口参数和返回值说明
示例代码: 提供接口调用示例
错误码: 完整的错误码说明
版本管理: API版本变更记录

9.2 开发文档

架构文档: 系统架构设计文档
数据库文档: 数据库设计文档
部署文档: 部署和运维文档
开发指南: 开发环境搭建和开发规范
故障排查: 常见问题和解决方案

10. 质量保证

10.1 代码质量

代码审查: 强制代码审查流程
静态分析: 使用SonarQube进行代码质量分析
测试覆盖率: 要求测试覆盖率达到80%以上
性能基准: 建立性能基准和监控
技术债务: 定期清理技术债务

10.2 发布流程

持续集成: 使用CI/CD自动化构建和测试
灰度发布: 实现灰度发布机制
回滚策略: 快速回滚机制
发布检查: 发布前的检查清单
发布通知: 发布状态通知机制

11. 团队协作

11.1 团队结构

架构师: 负责系统架构设计和技术选型
后端工程师: 负责具体功能开发
数据库工程师: 负责数据库设计和优化
测试工程师: 负责测试用例编写和执行
运维工程师: 负责部署和运维

11.2 沟通机制

每日站会: 每日进度同步和问题讨论
周会: 每周工作总结和计划
技术分享: 定期技术分享和学习
代码审查: 代码审查和技术讨论
文档协作: 使用协作工具维护文档

12. 风险管理

12.1 技术风险

技术选型风险: 评估新技术的成熟度和风险
性能风险: 提前进行性能测试和优化
安全风险: 定期进行安全评估和测试
依赖风险: 管理第三方依赖的版本和安全性
数据风险: 建立数据备份和恢复机制

12.2 项目风险

进度风险: 合理评估开发工期和资源需求
质量风险: 建立完善的测试和质量保证机制
人员风险: 知识共享和文档化减少人员依赖
需求风险: 及时沟通需求变更和影响评估
集成风险: 提前进行系统集成测试

13. 总结

本开发文档详细规划了畜牧养殖管理平台后端服务的开发计划，包括：

13.1 开发亮点

微服务架构: 采用模块化的微服务架构设计
TypeScript: 使用TypeScript提升代码质量和开发效率
完善的测试: 建立完整的测试体系保证代码质量
自动化部署: 使用Docker和CI/CD实现自动化部署
监控告警: 完善的监控和告警机制

13.2 技术特色

高性能: 通过缓存和数据库优化提升性能
高可用: 集群部署和故障转移机制
安全性: 多层次的安全防护措施
可扩展: 模块化设计支持功能扩展
易维护: 规范的代码和完善的文档

13.3 开发保障

团队协作: 明确的角色分工和协作机制
质量控制: 严格的代码审查和测试要求
风险管控: 全面的风险识别和应对措施
进度管理: 详细的任务分解和时间规划
文档完善: 完整的开发和API文档

13.4 后续优化

性能优化: 持续的性能监控和优化
功能扩展: 根据业务需求扩展新功能
技术升级: 跟进技术发展升级技术栈
用户体验: 根据用户反馈优化接口设计
运维自动化: 进一步提升运维自动化水平

16 KiB Raw Permalink Blame History Unescape Escape

后端开发文档

版本历史

1. 项目概述

1.1 项目介绍

1.2 技术栈

1.3 项目结构

2. 开发环境搭建

2.1 环境要求

2.2 安装步骤

2.3 开发工具配置

3. 开发计划

3.1 第一阶段：基础架构搭建（1-2周）

3.1.1 项目初始化

3.1.2 数据库设计与连接

3.1.3 基础中间件开发

3.1.4 认证授权系统

3.2 第二阶段：核心业务模块（3-4周）

3.2.1 用户管理模块

3.2.2 养殖场管理模块

3.2.3 动物管理模块

3.2.4 交易管理模块

3.3 第三阶段：高级功能开发（2-3周）

3.3.1 文件上传服务

3.3.2 消息通知系统

3.3.3 数据统计分析

3.3.4 系统管理功能

3.4 第四阶段：测试与优化（1-2周）

3.4.1 单元测试

3.4.2 集成测试

3.4.3 性能优化

4. 开发规范

4.1 代码规范

4.2 API设计规范

4.3 数据库规范

4.4 Git工作流

5. 部署配置

5.1 环境配置

5.2 Docker配置

5.3 PM2配置

6. 监控与日志

6.1 日志配置

6.2 性能监控

6.3 告警配置

7. 安全措施

7.1 认证安全

7.2 数据安全

7.3 传输安全

8. 测试策略

8.1 测试类型

8.2 测试工具

8.3 测试数据

9. 文档管理

9.1 API文档

9.2 开发文档

10. 质量保证

10.1 代码质量

10.2 发布流程

11. 团队协作

11.1 团队结构

11.2 沟通机制

12. 风险管理

12.1 技术风险

12.2 项目风险

13. 总结

13.1 开发亮点

13.2 技术特色

13.3 开发保障

13.4 后续优化

16 KiB

Raw Permalink Blame History