# 业务订单详情-修改总金额功能

## Goal

在业务订单详情页面（`admin/src/views/consumer/prescription/order_list.vue`）增加修改总金额的功能，支持权限控制，并在操作日志中记录修改历史。已完成状态的订单不允许修改金额。

## What I already know

### 前端架构
- 详情页面：`admin/src/views/consumer/prescription/order_list.vue`（60k+ tokens，包含详情抽屉）
- API文件：`admin/src/api/tcm.ts`（已有 `prescriptionOrderDetail`、`prescriptionOrderEdit`、`prescriptionOrderLogs` 等接口）
- 订单状态枚举：
  - `fulfillment_status = 3`：已完成
  - 已完成/已取消订单不可编辑（line 3025）
- 操作日志展示：详情抽屉中已有操作日志时间线（line 1192-1218）

### 后端架构
- 控制器：`server/app/adminapi/controller/tcm/PrescriptionOrderController.php`
- 逻辑层：`server/app/adminapi/logic/tcm/PrescriptionOrderLogic.php`
- 模型：`server/app/common/model/tcm/PrescriptionOrder.php`
- 日志模型：`server/app/common/model/tcm/PrescriptionOrderLog.php`
- 日志写入方法：`PrescriptionOrderLogic::writeLog()` (line 2638-2658)
- 日志读取方法：`PrescriptionOrderLogic::getLogs()` (line 1913)

### 现有日志记录模式
```php
self::writeLog($orderId, $adminId, $adminInfo, 'action_name', '操作摘要');
```
日志字段：
- `prescription_order_id`：订单ID
- `admin_id`：操作人ID
- `admin_name`：操作人姓名
- `action`：操作类型（最多32字符）
- `summary`：操作摘要（最多500字符）
- `create_time`：创建时间

## Confirmed Facts

- ✅ 总金额字段：`amount` (decimal(10,2), NOT NULL, DEFAULT '0.00', COMMENT '业务订单金额')
- ✅ 状态限制：已完成（`fulfillment_status = 3`）和已取消（`fulfillment_status = 4`）都不允许修改金额
- ✅ 权限控制：新增独立菜单权限节点 `tcm.prescriptionOrder/updateAmount`
- ✅ 金额校验规则：
  - 最小值：必须大于 0（不能为0或负数）
  - 最大值：无限制
  - 精度：保留2位小数
- ✅ 需代收金额：前端计算属性自动计算（`amount - linked_pay_paid_total`），无需后端处理
- ✅ 按钮位置：放在金额显示区域旁边（在显示总金额的卡片内）

## Requirements (final)

### 功能需求
1. 在业务订单详情页面的金额显示卡片内增加"修改金额"按钮
2. 点击按钮弹出修改金额对话框，显示当前金额，允许输入新金额
3. 已完成（`fulfillment_status = 3`）和已取消（`fulfillment_status = 4`）状态的订单隐藏修改金额按钮
4. 修改金额需要权限控制（`v-perms="['tcm.prescriptionOrder/updateAmount']"`）
5. 金额校验：
   - 必须大于 0
   - 保留2位小数
   - 最大值无限制
6. 修改成功后，在操作日志中记录：
   - 操作人姓名
   - 原金额
   - 新金额
   - 操作时间
   - 日志格式：`将订单金额从 ¥{原金额} 修改为 ¥{新金额}`
7. 修改成功后立即刷新订单详情数据，需代收金额自动重新计算

### 技术需求
- 前端：在金额显示卡片内增加修改按钮和对话框
- 前端：新增API接口 `prescriptionOrderUpdateAmount(params: { id: number; amount: number })`
- 后端：新增控制器方法 `PrescriptionOrderController::updateAmount()`
- 后端：新增验证规则 `PrescriptionOrderValidate::updateAmount`
- 后端：新增逻辑层方法 `PrescriptionOrderLogic::updateAmount()`
- 后端：记录操作日志（action: `update_amount`）
- SQL：新增菜单权限记录（`server/sql/1.9.20260508/add_update_amount_menu.sql`）

## Acceptance Criteria (final)

- [ ] 已完成和已取消状态的订单不显示"修改金额"按钮
- [ ] 无权限的管理员不显示"修改金额"按钮
- [ ] 修改金额对话框正确显示当前金额
- [ ] 输入金额 ≤ 0 时提示错误
- [ ] 输入金额精度超过2位小数时自动截断或提示
- [ ] 提交成功后，订单 `amount` 字段更新为新金额
- [ ] 操作日志中正确记录：`{操作人} 将订单金额从 ¥{原金额} 修改为 ¥{新金额}`
- [ ] 修改后详情页面数据自动刷新，需代收金额正确显示
- [ ] 后端返回错误时前端正确提示

## Definition of Done

- 前后端代码实现完成
- 新增菜单权限SQL脚本
- 金额修改功能测试通过（正常流程、权限控制、状态限制）
- 操作日志记录正确
- 代码通过 lint/typecheck
- 无 console.log 残留

## Out of Scope (explicit)

- 批量修改金额
- 修改金额审批流程
- 金额修改历史版本对比
- 修改其他订单字段（如运费、优惠等）

## Technical Approach

### 实现流程

#### 1. 后端实现（优先）

**SQL 菜单权限**（`server/sql/1.9.20260508/add_update_amount_menu.sql`）
```sql
INSERT INTO `zyt_system_menu` (`pid`, `type`, `name`, `icon`, `sort`, `perms`, `paths`, `component`, `selected`, `params`, `is_cache`, `is_show`, `is_disable`) 
VALUES 
(处方订单菜单ID, 'A', '修改订单金额', '', 0, 'tcm.prescriptionOrder/updateAmount', '', '', '', '', 0, 0, 0);
```

**验证规则**（`PrescriptionOrderValidate.php`）
```php
public function updateAmount(): PrescriptionOrderValidate
{
    return $this->only(['id', 'amount'])
        ->append('id', 'require|number')
        ->append('amount', 'require|float|gt:0');
}
```

**逻辑层**（`PrescriptionOrderLogic.php`）
```php
public static function updateAmount(array $params, int $adminId, array $adminInfo): bool
{
    $id = (int) $params['id'];
    $newAmount = round((float) $params['amount'], 2);
    
    // 权限检查
    $order = PrescriptionOrder::find($id);
    if (!$order) {
        self::setError('订单不存在');
        return false;
    }
    
    // 状态检查：已完成(3)和已取消(4)不允许修改
    if (in_array($order->fulfillment_status, [3, 4], true)) {
        self::setError('已完成或已取消的订单不允许修改金额');
        return false;
    }
    
    $oldAmount = round((float) $order->amount, 2);
    
    // 更新金额
    $order->amount = $newAmount;
    $order->save();
    
    // 记录日志
    $summary = sprintf('将订单金额从 ¥%.2f 修改为 ¥%.2f', $oldAmount, $newAmount);
    self::writeLog($id, $adminId, $adminInfo, 'update_amount', $summary);
    
    return true;
}
```

**控制器**（`PrescriptionOrderController.php`）
```php
public function updateAmount()
{
    $params = (new PrescriptionOrderValidate())->post()->goCheck('updateAmount');
    $result = PrescriptionOrderLogic::updateAmount($params, $this->adminId, $this->adminInfo);
    
    if ($result === false) {
        return $this->fail(PrescriptionOrderLogic::getError());
    }
    
    return $this->success('修改成功');
}
```

#### 2. 前端实现

**API 接口**（`admin/src/api/tcm.ts`）
```typescript
export function prescriptionOrderUpdateAmount(params: { id: number; amount: number }) {
    return request.post({ url: '/tcm.prescriptionOrder/updateAmount', params })
}
```

**页面实现**（`admin/src/views/consumer/prescription/order_list.vue`）
- 在金额显示卡片内增加"修改金额"按钮（带权限和状态判断）
- 新增修改金额对话框（el-dialog + el-input-number）
- 提交后调用 API，成功后刷新详情数据

### 关键判断逻辑

```typescript
// 是否可以修改金额
const canUpdateAmount = (row: any) => {
    // 已完成(3)或已取消(4)不允许修改
    return row.fulfillment_status !== 3 && row.fulfillment_status !== 4
}
```

## Implementation Plan

### PR1: 后端实现（优先）
- [ ] 创建 SQL 菜单权限文件
- [ ] 添加验证规则 `updateAmount`
- [ ] 实现逻辑层方法 `PrescriptionOrderLogic::updateAmount()`
- [ ] 实现控制器方法 `PrescriptionOrderController::updateAmount()`
- [ ] 测试后端接口（Postman/curl）

### PR2: 前端实现
- [ ] 添加 API 接口 `prescriptionOrderUpdateAmount`
- [ ] 在金额卡片内添加"修改金额"按钮（带权限和状态判断）
- [ ] 实现修改金额对话框
- [ ] 实现提交逻辑和数据刷新
- [ ] 测试完整流程（权限、状态、校验、日志）

### PR3: 测试和优化
- [ ] 测试各种边界情况（0、负数、超大金额、精度）
- [ ] 测试权限控制
- [ ] 测试状态限制
- [ ] 验证操作日志记录
- [ ] 代码 lint/typecheck
- [ ] 清理 console.log

## Technical Notes

### 文件清单
- 前端页面：`admin/src/views/consumer/prescription/order_list.vue`
- 前端API：`admin/src/api/tcm.ts`
- 后端控制器：`server/app/adminapi/controller/tcm/PrescriptionOrderController.php`
- 后端逻辑：`server/app/adminapi/logic/tcm/PrescriptionOrderLogic.php`
- 后端验证：`server/app/adminapi/validate/tcm/PrescriptionOrderValidate.php`
- SQL脚本：`server/sql/1.9.20260508/add_update_amount_menu.sql`（待创建）

### 参考实现
- 操作日志写入：`PrescriptionOrderLogic::writeLog()` (line 2638)
- 操作日志读取：`PrescriptionOrderLogic::getLogs()` (line 1913)
- 状态判断逻辑：`order_list.vue` line 3025

### 约束
- 日志 action 字段最多32字符
- 日志 summary 字段最多500字符
- 遵循 likeadmin 分层架构：Controller → Logic → Model
- 权限通过菜单节点 + `v-perms` 指令控制