# 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 组件实现。