From deda4a222fa6406d129fc14e9be87d9e8134e827 Mon Sep 17 00:00:00 2001 From: xiaji Date: Mon, 18 May 2026 17:30:53 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E5=AE=8C=E6=95=B4?= =?UTF-8?q?=E7=9A=84README=E9=A1=B9=E7=9B=AE=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 165 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..f602c3c --- /dev/null +++ b/README.md @@ -0,0 +1,165 @@ +# 视频主设备管理系统 + +基于 Django REST Framework 的视频设备全生命周期管理后端API服务。 + +## 项目背景 + +随着视频监控、视频会议等业务的扩展，视频主设备（如视频编码器、解码器、矩阵、NVR等）数量快速增长。当前采用人工表格管理方式，存在设备信息分散、维护记录缺失、IP地址冲突、序列号追溯困难等问题。 + +## 功能特性 + +### 核心模块 + +| 模块 | 功能说明 | +|------|----------| +| **设备管理** | 设备增删改查；按地点/楼栋/状态筛选；服役时长自动计算 | +| **序列号管理** | 支持多序列号（主序列号+辅助）；唯一性校验 | +| **IP地址管理** | 支持多IP（管理/业务/备用）；主IP标识；唯一性校验 | +| **维修记录** | 故障描述/维修内容/更换配件/维修人/费用；历史追溯 | +| **附件与缩略图** | 照片/说明书上传；自动生成缩略图展示 | +| **巡检管理** | 最后巡检时间记录；保修到期预警 | +| **Excel导入导出** | 批量导入设备；导出设备列表（含主IP/序列号/维修简述） | + +### 技术栈 + +| 层级 | 技术选型 | +|------|----------| +| 后端框架 | Django 4.2 + Django REST Framework 3.15 | +| 数据库 | SQLite3 (可切换MySQL/PostgreSQL) | +| 对象存储 | 本地文件系统 (可扩展MinIO) | +| 图片处理 | Pillow | +| 身份认证 | JWT + Session | +| API文档 | drf-yasg (Swagger/Redoc) | +| Excel处理 | openpyxl + pandas | +| 日志系统 | loguru | + +## 快速开始 + +### 环境要求 + +- Python 3.8+ +- pip + +### 安装依赖 + +```bash +pip install -r requirements.txt +``` + +### 数据库迁移 + +```bash +python manage.py makemigrations +python manage.py migrate +``` + +### 创建管理员 + +```bash +python manage.py createsuperuser +``` + +### 启动服务 + +```bash +python manage.py runserver 0.0.0.0:8000 +``` + +## 访问地址 + +| 服务 | 地址 | +|------|------| +| Swagger API文档 | http://localhost:8000/swagger/ | +| Redoc API文档 | http://localhost:8000/redoc/ | +| Django Admin后台 | http://localhost:8000/admin/ | +| 设备列表API | http://localhost:8000/api/devices/ | + +## API端点 + +### 设备管理 + +| 方法 | 端点 | 说明 | +|------|------|------| +| GET | `/api/devices/` | 设备列表（分页/过滤/搜索） | +| POST | `/api/devices/` | 创建设备（可同时创建主序列号和主IP） | +| GET | `/api/devices/{id}/` | 设备详情（含序列号/IP/维修记录） | +| PUT | `/api/devices/{id}/` | 全量更新设备 | +| PATCH | `/api/devices/{id}/` | 部分更新设备 | +| DELETE | `/api/devices/{id}/` | 删除设备（级联删除子表） | +| GET | `/api/devices/export_excel/` | 导出Excel | +| POST | `/api/devices/import_excel/` | 导入Excel | +| POST | `/api/devices/{id}/upload_attachment/` | 上传附件 | + +### 其他资源 + +- `/api/serials/` - 序列号管理 +- `/api/ips/` - IP地址管理 +- `/api/maintenance/` - 维修记录管理 +- `/api/attachments/` - 附件管理 + +### 认证 + +```bash +# 获取JWT Token +POST /api/token/ +Body: { + "username": "your_username", + "password": "your_password" +} + +# 使用Token +Authorization: Bearer +``` + +## Excel导入模板列名 + +| 列名 | 说明 | 必填 | +|------|------|------| +| 地点 | 设备所在地点 | 是 | +| 楼栋 | 所在楼栋 | 否 | +| 设备名称 | 设备标识名 | 是 | +| 型号 | 设备型号 | 否 | +| 品牌 | 设备品牌 | 否 | +| 状态 | normal/warning/offline/repair/scrap | 否（默认normal） | +| 负责人 | 运维负责人 | 否 | +| 主序列号 | 设备主键号 | 否 | +| 主IP | 主要管理IP地址 | 否 | + +## 项目结构 + +``` +netmeeting-infra/ +├── config/ +│ ├── settings.py # Django配置 +│ ├── urls.py # 主路由 +│ └── wsgi.py +├── device_management/ +│ ├── models.py # 5个数据库模型 +│ ├── serializers.py # DRF序列化器 +│ ├── views.py # ViewSet视图 +│ ├── urls.py # API路由 +│ ├── admin.py # Admin配置 +│ └── migrations/ # 数据库迁移文件 +├── manage.py +├── requirements.txt +└── README.md +``` + +## 数据库表结构 + +- `device` - 设备主表（15个业务字段） +- `device_serial` - 序列号子表（唯一约束） +- `device_ip` - IP地址子表（唯一约束） +- `maintenance_record` - 维修记录子表 +- `device_attachment` - 附件管理表 + +## 部署方式（可选） + +```bash +# Docker + Nginx + Gunicorn +# 详见Django官方部署文档 +``` + +## 许可证 + +BSD License