# 移动端适配概念文档

## 功能一句话

让手机浏览器打开 X-Financial Web 时具备可导航、可对话、控件完整可点的移动端体验。

## 背景与问题

本轮目标是 Web 在手机浏览器中的适配，不是 `mobile/app` 原生应用。

当前 Web 已经有部分移动端样式，例如侧边栏抽屉、移动遮罩和报销助手工作台的弹层基础样式，但仍有两个直接影响手机使用的问题：

- 应用壳层已有 `mobileSidebarOpen` 状态和 `.mobile-hamburger-btn` 样式，却缺少真正可见的手机导航按钮。
- 报销智能体使用 Element Plus `el-dialog` 打开全屏工作台，但手机宽度下仍保留弹窗式留边和双栏工作台逻辑，底部输入区把附件、日期、计算器、输入框和发送按钮挤在一行，容易展示不全。

## 目标与非目标

### 目标

- 手机浏览器下提供明确的 Web 导航入口。
- 智能体对话在手机视口下以全屏工作台呈现，不保留弹窗留边。
- 对话主区、洞察侧栏、底部输入区在手机上不互相挤压。
- 附件、日期、差旅计算器和发送控件在窄屏下完整展示。
- 侧栏洞察在手机上转为覆盖式面板，不占用主对话宽度。
- 保持 X-Financial 企业 SaaS 风格：白底、细边框、低饱和、直角控件。

### 非目标

- 本轮不改 `mobile/app` 原生应用。
- 本轮不重写所有 Web 业务页面为移动端卡片流。
- 本轮不调整后端接口、数据库和智能体业务协议。
- 本轮不改变报销助手的会话、附件、日期和差旅计算器业务逻辑。

## 用户与场景

- 员工、财务或审批人员在手机浏览器中临时打开 Web 工作台。
- 用户通过侧边栏进入单据、预算、票据夹或智能体助手。
- 用户在报销智能体中上传附件、选择业务日期、打开差旅计算器并发送问题。

## 功能能力

### 手机导航入口

输入：

- 手机浏览器打开 Web。
- 视口宽度小于等于 `760px`。

输出：

- 页面右上角显示移动端导航按钮。
- 点击按钮打开侧边栏抽屉。
- 点击遮罩或导航项关闭侧边栏。

### 智能体全屏工作台

输入：

- 用户从工作台、单据、票据夹或预算中心打开报销智能体。
- 当前视口为手机宽度。

输出：

- `el-dialog` 使用 100dvh 全屏，占满手机浏览器可视区域。
- 工作台不再保留外边距和圆角弹窗感。
- 对话主面板独占宽度。
- 右侧洞察面板在打开时覆盖主对话，不挤压主对话宽度。

### 底部输入控件

输入：

- 用户添加附件、选择日期、打开差旅计算器或输入文本。

输出：

- 工具按钮在手机上独占一行，固定三列展示。
- 输入框和发送按钮在下一行展示。
- 日期与差旅计算器浮层改为固定底部浮层，宽度适配手机视口。
- 附件区域可滚动，避免把输入区挤出屏幕。

## 方案设计

### Web 壳层

- 在 `AppShellRouteView.vue` 增加 `.mobile-hamburger-btn` 模板节点。
- 复用现有 `mobileSidebarOpen` 状态和遮罩关闭逻辑。
- 在 `app.css` 中补齐按钮默认隐藏，手机媒体查询内显示。

### 报销智能体

- 保持 `TravelReimbursementCreateView.vue` 的业务结构不变。
- 在 `travel-reimbursement-create-view-part4.css` 的手机断点中覆盖 Element Plus 弹层、工作台、布局和输入区样式。
- 手机断点下：
  - overlay padding 设为 `0`。
  - 工作台 `height/min-height` 使用 `100dvh`。
  - `assistant-layout` 改为单列。
  - `insight-panel-shell` 改为绝对定位覆盖面板。
  - `composer-row` 改为两行网格布局。

## 算法与公式

当前功能不涉及显式数学公式。

核心断点规则：

```css
@media (max-width: 760px) {
  /* phone browser layout */
}
```

## 测试方案

- 静态回归测试：`node --test web/tests/app-shell-mobile-browser.test.mjs`。
- Web 构建：`npm.cmd --prefix web run build`。
- 手机视口浏览器验证：
  - 以 390x844 或相近视口打开 Web。
  - 验证导航按钮可见且侧栏可打开。
  - 打开报销智能体，验证工作台占满手机视口。
  - 验证底部附件、日期、差旅计算器、输入框和发送按钮完整展示。
  - 打开洞察面板，验证其覆盖展示而不是挤压主对话。

## 指标与验收

- `mobile/app` 无本轮改动。
- 手机浏览器下 Web 存在可点击导航入口。
- 报销智能体不再呈现带留边的弹窗效果。
- 底部输入工具控件不被挤出屏幕。
- 定向静态测试通过。
- Web 构建通过。

## 风险与开放问题

- 其他业务页面仍可能存在表格密度过高的问题，需要按页面继续做字段折叠或卡片化。
- 一些二级确认弹窗、票据预览和日期控件需要后续逐页检查。
- 手机浏览器地址栏收起/展开会改变视口高度，后续应继续用真实设备补充验证。