# Web-Admin 订单编辑锁「查看不加锁」Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 订单详情只读不加锁；仅写操作加锁；关闭解锁；锁 TTL 5 分钟；强制解锁可用；lockInfo 字段与前端对齐。

**Architecture:** DB 字段 `lock_operator_id`/`lock_time` 保持不变。CRUD 增加 TTL/force；`GET` 详情只读返回 lockInfo；写弹窗前后端 lock/unlock；写 API 统一校验他人未过期锁。

**Tech Stack:** FastAPI + SQLAlchemy、Vue3 + Element Plus、现有 `web-admin` 订单页。

## Global Constraints

- TTL = 300 秒（5 分钟）
- 不改表结构
- 不改小程序
- lockInfo 字段：`isLocked`, `lockBy`, `lockById`, `lockTime`, `isExpired`
- `admin` / `super_admin` 可 force unlock
- Spec: `docs/superpowers/specs/2026-08-05-web-admin-order-edit-lock-design.md`

---

### Task 1: CRUD TTL + force unlock

**Files:**
- Modify: `backend/app/crud/order.py` (`lock_order`, `unlock_order`，新增辅助方法)

- [ ] **Step 1:** 在 `OrderCRUD` 中增加常量与辅助方法，改写 `lock_order`/`unlock_order`

```python
ORDER_EDIT_LOCK_TTL_SECONDS = 300

def is_order_lock_expired(self, order, ttl_seconds: int = ORDER_EDIT_LOCK_TTL_SECONDS) -> bool:
    if not order.lock_operator_id:
        return True
    if not order.lock_time:
        return True
    return (datetime.now() - order.lock_time).total_seconds() > ttl_seconds

def lock_order(..., ttl_seconds: int = ORDER_EDIT_LOCK_TTL_SECONDS):
    # empty / self / expired -> acquire; else ValueError with lock time

def unlock_order(..., force: bool = False):
    # force clears any; else only self; no lock -> success idempotent
```

- [ ] **Step 2:** 本地用 Python 片段或现有测试思路验证过期判断逻辑（无强制要求新测文件时可手工跑 import）。

---

### Task 2: admin API — 详情去自动锁 + lockInfo + 合并 unlock + 写接口校验

**Files:**
- Modify: `backend/app/api/admin.py`

- [ ] **Step 1:** 新增 `_build_order_lock_info(db, order)` 与 `_ensure_order_write_lock(db, order, operator_id)`
- [ ] **Step 2:** `get_order` 去掉 `lock_order`；过期锁可顺手清空；返回统一 `lockInfo`
- [ ] **Step 3:** 删除重复的第一个 `unlock_order` 路由（约 4390）；保留锁定管理区唯一 unlock，接受 `request: dict` 含 `force`
- [ ] **Step 4:** 写接口（adjust / assign-deliverer / assign-delivery / review-cancel / cancel / complete / force-complete）入口调用 `_ensure_order_write_lock`

---

### Task 3: 前端 API + 订单页加解锁

**Files:**
- Modify: `web-admin/src/api/business.ts`
- Modify: `web-admin/src/views/system/order/index.vue`

- [ ] **Step 1:** 增加 `fetchOrderLock` / `fetchOrderUnlock`
- [ ] **Step 2:** 写弹窗打开前 lock；关闭/成功 unlock；详情关闭 unlock；强制解锁；`beforeunload` 尽力 unlock
- [ ] **Step 3:** 提示条字段已对齐（lockBy/lockTime）

---

### Task 4: 验证

- [ ] 后端语法检查 / 关键函数冒烟
- [ ] `graphify update .`（若本会话改了代码）
- [ ] 不主动 commit（除非用户要求）