抽离公共状态组件

pages/mall/admin/docs/UNI_APP_X_PAGE_FIX_GUIDE.md

@@ -2151,7 +2151,41 @@ curl -i -X OPTIONS "http://192.168.1.61:9122/rest/v1/ml_coupon_templates?select=
 1. **统一数据源 (Single Source of Truth)**：一旦存在后台建表规范 (如 `CONSUMER_DB_DOC`)，前端 `interface` 层应100%镜像字段名，规避繁琐的字段隐射。
 2. **渐进式数据增强 (Progressive Data Enhancement)**: 表格展示优先处理 `loadData`，并引入 `buildParentOptions` 把平铺的数据（Flat Data）映射到 `tree` 组件或下拉框（Select/Picker）。
 3. **细节决定体验**: 在处理 `div`/`view` 改写的组件时，必须补充缺失的交互态（鼠标悬浮、点击动效、内部绝对居中对齐）。
+4. **组件化复用 (Componentization)**: 对于管理后台高频使用的 UI 元素（如状态开关），必须抽取为全局或业务组件（如 `StatusSwitch`），确保交互一致性，支持自定义文字（开启/显示、关闭/隐藏）并简化外部代码量。
 
 ---
 
-这个指南现在涵盖了 uni-app-x 项目开发中最常见的 31 类问题（包含数据源集成实战），为后续开发提供了完整的故障排除和标准化指导。 🚀
+## 🎯 阶段十七: 全局 UI 组件化与标准化 (StatusSwitch 实战)
+
+### **背景与目标**
+
+为了消除管理后台各子页面中“状态开关”实现不统一（样式各异、交互逻辑分散）的问题，本阶段实施了全局 `StatusSwitch` 组件的封装与存量页面自动化替换。
+
+### **核心技术实现**
+
+#### **1. 业务组件封装 (`StatusSwitch.uvue`)**
+
+- **双向绑定**: 完美支持 `v-model` (uts 模式下的 `modelValue`)。
+- **自定义语义化**: 通过 `activeText` 和 `inactiveText` 区分不同场景（如：开启/关闭、显示/隐藏、启用/禁用）。
+- **像素级布局对齐**:
+  - 强制 `line-height` 等于容器高度 (24px)，解决 uts 环境下文本垂直居中的顽疾。
+  - 响应式 `switch-dot` 偏移逻辑，确保开关滑块在开启态精确到位。
+  - 顶部容器追加 `cursor: pointer;` 增强 Web/H5 端的交互反馈。
+
+#### **2. 存量代码“手术级”替换**
+
+针对以下高频场景完成了组件替换：
+
+- **商品分类 (`classification/index.uvue`)**: 剔除冗余的 20+ 行 CSS，简化模板结构。
+- **商品标签 (`labels/index.uvue`)**: 同时支持“状态”和“移动端展示（显示/隐藏）”两种不同语义。
+- **商品保障 (`protection/index.uvue`)**: 统一各页面视觉断点。
+
+### **标准化规范 (开发红线)**
+
+- **禁止内联开关样式**: 凡涉及状态切换的开关，严禁在页面级定义 `.switch-mock` 或 `.status-switch-mini`。必须统一导入并使用 `@/components/StatusSwitch.uvue`。
+- **接口同步**: 必须通过 `v-model` 绑定数据项属性，并在 `@change` 事件中通过 Supabase 完成数据库状态回写，确保 UI 与持久层同步。
+- **文字对齐**: 任何时候文字都应在开关中央水平垂直居中，禁止出现文字偏上或偏下的视觉瑕疵。
+
+---
+
+这个指南现在涵盖了 uni-app-x 项目开发中最常见的 32 类问题（包含全局组件化最佳实践），为后续开发提供了完整的故障排除和标准化指导。 🚀