refactor(settings): drop source line numbers from the settings catalog

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

app/application/settings/contract.py

@@ -138,7 +138,6 @@ class SettingSpec:
     :param sensitive: 是否包含需要脱敏展示的敏感值
     :param systemconfig_key: 数据库配置对应的枚举键；运行配置时为 None
     :param source_file: 声明该设置的源文件路径，便于追溯
-    :param source_line: 设置声明的源码行号；无法定位时为 0
     """
 
     key: str
@@ -160,7 +159,6 @@ class SettingSpec:
     sensitive: bool = False
     systemconfig_key: Optional[SystemConfigKey] = None
     source_file: str = ""
-    source_line: int = 0
 
 
 @dataclass(frozen=True, slots=True)
@@ -648,7 +646,6 @@ def build_setting_specs() -> tuple[dict[str, SettingSpec], dict[str, SettingSpec
             ),
             sensitive=is_secret_setting_key(key),
             source_file=str(metadata.get("source_file") or ""),
-            source_line=int(metadata.get("source_line") or 0),
         )
 
     system_specs: dict[str, SettingSpec] = {}
@@ -686,7 +683,6 @@ def build_setting_specs() -> tuple[dict[str, SettingSpec], dict[str, SettingSpec
             sensitive=contract.sensitive,
             systemconfig_key=item,
             source_file=str(source_metadata.get("source_file") or ""),
-            source_line=int(source_metadata.get("source_line") or 0),
         )
     return core_specs, system_specs
 

app/application/settings/service.py

@@ -391,7 +391,6 @@ class SystemSettingsService:
             ),
             "source": {
                 "file": spec.source_file,
-                "line": spec.source_line,
             },
         }
         if include_schema:

app/schemas/types.py

@@ -426,7 +426,7 @@ class SystemConfigKey(Enum):
     MediaServers = "MediaServers"
     # 消息通知配置
     Notifications = "Notifications"
-    # App 中心推送自动接入凭据，业务内部维护且不进入通知渠道配置
+    # App 中心推送自动接入的内部凭据状态；按服务地址隔离，不通过通知渠道配置下发
     AppPushCredentials = "AppPushCredentials"
     # 通知场景开关设置
     NotificationSwitchs = "NotificationSwitchs"

scripts/generate_system_settings_catalog.py

@@ -162,7 +162,7 @@ def _extract_model_fields(
     default_group: str | None = None,
 ) -> dict[str, dict[str, Any]]:
     """
-    提取 Pydantic 配置模型字段的说明、分类和源码位置。
+    提取 Pydantic 配置模型字段的说明、分类和源文件。
     """
     module, lines = _load_module(path)
     class_node = _find_class(module, class_name)
@@ -186,14 +186,13 @@ def _extract_model_fields(
             "description": description,
             "group": group,
             "source_file": str(path.relative_to(PROJECT_ROOT)),
-            "source_line": node.lineno,
         }
     return results
 
 
 def _extract_systemconfig_fields(path: Path) -> dict[str, dict[str, Any]]:
     """
-    提取 SystemConfigKey 枚举值的业务说明和源码位置。
+    提取 SystemConfigKey 枚举值的业务说明和源文件。
     """
     module, lines = _load_module(path)
     class_node = _find_class(module, "SystemConfigKey")
@@ -207,7 +206,6 @@ def _extract_systemconfig_fields(path: Path) -> dict[str, dict[str, Any]]:
             "enum_name": field_name,
             "description": " ".join(_preceding_comments(lines, node.lineno, exclude_sections=False)).strip(),
             "source_file": str(path.relative_to(PROJECT_ROOT)),
-            "source_line": node.lineno,
         }
     return results
 
@@ -272,15 +270,19 @@ def generate_catalog() -> dict[str, Any]:
     }
 
 
+def render_catalog() -> str:
+    """
+    按稳定的键序和缩进序列化来源目录，生成与一致性测试共用同一输出格式。
+    """
+    return json.dumps(generate_catalog(), ensure_ascii=False, indent=2, sort_keys=True) + "\n"
+
+
 def main() -> int:
     """
     写入格式稳定的系统设置来源目录。
     """
     OUTPUT_PATH.parent.mkdir(parents=True, exist_ok=True)
-    OUTPUT_PATH.write_text(
-        json.dumps(generate_catalog(), ensure_ascii=False, indent=2, sort_keys=True) + "\n",
-        encoding="utf-8",
-    )
+    OUTPUT_PATH.write_text(render_catalog(), encoding="utf-8")
     print(f"generated {OUTPUT_PATH.relative_to(PROJECT_ROOT)}")
     return 0
 

tests/test_system_settings_contract.py

@@ -20,6 +20,7 @@ from app.application.settings.contract import (
 )
 from app.runtime.config import Settings
 from app.schemas.types import SystemConfigKey
+from scripts import generate_system_settings_catalog as catalog_generator
 
 
 def test_subscription_search_strategy_contract_declares_three_choices() -> None:
@@ -51,7 +52,6 @@ def test_settings_contract_covers_every_declared_source() -> None:
         assert spec.description
         assert spec.group
         assert spec.source_file
-        assert spec.source_line > 0
         schema = build_value_schema(spec)
         assert schema.get("description") == spec.description
         assert isinstance(schema, dict)
@@ -227,3 +227,12 @@ def test_system_setting_operations_expose_the_three_stage_contract() -> None:
     update_body_ref = branches["config.system.update"]["properties"]["body"]["$ref"]
     update_body = schema["$defs"][update_body_ref.rsplit("/", 1)[-1]]
     assert "expected_revision" in update_body["properties"]
+
+
+def test_system_settings_catalog_matches_source_declarations() -> None:
+    """
+    来源目录必须由生成脚本从源码注释产出；手工修改目录或改注释后未重新生成都会在这里失败。
+    """
+    assert catalog_generator.OUTPUT_PATH.read_text(encoding="utf-8") == catalog_generator.render_catalog(), (
+        "请运行 python scripts/generate_system_settings_catalog.py 重新生成系统设置来源目录"
+    )