PYTHON_3_10_COMPATIBILITY.md

@@ -11,7 +11,27 @@
 ✅ 类型注解完全兼容 Python 3.10
 ✅ `match` 关键字未用作 Python 3.10 的模式匹配语句（仅用作 `re.match()` 的变量名）
 
+### 重要依赖说明
+
+#### pysnmp 兼容问题解决
+**问题**：`pysnmp==7.1.15` 存在以下兼容性问题：
+- 使用已废弃的 `asyncio.coroutine` 装饰器（Python 3.11 中已移除）
+- 与 Python 3.10+ 的 asyncio 不兼容
+
+**解决方案**：
+使用社区维护的分支 `pysnmp-lextudio==5.0.31`
+- 完全向后兼容原有 pysnmp API
+- 支持 Python 3.6+
+- 积极维护，修复了 asyncio 兼容性问题
+- 导入方式完全不变
+
+```python
+# 无需修改代码，导入方式保持一致
+from pysnmp.hlapi.asyncio import bulkCmd, getCmd, nextCmd
+```
+
 ### 依赖版本要求
+- `pysnmp-lextudio==5.0.31` - SNMP 协议兼容替代
 - `typing-extensions>=4.5.0` - 提供额外的类型支持
 - 所有核心依赖（FastAPI、SQLAlchemy、Pydantic 等）均已验证兼容
 
@@ -38,6 +58,9 @@ pip install -r requirements.txt
 ## 验证
 可以使用以下命令验证 Python 版本兼容性：
 ```bash
-python --version  # 应为 3.10.x
+python --version  # 应为 3.10.x 或 3.11.x
 python -c "import sys; assert sys.version_info >= (3, 10), 'Python 3.10+ required'"
+
+# 验证 pysnmp 导入
+python -c "from pysnmp.hlapi.asyncio import bulkCmd, getCmd, nextCmd; print('pysnmp OK')"
 ```

backend/requirements.txt

@@ -10,7 +10,9 @@ celery==5.3.6
 redis==5.0.3
 python-multipart==0.0.9
 alembic==1.13.1
-pysnmp==7.1.15
+# 注意: pysnmp 7.x 与 Python 3.10+/asyncio 存在兼容性问题
+# 使用 lextudio 维护的分支（向后兼容，支持 Python 3.6+）
+pysnmp-lextudio==5.0.31
 scapy==2.5.0
 python-dotenv==1.0.1
 passlib[bcrypt]==1.7.4