---
name: new-page
description: 根据设计截图和菜单入口名称，在 AirLogistics 项目中创建新的业务页面。自动分析截图判断页面类型（6种典型类型之一），规划所需文件，然后完整实现（Kotlin + XML + 路由注册 + 菜单接入）。当用户说"创建页面"、"新建页面"、"实现这个页面"、"做这个页面"或提供设计截图要求开发时触发。
---

# 新建业务页面

根据设计截图和菜单入口名称，在 AirLogistics 项目中完整创建一个新的业务页面。

## 前置要求

用户需要提供：
1. **设计截图**（必须）— 页面 UI 设计图
2. **菜单入口名称**（必须）— 页面在首页菜单中显示的名称
3. **所属模块**（可选）— 如 module_gjj（国际进港）、module_gjc（国际出港）等，可从截图标题推断

## 执行步骤

### 第 1 步：分析截图，判定页面类型

仔细阅读截图，提取以下信息：

1. **页面标题**（标题栏文字）
2. **搜索区字段**（每个搜索控件的 hint 文本、类型：日期/输入/下拉/扫码）
3. **列表项字段**（每个数据字段的标签名和显示格式）
4. **底部操作栏**（统计项 + 操作按钮）
5. **特殊交互**（全选、展开/收起、右箭头、子列表等）

然后对照 CLAUDE.md 中的 **6 种典型页面类型**判定：

| 类型 | 关键特征 | 判定依据 |
|------|----------|----------|
| **类型 1：列表查询页** | 搜索 + 分页列表 + 底部统计 | 无全选、无勾选，纯查看 |
| **类型 2：多选列表 + 批量操作页** | 类型 1 + 全选按钮 + 飞机图标选中态 + 操作按钮 | 有全选、有批量操作按钮（如"清除提货"） |
| **类型 3：嵌套多选列表页** | 类型 2 + 子列表（展开/收起）+ 主子联动全选 | 有展开按钮、列表项内含子 RecyclerView |
| **类型 4：Tab 详情页** | 自定义 Tab 栏 + ViewPager2 + 多 Fragment | 有 Tab 切换、无列表搜索 |
| **类型 5：编辑表单页** | ScrollView + PadDataLayoutNew 表单 + 保存/取消 | 有可编辑字段、有保存按钮 |
| **类型 6：添加表单页** | 类型 5 + 输入回调 + 实时计算 | 有 setRefreshCallBack 联动 |

**向用户确认**判定结果，格式：

```
📋 页面分析结果：

页面标题：XXX
页面类型：类型 N — XXXX
所属模块：module_xxx

搜索条件：
  1. XXX（DATE）
  2. XXX（SPINNER）
  3. XXX（INPUT + 扫码）

列表字段（第一行）：XXX | XXX | XXX
列表字段（第二行）：XXX | XXX | XXX

底部操作：全选 + 统计（合计/总件数/总重量） + [操作按钮名称]

是否正确？确认后开始实现。
```

### 第 2 步：查找参考模板并提取 UI 设计规范

根据判定的页面类型，在项目中找到**同类型的最新参考实现**，并严格提取 UI 设计规范。

**查找策略**（优先级从高到低）：
1. 优先查找**最近提交的同类型页面**（最新的页面代表最新的 UI 规范）
2. 其次在**同模块**内查找同类型页面
3. 最后在 **module_gjc**（国际出港）查找

**最新典型参考页面**（2024年后新增，代表当前 UI 规范）：

| 页面类型 | 参考页面 | 布局文件 |
|----------|----------|----------|
| 列表查询页 | 航班查询列表 | `activity_flight_query_list.xml` / `item_flight_query_list.xml` |
| 列表查询页 | 日志查询页 | `activity_log_query.xml` / `item_log_query.xml` |
| 详情页 | 航班查询详情 | `activity_flight_query_details.xml` |
| 详情页 | 日志详情 | `activity_log_detail.xml` |

**必须读取的参考文件**：
- 上述最新典型参考页面中**与当前页面类型匹配的布局 XML**（Activity 布局 + Item 布局）
- 对应的 Activity、ViewModel、ViewHolder Kotlin 代码
- Dialog（如有批量操作弹窗）

**UI 设计规范提取（必做）**：

读取参考布局后，必须逐一确认以下规范项，并在开发计划中明确列出：

| 规范项 | 必须确认的内容 |
|--------|---------------|
| 页面背景色 | 根容器 `background` 属性（新规范：`@color/color_f2`） |
| 搜索区样式 | 使用的搜索控件类型、间距、布局方式 |
| 搜索按钮样式 | 图标资源、尺寸、style（新规范：`@drawable/img_search`，36dp） |
| 底部栏背景色 | 背景色 + 文字颜色（新规范有两种变体） |
| 底部栏文字样式 | 字号、粗细、颜色 |
| 列表项背景 | 背景、间距、padding |
| 详情页卡片样式 | 背景、圆角、padding、行间距 |
| 表单控件 | 使用 PadDataLayoutNew（非旧版 PadDataLayout） |

**同时检查**：
- 该页面需要的**下拉列表数据源 API** 是否已存在（代理人、特码等）
- 该页面需要的 **Bean 类**是否已存在，或需要新建
- `ARouterConstants` 中是否已有对应路由常量
- `Constant.AuthName` 中是否已有对应权限名

### 第 3 步：制定文件清单

列出所有需要**新建**和**修改**的文件。

**新建文件清单**（根据页面类型调整）：

| 类别 | 文件 | 路径 |
|------|------|------|
| Bean | `XxxBean.kt`（如需） | `module_base/.../bean/` |
| Activity | `XxxActivity.kt` | `module_xxx/.../activity/` |
| ViewModel | `XxxViewModel.kt` | `module_xxx/.../viewModel/` |
| ViewHolder | `XxxViewHolder.kt` | `module_xxx/.../holder/` |
| Dialog | `XxxDialogModel.kt`（如需） | `module_xxx/.../dialog/` |
| Activity 布局 | `activity_xxx.xml` | `module_xxx/.../res/layout/` |
| Item 布局 | `item_xxx.xml` | `module_xxx/.../res/layout/` |
| Dialog 布局 | `dialog_xxx.xml`（如需） | `module_xxx/.../res/layout/` |

**修改文件清单**（固定）：

| 文件 | 修改内容 |
|------|----------|
| `Api.kt` | 添加 API 接口方法 + import |
| `ARouterConstants.kt` | 添加路由常量（如不存在） |
| `Constant.kt` | 添加 AuthName 常量（如不存在） |
| `AndroidManifest.xml` | 注册 Activity |
| `HomeFragment.kt` | 添加菜单项 + 点击路由处理 |
| 旧版 Activity（如有） | 注释掉 `@Route` 注解避免冲突 |

### 第 4 步：创建 Bean（如需）

如果截图中的列表字段与现有 Bean 不匹配，创建新的 Bean 类。

**规则**：
- 放在 `module_base/.../bean/` 目录下
- 如果是类型 2/3（多选），必须包含 `ObservableBoolean` 选中状态：

```kotlin
val checked: ObservableBoolean = ObservableBoolean(false)
var isSelected: Boolean
    get() = checked.get()
    set(value) = checked.set(value)
```

- 字段类型映射：数字用 `Int/Long/Double`，文本用 `String = ""`，时间用 `String = ""`
- 在 `Api.kt` 的 import 区按字母顺序添加 import

### 第 5 步：添加 API 接口

在 `Api.kt` 中添加 API 方法。

**标准 API 组合**（根据页面需要选取）：
- `getXxxList(@Body)` — 分页查询，返回 `PageInfo<XxxBean>`
- `getXxxTotal(@Body)` — 分页合计，返回 `BaseResultBean<ManifestTotalDto>`
- 批量操作 API — 返回 `BaseResultBean<Boolean>`
- 下拉列表 API（代理人、特码等）— 如不存在则添加

**API 路径命名**：先使用 `ModuleName/methodName` 格式占位（如 `IntImpPickUpRecord/pageQuery`），后续由第 13 步替换为真实接口路径

### 第 6 步：添加路由和权限常量

1. 在 `ARouterConstants.kt` 添加路由（如不存在）：
```kotlin
const val ACTIVITY_URL_XXX = "/module/XxxActivity"
```

2. 在 `Constant.kt` 的 `AuthName` 中添加权限名（如不存在）：
```kotlin
const val XxxPage = "AppXxxPage"
```

### 第 7 步：创建 ViewHolder

根据 item 布局创建 ViewHolder。

**类型 1**：基础绑定
**类型 2**：增加图标点击切换 `checked` 状态
**类型 3**：增加子列表 `setCommonAdapter` + 展开按钮 + 父子联动

### 第 8 步：创建 ViewModel

**必须包含的元素**（根据截图）：
- 搜索条件 `MutableLiveData`（与搜索区对应）
- 下拉列表数据源 `MutableLiveData<List<KeyValue>>`
- 统计字段 `MutableLiveData<String>`
- 适配器配置：`itemViewHolder` + `itemLayoutId`
- `searchClick()` 方法
- `getData()` override：调用列表 API + 统计 API

**类型 2 额外**：`isAllChecked` + `checkAllClick()` + 批量操作方法
**类型 3 额外**：`isAllExpanded` + `toggleAllExpand()` + 联动全选逻辑

**下拉列表初始化**：
- 代理人：`DictUtils.getAgentList()` / `NetApply.api.getIntImpAgentList()` / `getIntExpAgentList()`
- 特码：`DictUtils.getSpecialCodeList(flag, ieFlag, parentcode)`
- 其他字典：`DictUtils` 或自定义 API

### 第 9 步：创建布局文件

**⚠️ 重要：所有布局必须严格遵循最新 UI 设计规范，参照第 2 步中提取的规范项。**

---

#### 新版 UI 设计规范（强制执行）

**1. 页面背景色**：
```xml
<!-- 根容器必须使用 color_f2 背景色 -->
<LinearLayout
    android:background="@color/color_f2"
    android:orientation="vertical">
```

**2. 搜索区规范**：
```xml
<!-- 搜索区：marginHorizontal=10dp, marginTop=10dp, gravity=center_vertical -->
<LinearLayout
    android:layout_marginHorizontal="10dp"
    android:layout_marginTop="10dp"
    android:gravity="center_vertical">

    <!-- 搜索控件使用 PadSearchLayout -->
    <PadSearchLayout
        type="@{SearchLayoutType.DATE}"
        hint='@{"请选择航班日期"}'
        icon="@{@drawable/img_date}"
        value="@={viewModel.date}"
        android:layout_width="0dp"
        android:layout_weight="1" />

    <!-- 搜索按钮：img_search 图标，36x36dp，padding=2dp -->
    <LinearLayout
        android:layout_width="0dp"
        android:layout_weight="1"
        android:gravity="center_vertical|start"
        android:paddingHorizontal="24dp">
        <ImageView
            android:layout_width="36dp"
            android:layout_height="36dp"
            android:padding="2dp"
            android:onClick="@{()-> viewModel.searchClick()}"
            android:src="@drawable/img_search" />
    </LinearLayout>
</LinearLayout>
```

**3. 底部统计栏规范**（两种变体，根据截图选择）：

**变体 A — 深蓝色底部栏**（多数列表页使用）：
```xml
<LinearLayout
    android:layout_height="50dp"
    android:background="@color/color_bottom_layout"
    android:gravity="center_vertical"
    android:paddingHorizontal="15dp">
    <TextView
        android:text='@{"合计："+viewModel.count+"条"}'
        android:textColor="@color/white"
        android:textSize="18sp"
        android:textStyle="bold" />
</LinearLayout>
```

**变体 B — 白色底部栏**：
```xml
<LinearLayout
    android:layout_height="50dp"
    android:background="@color/white"
    android:gravity="center_vertical"
    android:paddingHorizontal="15dp">
    <TextView
        android:text='@{"合计:" + viewModel.count + "条"}'
        android:textColor="@color/bottom_tool_tips_text_color"
        android:textSize="18sp"
        android:textStyle="bold" />
</LinearLayout>
```

**4. 详情页/表单页规范**：
- 必须使用 **PadDataLayoutNew**（非旧版 PadDataLayout）
- 卡片背景：`@drawable/bg_white_radius_8`，padding `15dp`
- 行间距：`marginTop="8dp"`
- 三列标准布局，每列 `layout_weight="1"`
```xml
<ScrollView android:fillViewport="true">
    <LinearLayout android:padding="15dp" android:orientation="vertical">
        <LinearLayout android:background="@drawable/bg_white_radius_8"
            android:padding="15dp" android:orientation="vertical">
            <LinearLayout android:orientation="horizontal">
                <PadDataLayoutNew layout_weight="1" enable="@{false}"
                    title='@{"航班日期"}' type="@{DataLayoutType.INPUT}"
                    value='@{viewModel.dataBean.fdate}' />
                <!-- 更多列... -->
            </LinearLayout>
            <LinearLayout android:orientation="horizontal" android:layout_marginTop="8dp">
                <!-- 第二行... -->
            </LinearLayout>
        </LinearLayout>
    </LinearLayout>
</ScrollView>
```

---

#### Activity 布局完整结构

```xml
<layout>
  <data>
    <import SearchLayoutType />
    <variable viewModel />
    <variable activity />  <!-- 类型 3 或有 Dialog 操作时 -->
  </data>
  <LinearLayout background="@color/color_f2" vertical>      <!-- ← 新规范：背景色 -->
    <include title_tool_bar />
    <!-- 搜索区：marginHorizontal=10dp, marginTop=10dp -->
    <LinearLayout horizontal marginHorizontal="10dp" marginTop="10dp">
      PadSearchLayout × N + 搜索按钮(img_search, 36dp)       <!-- ← 新规范：搜索按钮 -->
    </LinearLayout>
    <!-- 列表 -->
    <SmartRefreshLayout> <RecyclerView /> </SmartRefreshLayout>
    <!-- 底部栏：50dp，根据截图选择深蓝/白色变体 -->          <!-- ← 新规范：底部栏 -->
    <LinearLayout height="50dp" background="..." paddingHorizontal="15dp">
      <TextView textSize="18sp" textStyle="bold" />
    </LinearLayout>
  </LinearLayout>
</layout>
```

#### Item 布局（从截图精确还原每一行每一列）

- 逐行对照截图中的字段顺序和标签文本
- 使用 `completeSpace` 对齐 Key 文本
- 运单号等关键字段用 `@color/colorPrimary`
- 类型 2/3 左侧有飞机图标：`loadImage="@{bean.checked.get() ? @drawable/img_plane_s : @drawable/img_plane}"`
- 列表项背景统一使用 `@drawable/bg_item`
- 间距统一：`marginHorizontal="15dp"`, `marginVertical="5dp"`, `padding="10dp"`

**关键原则：务必尽可能还原截图上的页面设计，不推测不假想。**

### 第 10 步：创建 Activity

**固定结构**：
```kotlin
@Route(path = ARouterConstants.ACTIVITY_URL_XXX)
class XxxActivity : BaseBindingActivity<XxxBinding, XxxViewModel>() {
    override fun layoutId() = R.layout.activity_xxx
    override fun viewModelClass() = XxxViewModel::class.java

    override fun initOnCreate(savedInstanceState: Bundle?) {
        setBackArrow("页面标题")  // 与截图标题一致
        binding.viewModel = viewModel
        binding.activity = this  // 类型 3 或有 Dialog 时

        // 类型 2/3：观察全选状态
        viewModel.isAllChecked.observe(this) { binding.checkIcon.alpha = if (it) 1.0f else 0.5f }

        // 绑定分页
        viewModel.pageModel.bindSmartRefreshLayout(binding.srl, binding.rv, viewModel, this)

        // 监听刷新事件
        FlowBus.with<String>(ConstantEvent.EVENT_REFRESH).observe(this) { viewModel.refresh() }

        // 初始化下拉列表（如有）
        viewModel.initAgentList()
        viewModel.initSpecialCodeList()

        viewModel.refresh()
    }
}
```

### 第 11 步：注册 Activity + 菜单入口

1. **AndroidManifest.xml**：在其他 gjj Activity 注册附近添加：
```xml
<activity android:name="com.lukouguoji.xxx.activity.XxxActivity"
    android:configChanges="orientation|keyboardHidden"
    android:exported="false" android:screenOrientation="userLandscape" />
```

2. **HomeFragment.kt**：
   - 在对应模块的菜单列表区添加 `RightMenu` 项（图标 + 标题）
   - 在 onClick 处理区添加路由跳转

3. **旧版 Activity**（如有）：注释掉 `@Route` 注解

### 第 12 步：编译验证

```bash
./gradlew assembleDebug
```

编译必须通过（0 errors）。如有错误，立即修复后重新编译。

### 第 13 步：查找并对接 API 接口

页面创建并编译通过后，通过"空港集团 - API 文档"Apifox MCP 工具查找真实接口，替换第 5 步中的占位路径。

**A. 基础接口查找（每次必查）：**

1. 根据页面所属业务路径（如"国际进港 → 原始舱单"），在 Apifox MCP 中按模块目录搜索
2. 查找以下基础接口：
   - **列表接口**（分页查询，如 `pageQuery`、`list`）
   - **合计接口**（统计，如 `total`、`count`、`statistics`）
   - **修改/保存接口**（如 `update`、`save`、`edit`）
   - **删除接口**（如 `delete`、`remove`）

**B. 智能接口匹配（根据页面分析）：**

3. 根据**页面类型特性**查找对应接口：
   - 类型 2（多选批量操作）→ 查找批量操作接口（如批量删除、批量确认等）
   - 类型 3（嵌套列表）→ 查找子列表相关接口
   - 类型 5/6（表单页）→ 查找详情查询接口、下拉选项字典接口
   - 类型 4（Tab 详情）→ 查找各 Tab 对应的数据接口
4. 根据**页面中的按钮和文案**，逐一匹配对应接口：
   - 例如页面有"审核"按钮 → 查找审核接口
   - 例如页面有"导出"按钮 → 查找导出接口
   - 例如页面有"打印"按钮 → 查找打印相关接口
   - 例如底部栏有"清除提货"按钮 → 查找清除提货接口
   - 例如搜索区有下拉框（代理人、状态等）→ 查找对应的字典/下拉数据接口
5. 根据**截图中可见的交互元素**，推断可能需要的接口：
   - 列表项有右箭头 → 可能需要详情接口
   - 列表项有编辑图标 → 可能需要编辑/更新接口
   - 有扫码图标 → 可能需要扫码查询接口

**C. 对接与校准：**

6. 找到接口后，更新 `Api.kt` 中的占位路径为真实路径
7. 根据接口的请求参数和返回字段结构，校准 Bean 类的字段名和类型
8. 遵循 memory 中的 API 搜索原则：不跨模块混用接口，遇到不确定的接口询问用户确认

### 第 14 步：重新编译验证

对接真实 API 后重新编译，确保无错误：

```bash
./gradlew assembleDebug
```

编译必须通过（0 errors）。如有错误，立即修复后重新编译。

## 注意事项

### UI 设计规范（强制）

- **必须使用最新 UI 规范**：不管是新增页面、覆盖旧页面还是修改旧页面，都必须完全采用最新典型参考页面的 UI 设计规范
- **页面背景色**：根容器必须使用 `@color/color_f2`（`#F2F2F2`），禁止使用旧的白色或其他背景
- **搜索按钮**：使用 `@drawable/img_search` 图标（36x36dp + padding 2dp），不使用旧的 `iv_search_action` style
- **底部栏**：高度 50dp，文字 18sp bold，根据截图选择深蓝色（`@color/color_bottom_layout` + 白字）或白色（`@color/white` + `@color/bottom_tool_tips_text_color`）
- **详情页/表单页**：必须使用 **PadDataLayoutNew**（非旧版 PadDataLayout），卡片用 `bg_white_radius_8`
- **严格匹配典型页面**：在写开发计划前，必须先读取最新典型参考页面（如航班查询列表、日志查询页等），总结并列出 UI 设计规范要点

### 通用规则

- **资源引用必须存在**：使用 drawable/color/mipmap 前确认资源存在，不存在则换用已有资源
- **import 路径查阅 CLAUDE.md**：基类和扩展函数的正确 import 路径参见开发指南的 Import 速查表
- **不创建不需要的文件**：如果截图中没有 Dialog 弹窗，不要创建 Dialog 文件
- **Bean 复用优先**：如果现有 Bean 的字段足以覆盖截图需求，直接复用
- **API 接口对接**：页面创建完成后，通过空港集团 API 文档 MCP 查找真实接口并替换占位路径。遵循 API 搜索原则，按业务模块目录查找，不跨模块混用
- **DataBinding 规则**：遵循 CLAUDE.md 中的 DataBinding 关键规则（双向绑定、字符串拼接、View 导入等）