# apps/frontend 前端优化计划

## 背景

本计划基于当前 `apps/frontend` 代码现状整理。当前前端使用 Vue 3、Vite、TypeScript、Vue Router、Element Plus，已开启 TypeScript strict 相关检查，路由页面基本采用动态 import，`npm run build` 当前可通过。

当前主要问题不是功能不可用，而是后台管理页面增多后，列表页重复逻辑、请求稳定性、登录态安全、构建产物治理和工程规范需要系统化优化。

## 优化目标

- 提升后台页面的可维护性和复用性。
- 减少列表页请求竞态和状态错乱风险。
- 强化管理端登录态和开发服务器安全边界。
- 规范构建产物和依赖拆包，提升缓存效果。
- 补齐 lint / format / CI 质量门禁。
- 为后续后台功能扩展降低开发成本。

## 当前观察

### 已确认现状

- `apps/frontend/package.json` 当前脚本包含 `dev`、`build`、`preview`、`typecheck`。
- `apps/frontend/tsconfig.app.json` 已开启 `strict`、`noUnusedLocals`、`noUnusedParameters` 等检查。
- `apps/frontend/src/router/index.ts` 已使用动态 import 拆分页面。
- `apps/frontend/src/lib/http.ts` 统一封装 axios 请求和后台 401 处理。
- 后台列表页普遍存在相同的 loading、error、pagination、load、reset 逻辑。
- `apps/frontend/vite.config.ts` 当前 `server.host` 与 `server.allowedHosts` 配置偏开放。
- 管理端 token 当前保存在 `localStorage`，`hasAdminSession()` 主要检查 token 是否存在。

### 构建验证

已执行：

```bash
cd apps/frontend
npm run build
```

结果：构建成功。

## 优先级 P0：安全与稳定性

### 1. 收紧 Vite dev server 访问控制

涉及文件：

- `apps/frontend/vite.config.ts`

当前配置：

```ts
server: {
  host: true,
  allowedHosts: true,
}
```

风险：

- `allowedHosts: true` 会允许任意 Host 访问开发服务。
- 如果配合公网隧道或局域网暴露，开发环境边界过宽。

建议方案：

- 默认只允许本地访问。
- 需要公网调试时通过环境变量显式开启。
- 支持 Host 白名单，例如 `VITE_ALLOWED_HOSTS`。

建议配置方向：

```ts
const allowedHosts = env.VITE_ALLOWED_HOSTS
  ? env.VITE_ALLOWED_HOSTS.split(',').map((host) => host.trim()).filter(Boolean)
  : ['localhost', '127.0.0.1']

server: {
  host: env.VITE_DEV_HOST === 'true',
  allowedHosts: env.VITE_ALLOW_ALL_HOSTS === 'true' ? true : allowedHosts,
}
```

验收标准：

- 本地 `npm run dev` 正常。
- 未设置环境变量时不默认允许任意 Host。
- 需要公网调试时可以通过环境变量开启。

### 2. 完善管理端登录态过期判断

涉及文件：

- `apps/frontend/src/utils/admin-auth.ts`
- `apps/frontend/src/router/index.ts`
- `apps/frontend/src/lib/http.ts`

当前问题：

- `hasAdminSession()` 只检查 token 是否存在。
- `expiresAt` 已存储但前端路由守卫未主动判断是否过期。
- `getAdminRole()` 在本地 role 缺失时默认返回 `operator`，权限默认值偏宽。

建议方案：

- `hasAdminSession()` 校验 token 和 expiresAt。
- token 过期时主动 `clearAdminSession()`。
- `getAdminRole()` 默认值调整为最低权限，或返回空角色并让调用方处理。
- 保持后端接口鉴权作为最终安全边界，前端仅用于体验优化。

验收标准：

- 过期 token 刷新页面会跳转登录页。
- role 缺失时不会默认获得 operator 权限。
- 401 且错误码为认证失效时仍会清理会话。

### 3. 列表请求增加竞态保护

涉及页面：

- `apps/frontend/src/views/admin/webhook-events/AdminWebhookEventsView.vue`
- `apps/frontend/src/views/admin/orders/AdminOrdersView.vue`
- `apps/frontend/src/views/admin/tasks/AdminTasksView.vue`
- `apps/frontend/src/views/admin/message-deliveries/AdminMessageDeliveriesView.vue`
- `apps/frontend/src/views/admin/users/AdminUsersView.vue`
- `apps/frontend/src/views/admin/audit-logs/AdminAuditLogsView.vue`
- `apps/frontend/src/views/admin/inventory/AdminInventoryView.vue`

当前风险：

- 用户连续查询、翻页或回车搜索时，旧请求可能晚于新请求返回并覆盖新结果。

建议方案：

- 短期使用 `requestId` 忽略过期响应。
- 中期在 HTTP 层或列表 composable 中支持 `AbortController`。

示例方向：

```ts
let latestRequestId = 0

async function loadPage(page = pagination.value.page) {
  const requestId = ++latestRequestId
  loading.value = true
  errorMessage.value = ''

  try {
    const response = await fetchList(page)
    if (requestId !== latestRequestId) return

    items.value = response.data.items
    pagination.value = response.data.pagination
  } catch (error) {
    if (requestId !== latestRequestId) return
    errorMessage.value = error instanceof Error ? error.message : '读取列表失败'
  } finally {
    if (requestId === latestRequestId) {
      loading.value = false
    }
  }
}
```

验收标准：

- 快速连续点击查询或分页时，页面最终展示最后一次请求结果。
- loading 状态不会被旧请求提前关闭。

## 优先级 P1：后台列表页复用与体验

### 4. 抽取通用 `useAdminListPage`

建议新增：

- `apps/frontend/src/composables/useAdminListPage.ts`

目标统一处理：

- `loading`
- `errorMessage`
- `items`
- `pagination`
- `loadPage`
- `resetPageAndLoad`
- 请求竞态保护
- 默认错误提示
- 默认 `pageSize`

适合改造页面：

- Webhook 日志
- 订单列表
- 任务列表
- 消息发送记录
- 审计日志
- 用户列表
- 库存列表

预期收益：

- 列表页脚本代码减少约 30% 到 50%。
- 分页、查询、错误处理行为统一。
- 后续增加 URL query 同步或请求取消时只需改一处。

验收标准：

- 至少完成 2 个代表页面改造，例如 Webhook 日志和订单列表。
- 改造后 `npm run typecheck` 与 `npm run build` 通过。

### 5. 筛选条件同步到 URL Query

适合页面：

- `AdminWebhookEventsView.vue`
- `AdminOrdersView.vue`
- `AdminTasksView.vue`
- `AdminMessageDeliveriesView.vue`
- `AdminAuditLogsView.vue`

当前问题：

- 刷新页面后筛选条件丢失。
- 无法复制当前筛选链接给其他管理员。

建议方案：

- 页面初始化时从 `route.query` 读取筛选条件和页码。
- 查询、重置、分页时使用 `router.replace()` 更新 query。
- 空筛选项不写入 URL。

验收标准：

- 刷新页面保留筛选条件。
- 分享 URL 后能恢复相同列表视图。
- 重置筛选会清理相关 query。

### 6. 统一日期范围组件

当前观察：

- 订单页已经使用 `type="daterange"`。
- Webhook、审计日志等页面仍使用两个独立日期选择器。

建议方案：

- 日志类、列表类页面统一使用 `el-date-picker type="daterange"`。
- 内部统一映射为 `dateFrom` 和 `dateTo` API 参数。

验收标准：

- Webhook 日志、审计日志、消息发送记录日期筛选交互一致。
- API 参数保持兼容。

### 7. 统一筛选触发策略

当前问题：

- 输入框通常支持 Enter 查询。
- select/date 改变后多数页面不自动查询。
- 不同列表页交互不完全一致。

建议二选一：

- 方案 A：所有筛选项变更后不自动查询，统一点击“查询”。
- 方案 B：select/date 变更自动查询，文本输入 Enter 或防抖查询。

建议优先方案 A，原因是后台列表数据量可能较大，可减少无意请求。

验收标准：

- 后台列表页筛选交互一致。
- 查询按钮与重置按钮行为一致。

## 优先级 P2：工程规范与类型质量

### 8. 增加 ESLint / Prettier

涉及文件：

- `apps/frontend/package.json`
- `apps/frontend/eslint.config.*`
- `apps/frontend/.prettierrc` 或等价配置

当前问题：

- package scripts 未提供 lint / format。
- 仅依赖 TypeScript 编译检查，无法覆盖 Vue 模板规范、Promise 处理、风格一致性等问题。

建议增加脚本：

```json
{
  "scripts": {
    "lint": "eslint . --ext .ts,.vue",
    "format": "prettier --write .",
    "format:check": "prettier --check ."
  }
}
```

建议依赖：

- `eslint`
- `@eslint/js`
- `typescript-eslint`
- `eslint-plugin-vue`
- `prettier`
- `eslint-config-prettier`

验收标准：

- `npm run lint` 可执行。
- `npm run format:check` 可执行。
- CI 至少执行 `typecheck`、`lint`、`build`。

### 9. 优化 HTTP 封装类型

涉及文件：

- `apps/frontend/src/lib/http.ts`
- `apps/frontend/src/services/**/*`

当前问题：

```ts
return http.get<ApiEnvelope<T>>(url, { params }) as unknown as Promise<ApiEnvelope<T>>
```

由于 axios interceptor 返回 `response.data`，代码使用 `as unknown as` 消除类型差异。

建议方案：

- 封装明确的 `request<T>()`。
- 统一返回 `Promise<ApiEnvelope<T>>`。
- blob 请求单独封装。

目标：

- 减少双重类型断言。
- 服务层返回值更可信。
- 错误类型可以逐步标准化。

验收标准：

- `apiGet`、`apiPost`、`apiDelete` 不再依赖 `as unknown as`。
- 现有 services 类型不退化。
- `npm run typecheck` 通过。

## 优先级 P3：构建产物与性能

### 10. 分析并治理 bundle

当前构建观察：

- 构建成功。
- 输出中出现较多 `css-*.js` 小 chunk。
- Element Plus 相关依赖和样式可能存在进一步优化空间。

建议步骤：

1. 引入 bundle 分析工具。
2. 查看 Vue、Element Plus、lodash、qrcode、dayjs 等依赖占比。
3. 评估是否需要配置 `manualChunks`。
4. 检查 Element Plus 样式自动导入是否导致过多碎片 chunk。

可选工具：

- `rollup-plugin-visualizer`
- Vite 官方构建输出分析

验收标准：

- 输出一份主要 chunk 占比结论。
- 明确是否需要手动拆分 vendor。
- 优化后首屏关键 chunk 不变大。

### 11. 稳定 vendor chunk 拆分

建议方向：

```ts
build: {
  rollupOptions: {
    output: {
      manualChunks: {
        'vue-vendor': ['vue', 'vue-router'],
        'element-plus': ['element-plus'],
      },
    },
  },
}
```

注意事项：

- 不建议盲目拆太细。
- 需要结合 bundle 分析结果决定。
- 后台页面较多时，可以考虑 admin 公共模块分组。

验收标准：

- 构建产物命名更稳定。
- 主要 vendor 包可长期缓存。
- 页面懒加载不被破坏。

## 优先级 P4：大型页面拆分

### 12. 拆分超大 Vue 文件

当前行数较大的文件包括：

- `apps/frontend/src/views/admin/fulfillment/AdminKuaishouCloudFulfillmentView.vue`
- `apps/frontend/src/views/admin/tasks/AdminTaskDetailView.vue`
- `apps/frontend/src/views/admin/fulfillment/AdminFulfillmentBindingsView.vue`
- `apps/frontend/src/views/admin/inventory/AdminInventoryView.vue`
- `apps/frontend/src/views/admin/platform-shops/AdminPlatformShopsView.vue`

建议拆分维度：

- 筛选区组件
- 表格区组件
- 表单区组件
- 弹窗组件
- 业务 composable
- 数据转换函数

验收标准：

- 单个 Vue 文件尽量控制在 300 到 500 行以内。
- 业务状态集中在 composable 或页面容器中。
- 展示组件保持 props / emits 清晰。

## 分阶段执行计划

### 阶段一：安全与稳定性基线

范围：

- 收紧 `vite.config.ts` dev server 配置。
- `hasAdminSession()` 增加过期判断。
- 给 Webhook 列表增加请求竞态保护。

验证：

```bash
cd apps/frontend
npm run typecheck
npm run build
```

### 阶段二：列表页抽象

范围：

- 新增 `useAdminListPage`。
- 先改造 Webhook 日志和订单列表。
- 确认抽象合理后推广到任务、消息、用户、审计日志。

验证：

- 手动检查查询、重置、分页、错误提示。
- `npm run typecheck`
- `npm run build`

### 阶段三：筛选体验统一

范围：

- 日期范围统一为 `daterange`。
- 列表页 URL query 同步。
- 统一查询触发策略。

验证：

- 刷新页面保留筛选。
- 分享链接可恢复筛选。
- 重置筛选清理 URL。

### 阶段四：工程质量门禁

范围：

- 增加 ESLint / Prettier。
- 增加 lint / format:check 脚本。
- CI 或本地验证流程加入 typecheck、lint、build。

验证：

```bash
cd apps/frontend
npm run typecheck
npm run lint
npm run build
```

### 阶段五：构建与大型页面治理

范围：

- Bundle 分析。
- 评估并配置 manualChunks。
- 拆分 900 行以上的大型 Vue 页面。

验证：

- 构建成功。
- 产物 chunk 数量和体积有明确对比。
- 页面功能无回归。

## 风险与注意事项

- 列表页抽象不要一次性改造所有页面，建议先选 2 个页面试点。
- URL query 同步要避免 watcher 循环触发请求。
- token 存储机制如果改为 Cookie，需要后端配合，不建议前端单独推进。
- manualChunks 需要基于分析结果调整，避免拆包过度导致请求数过多。
- ESLint 首次接入可能暴露大量历史问题，建议先设置合理规则，再逐步收紧。

## 推荐近期落地清单

1. 修改 `vite.config.ts`，收紧 `allowedHosts`。
2. 修改 `admin-auth.ts`，增加 token 过期判断。
3. 在 `AdminWebhookEventsView.vue` 试点请求竞态保护和日期范围统一。
4. 抽取 `useAdminListPage`，先改造 Webhook 和订单列表。
5. 增加 ESLint / Prettier 基础配置。
6. 引入 bundle 分析，确认 Element Plus 和 CSS chunk 优化方向。