## Context

现有换货管理系统仅支持物流换货流程，包含：创建 → 待填写信息 → 待发货 → 已发货 → 已完成 五个阶段。部分场景下（如现场换货、远程换货等），不需要物流环节，直接完成换货即可。

后端已实现直接换货类型的数据库字段和 API 接口升级，前端需要适配新的接口规范和 UI 交互。

## Goals / Non-Goals

### Goals

- 支持创建直接换货单，自动完成换货流程
- 适配后端新增的 flow_type、shipped_at、completed_at 字段
- 根据流程类型动态控制 UI 展示和操作权限
- 保持向后兼容，历史数据正常展示

### Non-Goals

- 不涉及客户端换货接口改造
- 不修改换货单状态定义
- 不改变物流换货的原有流程逻辑

## Decisions

### 1. 流程类型枚举定义

```typescript
export enum ExchangeFlowType {
  SHIPPING = 'shipping', // 物流换货
  DIRECT = 'direct' // 直接换货
}

export const EXCHANGE_FLOW_TYPE_MAP = {
  [ExchangeFlowType.SHIPPING]: '物流换货',
  [ExchangeFlowType.DIRECT]: '直接换货'
}
```

**Rationale**: 使用枚举统一管理流程类型，避免硬编码字符串，方便维护和扩展。

### 2. 创建表单的条件渲染

使用 `v-if` 根据选中的 flow_type 动态显示字段：

- flow_type = 'direct' 时，显示"新资产标识符"和"是否迁移数据"
- flow_type = 'shipping' 时，隐藏这些字段

**Rationale**: 符合 Element Plus 表单最佳实践，避免不必要的字段提交。

**Alternatives considered**:

- 使用 `v-show` 隐藏：会导致隐藏字段仍参与表单验证
- 使用动态表单项：增加复杂度，不够直观

### 3. 详情页按钮权限控制

在详情页组件中定义计算属性：

```typescript
const canShip = computed(
  () => exchange.value.flow_type === 'shipping' && exchange.value.status === 2
)

const canComplete = computed(
  () => exchange.value.flow_type === 'shipping' && exchange.value.status === 3
)

const canCancel = computed(
  () => exchange.value.flow_type === 'shipping' && [1, 2].includes(exchange.value.status)
)
```

**Rationale**: 将权限逻辑集中在计算属性中，模板中直接使用 `v-if`，代码清晰且易于测试。

### 4. 信息区块隐藏策略

对于 direct 类型，收货信息和物流信息区块采用以下策略：

- **选择方案**: 使用 `v-if="exchange.flow_type === 'shipping'"` 完全隐藏
- **原因**: direct 类型这些字段为 null，显示空白区块或"不适用"会造成页面冗余

**Alternatives considered**:

- 显示"不适用"占位：增加不必要的视觉噪音
- 显示空区块：用户体验不佳

### 5. API 错误处理

后端对不合法操作返回 400 错误，前端需要：

1. 在操作按钮级别根据 flow_type 和 status 做前置检查（优先）
2. 对后端返回的错误消息直接展示（兜底）

**Rationale**: 前置检查提供更好的用户体验，后端错误处理作为安全兜底。

## Risks / Trade-offs

### Risk: 历史数据 flow_type 为空

**Mitigation**: 后端承诺 flow_type 为空时等同于 'shipping'，前端在渲染时做兼容处理：

```typescript
const flowType = exchange.flow_type || 'shipping'
```

### Trade-off: UI 复杂度增加

引入流程类型后，详情页的条件渲染逻辑增多。

**Mitigation**:

- 使用计算属性封装权限判断逻辑
- 添加单元测试覆盖不同流程类型的渲染场景

## Migration Plan

### 阶段 1: API 类型升级（无破坏性）

- 更新 TypeScript 接口定义
- 向后兼容，不影响现有调用

### 阶段 2: UI 适配（向后兼容）

- 列表页新增流程类型列和筛选
- 详情页新增时间戳展示
- 历史数据按 shipping 处理，正常显示

### 阶段 3: 创建功能升级（新增能力）

- 新增流程类型选择
- 支持创建 direct 类型换货单

### 阶段 4: 测试与发布

- 功能测试、回归测试
- 灰度发布，监控错误

## Open Questions

无
