# OA 审批进度与打回/撤销重提 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:** 按钉钉语义落地审批进度展示,并分阶段实现:P0 稳单轮进度轴;P1 打回同实例再提交 + 撤销关联新单。 **Architecture:** 详情进度由后端投影 `progress`(发起/任务/未到达/终态/轮次),任务仍落 `oa_task`;P1 新增 `oa_instance_event` 记录提交/打回/撤销等非任务事件,并给实例增加 `returned` 状态与 `source_instance_id`。轮内按流程树节点序排序(已有 `_sort_tasks_for_detail`),轮间按 `round_no`。 **Tech Stack:** FastAPI · SQLAlchemy · MySQL 5.7 · Vue 3 · Element Plus · Python `unittest` **Design spec:** `docs/superpowers/specs/2026-07-15-oa-approval-progress-timeline-design.md` --- ## Open questions 收口(本计划采纳) | # | 决议 | |---|------| | 1 | 打回后实例状态 = **`returned`**(待发起人修改再提交);列表「我发起的」需能筛出该状态 | | 2 | P1 打回目标 **仅退回发起人(start)**;不支持退回到中间审批节点 | | 3 | 使用独立表 **`oa_instance_event`**(对齐钉钉 `operation_records` 思路),不用纯 task 投影硬扛多轮 | --- ## File Map | 文件 | 职责 | |------|------| | `docs/sql/patch_2026-07-15_oa_progress_return.sql` | **P1 新建** `oa_instance_event`;`oa_instance` 增 `source_instance_id`、`current_round`;注释扩展 status | | `backend/app/models/models.py` | `OaInstance` 新字段;**新建** `OaInstanceEvent` | | `backend/app/services/oa_engine.py` | `build_progress`;`return_task`;`resubmit_instance`;start/withdraw 写事件;详情带 `progress` | | `backend/app/crud/oa_approval.py` | `DEFAULT_ADVANCED_SETTINGS.allowReturn` | | `backend/app/api/oa_approval.py` | `POST .../return`、`POST .../resubmit`;start 接受 `sourceInstanceId` | | `backend/tests/test_oa_engine.py` | 排序/progress/打回/再提交/关联单测 | | `backend/tests/test_oa_progress.py` | **新建** progress 投影单测(可并入 engine 测) | | `web-admin/src/api/oaApproval.ts` | return / resubmit / start 扩展 | | `web-admin/src/views/oa-approval/instances/detail.vue` | 消费 `progress`;打回/再提交按钮;轮次 UI | | `web-admin/src/views/oa-approval/start/index.vue` | 撤销重提带 `sourceInstanceId`;`returned` 再提交入口可进编辑 | | `web-admin/src/views/oa-approval/designer/index.vue` | 高级设置「允许打回」开关 | | `web-admin/src/views/oa-approval/mine/index.vue` 或 `RuntimeList.vue` | 状态文案含 `returned` | --- ## 依赖顺序 ```text Task 1 P0 progress 投影 API + 单测 → Task 2 P0 详情页改吃 progress + 未到达 + 文案 → Task 3 P1 schema / model / allowReturn → Task 4 P1 return_task 引擎 + API → Task 5 P1 resubmit_instance + 事件轮次 → Task 6 P1 撤销重提关联(source_instance_id) → Task 7 P1 前端打回 / 再提交 / 多轮轴 / 关联提示 → Task 8 验收清单走查 + 图谱更新 ``` **说明:** 会话中已落地的 `_flow_node_key_order` / `_sort_tasks_for_detail` / 详情简易 `timelineItems` 视为 Task 1–2 的起点,需并入正式 `progress` 契约,避免前后端各拼一套。 --- ### Task 1: P0 — 后端 `progress` 投影 **Files:** - Modify: `backend/app/services/oa_engine.py` - Modify: `backend/tests/test_oa_engine.py` - [ ] **Step 1: 增加 failing 单测(progress 含发起 + 抄送先于审批 + 未到达)** 在 `backend/tests/test_oa_engine.py` 增加: ```python class TestBuildProgress(unittest.TestCase): def test_cc_before_approval_and_pending_ahead(self): from app.services.oa_engine import build_progress_items root = { "id": "s", "type": "start", "child": { "id": "c1", "type": "cc", "name": "抄送人", "child": { "id": "a1", "type": "approval", "name": "审批人", "child": { "id": "a2", "type": "approval", "name": "总经理", "child": {"id": "e1", "type": "end"}, }, }, }, } ts = datetime(2026, 7, 15, 14, 5, 7) # 审批任务 create 同秒但列表故意审批在前 t_approval = MagicMock( id="tA", node_key="a1", node_name="审批人", task_type="approval", status="pending", assignee_user_id="u2", order_num=0, create_time=ts, update_time=ts, comment_text=None, resolve_source="users", ) t_cc = MagicMock( id="tC", node_key="c1", node_name="抄送人", task_type="cc", status="done", assignee_user_id="u9", order_num=0, create_time=ts, update_time=ts, comment_text=None, resolve_source="users", ) inst = MagicMock( status="running", initiator_user_id="u0", create_time=ts, update_time=ts, ) items = build_progress_items( inst=inst, flow_root=root, tasks=[t_approval, t_cc], name_map={"u0": "发起人甲", "u2": "审批乙", "u9": "抄送丙"}, events=[], # P0 可空 ) kinds = [x["kind"] for x in items] self.assertEqual(kinds[0], "submit") # 已产生:cc 再 approval self.assertEqual( [x["nodeKey"] for x in items if x["kind"] == "task"], ["c1", "a1"], ) # running 时未到达 a2 pending = [x for x in items if x["kind"] == "pending_node"] self.assertTrue(any(p["nodeKey"] == "a2" for p in pending)) ``` - [ ] **Step 2: 跑测确认失败** ```bash cd backend && ./venv/bin/python -m unittest tests.test_oa_engine.TestBuildProgress -v ``` Expected: `ImportError` 或 `AttributeError: build_progress_items` - [ ] **Step 3: 实现 `build_progress_items` + 详情挂载** 在 `oa_engine.py` 增加(要点): ```python def build_progress_items( *, inst: Any, flow_root: Optional[Dict[str, Any]], tasks: List[Any], name_map: Dict[str, str], events: Optional[List[Any]] = None, ) -> List[Dict[str, Any]]: """投影审批进度。P0:submit + 按树序 tasks + pending_node + terminal。 P1:插入 return/resubmit 事件并带 roundNo。""" items: List[Dict[str, Any]] = [] round_no = 1 # 1) 首条提交(无 events 时用实例创建) items.append({ "kind": "submit", "roundNo": round_no, "title": "发起人", "status": "submitted", "assigneeUserId": inst.initiator_user_id, "assigneeUserName": name_map.get(inst.initiator_user_id or "", ""), "timestamp": _fmt_dt(getattr(inst, "create_time", None)), "commentText": "", "nodeKey": "", "taskType": "", }) sorted_tasks = _sort_tasks_for_detail(list(tasks), flow_root=flow_root) reached_keys = {(t.node_key or "").strip() for t in sorted_tasks if (t.node_key or "").strip()} for t in sorted_tasks: items.append({ "kind": "task", "roundNo": round_no, "title": t.node_name or t.node_key or "-", "status": t.status, "assigneeUserId": t.assignee_user_id, "assigneeUserName": name_map.get(t.assignee_user_id or "", ""), "timestamp": _fmt_dt(t.update_time or t.create_time), "commentText": t.comment_text or "", "nodeKey": t.node_key or "", "taskType": t.task_type or "", "resolveSource": getattr(t, "resolve_source", None) or "", "taskId": t.id, }) # 2) 未到达:running 时,流程树中 approval/cc 且不在 reached_keys if inst.status == "running" and isinstance(flow_root, dict): order = _flow_node_key_order(flow_root) for nid, _idx in sorted(order.items(), key=lambda x: x[1]): node = _find_node(flow_root, nid) if not node: continue nt = _node_type(node) if nt not in ("approval", "cc") or nid in reached_keys: continue items.append({ "kind": "pending_node", "roundNo": round_no, "title": node.get("name") or ("抄送人" if nt == "cc" else "审批人"), "status": "not_reached", "assigneeUserId": "", "assigneeUserName": "", "timestamp": "", "commentText": "", "nodeKey": nid, "taskType": nt, }) # 3) 终态 if inst.status == "completed": items.append(_terminal_item("done", "流程结束", inst)) elif inst.status == "rejected": items.append(_terminal_item("rejected", "流程结束(已拒绝)", inst)) elif inst.status == "cancelled": items.append(_terminal_item("cancelled", "已撤销", inst)) return items def _fmt_dt(dt: Any) -> str: if not dt: return "" if hasattr(dt, "strftime"): return dt.strftime("%Y-%m-%d %H:%M:%S") return str(dt) def _terminal_item(status: str, title: str, inst: Any) -> Dict[str, Any]: return { "kind": "terminal", "roundNo": getattr(inst, "current_round", None) or 1, "title": title, "status": status, "assigneeUserId": "", "assigneeUserName": "", "timestamp": _fmt_dt(getattr(inst, "update_time", None)), "commentText": "", "nodeKey": "", "taskType": "", } ``` 在 `get_instance_detail` 中: ```python data["progress"] = build_progress_items( inst=inst, flow_root=flow_root, tasks=tasks, name_map=name_map, events=[], # Task 3+ 再查 oa_instance_event ) # 保留 data["tasks"] 供审批按钮找 pending;UI 进度优先 progress ``` - [ ] **Step 4: 跑测通过** ```bash cd backend && ./venv/bin/python -m unittest tests.test_oa_engine.TestBuildProgress tests.test_oa_engine.TestOaEngineHelpers -v ``` Expected: OK - [ ] **Step 5: Commit** ```bash git add backend/app/services/oa_engine.py backend/tests/test_oa_engine.py git commit -m "$(cat <<'EOF' feat(oa): project approval progress for instance detail EOF )" ``` --- ### Task 2: P0 — 详情页消费 `progress` **Files:** - Modify: `web-admin/src/views/oa-approval/instances/detail.vue` - Modify: `web-admin/src/api/oaApproval.ts`(可选:为 progress 补类型注释) - [ ] **Step 1: 用 `detail.progress` 替换本地 `timelineItems` 拼装** `timelineItems` 改为: ```typescript const timelineItems = computed(() => { const list = detail.value?.progress if (Array.isArray(list) && list.length) { return list.map((p: any, idx: number) => ({ key: `${p.kind}-${p.taskId || p.nodeKey || idx}-${p.roundNo || 1}`, title: p.title || '-', status: p.status || 'info', timestamp: p.timestamp || '', assignee: p.assigneeUserName || p.assigneeUserId || '', resolveSource: p.resolveSource || '', commentText: p.commentText || '', taskType: p.taskType || '', kind: p.kind || '', roundNo: p.roundNo || 1 })) } return [] // 无 progress 时不要静默用错序 tasks }) ``` 文案映射补充: ```typescript not_reached: '未到达', submitted: '已提交', ``` 模板中:若 `item.kind === 'pending_node'`,不显示「处理人」行;`item.kind === 'terminal'` 可不显示处理人。 按钮文案确认:拒绝按钮文案为 **「拒绝」**,禁止写成「打回」。 - [ ] **Step 2: 手工验收** 1. 打开已有实例 `F6E46BC0CB2C4A12A4B324A9735ED1E0`(或本地等价:设计抄送→审批)。 2. 进度应为:发起人 → 抄送人 → 审批人(待处理)→(若有后续)未到达。 3. 拒绝后进度末尾为「流程结束(已拒绝)」且无「未到达」。 - [ ] **Step 3: Commit** ```bash git add web-admin/src/views/oa-approval/instances/detail.vue web-admin/src/api/oaApproval.ts git commit -m "$(cat <<'EOF' feat(oa): render instance detail progress from API projection EOF )" ``` --- ### Task 3: P1 — Schema / Model / 高级设置 **Files:** - Create: `docs/sql/patch_2026-07-15_oa_progress_return.sql` - Modify: `backend/app/models/models.py` - Modify: `backend/app/crud/oa_approval.py` - [ ] **Step 1: 编写 SQL patch** ```sql -- docs/sql/patch_2026-07-15_oa_progress_return.sql -- OA 审批进度多轮 + 打回 + 撤销重提关联 ALTER TABLE oa_instance ADD COLUMN source_instance_id VARCHAR(64) NULL COMMENT '撤销重提所关联的原实例ID' AFTER status, ADD COLUMN current_round INT NOT NULL DEFAULT 1 COMMENT '当前提交轮次,从1起' AFTER source_instance_id; -- status 语义扩展(无需改列类型):running/returned/completed/rejected/cancelled -- returned = 已打回,待发起人修改再提交 CREATE TABLE IF NOT EXISTS oa_instance_event ( id VARCHAR(64) NOT NULL COMMENT '主键ID', instance_id VARCHAR(64) NOT NULL COMMENT '实例ID', round_no INT NOT NULL DEFAULT 1 COMMENT '轮次', event_type VARCHAR(32) NOT NULL COMMENT 'submit/return/withdraw/complete/reject_end', actor_user_id VARCHAR(64) NULL COMMENT '操作人', task_id VARCHAR(64) NULL COMMENT '关联任务(打回时)', node_key VARCHAR(64) NULL COMMENT '节点key', comment_text VARCHAR(512) NULL COMMENT '意见', tenant_no VARCHAR(64) NOT NULL DEFAULT 'zkxw' COMMENT '租户编号', order_num INT NULL COMMENT '排序号', remark VARCHAR(512) NULL COMMENT '备注', create_by VARCHAR(64) NULL COMMENT '创建人id', create_dept_id VARCHAR(64) NOT NULL DEFAULT '' COMMENT '创建人部门ID', create_time DATETIME NOT NULL COMMENT '创建时间', update_by VARCHAR(64) NULL COMMENT '更新人id', update_time DATETIME NOT NULL COMMENT '更新时间', del_flag SMALLINT NOT NULL DEFAULT 0 COMMENT '删除标记', PRIMARY KEY (id), KEY idx_oa_evt_inst (instance_id, del_flag, create_time) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='OA实例操作事件(进度轴)'; ``` 在目标库执行该 patch(本地/测试库按环境)。 - [ ] **Step 2: 更新 SQLAlchemy 模型** `OaInstance` 增加: ```python source_instance_id = Column(String(64), nullable=True, comment="撤销重提原实例") current_round = Column(Integer, nullable=False, default=1, comment="当前轮次") ``` 新建: ```python class OaInstanceEvent(Base): __tablename__ = "oa_instance_event" id = Column(String(64), primary_key=True) instance_id = Column(String(64), nullable=False) round_no = Column(Integer, nullable=False, default=1) event_type = Column(String(32), nullable=False) actor_user_id = Column(String(64), nullable=True) task_id = Column(String(64), nullable=True) node_key = Column(String(64), nullable=True) comment_text = Column(String(512), nullable=True) tenant_no = Column(String(64), nullable=False, default="zkxw") order_num = Column(Integer, nullable=True) remark = Column(String(512), nullable=True) create_by = Column(String(64), nullable=True) create_dept_id = Column(String(64), nullable=False, default="") create_time = Column(DateTime, nullable=False, default=datetime.now) update_by = Column(String(64), nullable=True) update_time = Column(DateTime, nullable=False, default=datetime.now, onupdate=datetime.now) del_flag = Column(SmallInteger, nullable=False, default=0) ``` - [ ] **Step 3: 高级设置默认值** ```python DEFAULT_ADVANCED_SETTINGS: Dict[str, Any] = { "supervisorFallbackToDeptLeader": True, "allowWithdrawRunning": True, "approverDedup": False, "commentRequired": False, "allowAddSign": True, "allowReturn": True, # 打回 } ``` 设计器 `designer/index.vue` 增加与「允许加签」同级的 `el-switch`:`allowReturn`,文案「允许审批人打回(退回发起人修改)」。 - [ ] **Step 4: Commit** ```bash git add docs/sql/patch_2026-07-15_oa_progress_return.sql backend/app/models/models.py backend/app/crud/oa_approval.py web-admin/src/views/oa-approval/designer/index.vue git commit -m "$(cat <<'EOF' feat(oa): add instance events schema and allowReturn setting EOF )" ``` --- ### Task 4: P1 — `return_task`(打回) **Files:** - Modify: `backend/app/services/oa_engine.py` - Modify: `backend/app/api/oa_approval.py` - Modify: `backend/tests/test_oa_engine.py` - [ ] **Step 1: 写 failing 单测(sqlite 内存或 MagicMock 链路)** 优先沿用 `TestCompleteTaskOrSign` 的 sqlite 内存风格:准备实例 `running` + pending task → `return_task` → 断言: - `inst.status == "returned"` - 所有 `pending` 任务变为 `cancelled`(新状态;展示「已取消」) - 存在 `event_type == "return"` 的 `OaInstanceEvent` - 打回任务自身 `status == "returned"`(或 `comment` + 专用状态;**统一用任务 status=`returned`**) ```python def test_return_sets_instance_returned_and_cancels_pending(self): from app.services.oa_engine import return_task # …插入 ver/inst/task 后 return_task(self.db, "t1", tenant_no="zkxw", user_id="u1", comment="请补充材料") inst = self.db.query(self.OaInstance).filter_by(id="i1").first() self.assertEqual(inst.status, "returned") ``` - [ ] **Step 2: 实现 `return_task`** 语义: 1. 校验任务 assignee、`task_type=approval`、`status=pending`、实例 `running`。 2. `advanced.allowReturn` 必须为 true。 3. 评论:若 `commentRequired` 或打回场景 **SHALL 要求非空意见**(打回强制意见,即使全局意见非必填)。 4. 当前任务 `status=returned`,写入 `comment_text`。 5. 同实例其余 `pending` → `cancelled`。 6. 实例 `status=returned`。 7. 写入 `oa_instance_event`:`event_type=return`,`round_no=inst.current_round`。 8. `commit` + `get_instance_detail`。 **注意:** `complete_task(..., action="reject")` 保持整单 `rejected`,**不得**改成打回。 - [ ] **Step 3: API** ```python @router.post("/tasks/{task_id}/return") async def return_oa_task(task_id: str, body: CommentBody, ...): data = return_task(db, task_id, tenant_no=..., user_id=..., comment=body.comment) return success_response(data, message="已打回") ``` - [ ] **Step 4: 跑测 + Commit** ```bash cd backend && ./venv/bin/python -m unittest tests.test_oa_engine -v git add backend/app/services/oa_engine.py backend/app/api/oa_approval.py backend/tests/test_oa_engine.py git commit -m "$(cat <<'EOF' feat(oa): add return-to-initiator action for approval tasks EOF )" ``` --- ### Task 5: P1 — `resubmit_instance`(同实例再提交) **Files:** - Modify: `backend/app/services/oa_engine.py` - Modify: `backend/app/api/oa_approval.py` - Modify: `backend/tests/test_oa_engine.py` - [ ] **Step 1: Failing 单测** - 仅 `status=returned` 且操作者为发起人可再提交。 - 更新 `form_data_json` 后 `current_round += 1`,状态改回 `running`。 - 写 `event_type=submit`(新轮)。 - 调用现有 `advance_from(..., from_node=None)` 从 start 后第一跳重建任务(中间节点重审)。 - **保留**旧轮 `oa_task` / `return` 事件,禁止物理删除历史任务。 - [ ] **Step 2: 实现** ```python def resubmit_instance( db: Session, instance_id: str, *, tenant_no: str, user_id: str, form_data: Optional[Dict[str, Any]] = None, initiator_select_user_ids: Optional[List[str]] = None, ) -> Dict[str, Any]: inst = _get_instance(db, instance_id, tenant_no) if inst.initiator_user_id != user_id: raise OaEngineError("仅发起人可再次提交") if inst.status != "returned": raise OaEngineError("仅打回待修改的审批可再次提交") ver = ... # 公式/校验与 start_instance 同源片段可抽私有函数 now = datetime.now() if form_data is not None: inst.form_data_json = _dumps(form_data) inst.current_round = int(inst.current_round or 1) + 1 inst.status = "running" inst.update_by = user_id inst.update_time = now db.add(inst) _add_event(db, inst, event_type="submit", round_no=inst.current_round, actor=user_id) advance_from( db, inst=inst, ver=ver, from_node=None, user_id=user_id, initiator_select_user_ids=initiator_select_user_ids, ) db.commit() return get_instance_detail(db, inst.id, tenant_no=tenant_no) ``` 创建任务时把 `remark` 或后续字段带上 `round_no`:**最低成本**在 `_create_tasks_for_node` 写入 `remark=json.dumps({"roundNo": inst.current_round})`,或给 `oa_task` 增加 `round_no` 列。 **本计划采纳:** patch 中同时 ```sql ALTER TABLE oa_task ADD COLUMN round_no INT NOT NULL DEFAULT 1 COMMENT '所属提交轮次' AFTER sign_mode; ``` 新建任务:`round_no=inst.current_round`。`build_progress_items` 按 `round_no` 分组排序。 - [ ] **Step 3: API `POST /instances/{id}/resubmit`** Body 与 start 类似:`formData`、`initiatorSelectUserIds`。 - [ ] **Step 4: 升级 `build_progress_items`** - 查询 events,按 `(round_no, create_time)` 展开。 - 每一轮:`submit` 事件 → 该轮 `tasks`(`round_no` 匹配)按树序 → 若为本轮且 running 则 pending_node。 - `return` 事件插在对应轮任务之后。 - 终态仅一轮结束时追加。 - [ ] **Step 5: 测通 + Commit** ```bash cd backend && ./venv/bin/python -m unittest tests.test_oa_engine -v git add docs/sql/patch_2026-07-15_oa_progress_return.sql backend/app/models/models.py backend/app/services/oa_engine.py backend/app/api/oa_approval.py backend/tests/test_oa_engine.py git commit -m "$(cat <<'EOF' feat(oa): support resubmit after return with multi-round progress EOF )" ``` --- ### Task 6: P1 — 撤销后重提关联新实例 **Files:** - Modify: `backend/app/services/oa_engine.py`(`start_instance`、`withdraw_instance`) - Modify: `backend/app/api/oa_approval.py` - Modify: `web-admin/src/api/oaApproval.ts` - Modify: `web-admin/src/views/oa-approval/start/index.vue` - Modify: `web-admin/src/views/oa-approval/mine/index.vue`(或列表组件) - [ ] **Step 1: `start_instance` 增加可选 `source_instance_id`** ```python # 若传入 source_instance_id: src = _get_instance(db, source_instance_id, tenant_no) if src.initiator_user_id != initiator_user_id: raise OaEngineError("只能从本人撤销的审批重提") if src.status != "cancelled": raise OaEngineError("仅已撤销的审批可关联重提") inst.source_instance_id = src.id # 可选:复制标题前缀「重提-」 ``` `withdraw_instance` 写 `event_type=withdraw`。 首次 `start_instance` 也写 `event_type=submit`(round 1),便于 progress 统一走 events。 - [ ] **Step 2: 详情返回** ```python data["sourceInstanceId"] = inst.source_instance_id or "" # 若有人从本单重提,可反查: data["resubmittedInstanceId"] = ... # query source_instance_id == inst.id limit 1 ``` - [ ] **Step 3: 前端「我发起的」** 对 `cancelled` 行提供「修改并重新提交」→ 跳转发起页: `/#/system-manage/oa-approval/start?appId=...&sourceInstanceId=...` 发起页 `onMounted`:若有 `sourceInstanceId`,拉旧详情预填 `formData`,提交时带上该字段。 详情页顶部:若有 `sourceInstanceId`,展示链接「由已撤销单重提,查看原单」。 - [ ] **Step 4: Commit** ```bash git add backend/app/services/oa_engine.py backend/app/api/oa_approval.py web-admin/src/api/oaApproval.ts web-admin/src/views/oa-approval/start/index.vue web-admin/src/views/oa-approval/instances/detail.vue web-admin/src/views/oa-approval/_placeholder/RuntimeList.vue git commit -m "$(cat <<'EOF' feat(oa): link revoke-and-resubmit as a new instance EOF )" ``` --- ### Task 7: P1 — 详情/待办 UI(打回 + 再提交 + 多轮) **Files:** - Modify: `web-admin/src/views/oa-approval/instances/detail.vue` - Modify: `web-admin/src/api/oaApproval.ts` - Modify: `web-admin/src/views/oa-approval/_placeholder/RuntimeList.vue`(状态文案) - [ ] **Step 1: API 封装** ```typescript export function fetchReturnOaTask(taskId: string, comment: string) { return request.post({ url: `${BASE}/tasks/${taskId}/return`, data: { comment } }) } export function fetchResubmitOaInstance( id: string, data: { formData?: Record; initiatorSelectUserIds?: string[] } ) { return request.post({ url: `${BASE}/instances/${id}/resubmit`, data }) } ``` - [ ] **Step 2: 详情操作区** - 审批人待办:在「拒绝」旁增加 **「打回」**(`allowReturn !== false`),`ElMessageBox.prompt` **必填意见**,调 `fetchReturnOaTask`。 - 发起人且 `status === 'returned'`:主按钮 **「修改并再次提交」** → 打开与发起类似的可编辑表单(可复用 start 页组件或详情内嵌 form-create 可编辑),提交调 `resubmit`。 - 进度轴:按 `roundNo` 在轮与轮之间插入分隔标题「第 N 轮」(`v-if` 轮号变化)。 - 状态 tag:`returned` → `warning`「待修改」。 - [ ] **Step 3: 手工走查脚本** 1. 发起(抄送→两级审批)→ 第一级同意 → 第二级打回。 2. 进度可见第 1 轮 + 打回意见;实例「待修改」。 3. 发起人改表单再提交 → 第 2 轮;原同意节点重新出现待办。 4. 拒绝一条单 → 结束且不能再提交。 5. 撤销 → 「我发起的」重提 → **新 instanceId**,详情可回跳旧单。 - [ ] **Step 4: Commit** ```bash git add web-admin/src/api/oaApproval.ts web-admin/src/views/oa-approval/instances/detail.vue web-admin/src/views/oa-approval/_placeholder/RuntimeList.vue git commit -m "$(cat <<'EOF' feat(oa): UI for return, resubmit, and multi-round progress EOF )" ``` --- ### Task 8: 收尾 - [ ] **Step 1: 对照设计验收勾选** 规格 `2026-07-15-oa-approval-progress-timeline-design.md` §6 P0/P1 清单全部勾选或注明缺口。 - [ ] **Step 2: 更新知识图谱** ```bash ./scripts/update-graph.sh backend # 若前端路由/API 有新增: ./scripts/update-graph.sh frontend ``` - [ ] **Step 3: 规格状态** 将设计文档表头「状态」改为「已定稿;实现按 plans/2026-07-15-oa-approval-progress-timeline.md」。 --- ## Spec coverage 自检 | 规格要求 | Task | |----------|------| | 轮内按设计节点序 | 1(继承排序)+ 5 | | 发起人 + 终态 + 未到达 | 1–2 | | 拒绝 ≠ 打回 | 4(独立 API)+ 7(文案) | | 撤销 → 新实例再提 | 6 | | 打回 → 同实例多轮 | 4–5、7 | | 打回后中间节点重审 | 5(`advance_from` from start) | | allowReturn 高级设置 | 3 | | operation_records 等价 | 3(`oa_instance_event`) | --- ## 风险与注意 - MySQL 5.7:`ALTER` 加列注意锁表窗口;测试库先跑 patch。 - 旧实例无 `oa_instance_event`:`build_progress_items` 必须能在 `events=[]` 时退化到 P0(用 `create_time` 伪造首条 submit)。 - 任务 status 新增 `returned` / `cancelled`:列表「已处理」查询勿把 `cancelled` 当同意。 - Autoflush=False 会话:取消 pending 时写库顺序参考现有或签测试。