fix(app-shell): the approval step line draws the route the request's run took, not the flow graph's first branch - #26666

Requested by Steedos · project thread
Fixes #26563

Clause-②: no
Metadata-protocol: none

维护者速读

• 改了什么:审批步骤线不再画服务端 flow_steps(流程图从起点沿 approve/true/第一条边走出的那一条主干),改为只画本次流程运行真实走过的步骤:同一 flow_run_id 下已通过的审批请求,按到达先后排列,最后是当前待审步骤;当前步骤之后一概不画。业务记录的审批面板照此绘制;审批请求页只持有自身这一行,证明不了任何已走步骤,所以暂不画步骤线。
• 为什么改:hotclm 的合同审批走「直属上级 → 仅财务」时,步骤线却写着「直属上级 · 法务负责人 + 财务负责人（会签） · 分管领导 · 总经理」,审批人被告知要与法务会签、后面还有两级,实际都不会发生。分诊裁定:⛔ 永不画猜测的路径。
• 风险与回滚:纯 UI 显示改动,无契约、无元数据、无服务端改动。代价是过渡期内审批请求页不再显示步骤线,业务记录面板上看不到自己未参与的步骤(列表读只对参与者开放)。回滚 = revert 本 PR。
• 先看:① ui/packages/app-shell/src/views/RecordApprovalsPanel.tsx 新增的 visitedApprovalSteps(哪些请求算「已走过」);② ui/packages/app-shell/src/views/approval-decision/ApprovalDecisionPanel.tsx 删去的那一行步骤线;③ RecordApprovalsPanel.visitedRoute-26563.test.tsx。
• 两分钟验证:pnpm --dir ui exec vitest run packages/app-shell/src/views/RecordApprovalsPanel.visitedRoute-26563.test.tsx,预期 11 个测试全绿,其中报告的路由只画出「直属上级、财务负责人」两步。
• 需要你做的:无,席位落地。

What changes

The approval step line drew the request's flow_steps. That field is built by plugin-approvals' attachFlowSteps, which walks the flow graph from its start node and takes the approve edge, else the true edge, else the first edge at each node. It marks done, current and upcoming against that one trunk. It is not the route the request takes. A request that a decision sent down another branch was drawn on rungs it never visits. When the request's own node is off the trunk, it is drawn on none of the trunk's rungs as current. A rung reached after a side branch rejoins showed the trunk's branch as done.

Measured first, as the triage asked: the single request read (GET /api/v1/approvals/requests/:id) carries neither a resolved route nor the visited nodes. Beyond flow_steps, the row names only its own node (flow_node_id, current_step, step_label) and its run (flow_run_id). So the route read is a plugin-approvals child (see Acceptance notes), and this PR draws only what a request row proves:

• Business record approvals panel. visitedApprovalSteps(pendingRequest, requests) builds the line from the request rows the panel already holds (the list read, no new request). A passed step is a request with the same flow_run_id, on another node, approved, and opened before the pending one. A node approved in several rounds is drawn once, at its latest round. The pending request comes last. Nothing ahead of it is drawn, because no request row says which branch the run takes next.
• Approval request page (record:approval_decision). The decision panel no longer draws a step line. Its bound row proves only its own step, which the page header already names, and one step is no line.
• ApprovalRequestLite declares the served flow_run_id and flow_node_id. The flow_steps doc says why no surface draws it.
• ApprovalStepLine's markup is unchanged. Its header now says the caller owns the proof of the steps it hands in, and the stale paragraph about the inbox sheet's copy of the stepper is gone (that sheet no longer draws one).
• The app-shell README's two approval paragraphs say the same.

Tests

• New RecordApprovalsPanel.visitedRoute-26563.test.tsx, 11 tests. The panel cases use the reported route (manager → finance only) with the served trunk attached. They pin a branch that rejoins the trunk (manager → legal only → executive), a request at the run's first rung, and a viewer served only the pending row. The unit cases for visitedApprovalSteps pin ordering, another run, a step not approved (returned, rejected), a row opened after the pending one, round dedup, an earlier round of the pending node, a decided request, an unlabeled step, and the controls for a missing run, node or open time.
• RecordApprovalsPanel.stepProgressVertical.test.tsx: the layout contract is unchanged. Its fixtures are now a run's request rows, so they reach the line the way the panel builds it. The connector-tint case now pins that every segment is green, because the line draws nothing ahead of the pending step.
• ApprovalDecisionPanel.stepLine-12491.test.tsx: rewritten to pin the absence of the line. The reported row with its served trunk draws no line and none of the trunk's rungs, a decided row draws none either, and the tally still draws above the decisions. The deleted layout cases duplicate the ones RecordApprovalsPanel.stepProgressVertical.test.tsx pins over the same ApprovalStepLine markup.
• approvalRequestsDataSource.servedPageStepLine-12491.test.tsx (console, the real served page): the step-line cases now pin that no line and no other trunk rung is drawn, at pending, at decided, and for a person-submitted request. The flow-origin cases are unchanged.

Acceptance notes

• Out of scope, for the seat to file (class a): the route read belongs to plugin-approvals. ApprovalService.attachFlowSteps serves the flow graph's trunk as flow_steps on every single read. For the reported request (node finance_only), every trunk entry is upcoming and its own node is absent. The child should serve the route the run took and only the steps ahead that the run's state determines. Then the request page can draw its line again, and visitedApprovalSteps can be deleted in favour of the served route. flow_steps' contract text in packages/spec/src/contracts/approval-service.ts reads "The owning flow's approval steps in graph order", so the child either changes that text or adds a field. Either way it is a contract change.
• Viewer-scoped steps. The list read serves a request only to its participants (slate, submitter, override actor). On the business record a viewer who took no part in an earlier rung does not see it, so the line can be shorter than the run's route, never wrong. The finance controller in the report sees no line on the record panel (one step). The submitter sees the whole route.
• Request page: no line rather than a one-step line. The seat suggested a one-step "current step" line there. A one-step line would repeat the step the page header already names, and ApprovalStepLine's own gate draws nothing under two steps, so the page draws none.
• Steps not drawn. A rung a reject edge routes to an approval node, and a rung sent back for revision, are not "passed" (not approved), so they are left out. A route that passes through them shows only its approved rungs.
• The upcoming styling in ApprovalStepLine has no caller today. It stays for the served route the child brings back.

Verification

• origin/main gained 12 commits after the branch point, and none of them touches a file of this diff. The branch was not merged with main before opening, and CI runs on the merge ref.
• No dogfood battery: the title carries no ! and Clause-② carries no (narrowing) arm.

Generated by Claude Code