sqxp/docs/superpowers/plans/2026-08-05-web-admin-order-edit-lock.md

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

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（除非用户要求）