feat(UME): 完善网元字段注释并补齐IPv6地址字段

为 ume_inventory_ne 的关键字段补充建表注释并在启动时执行 COMMENT ON 同步历史库结构，同时新增 ipv6_address 字段并完成入库映射、接口返回与前端类型定义对齐。

Co-authored-by: Cursor <cursoragent@cursor.com>

netx_api/main.py

@@ -198,6 +198,7 @@ def on_startup() -> None:
             conn.exec_driver_sql("ALTER TABLE ume_inventory_ne ADD COLUMN IF NOT EXISTS device_level VARCHAR(64) DEFAULT ''")
             conn.exec_driver_sql("ALTER TABLE ume_inventory_ne ADD COLUMN IF NOT EXISTS host_name VARCHAR(256) DEFAULT ''")
             conn.exec_driver_sql("ALTER TABLE ume_inventory_ne ADD COLUMN IF NOT EXISTS location VARCHAR(512) DEFAULT ''")
+            conn.exec_driver_sql("ALTER TABLE ume_inventory_ne ADD COLUMN IF NOT EXISTS ipv6_address VARCHAR(128) DEFAULT ''")
             conn.exec_driver_sql(
                 "ALTER TABLE ume_inventory_ne ADD COLUMN IF NOT EXISTS hardware_version VARCHAR(128) DEFAULT ''"
             )
@@ -225,6 +226,26 @@ def on_startup() -> None:
             conn.exec_driver_sql("ALTER TABLE ume_alarms_current DROP COLUMN IF EXISTS user_label")
             conn.exec_driver_sql("ALTER TABLE ume_alarms_history DROP COLUMN IF EXISTS ne_name")
             conn.exec_driver_sql("ALTER TABLE ume_alarms_history DROP COLUMN IF EXISTS user_label")
+            conn.exec_driver_sql("COMMENT ON TABLE ume_inventory_ne IS '网元对象详细信息'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.ne_id IS '网元uuid'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.ne_name IS '资源名称'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.ne_type IS '网元类型'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.user_label IS '用户标签'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.address_type IS '管理地址类型(1:IPv4,2:IPv6)'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.ip_address IS '网元IPv4地址'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.net_mask IS '管理IPv4掩码(点分十进制)'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.ipv6_address IS 'IPv6地址'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.admin_status IS '管理状态(0-离线,1-在线)'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.connection_status IS '连接状态(0-断链,1-正常)'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.consistent_state IS '数据一致性状态(1一致,2不一致,3冲突)'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.maintain_status IS '工程状态(0普通,1调测,2新建)'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.vendor IS '网元提供商'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.interface_version IS '网元接口版本号'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.hardware_version IS '硬件版本'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.mac IS '设备机架MAC地址'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.loopback IS '业务环回IP(IPv4)'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.device_level IS '网元层次'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.host_name IS '主机名称'")
     except Exception:
         pass
     try:
@@ -408,6 +429,7 @@ def ume_list_ne(
             "ne_name": str(x.ne_name or ""),
             "user_label": str(x.user_label or ""),
             "ip_address": str(x.ip_address or ""),
+            "ipv6_address": str(x.ipv6_address or ""),
             "ne_type": str(x.ne_type or ""),
             "device_level": str(x.device_level or ""),
             "host_name": str(x.host_name or ""),
@@ -441,6 +463,7 @@ def ume_get_ne(ne_id: str, db: Session = Depends(get_db)) -> dict[str, Any]:
         "ne_name": str(row.ne_name or ""),
         "user_label": str(row.user_label or ""),
         "ip_address": str(row.ip_address or ""),
+        "ipv6_address": str(row.ipv6_address or ""),
         "ne_type": str(row.ne_type or ""),
         "device_level": str(row.device_level or ""),
         "host_name": str(row.host_name or ""),

netx_api/mcp_server.py

@@ -442,6 +442,7 @@ def main() -> None:
             conn.exec_driver_sql("ALTER TABLE ume_inventory_ne ADD COLUMN IF NOT EXISTS device_level VARCHAR(64) DEFAULT ''")
             conn.exec_driver_sql("ALTER TABLE ume_inventory_ne ADD COLUMN IF NOT EXISTS host_name VARCHAR(256) DEFAULT ''")
             conn.exec_driver_sql("ALTER TABLE ume_inventory_ne ADD COLUMN IF NOT EXISTS location VARCHAR(512) DEFAULT ''")
+            conn.exec_driver_sql("ALTER TABLE ume_inventory_ne ADD COLUMN IF NOT EXISTS ipv6_address VARCHAR(128) DEFAULT ''")
             conn.exec_driver_sql(
                 "ALTER TABLE ume_inventory_ne ADD COLUMN IF NOT EXISTS hardware_version VARCHAR(128) DEFAULT ''"
             )
@@ -468,6 +469,26 @@ def main() -> None:
             conn.exec_driver_sql("ALTER TABLE ume_alarms_current DROP COLUMN IF EXISTS user_label")
             conn.exec_driver_sql("ALTER TABLE ume_alarms_history DROP COLUMN IF EXISTS ne_name")
             conn.exec_driver_sql("ALTER TABLE ume_alarms_history DROP COLUMN IF EXISTS user_label")
+            conn.exec_driver_sql("COMMENT ON TABLE ume_inventory_ne IS '网元对象详细信息'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.ne_id IS '网元uuid'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.ne_name IS '资源名称'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.ne_type IS '网元类型'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.user_label IS '用户标签'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.address_type IS '管理地址类型(1:IPv4,2:IPv6)'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.ip_address IS '网元IPv4地址'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.net_mask IS '管理IPv4掩码(点分十进制)'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.ipv6_address IS 'IPv6地址'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.admin_status IS '管理状态(0-离线,1-在线)'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.connection_status IS '连接状态(0-断链,1-正常)'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.consistent_state IS '数据一致性状态(1一致,2不一致,3冲突)'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.maintain_status IS '工程状态(0普通,1调测,2新建)'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.vendor IS '网元提供商'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.interface_version IS '网元接口版本号'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.hardware_version IS '硬件版本'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.mac IS '设备机架MAC地址'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.loopback IS '业务环回IP(IPv4)'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.device_level IS '网元层次'")
+            conn.exec_driver_sql("COMMENT ON COLUMN ume_inventory_ne.host_name IS '主机名称'")
     except Exception:
         pass
     for line in sys.stdin:

netx_api/models.py

@@ -135,27 +135,28 @@ class UmeAlarmBatch(Base):
 class UmeInventoryNE(Base):
     __tablename__ = "ume_inventory_ne"
 
-    ne_id: Mapped[str] = mapped_column(String(128), primary_key=True)
+    ne_id: Mapped[str] = mapped_column(String(128), primary_key=True, comment="网元uuid")
-    ne_name: Mapped[str] = mapped_column(String(256), default="", index=True)
+    ne_name: Mapped[str] = mapped_column(String(256), default="", index=True, comment="资源名称")
-    user_label: Mapped[str] = mapped_column(String(256), default="", index=True)
+    user_label: Mapped[str] = mapped_column(String(256), default="", index=True, comment="用户标签")
-    ip_address: Mapped[str] = mapped_column(String(128), default="", index=True)
+    ip_address: Mapped[str] = mapped_column(String(128), default="", index=True, comment="网元IPv4地址")
-    ne_type: Mapped[str] = mapped_column(String(128), default="")
+    ipv6_address: Mapped[str] = mapped_column(String(128), default="", index=True, comment="IPv6地址")
-    device_level: Mapped[str] = mapped_column(String(64), default="")
+    ne_type: Mapped[str] = mapped_column(String(128), default="", comment="网元类型")
-    host_name: Mapped[str] = mapped_column(String(256), default="")
+    device_level: Mapped[str] = mapped_column(String(64), default="", comment="网元层次")
+    host_name: Mapped[str] = mapped_column(String(256), default="", comment="主机名称")
     location: Mapped[str] = mapped_column(String(512), default="")
-    hardware_version: Mapped[str] = mapped_column(String(128), default="")
+    hardware_version: Mapped[str] = mapped_column(String(128), default="", comment="硬件版本")
-    loopback: Mapped[str] = mapped_column(String(128), default="")
+    loopback: Mapped[str] = mapped_column(String(128), default="", comment="业务环回IP(IPv4)")
-    consistent_state: Mapped[str] = mapped_column(String(64), default="")
+    consistent_state: Mapped[str] = mapped_column(String(64), default="", comment="数据一致性状态")
-    interface_version: Mapped[str] = mapped_column(String(128), default="")
+    interface_version: Mapped[str] = mapped_column(String(128), default="", comment="网元接口版本号")
-    mac: Mapped[str] = mapped_column(String(128), default="")
+    mac: Mapped[str] = mapped_column(String(128), default="", comment="设备机架MAC地址")
-    admin_status: Mapped[str] = mapped_column(String(64), default="")
+    admin_status: Mapped[str] = mapped_column(String(64), default="", comment="管理状态")
-    address_type: Mapped[str] = mapped_column(String(64), default="")
+    address_type: Mapped[str] = mapped_column(String(64), default="", comment="管理地址类型(1:IPv4,2:IPv6)")
-    connection_status: Mapped[str] = mapped_column(String(64), default="")
+    connection_status: Mapped[str] = mapped_column(String(64), default="", comment="连接状态")
-    maintain_status: Mapped[str] = mapped_column(String(64), default="")
+    maintain_status: Mapped[str] = mapped_column(String(64), default="", comment="工程状态")
-    net_mask: Mapped[str] = mapped_column(String(128), default="")
+    net_mask: Mapped[str] = mapped_column(String(128), default="", comment="管理IPv4掩码")
     create_time: Mapped[str] = mapped_column(String(64), default="")
     creator: Mapped[str] = mapped_column(String(128), default="")
-    vendor: Mapped[str] = mapped_column(String(64), default="ZTE")
+    vendor: Mapped[str] = mapped_column(String(64), default="ZTE", comment="网元提供商")
     source_type: Mapped[str] = mapped_column(String(64), default="ume_restconf")
     first_seen_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
     last_seen_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, index=True)

netx_api/ume_sync_service.py

@@ -187,6 +187,7 @@ def sync_inventory_full(db: Session, client: UMEClient, *, trigger_mode: str = "
             existing.ne_name = _s(_pick(row, "name", "ne-name"))
             existing.user_label = _s(_pick(row, "user-label", "user_label"))
             existing.ip_address = _s(_pick(row, "ip-Address", "ip-address", "ip"))
+            existing.ipv6_address = _s(_pick(row, "ipv6-address", "ipv6_address"))
             existing.ne_type = _s(_pick(row, "type", "ne-type"))
             existing.device_level = _s(_pick(row, "device-level"))
             existing.host_name = _s(_pick(row, "host-name"))

tests/test_ume_sync.py

@@ -149,6 +149,7 @@ class UmeSyncServiceTests(unittest.TestCase):
                         "name": "ne1",
                         "user-label": "网元1",
                         "ip-Address": "10.0.0.1",
+                        "ipv6-address": "2001:db8::1",
                         "type": "A",
                         "device-level": "Access",
                         "host-name": "host-1",
@@ -172,6 +173,7 @@ class UmeSyncServiceTests(unittest.TestCase):
         self.assertEqual(ne.device_level, "Access")
         self.assertEqual(ne.host_name, "host-1")
         self.assertEqual(ne.hardware_version, "V1")
+        self.assertEqual(ne.ipv6_address, "2001:db8::1")
 
     def test_sync_inventory_marker_pagination(self):
         class _C:

web/src/types.ts

@@ -100,6 +100,7 @@ export type UmeNeItem = {
   ne_name: string;
   user_label: string;
   ip_address: string;
+  ipv6_address?: string;
   ne_type: string;
   device_level?: string;
   host_name?: string;