saasshop/docs/admin-ui/ant-design-pro-mapping.md

Ant Design Pro 风格对齐：SaaSShop（总台管理）落地映射

目标：在不引入 React/构建链的前提下，借鉴 Ant Design Pro 的信息层级、布局与交互模式，形成一套可复用、可测试、可持续演进的后台 UI 规范。

参考文档：

• Ant Design Pro 文档总览：https://pro.ant.design/zh-CN/docs/overview
• ProComponents：
  • ProLayout：https://procomponents.ant.design/components/layout/
  • ProForm：https://procomponents.ant.design/components/form/
  • ProTable：https://procomponents.ant.design/components/table/
  • ProList：https://procomponents.ant.design/components/list/
  • ProDescriptions：https://procomponents.ant.design/components/descriptions/

1. 我们当前的约束

• 技术栈：Laravel + Blade + 少量原生 JS（public/js/admin.js），无构建链。
• 交付要求：页面“无 JS 也可用”，JS 只做渐进增强。
• 治理要求：
  • 信息降噪：减少重复入口/重复大标题/重复按钮。
  • 快捷区“动作导向”：默认只放“点完能做事”的治理入口，其余下沉高级筛选。
  • 必须可测试：核心 UI 结构用 data-role + Feature Test 锁住。

2. Ant Design Pro 关键模式（抽象）

2.1 ProLayout（布局）

• 顶部导航 / 侧边导航 + 内容区（PageContainer）。
• 统一页面标题、面包屑、右上角操作区。

在 SaaSShop 的落地：

• resources/views/admin/layouts/app.blade.php：顶部导航（TopNav）作为主菜单（已落地）。
• 页面内容区统一使用：PageHeader + KPI/卡片/表格。

2.2 PageContainer（页面容器）

• 标题 + 描述 + actions + tabs（可选）。

在 SaaSShop 的落地：

• 复用 .page-header 结构；后续可标准化为 Blade 组件（不强依赖）。

2.3 ProTable（检索 + 表格 + 工具区）

• Search（可折叠）
• Toolbar（批量动作/导出/创建）
• Table（列宽/固定/溢出治理）
• Alert（当前筛选条件/已选中多少条）

在 SaaSShop 的落地：

• Filters Card：<details class="filters-card" data-storage-key="..."> 作为可折叠搜索区（已在平台订单/订阅/套餐等落地）。
• Toolbar：统一 .actions + btn 系列；批量动作必须“UI 禁用 + 后端兜底 + 测试护栏”。
• Table：继续推进 table-layout: fixed、不换行、溢出提示等治理护栏。

2.4 ProForm（表单）

• 分组/分区（Card）
• 校验提示统一
• 提交按钮固定位置

在 SaaSShop 的落地：

• 表单提交统一使用 data-action="disable-on-submit"（防重复点击）。
• 表单字段逐步采用：日期 type=date、金额 step=0.01、select 选项收敛。

2.5 ProDescriptions（详情页）

• 详情页以“信息块 + 动作块”组织，而不是单个超长表单。

在 SaaSShop 的落地：

• 平台订单详情页：治理块（回执/对账/退款/同步）继续以“卡片化 + 锚点直达 + :target 高亮”维持可治理。

3. 组件化建议（不引入 React）

只做“结构/样式/交互模式”的组件化，不做 React 组件。

• Layout：TopNav（已）、PageHeader、Content Grid（two-col / kpi-grid）。
• Card：统一标题/副标题/footnote。
• Table：统一 .table-fixed / .table-actions / 空状态。
• MiniBars / MiniChart：作为“图形化 + 可点击治理”的基础图形组件。
• Collapsible：统一 <details data-storage-key="..."> + admin.js 记忆开合。

4. 实施优先级（建议）

1. 总台 Dashboard：继续按 Ant Design Pro 的“分析页”信息层级推进（北极星→漏斗→治理入口→最近订单）。
2. 平台订单/订阅/套餐列表：按 ProTable 模式统一“折叠搜索 + 工具区 + 表格”。
3. 详情页治理块：按 ProDescriptions + Card 分区，把“动作”集中到清晰区域，减少长页迷路。

5. 可测试护栏（建议）

• 所有关键结构用 data-role 标识：
  • 页面容器、卡片、快捷入口、折叠区、mini bar、关键按钮。
• 针对“容易回退”的点，增加断言：
  • 快捷入口数量（<=7）
  • 关键治理入口存在
  • back 口径不嵌套、不 escape

---

说明：这里的“Ant Design Pro 对齐”指 对齐其布局与交互范式，不直接引入其 React 组件实现。