01 · 代码结构与子系统
一、入口 Fragment
LightsSettingsFragment（.../lights/LightsSettingsFragment.java）
@VoiceSearchProvider
@RouterProvider(path = CarSettingsJump.CarLightLockSettings.LIGHT_URI_PATH)
@Module(SettingsConstant.TAG_Light)
@MonitorFragment
public class LightsSettingsFragment extends AudioControlSettingsFragment
implements IPageRouteHandler {
@Override public String getPageAlias() { return PageAlias.PAGE_LIGHT; }
@Override public int getPreferenceScreenResId() { return R.xml.miauto_lights_settings_fragment; }
@Override public BaseRightFragment getRightFragment() { return new LightsRightFragment(); }
@Override public List<Integer> getPreferenceKeyResIdsToRemove() { /* 8 条配置裁剪规则 */ }
}继承链：LightsSettingsFragment → AudioControlSettingsFragment（提供 CarAudioControlManager）→ TopLevelSettingsFragment。注意它比 VehicleBody 多继承了 AudioControlSettingsFragment（带音频控制能力）。
分包异常（重要）：氛围灯 Controller 跨 3 个包（历史命名混乱）：
miauto.lights—— 外部灯 + 氛围灯总开关/模式/颜色模式miauto.display—— 取色板/主题（ColorPickManager/ColorPickController/DoubleColor*）micar.settings.display（⚠️根前缀不同）—— 动态效果/亮度/脚部灯/迎宾/夜间减弱
LightsRightFragmentController 也在 miauto.vehicle 包（与 Fragment 不同包）。
二、Controller 继承体系
根：CarPropertyMgrPreferenceController<V>。按 UI 形态：
BaseVehicleTabPreferenceController（NewTabPreference，多档位）BaseVehicleNewSwitchPrefController（开关）BaseVehicleProgressPrefController<SliderPreference>（滑杆）CircleImageTabPreferenceController（圆形主题 Tab，氛围灯专用，base/settingsVehicleLib）BaseAtmosphereModeSubItemTabPrefController（氛围灯模式子项基类）
异常：FogLightButtonController 跳过 Base 层，直接继承 CarPropertyMgrPreferenceController<MiCarLoadingButtonPreference>。
三、外部灯 Controller（11 个，miauto.lights 包）
| Controller | 基类 | 信号 | 功能 |
|---|---|---|---|
ExteriorLightsTabLayPreferenceController | Tab | HEADLIGHT + FRONT_POSITION_LAMP_CONFIG + EXTERIOR_LIGHT_FUNCTION_SET_NOT_AVAILABLE_REASON | 外灯总开关 4 档（OFF/位置灯/近光/AUTO），按 reason 置灰/二次确认 |
FogLightButtonController | 直接 CarPropertyMgr | FOG | 后雾灯按钮（带 loading） |
HeadLightsDelayTabLayoutPrefController | Tab | HEADLIGHT_DELAY | 大灯延时（OFF/15/30/60s） |
HeadLightsHeightTabLayoutPrefController | Tab | HEADLIGHT_HEIGHT | 近光高度 4 档（⚠️复用 ExteriorLightMode 常量当索引，语义错位） |
HighBeamAutoAdjustPrefController | Switch | ADAPT_HIGH_BEAM_SWITCH | 自适应远光（isAHBHighBeamConfig 时改文案为”自动远光”） |
PositionA2LAMPSwitchController | Switch | A2_POSITION_LAMP | 白天保持十字灯（dependKey=外灯总开关，不可用时按 reason toast） |
LightAutoCancelTurnPrefController | Switch | LIGHT_AUTO_CANCEL_TURN + _UNAVL_RSN | 转向灯自动取消（按 reason 弹 4 类 toast） |
KunLunWelcomeLightSwitchController | Switch | WELCOME_LIGHT | 昆仑迎宾灯（OFF/BRIEF 二值 Switch） |
WelcomeLightTabLayoutPrefController | Tab | WELCOME_LIGHT | 通用迎宾灯 4 档（OFF/BRIEF/GRACE/CRAZY） |
ReadingLampTabLayPrefController | Tab | READING_LEAM（⚠️拼写错，应为 LAMP） | 阅读灯（OFF/ON/AUTO） |
KeyBgLightLevelPrefController | Progress | KEY_BG_LEVEL | 按键背光亮度滑杆 |
四、氛围灯 Controller（跨 3 包）
总开关/模式层（miauto.lights）
| Controller | 信号 | 功能 |
|---|---|---|
AtmosphereLightTabLayoutPrefController | MOOD_LIGHT_TRIGGER | 总开关（OFF/ON/AUTO），父信号驱动子项显隐 |
AtmosphereModeTabPrefController | MOOD_LIGHT_MODE_SETTINGS | 模式（常亮/呼吸/音乐），ViewModel 推 ModeData |
AtmosphereColorModeTabPrefController | AMBIENT_LIGHT_THEME_MODE_STATUS | 颜色模式（单色/双色/自定义，仅 26A） |
BaseAtmosphereModeSubItemTabPrefController | (抽象基类) | 子项按模式显隐：子类实现 getVisibleAtmosphereMode() |
颜色/主题层（miauto.display）
| Controller | 信号 | 功能 |
|---|---|---|
DisplayAtmosphereThemeTabLayPreferenceController | MOOD_LIGHT_THEME_SETTINGS | 非 26A 主题（6 圆形：THEME1-5+CUSTOM） |
SingleColorTabLayPreferenceController | MOOD_LIGHT_THEME_SETTINGS | 26A 单色主题（5 圆形） |
DoubleColorTabLayPreferenceController | AMBIENT_LIGHT_BICOLOUR_THEME_STATUS | 26A 双色主题（5 圆形） |
ColorPickController | ATMOSPHERE_COLOR | 非 26A 单层取色板 |
DoubleColorPickController | ATMOSPHERE_COLOR + _LOWER + _SYNC | 26A 双层取色板（组合 2 个 SingleColorPickController） |
SingleColorPickController | (非 Controller，子部件) | 双层取色板的单层单元，由 ColorPickManager 路由 |
ColorPickManager | (object 单例) | 双拼色同步中枢：按下标路由 + 位掩码屏蔽 + 延时回弹 |
AtmosphereLightSyncReceiver | (广播) | 跨进程同步上下层色（action mi.car.settings.action.ATMOSPHERE_LIGHT_SYNCHRONIZE） |
动态效果层（micar.settings.display）
| Controller | 信号 | 功能 |
|---|---|---|
AtmosphereLightBrightnessProgressPrefController | MOOD_LIGHT_BRIGHTNESS | 亮度滑杆 1-100（仅常亮模式） |
LightBreathStateTabPrefController | MOOD_LIGHT_BREATH_STATE | 呼吸（慢/快，仅呼吸模式） |
MusicRhythmTabPrefController | MOOD_LIGHT_RHYTHM_TYPE | 律动（保持当前色/跟随封面，仅音乐模式） |
WelcomeLightSwitchPrefController | WELCOME_LIGHT_SWITCH | 上下车迎宾联动开关 |
AmbientLightDimmingDownSwitchPrefController | AMBIENT_LIGHT_DIMMING_DOWN_SWITCH | 夜间氛围灯减弱 |
FootLightTabLayoutPrefController | FOOT_LIGHT_TAB | 照脚灯（仅照明/跟随氛围） |
五、右栏车模可视化（核心特色）
LightsRightFragment（继承 BaseScrollModelRightFragment）—— 左滚联动右栏：
- 滚到外灯区 → 显示外灯点亮状态车模图（6 种：雾灯+远光/雾灯+近光/远光/近光/位置灯/默认）
- 滚到氛围灯区 → 车模 + 颜色遮罩（
ColorMatrixColorFilter）+ 呼吸动画（慢 2000ms/快 1000ms）+ Lottie 律动动画
LightsRightFragmentController（继承 FragmentVehicleController）订阅两批信号：
- 外灯状态（Warning 域 POSITION/LOW/HIGH/FOG_BEAM_STATUS）→
setExternalLightsDataImgRes - 氛围灯（MOOD_LIGHT_TRIGGER/ATMOSPHERE_COLOR/主题/双色/模式/律动）→
updateAtmosphereColor
updateAtmosphereColor() 关键逻辑：
- 音乐律动态（
MUSIC_RHYTHM_STATE=1 && 模式=MUSIC && 律动=跟随封面）→ 用ATMOSPHERE_COLOR_IN_RHYTHM(专辑封面色) - 双层（isDualLayerAtmosphereLightEnable）→ 按颜色模式分 SINGLE/BICOLOR/CUSTOM 映射颜色 →
setUpper/LowerAtmosphereMaskColor - 单层 → 用 MOOD_LIGHT_THEME_SETTINGS（CUSTOM 用 ATMOSPHERE_COLOR）→
setAtmosphereMaskColor
右栏布局按 W-HUD 选：micar_ui_lights_right_fragment（带 HUD）或 _low_no_hud。含车模底图 + 单层/双层遮罩 + Lottie 律动。
六、主 XML 完整结构（25 项）
miauto_lights_settings_fragment.xml，根 key=psk_settings_lights_entry，3 大 Category：
| Category | 项 |
|---|---|
外部灯（pk_settings_quickctrl_light_category） | 外灯总开关 · 后雾灯 · 大灯延时 · 近光高度 · A2 位置灯(dependKey) · 自适应远光 · 转向灯自动取消 · 迎宾灯(KunLun/通用二选一) · 迎宾光毯 · 迎宾尾翼随动 |
氛围灯（pk_settings_display_atmosphere_lights_category） | 总开关 · 模式(dependKey) · 亮度 · 呼吸 · 律动 · [非26A] 主题6圆形+取色板 / [26A] 颜色模式+单色+双色+双层取色板 · 上下车迎宾 · 夜间减弱 · 照脚灯 |
更多（pk_lights_more_category） | 阅读灯 · 按键背光亮度 |
26A 组（
pk_settings_display_atmosphere_light_26A）与非 26A 组（_default）互斥，由isDualLayerAtmosphereLightEnable裁剪其一。
七、AtmosphereData ViewModel（解耦总线）
氛围灯 Controller 间通过 6 个 LiveData 解耦通信（AtmosphereData.java）：
Theme（主题切换 → 通知 ColorPickController 刷光标）TabChange（取消延迟任务）ModeData（模式 → 通知子项显隐）MusicRhythmType（律动类型 → 跟随封面时隐藏颜色设置）ColorModeData（颜色模式 → 通知单/双色/自定义显隐）ThemeName（主题名 → 颜色模式标题显示）
八、代码异味清单（对抗验证）
| # | 异味 |
|---|---|
| 1 | 分包跨 3 个（micar.settings.display 根前缀异常） |
| 2 | 迎宾灯三态歧义（3 Controller 绑 2 个不同信号） |
| 3 | HeadLightsHeight 滥用 ExteriorLightMode 常量当高度索引 |
| 4 | READING_LEAM 拼写错（LAMP）；BEAM_AUTOADJUST 命名误导（值=氛围灯模式） |
| 5 | FogLightButtonController 跳过 Base 层直接继承 CarPropertyMgr |
| 6 | ColorPickController(非26A) 与 DoubleColorPickController(26A) 颜色逻辑重复实现 |
| 7 | AtmosphereLightBrightnessProgressPrefController 因非 Tab 不能继承 BaseAtmosphereModeSubItem，复制了模式判断逻辑 |
| 8 | SingleColorPickController 命名误导（非 PreferenceController） |
| 9 | LightsRightFragmentController 与 Fragment 不同包 |
| 10 | 多处 AI(claude) 生成标记（2026-04/05/06，外灯 reason 置灰、车模 prefKey 生命周期） |