# IPAM 管理系统 - 开发文档

## 项目概述

IPAM (IP Address Management) 是一个企业级IP地址管理系统，用于自动化扫描、发现和管理网络IP资产。

## 需求优先级划分

### P0 - 核心功能（必须优先实现）

#### 1. 项目基础架构
- [ ] FastAPI 后端框架搭建
- [ ] MySQL 数据库模型设计
- [ ] Redis 缓存配置
- [ ] Celery 异步任务框架
- [ ] Docker & Docker Compose 容器化部署

#### 2. 网络与子网管理
- [ ] 网段CRUD（支持CIDR格式）
- [ ] 网段分组管理
- [ ] 网段统计视图（总IP、已用、空闲、使用率）

#### 3. IP资产台账
- [ ] IP地址实体模型
- [ ] 基础字段：IP、MAC、主机名
- [ ] IP状态管理（在线、离线、空闲、保留）
- [ ] 自定义字段扩展框架

#### 4. 基础扫描引擎
- [ ] ICMP Ping扫描
- [ ] 手动触发扫描

### P1 - 重要功能（核心功能完成后实现）

#### 1. 高级扫描功能
- [ ] ARP扫描获取MAC地址
- [ ] 反向DNS解析主机名
- [ ] 定时扫描任务调度

#### 2. SNMP设备集成
- [ ] SNMP凭据池（v2c + v3）
- [ ] 网络设备台账
- [ ] SNMP连通性测试
- [ ] ARP表拉取（IP-MAC映射）
- [ ] MAC地址表拉取（MAC-端口映射）

#### 3. 告警与异常检测
- [ ] IP冲突告警
- [ ] 非授权接入告警
- [ ] 网段耗尽预警

### P2 - 增强功能

#### 1. 厂商深度发现
- [ ] Cisco/H3C私有MIB支持
- [ ] LLDP/CDP邻居发现
- [ ] 物理拓扑解析
- [ ] OUI厂商识别

#### 2. 系统管理
- [ ] 操作审计日志
- [ ] IP历史轨迹
- [ ] 角色权限控制

#### 3. 前端界面
- [ ] Vue 3 + Element Plus
- [ ] 网段大盘视图
- [ ] IP台账表格
- [ ] 网络拓扑展示

## 技术栈

### 后端
- **Web框架**: FastAPI 0.110+
- **数据库**: MySQL 8.0
- **ORM**: SQLAlchemy 2.0
- **缓存**: Redis 7.0
- **异步任务**: Celery 5.3+
- **SNMP**: pysnmp
- **网络探测**: Scapy
- **数据验证**: Pydantic 2.0

### 前端
- **框架**: Vue 3
- **UI组件**: Element Plus
- **状态管理**: Pinia
- **路由**: Vue Router 4

### 部署
- **容器化**: Docker + Docker Compose
- **反向代理**: Nginx

## 项目结构

```
ipam/
├── backend/                 # 后端代码
│   ├── app/
│   │   ├── api/            # API路由
│   │   │   ├── v1/
│   │   │   │   ├── networks.py
│   │   │   │   ├── ips.py
│   │   │   │   ├── scan.py
│   │   │   │   └── devices.py
│   │   │   └── dependencies.py
│   │   ├── core/           # 核心配置
│   │   │   ├── config.py
│   │   │   ├── database.py
│   │   │   └── security.py
│   │   ├── models/         # 数据库模型
│   │   │   ├── network.py
│   │   │   ├── ip.py
│   │   │   ├── device.py
│   │   │   └── alert.py
│   │   ├── schemas/        # Pydantic模型
│   │   │   ├── network.py
│   │   │   ├── ip.py
│   │   │   └── scan.py
│   │   ├── services/       # 业务逻辑
│   │   │   ├── network_service.py
│   │   │   ├── scan_service.py
│   │   │   └── snmp_service.py
│   │   ├── tasks/          # Celery任务
│   │   │   ├── celery_app.py
│   │   │   ├── scan_tasks.py
│   │   │   └── snmp_tasks.py
│   │   └── main.py
│   ├── requirements.txt
│   ├── Dockerfile
│   └── .env.example
├── frontend/               # 前端代码
│   ├── src/
│   ├── package.json
│   └── Dockerfile
├── docker-compose.yml
├── docs/                   # 文档
│   └── DEVELOPMENT.md
└── README.md
```

## 数据库设计

### 核心表结构

#### networks（网段表）
```sql
id INT PRIMARY KEY
cidr VARCHAR(50) UNIQUE    -- 如: 192.168.1.0/24
name VARCHAR(100)
description TEXT
group_name VARCHAR(100)    -- 分组名称
gateway VARCHAR(50)
vlan_id INT
total_ips INT
used_ips INT DEFAULT 0
reserved_ips INT DEFAULT 0
created_at DATETIME
updated_at DATETIME
```

#### ip_addresses（IP地址表）
```sql
id INT PRIMARY KEY
network_id INT FOREIGN KEY
ip_address VARCHAR(50) UNIQUE
mac_address VARCHAR(50) NULL
hostname VARCHAR(255) NULL
status ENUM('available', 'online', 'offline', 'reserved')
owner VARCHAR(100) NULL
business_type VARCHAR(50) NULL
notes TEXT NULL
custom_fields JSON          -- 自定义字段
last_seen DATETIME NULL
created_at DATETIME
updated_at DATETIME
```

#### scan_tasks（扫描任务表）
```sql
id INT PRIMARY KEY
network_id INT NULL
task_type ENUM('ping', 'arp', 'snmp')
status ENUM('pending', 'running', 'completed', 'failed')
progress INT DEFAULT 0
started_at DATETIME NULL
completed_at DATETIME NULL
result TEXT NULL
created_at DATETIME
```

#### snmp_credentials（SNMP凭据表）
```sql
id INT PRIMARY KEY
name VARCHAR(100)
version ENUM('v2c', 'v3')
community_string VARCHAR(255) NULL  -- v2c
username VARCHAR(100) NULL           -- v3
auth_password VARCHAR(255) NULL      -- v3
auth_protocol VARCHAR(50) NULL       -- MD5, SHA
priv_password VARCHAR(255) NULL      -- v3
priv_protocol VARCHAR(50) NULL       -- DES, AES
created_at DATETIME
```

#### network_devices（网络设备表）
```sql
id INT PRIMARY KEY
name VARCHAR(100)
ip_address VARCHAR(50)
device_type VARCHAR(50)  -- core, distribution, access
vendor VARCHAR(100) NULL
model VARCHAR(100) NULL
snmp_credential_id INT FOREIGN KEY
last_polled_at DATETIME NULL
created_at DATETIME
```

#### alerts（告警表）
```sql
id INT PRIMARY KEY
alert_type ENUM('ip_conflict', 'unauthorized', 'subnet_full')
severity ENUM('warning', 'error', 'critical')
message TEXT
resolved BOOLEAN DEFAULT FALSE
resolved_at DATETIME NULL
created_at DATETIME
```

## API 接口设计

### 网段管理
- `GET /api/v1/networks` - 获取网段列表
- `POST /api/v1/networks` - 创建网段
- `GET /api/v1/networks/{id}` - 获取网段详情
- `PUT /api/v1/networks/{id}` - 更新网段
- `DELETE /api/v1/networks/{id}` - 删除网段
- `GET /api/v1/networks/{id}/stats` - 获取网段统计数据

### IP地址管理
- `GET /api/v1/ips` - 获取IP列表
- `GET /api/v1/ips/{id}` - 获取IP详情
- `PUT /api/v1/ips/{id}` - 更新IP信息
- `GET /api/v1/ips/export` - 导出IP台账

### 扫描管理
- `POST /api/v1/scan/ping/{network_id}` - 触发Ping扫描
- `GET /api/v1/scan/tasks/{task_id}` - 获取扫描任务状态

## 开发规范

1. **代码风格**: 遵循 PEP 8，使用 black 格式化
2. **类型注解**: 使用 Python 类型注解
3. **数据库迁移**: 使用 Alembic 管理数据库迁移
4. **API文档**: FastAPI 自动生成 Swagger 文档
5. **日志**: 使用 logging 模块记录关键操作
6. **测试**: 每个模块完成后编写单元测试

## 部署说明

详见 `docker-compose.yml` 配置文件。