卓安Claw 手机号身份、客户 H5 与案件办理模块 V1 实现说明

日期：2026-11-13
状态：原型演示版已实现
调研依据：../research/卓安Claw-客户H5与案件办理模块-GitHub与行业调研-2026-11-13.md

1. 本次需求

1. 在甲方现有小程序里嵌入 H5，客户用手机号登录，看自己案件的办理状态。
2. 手机号成为卓安Claw全系统主识别标识：员工登录看角色和功能，客户登录看自己的案件。
3. 补齐诊断分析、服务方案、办案、办案清单、文书函件、日程与时效、三级复核、会诊、结案归档、回访与随访、驾驶舱、审计、知识空间的原型。
4. 全量代码提交 Gitee。

2. 手机号身份

2.1 识别顺序

手机号
  → 员工 zhuoan_user.mobile（active）
    → 员工会话 → 卓安办案台 /
  → 客户 client.phone
    → 客户会话 → 客户 H5 /client

• 员工优先；同一手机号既是员工又是客户时，先按员工登录。
• 客户手机号关联多个 client 时，登录页要求选择身份；验证码不消费，可重试。
• 手机号规范化：去空格/横线，+86、0086 前缀收敛为 11 位；国际号码保留 6–20 位数字。
• 管理员账号表新增手机号列，可直接维护登录手机号；新建账号允许不填用户名，按手机号生成。
• Agent 身份上下文新增“登录手机（脱敏）”。

2.2 验证码

• 6 位、5 分钟有效、一次性、服务端 SHA-256 加盐存储。
• 同号码 60 秒发送限流；最多 5 次失败；过期/已用不可复用。
• 演示环境 ZHUOAN_OTP_DEBUG=1 把验证码返回登录页；生产必须接短信/企业微信网关并关闭。
• 生产待补：短信通道、模板报备、图形/行为风控、备用认证、换号重新认证。

2.3 会话隔离

• 员工：zhuoan_session，沿用原有角色/数据范围。
• 客户：zhuoan_client_session，只含 typ=client、cid、mobile、过期时间。
• 客户 cookie 不能调用员工 API；员工 cookie 不能当客户会话。
• 验证码登录成功时清除另一侧会话，避免双身份串用。

3. 客户 H5

入口：/client（静态页 channel/web/static/zhuoan-client/），适合直接嵌入甲方小程序 WebView。

已实现：

• 手机号 + 验证码登录；多客户身份选择；退出登录。
• 我的案件列表：案号、案件名、当前阶段、进度百分比、承办律师、分所、最近进展、下次预约。
• 案件详情：
• 当前阶段 + 12 节点进度。
• 客户友好的“当前进展/下一步”说明。
• 近期预约（时间、类型、地点、负责人、状态）。
• 阶段时间线（只取节点推进记录，不取内部案程/工作底稿）。
• 服务团队（负责人 + 团队成员姓名/角色）。
• 我方角色、受理法院、收案日期、清单完成度。
• 服务边界说明：不展示案卷、证据、内部工作底稿。
• 权限：只允许 case.client_id == client_session.cid；越权返回 404。
• 审计：客户查看案件写 client_case_view。

未做（等卓安确认客户公开策略）：

• 文书/证据共享、电子签、在线支付、客户消息、材料补充上传。
• 客户满意度评价、服务请求工单。
• 多案件合并、家庭成员授权。

4. 案件办理模块

新增 zhuoan_case_work 通用业务记录表（原型；正式版按模块拆对象）：

模块	状态	关键字段	谁能写
诊断分析	草稿/待确认/已确认	争议焦点、要件事实与证据、证据缺口、风险等级、结论	谈案/承办/管理者
服务方案	草稿/待客户确认/已确认	服务范围、策略、阶段计划、报价口径、风险告知、客户确认	谈案/承办/管理者
办案	草稿/进行中/已完成	动作类型（会见/阅卷/开庭/沟通/其他）、摘要、发现/风险、下一步	承办/管理者
三级复核	待复核/需修改/已通过	层级、复核人、意见、结论	承办/管理者
会诊	待会诊/已会诊/已关闭	议题、参与人、意见、处置结论	承办/管理者
结案归档	待结案/待归档/已归档	结案摘要、未了事项、归档状态、归档编号	承办/管理者
回访与随访	待回访/已完成/需跟进	类型、满意度、结果、下次回访	客服/客户经理/承办/管理者

• 每条记录绑定 case_id，可带 stage_key、发生时间、截止时间。
• 写操作按案件数据范围校验；不通过 case_id 直读案卷。
• 记录写入案管 audit_log；Agent 只能读摘要，写入仍走人工确认。
• 演示库自动种 7 条带“演示：”前缀的样例记录；生产不启用。

案件页同步：

• 诊断/方案/复核 tab 下方增加该模块最近 3 条记录与“新建”入口。
• 顶栏模块页提供跨案件记录列表、指标、案件筛选、新建/详情/状态更新。

5. 线索公海与六个占位模块

5.1 线索与公海

• 公海 / 我的线索 / 已分配 / 全部四个范围。
• 线索卡：姓名、脱敏手机、类型、渠道、负责人、跟进状态、质量分、下一步。
• 动作：详情（跟进时间线/线索事件/录音元数据）、认领、分配、转案件。
• 客服只能认领给自己；管理者/客户经理可分配；转案件沿用原转化接口。
• 线索负责人落 zhuoan_lead_ops，不改编 intake 原表。

5.2 六个案件队列

模块	队列口径	当前能力
接诊	当前节点 receive	接诊队列、清单缺项、超期、文书数、打开案件
检查与取证	当前节点 exam	检查队列、清单缺项、文书数、打开案件
案件分配	全部案件，未分配优先	负责人下拉、保存分配、成员列表、审计
质量评查	全部案件	完成率、缺项、超期、复核状态、打开案件复核 tab
全所案件	当前数据范围全部案件	分所/关键词筛选、阶段/负责人/完成率/风险
线索与公海	见 5.1	线索池

• 队列接口：/api/zhuoan/case-queue?module=...
• 分配接口：POST /api/zhuoan/assignments/assign
• 线索接口：/api/zhuoan/leads、/api/zhuoan/leads/<id>、POST /api/zhuoan/leads/<id>/assign
• 办案清单跨案件页新增“生成缺项任务”，复用 tasks/from-checklist，重复清单项自动跳过。

6. 跨案件模块概览

• 办案清单：每案清单总数、完成率、本节点完成数、必做缺项；按缺项优先排序。
• 文书函件：每案文书数、有本地文件数、最近上传时间、零文书案件。
• 日程与时效：未来 30 天时限 + 开庭/会见；超期、本周、排期指标。
• 审计：全所/数据范围内审计查询；承办只看自己有权限案件的审计，管理者看全所。
• 驾驶舱、知识空间沿用已有实现。

7. 案件闭环深化（本轮）

7.1 三级复核流转

• 复核记录状态：草稿 → 待复核 → 需修改 / 已通过。
• 动作：
• 提交复核：草稿/需修改 → 待复核。
• 退回修改：待复核 → 需修改，必须填复核意见。
• 通过并签字：待复核 → 已通过，必须填复核意见 + 复核人姓名。
• 默认禁止自审：创建人不能通过自己创建的记录；管理者可例外，但写审计。
• zhuoan_case_work_event 记录每次流转：动作、操作者、角色、意见、上一事件哈希、当前哈希。
• 前端复核详情显示流转按钮、意见/复核人输入框和事件链；非复核记录仍保留普通状态更新。

7.2 日程与时效

• 跨案件日历新增/编辑开庭、会见、时限。
• 字段：案件、标题、开始/结束、地点、法官/联系人、状态；时限另有截止时间、计算依据、提前提醒。
• 保存前做同案件时段冲突探测：已有预约/排期重叠时提示确认。
• 复用 /api/casemgr/hearings、/api/casemgr/deadlines 的 GET/POST/PATCH，不另造一套表。
• 提醒字段 remind_days 写入案管；跨案件日历新增“待提醒”队列，按 1,3,7 这类规则取最大提前天数，命中未完成时限即进入队列，逾期项单独标注。
• 真实短信/企微/站内推送仍由 reminder worker 接入，当前只做提醒视图。

7.3 文书函件

• 跨案件文书页增加“生成”“版本/送审”。
• 生成：
• 选案件、文书类型；
• 调 /api/casemgr/documents/generate 读取模板与填充预览；
• 调 /api/casemgr/documents/generate-docx 生成 Word 并登记文书台账。
• 版本：
• 按案件读取文书台账，显示名称、类型、版本、上传日期；
• 每份文书可“送三级复核”，创建 review 草稿记录并携带 doc_id/doc_name；
• 复核通过后才进入定稿流程（正式版再接电子签/用印）。

7.4 结案归档：快照、冻结、借阅

• 归档仍走原门禁：案件已结 + 已推进到「归档/质控」+ 材料核对；管理者可强制归档。
• 归档成功时生成快照 zhuoan_archive：
• 案件号、标题、状态、阶段、结案小结、材料核对项、文书数、复核记录；
• 快照 JSON 规范化后计算 SHA-256，作为归档指纹；
• 写审计 zhuoan_archive_snapshot。
• 归档后冻结/解冻（仅管理者）：frozen + 冻结原因，写审计。
• 借阅 zhuoan_archive_borrow：
• 承办律师申请 → 待审批；管理者登记 → 借阅中；
• 管理者审批：批准 → 借阅中，驳回 → 已驳回；冻结状态禁止批准；
• 归还 → 已归还，记录归还时间；
• 全程写审计，归档档案弹窗展示快照哈希、冻结状态、借阅记录和审批按钮。
• 六类材料分类等待卓安确认；当前门禁仍按四项（裁判文书/送达回证/结算单/卷宗材料），后续映射为六类而不改流程。

7.5 客户/线索级回访

• 客服没有案件权限，不能走案件级回访；新增 zhuoan_customer_followup，对象是客户或线索，不读案卷。
• 列表按客户/线索合并展示：名称、脱敏手机、来源、归属、下次回访、最近回访。
• 回访类型：结案回访/服务随访/复购回访/投诉回访；满意度：满意/一般/不满意/未评价；结果必填。
• 写审计：客户对象记 client，线索对象记 intake。
• 前端：客服侧「回访与随访」进入客户/线索回访页；案件级回访仍保留在案件闭环模块。

7.6 会诊：参与人、纪要与结论转任务

• 会诊记录字段新增“会诊纪要”，与议题、意见、处置结论一起保存。
• 参与人独立登记 zhuoan_consult_participant：姓名、角色/单位、状态（待邀请/已邀请/已接受/已拒绝）、登记人、登记时间、响应时间。
• 详情页可登记参与人、标记已邀请、接受、拒绝；每次变更写案件审计。
• “结论转任务”：把会诊结论写成案件任务，带 case_id、标题、负责人、截止时间。
• 复用 /api/zhuoan/tasks，任务进入统一任务链，不另造待办。
• 尚未做短信/企微邀请通道和会诊纪要模板，当前为登记与状态留痕原型。

7.7 办案清单：条件项、逾期与门禁

• 清单模板仍按 12 节点生成必做项；新增 6 个条件项（排非、专家论证、取保候审、庭前会议、刑事附带民事、涉案财物处置），默认不计入必做缺项。
• 条件项以“条件项”徽标和触发条件展示；未触发时可标“不适用”，触发后改为进行中/已完成。
• 清单项支持设置/修改截止日期；超过截止且未完成/不适用即标记逾期。
• 案件页当前节点上方单列“逾期项”，跨案件概览增加逾期案件数/逾期项数和红色标记。
• 生成任务时跳过“未触发”的条件项，也不再把“不适用”项生成任务。
• 门禁仍按必做项：推进节点前检查目标节点之前所有未完成必做项；归档另按四项材料核对。

7.8 Agent 副驾：绑定范围与重新进入

• 副驾绑定的是“当前案件/当前线索”，不是全所数据权限：
• 前端只在 /message、/stream 请求里传 case_id 或 lead_id；
• 服务端按登录用户重新解析角色和数据范围，前端不能伪造案件上下文；
• 越权/不存在的 case_id 直接返回错误，不启动 Agent。
• 绑定案件时注入：案件编号、名称、类型、案由、节点、状态、委托方、当前节点清单、最近节点记录、预约与时限；按角色裁剪。
• zhuoan_case 工具只读当前案件上下文、清单、案卷检索、录音检索与知识检索；写操作只生成待律师确认动作。
• 退出案件只清除会话绑定，不删除案件或会话；顶部常驻未绑定条和“选择案件”入口，副驾空状态也提供同一入口。
• 客服没有案件工作台：侧栏不显示“我的工作台”，工作台入口统一落到“客户”，侧栏高亮、顶栏页签和主内容保持一致。
• 客服客户列表：客户行不再直接跳案件。客服点击客户打开「客户信息」弹窗（手机号、分所、来源、在办案件数、备注），服务端同时剥离 caseId 与案件时限 nextFollow，避免误触 403；有 case:view 的角色仍按原逻辑打开案件。
• 客户信息弹窗采用资料卡：头像、名称、客户/阶段/在办案件 pill、四格资料、下一步、备注、标签和合规提示；来源英文值映射中文；窄屏单列。合规提示只说明利益冲突检测应在转案/分诊/案件概览执行，不展示命中详情；完整位置建议见 卓安Claw-利益冲突检测-产品位置建议-2026-11-14.md。
• 方案 B 已落地：副驾可在授权范围内跨案件/跨客户工作，但每次跨案必须有显式锚点并写审计。
• 每个回合仍有一个“当前对象”（当前案件或当前线索/客户），决定对话主上下文；切换对象必须走案件/客户选择器，写 agent_context_switch；
• 工具层 case_manager 允许显式传入其他案件的 case_id 或记录 id，但必须通过 can_access_case 的数据范围校验（本人/部门/分所/全所/案件团队）；
• case_list 必须带 search/status/case_type/client_id 条件，返回结果再按数据范围过滤并最多 50 条，写 agent_case_list；禁止无条件的全量案件列表；
• stats、case_analytics、calendar、search、natural_search、reminders_upcoming、conflict_check、intake_*、content_*、entity_* 等全所/跨域方法直接拒绝，避免静默遍历；
• 其他案件的 case_get、时限/排期/程序/卷宗/审计操作允许在授权范围内执行，但写 agent_case_cross_access，记录方法、目标案件、角色与时间；
• 线索/客户上下文仍移除 case_manager，防止从客户 id 静默穿透到案卷；需要看案件时走显式案件切换；
• 工具附着失败时按失败关闭处理，不退回无范围的旧行为。
• 销售/客户经理的多客户场景：在客户列表点「问 Agent」或顶部「选择客户」即显式切换客户，写 agent_context_switch；切换后只加载该客户/线索的上下文，不读案卷正文。
• Agent 主动切换：zhuoan_case(method=propose_switch, target_case_id=...) 只生成 switch_context 确认卡，不自动切前端；律师点「切换过去」后才切换并写 agent_context_switch。
• case_manager 的写方法已收口为待确认动作：
• case_update / case_delete / case_change_phase / case_archive / case_unarchive、排期/时限/程序/卷宗写方法、备注写、案件关联、document_generate_docx、document_upload_version 等只生成 zhuoan_agent_action(kind=case_manager)，不直接落库；
• 动作绑定目标案件；跨案件写入的动作出现在目标案件工作台，律师确认后才执行；
• 确认执行时仍走数据范围校验，并写 agent_action_confirmed 审计；
• 建案 case_create 直接拒绝，避免在会话里创建无明确归属的新案件。

7.9 授权工作清单

• 新增 zhuoan_case(method=worklist)：返回当前用户授权范围内的在办案件/待跟进客户摘要，默认 20 条、最多 50 条。
• 案件项：案号、名称、状态、阶段、必做缺项、逾期项、最近时限；客户/线索项：名称、类型、脱敏手机、阶段、归属、来源、下次跟进、关联案件。
• 清单只读、只做摘要；不返回案卷正文，不返回全所数据；客户经理/客服只返回客户/线索，不返回案件。
• 读取写 agent_worklist_read 审计；该工具用于回答“我手上今天有哪些案子/客户”，详情仍需显式切换对象。
• 副驾空状态增加「我的工作清单」快捷提示；身份上下文提示 Agent 优先用该工具，不要尝试全所遍历。

7.10 界面刷新（2026-11）

目标：与及锋超级 AI 开发助手（OpenClaw Pro）统一为暖纸底 + 陶土主色；解决“字小、卡片不明显、功能挤在一起”。

• 配色：--zhuoan-paper #f6f5ef、--zhuoan-surface #fbfaf6、--zhuoan-accent #bd5b3d、--zhuoan-ink #211f1b；深色为 #1e1d1a / #252420 / #d97858 / #f3f0e7。明暗变量统一在 zhuoan-theme.css 定义，聊天区 Tailwind primary 同步为陶土色。
• 字号：正文/表格 14px，卡片标题 15px，指标数字 28px，导航 14px，辅助标签不低于 12px；不再使用 9–11px 的功能性文字。
• 卡片：暖白表面、1px 暖色描边、14px 圆角、轻阴影；指标卡、队列卡、工作卡、审计卡统一层级。
• 案件队列：主栏被右侧副驾挤到 <1080px 时，7 列表格通过容器查询自动变为卡片（案名独占一行，节点/分所/复核、清单/风险分行，操作区置底）；<720px 再降为 2 列。
• 重复标题：模块页头已由 zhuoanUpdateHeader 输出，移除队列/清单/文书/日程/复核/线索/审计内部重复的标题块，只保留紧凑操作条（说明 + 按钮）。
• 12 节点轨道：显示短标签（咨询/建档/分诊/接诊/检查/诊断/方案/办案/复核会诊/结案/归档/回访），完整节点名放在 title，避免 855px 主栏下标签换行挤压。
• 窄栏适配：1366px 下页头操作收为单行；副驾输入区宽度 ≤440px 时工具组与模型/发送组分两行，模型名不再压住图标。
• 参考来源（GitHub）：dougdevitre/justice-components（法律科技组件、WCAG、DashboardShell/SideNav/Timeline）、dislove/calegal 的 DESIGN.md（正文 16px、元数据 12–14px、卡片 10px 圆角、44px 触控目标、语义状态色）、shadcn/Primer 后台模式（14px 基准、细边框、克制强调色、激活导航约 12% 主色）。

7.11 客户 H5 服务闭环（2026-11）

目标：让客户不只看进度，还能收文书、补充材料、申请预约，形成“律所服务 → 客户反馈”的闭环；同时保证未共享案卷不可见。

• 演示登录：ZHUOAN_DEMO_SEED=1 时启用 /api/zhuoan/auth/demo-login，固定手机号 13200008888（何某，1 件案件），直接建立客户会话；/api/zhuoan/auth/config 告诉 H5 显示免验证码面板。生产环境未开 demo seed 时仍走原短信验证码流程，后端 OTP 接口保留。
• 文书共享：新增侧表 zhuoan_client_document，律师在案件材料里点「共享客户」才可见；共享时校验案件属于该客户、文书有原件、非 C 类、案件未归档。客户 H5 可列表、查看原件、确认已阅；查看/确认/共享/取消共享全部写审计。
• 材料补充：新增 zhuoan_client_upload，客户 H5 上传文件走 save_upload 进入案件材料台账（类型「客户补充」），同时登记来源；禁止可执行文件，归档案件不可上传。
• 预约申请：客户在案件详情选择期望时间，写入 zhuoan_appointment（type=客户申请、status=待确认、created_by=client:<id>），承办律师/管理者在预约队列和案件预约里直接看到。
• 预约取消：新增 POST /api/zhuoan/client/appointments/<id>/cancel，客户只能取消本人案件下 待确认 的预约；写 status=已取消、追加取消说明、写审计 client_appointment_cancel。已确认/已完成 返回 400 并提示联系客户经理；已取消重复调用幂等。H5 近期预约展示 待确认/已确认/已完成/已取消，待确认项带「取消预约」，已确认项提示联系客户经理；取消后列表保留已取消记录。
• 服务消息：/api/zhuoan/client/messages 汇总阶段推进、预约、待确认文书、客户补充材料，按时间倒序展示；不做已读状态（V1）。
• H5 页面：登录页显示固定演示账号；主页增加「服务消息」；案件详情增加「律师共享文书」「补充材料」「申请预约」三张卡，底部说明改为“未共享案卷不可见”。
• 权限边界：客户只能按 client_id 访问本人案件；共享表与上传表均按 client_id + case_id 双重校验；C 类文书即使被误调用共享接口也返回 400。

7.12 客户 H5 服务团队联系人（2026-11）

目标：客户在 H5 上能直接看到“谁是我的客户经理、谁是我的承办律师”，并能一键拨号。

• 数据表：新增 zhuoan_client_manager（client_id 主键、manager_user_id、service_name、service_phone），允许律所配置客户经理的显示名/服务电话，不依赖员工账号资料。
• 解析顺序：显式配置行 → 演示环境固定账号（何某演示客户固定为「李婷 · 客户经理 · 13800000002」）→ 已转化线索的负责人（intake 手机号 → zhuoan_lead_ops.owner_user_id）。
• 律师联系人：从 zhuoan_case_scope 的 owner_user_id（承办律师）和 team（案件团队）解析；有手机号则显示 tel: 拨号链接，没有则显示「由律所转接」。
• 接口：/api/zhuoan/client/me 与 /api/zhuoan/client/cases/<id> 返回 contacts.manager 和 contacts.lawyers，不返回其他员工列表。
• H5：主页增加「我的服务团队」卡片（客户经理 + 案件律师）；案件详情「服务团队」卡同步显示电话；未配置时不展示空卡。
• 边界：客户只能看到与自己客户/案件关联的员工，不暴露全所通讯录。

7.13 谈案录音转写与 AI 质检（2026-11）

目标：补齐“录音 → 转写 → 五维质检 → 主管复核 → 评定取数”的演示闭环。

• 复用表：zhuoan_comm_record、zhuoan_comm_transcript、zhuoan_comm_analysis（原 V1 已建表，本轮接入使用）。
• 转写：录音详情弹窗展示分段转写；V1 支持人工粘贴/修正转写文本（POST /communications/<id>/transcript），正式 ASR worker 后续替换。
• 质检：POST /communications/<id>/analyze 生成五维结果——合规话术、服务质量、客户意向、报价、风险；每维带分数、等级、摘要、证据片段与提示；模型标记 rule-demo-v1，明确是演示规则，不冒充大模型结论。
• 复核：POST /communications/<id>/review，仅管理者/客户经理可操作；通过/退回会写 zhuoan_comm_event 与审计，结果状态进入 已通过/已退回。
• 列表：记录行可点击打开详情；指标增加「待复核」「质检平均分」；演示环境自动预置一条已分析合成录音（非真实客户录音），含 7 句转写与五维结果。
• 权限：沿用录音查看范围；非管理者默认只看自己上传的录音；质检复核需主管/客户经理；不把录音全文写入客户 H5 或对外模型。
• 后续：真实 ASR、LLM 质检、录音与律师评定的自动取数仍待接；当前结果已可供主管人工复核和后续评定表读取。

7.14 录音质检结果进入律师评定（2026-11）

目标：把录音质检从“单条录音详情”汇总到经营分析和律师评定，形成可追溯的取数链。

• 后端：/api/zhuoan/ops 新增 recordingQuality，按录音上传人聚合：
• total / analyzed / pendingReview / avgScore / complianceFlags / riskFlags；
• byUploader：上传人、录音数、已分析数、待复核数、平均分、合规提示数、风险提示数、关联案件数；
• dimensions：合规话术、服务质量、客户意向、报价、风险五维均分。
• 归因：按 zhuoan_comm_record.uploaded_by_user_id 归到录音上传人；演示账号用 zhuoan_client_manager.service_name 覆盖显示名，保证与 H5 的「李婷」一致。
• UI：经营分析 →「律师评定」新增「谈案录音质检」卡，包含已分析录音、质检均分、待复核、合规/风险提示四项指标和上传人明细表；维度均分以说明行展示。
• 口径：录音质检分目前是独立维度，尚未并入原有案件质量分/律师评级公式；是否加权、权重多少需要卓安确认后再改，避免把演示规则当成正式绩效结论。
• 审计：质检生成和复核已有事件/审计；经营分析只读聚合，不修改原始分析结果。

7.15 Agent 节点建议（2026-11）

目标：让副驾从“一个聊天窗”变成每个办案节点都能给出下一步建议的业务助手，同时不越权、不自动写入。

• 节点提示库：ZHUOAN_STAGE_PROMPTS 覆盖 12 个节点，每节点 3 条建议；例如接诊问事实/证据/程序阶段，诊断问争议焦点/证据缺口，复核问三级复核要点与文书风险，归档问材料齐全与 C 类本地保存。
• 展示位置：
• 案件概览新增「Agent 本节点建议」卡，标题显示当前节点短名；点击建议只填入右侧副驾输入框。
• 右侧副驾空状态快捷提示也优先使用当前节点建议，没有节点时回退到角色提示。
• 交互边界：建议是静态提示库，不调用模型、不自动执行、不写案件；写入仍走原有的 zhuoan_agent_action 待律师确认。
• 角色适配：节点提示对所有角色可见；客服/客户经理仍受客户/线索上下文与数据范围限制，不会因提示卡获得案件材料权限。
• 静态提示库保留为接口失败/无数据时的兜底；动态数据建议见 7.16。

7.16 上下文感知的 Agent 建议与采纳率（2026-11）

目标：让建议真正读取当前案件数据，而不是只按节点套模板；同时记录“是否被律师采纳”。

• 生成器：zhuoan_agent_suggestions.py 读取本案时限、清单、复核记录、文书解析状态、录音质检状态，按优先级生成最多 4 条建议：
• 超期时限：列出前两项及逾期天数；
• 本节点必做清单缺项：列出未完成项与本阶段完成率；
• 复核节点无记录/未入库；
• 文书解析失败或未索引；
• 录音质检待复核或本案尚无录音；
• 数据不足时回退到 7.15 的节点提示库。
• 接口：
• GET /api/zhuoan/cases/<id>/agent-suggestions：按当前用户数据范围校验案件访问，返回 stage_key、stage_label、items[{id,kind,priority,text,reason,manual_state?}]；越权返回 403；
• POST /api/zhuoan/agent-suggestions/event：记录 shown/clicked/resolved/dismissed 与可选 note，写 zhuoan_agent_suggestion_event；点击写 agent_suggestion_clicked，人工处理写 agent_suggestion_resolved，忽略写 agent_suggestion_dismissed。
• UI：案件概览卡改为调用接口，显示“基于本案时限、清单、文书、复核、录音数据生成 N 条建议”；点击建议只填入右侧副驾输入框。接口失败时保留静态提示。接口按当前用户返回 manual_state，已人工处理的建议在刷新后仍显示“已”，已忽略的建议不再出现。
• 副驾空状态：动态建议加载后优先使用动态文本，未加载时用节点提示。
• 采纳统计：按 用户 + 案件 + 建议 去重统计曝光/点击；曝光仅在案件概览卡实际可见时记录，避免后台页面虚增。/api/zhuoan/ops.agentSuggestions 返回 shown/clicked/adoptionRate，并附 byStage（按节点）与 byUser（按用户/律师）明细；经营分析「律师评定」新增「Agent 建议采纳」卡及两张明细表。
• 执行闭环：对已点击建议按业务对象当前状态推断是否闭环——时限是否完成、清单项是否完成/不适用、复核是否已提交/入库、文书是否已可检索、录音质检是否已复核；新增 trackableClicked/closed/closedRate，节点通用建议不计入闭环分母。
• 人工闭环：案件建议行右侧增加“✓ 标记已处理”动作；律师确认后写 resolved，若此前未点击会自动补记 clicked，按钮变为“已”并写审计；刷新后由 manual_state 恢复。统计时最新人工结果优先：resolved 直接计为已闭环，dismissed 移出闭环分母并从建议列表隐藏；agentSuggestions.manualResolved 返回人工闭环数。
• 转任务：建议行“任务”按钮调用 POST /api/zhuoan/tasks，任务写入 source_type=agent_suggestion、source_id=建议 id，创建成功补记 clicked（note=转为任务）；建议接口返回 task_status，刷新后按钮保持“已建”。任务完成后 _suggestion_closed 优先按关联任务状态判定闭环，任务未完成则保持可跟踪。
• 兼容：zhuoan_task 新增 source_type/source_id 与来源索引；新库由 schema.sql 建列，老库由 case_manager/migrate.py 补列，创建任务时再做一次幂等兜底。
• 口径：采纳 = 点击建议或人工标记处理，不代表系统已自动执行；建议由规则引擎生成，不是大模型结论；人工处理是律师对“已在系统外完成”的确认。

7.17 AI 深入分析（可选，2026-11）

目标：在不改变规则建议主链路的前提下，用当前已配置模型对本案结构化事实做一次只读分析。

• 入口：案件建议卡右上角「AI 分析」按钮；只有律师显式点击才调用，不自动生成、不自动轮询。
• 输入白名单：当前阶段、案件类型/状态/办理阶段，以及规则引擎生成的时限、清单、复核、文书解析、录音质检事实；不发送案卷正文、客户姓名、案号、电话、身份证或文书内容。模型由用户在「设置 → 模型」中选择。
• 输出：严格 JSON，最多 3 条，字段 text/reason/priority；后端清洗手机号/案号、限制长度，生成 ai:<uuid> id。
• 接口：POST /api/zhuoan/cases/<id>/agent-suggestions/ai；同用户同案 20 秒冷却；按案件数据范围校验；成功写审计 agent_ai_suggestions_generated（只记条数和模型名）；模型失败返回 502，规则建议仍可用。
• UI：按钮「AI 分析」→「分析中…」→「重新分析」；AI 建议沿用点击填输入框、转任务、人工闭环；结果只替换当前视图，刷新/切换节点回到规则建议；底部提示“不含案卷正文，仅本次查看”。
• 边界：未做流式输出、未持久化 AI 结果、未把 AI 建议自动写入案件；模型可用性取决于当前配置。

8. 验证

已完成：

1. Python 编译检查：zhuoan_auth.py、zhuoan_login.py、zhuoan_client_portal.py、zhuoan_case_work.py、zhuoan_module_overview.py、zhuoan_leads.py、zhuoan_case_queues.py、zhuoan.py、pages.py、web_channel.py。
2. JS 语法检查：zhuoan.js、admin.js、client.js。
3. 员工验证码登录：13800000004 → 承办律师 → 员工会话 → /api/zhuoan/me 返回角色。
4. 客户验证码登录：13200008888 → 何某 → 客户会话 → /api/zhuoan/client/cases 返回 1 件案件；访问其他客户案件返回 404。
5. H5 移动端实测（390×844）：登录、案件列表、案件详情、阶段进度、预约、服务团队、时间线均正常；0 JS 错误。
6. 模块 UI 实测（1920×1080）：诊断/方案/办案/复核/会诊/结案/回访、清单/文书/日程、审计均可渲染；诊断新建记录成功并写审计。
7. 案件 tab：诊断/方案/复核 tab 能显示最近记录和新建入口。
8. 六个占位模块： - 全所案件 10 件、接诊 3 件、检查队列、分配/质量队列接口均返回数据。 - 线索“全部”4 条；公海为空时显示空状态。 - 案件分配接口实测：把未分配案件分给承办律师后，再恢复公海，均成功并写审计。 - 1920×1080 实测：线索池、全所案件、接诊队列渲染正常。
9. 案件闭环本轮： - 三级复核函数实测：提交 → 待复核，通过 → 已通过，事件链生成两条哈希；测试记录已清理。 - 日程模块实测：5 条可编辑记录，编辑弹窗正常。 - 文书模块实测：10 个案件可生成，模板预览返回 73 字。 - 文书生成接口实测成功生成 Word 并登记台账；生成 1 份演示文书。
10. 归档快照与借阅（HTTP 实测，ZA-2026-0320）： - 管理者归档 → 返回快照 SHA-256（f0e170b66f280fd2…）； - 承办申请借阅 → 待审批；承办自行审批 → 400 无权； - 管理者批准 → 借阅中；冻结后再次借阅 → 400「归档已冻结」； - 归还 → 已归还；解冻、取消归档均成功；测试归档/借阅记录已清理。
11. 客户/线索级回访（UI 实测）： - 客服 13800000001 登录 → 「回访与随访」14 个客户/线索对象； - 打开发起回访弹窗，类型/满意度/结果字段正常，无前端报错； - 客户经理 13800000002 同样可进入；案件材料接口仍按其角色返回 403。
12. 办案清单条件项与逾期（HTTP 实测）： - ZA-2026-0320 清单 30 项，其中条件项 6 项，必做 24 项； - 给归档节点清单项设过去日期 → overdue=true，汇总逾期 1； - 清除日期 → 逾期恢复 0； - 跨案件概览返回 overdue_cases/overdue_items 指标； - 1920×1080 实机：案件页清单显示条件项徽标、截止按钮；设过去日期后出现逾期徽标和“逾期 1”，清除后恢复；0 JS 错误。
13. 会诊参与人（HTTP + UI 实测）： - 登记参与人 → 待邀请；标记已邀请 → 已邀请；接受 → 已接受； - 非法状态 → 400；指标 total=1/accepted=1/pending=0； - 1920×1080 会诊详情显示参与人列表、登记表单和接受/拒绝按钮，0 JS 错误； - 测试参与人已清理。
14. 日程待提醒（HTTP + UI 实测）： - 日历概览返回 5 条待提醒：4 条逾期 + 1 条 7 天内到期； - 每条返回 days_until、原始 remind_days（1,3,7）和状态； - 1920×1080 日历页显示“待提醒”卡片 5 行，逾期显示“逾期 N 天”，0 JS 错误。
15. Agent 副驾绑定与入口（UI + HTTP 实测）： - 退出案件后顶部显示“未绑定 / 选择案件”，点击可打开 10 个可访问案件； - 选择后恢复“正在办理”和案件名称，退出后入口仍在；0 JS 错误； - 伪造/不存在的 case_id 调 /message 返回“案件不存在或无权访问”，不启动 Agent。
16. 方案 B 工具收口（case_manager 实测）： - 承办律师（案件团队范围）case_get 本案 → 成功；同案库另一案 → 拒绝“数据范围无权访问”； - case_list 无筛选 → 拒绝；带 search=ZA → 成功，结果按数据范围过滤； - stats / search → 拒绝；client_get 本案客户 → 成功，非授权客户 → 拒绝； - 管理者跨案 case_get 其他案件 → 成功，并写 agent_case_cross_access 审计； - 切换案件/客户的 /api/zhuoan/agent/switch 成功写 agent_context_switch；伪造案件 → 403； - UI 选案后恢复“正在办理”，审计表出现切换记录；线索绑定也写切换审计。
17. case_manager 写操作确认（实测）： - 直接调用 deadline_update → 返回 pending=true 和 action_id，数据库截止项未变； - zhuoan_agent_action 生成 kind=case_manager、目标案件正确； - 通过 /api/zhuoan/actions/<id>/confirm 确认后执行 deadline_update，动作状态变为 confirmed； - 测试写入已恢复原值，测试动作已清理。
18. Agent 主动切换确认卡（UI 实测）： - propose_switch 生成 switch_context 动作，绑定当前案件； - 案件页显示「切换案件」和「切换过去」；点击后副驾切到目标案件（ZA-2026-0324）； - 确认写 agent_action_confirmed，切换写 agent_context_switch；0 JS 错误。
19. 授权工作清单（HTTP/工具实测）： - 承办律师（案件团队范围）返回 1 个本案 + 1 个关联客户，其他案件/客户不返回； - 客服返回 0 个案件 + 14 个客户/线索，验证客服不读案件； - 返回阶段、必做缺项、逾期、最近时限、下次跟进；写 agent_worklist_read 审计； - 空状态「我的工作清单」快捷提示可填入问题，0 JS 错误。
20. 导航同步（UI 实测）： - 客服账号：侧栏高亮「客户」、面包屑「客户」、顶栏仅「客户」页签、主界面为客户页； - 工作台入口对客服统一落到客户页，不再出现“侧栏工作台 / 主界面客户”的错位； - 承办律师账号仍为「我的工作台」高亮，主界面工作台，未受影响。
21. 主题与品牌清理（UI 实测）： - 右上角 GitHub 图标及其 GitHub 链接已移除，DOM 中 github.com 外链为 0； - 左侧栏跟随主题：深色 rgb(37,36,32)，浅色 rgb(251,250,246)，导航文字/高亮同步切换； - 浅色下侧栏、Logo 区、导航分组、页脚均正常可读。
22. 归档档案弹窗（代码/接口验证）： - 展示快照哈希、归档时间、冻结状态、借阅记录； - 管理者可见冻结/解冻、批准/驳回；承办可见申请借阅；归还按钮按状态显示。
23. 界面刷新（1600×1000 / 1366×1000，明暗主题实测）： - 主栏 855px / 705px 无横向溢出；案件队列在 <1080px 自动转卡片，案名不再竖排； - 日历/清单/文书/复核/线索/审计页标题不重复，只保留紧凑操作条； - 12 节点轨道短标签单行显示，完整节点名在 tooltip； - 1366px 下页头动作收为单行；副驾输入区 362px 宽时工具组/模型组分两行，无重叠； - 明暗主题下卡片、指标、表格、进度条、超期徽标对比正常；0 JS 错误。
24. 客户 H5 服务闭环（API + 390×844 UI 实测）： - demo-login 固定 13200008888 直接进入，1 件案件；OTP 面板隐藏，0 JS 错误； - 共享起诉状 → 客户列表 1 份、查看原件 37,235 bytes、确认已阅； - C 类文书共享返回 400；跨客户案件上传返回 400； - 客户上传补充材料 201，进入案件材料台账；预约申请 201，承办律师预约队列可见 type=客户申请 / status=待确认； - 服务消息汇总预约与材料提交；H5 上传/预约 UI 实测成功，0 JS 错误。 - 预约取消 API：待确认预约取消 200→已取消，重复取消幂等；已确认预约取消返回 400“联系客户经理”；非本人案件预约返回 404。 - H5 预约取消 UI（390×844）：待确认行显示「取消预约」，点击确认后提示“预约已取消”，列表保留已取消状态、按钮消失；已确认行显示“如需取消请联系客户经理”；0 JS 错误。
25. 客户 H5 服务团队（API + 390×844 UI 实测）： - /me 与案件详情返回 contacts：客户经理「李婷」13800000002、承办律师「周航」； - 主页「我的服务团队」卡显示客户经理电话拨号链接、律师「由律所转接」； - 案件详情「服务团队」卡同步显示，0 JS 错误。
26. 谈案录音转写与质检（API + 1600×1000 UI 实测）： - 演示环境自动生成 1 条已分析合成录音（ZA-2026-0324，电话，10 段转写）； - 五维结果：合规话术 95/低、服务质量 90/良好、客户意向 95/高、报价 85/已记录、风险 65/中； - 列表指标：全部 1、已分析 1、待复核 1、平均分 86； - 保存转写 200、重新分析 200；管理者复核通过 200，状态变更为已通过； - 录音详情弹窗显示转写、五维卡片、复核按钮；0 JS 错误；演示结果已重置为待复核。
27. 录音质检进入律师评定（API + UI 实测）： - /api/zhuoan/ops.recordingQuality：total 1、analyzed 1、pendingReview 1、avgScore 86； - 上传人「李婷」：1 条、已分析 1、待复核 1、平均分 86、合规提示 0、风险提示 0、关联案件 1； - 维度均分：合规 95、服务 90、意向 95、报价 85、风险 65； - 经营分析「律师评定」tab 显示「谈案录音质检」卡与上传人明细表，0 JS 错误； - 录音质检分暂未并入案件质量分/律师评级，仅作为独立评定维度展示。
28. Agent 节点建议（UI 实测，静态兜底）： - 接口不可用时，案件概览卡回退到静态节点提示；复核节点显示 3 条复核建议； - 点击第一条后右侧副驾输入框自动填入对应提示； - 右侧副驾空状态快捷提示同步切换；0 JS 错误； - 建议只填输入框，不自动发送、不写案件。
29. 上下文感知建议与采纳率（API + UI 实测）： - GET /cases/ZA-2026-0324/agent-suggestions 返回 4 条：2 项超期时限、复核无记录、本阶段必做项缺项、1 份文书解析失败； - 案件概览卡显示 4 条动态建议与“基于本案时限、清单、文书、复核、录音数据生成”说明； - 点击第一条后副驾输入框填入“先处理超期时限：上诉期限届满（逾期 9 天）…”； - 事件表记录 shown/clicked；/api/zhuoan/ops.agentSuggestions 返回 shown 8、clicked 1、adoptionRate 12.5%； - 经营分析「律师评定」显示「Agent 建议采纳」卡；0 JS 错误； - 采纳口径为“点击建议”，不代表已执行。
30. 采纳明细与曝光口径（API + UI 实测）： - agentSuggestions.byStage：三级复核/会诊 曝光 4 / 采纳 1 / 25%；归档/质控 曝光 4 / 采纳 0 / 0%； - agentSuggestions.byUser：演示用户 曝光 8 / 采纳 1 / 12.5%（按用户去重，不再按角色重复计）； - 经营分析卡下方显示「按节点」「按用户」两张明细表，0 JS 错误； - 仅打开经营分析、案件概览隐藏时，shown 事件不增加；切到案件概览并可见时才记录。
31. 建议执行闭环（API + UI 实测）： - 当前点击的“超期时限”建议对应 deadline:e49f1dc6…，时限未完成时 closed 0 / trackableClicked 1 / closedRate 0%； - 临时把该时限标记完成，接口返回 closed 1 / 1 / 100%；随后恢复未完成，回到 0%； - 经营分析卡显示「已闭环 0/1、闭环率 0%」，按节点/按用户表新增「闭环率」列； - 节点通用建议不计入闭环分母；0 JS 错误。 - 人工闭环实测：点击“复核无记录”建议右侧 ✓ → 确认后按钮变“已”、写 resolved 与审计；/api/zhuoan/ops.agentSuggestions 的 manualResolved 增加，closedRate 按人工结果更新； - 忽略口径实测：已点击建议再写 dismissed 后，clicked 计数保留但 trackableClicked 不增加，说明人工忽略已移出闭环分母； - 刷新持久化实测：重新加载 /zhuoan 并进入同案，已处理项仍返回 manual_state=resolved、按钮为“已”且禁用；dismissed 项不再出现在 4 条建议中； - 1600×1000 实测：4 条建议完整换行显示、行内 ✓ 不溢出，0 JS 错误。 - 转任务实测：点击“超期时限”建议的“任务”按钮，创建 source_type=agent_suggestion、source_id=deadline:… 的任务，按钮变“已建”、补记 clicked；刷新后仍显示“已建”，任务列表可查到该任务；0 JS 错误。 - 任务闭环实测（临时库副本）：关联任务 进行中 时 _suggestion_closed=False，改为 已完成 后返回 True；不修改演示库业务对象。
32. AI 深入分析（API + UI 实测）： - POST /cases/ZA-2026-0324/agent-suggestions/ai 返回 3 条，model=deepseek-v4-flash，覆盖超期时限、三级复核/会诊、文书解析与录音质检； - 1600×1000 点击「AI 分析」：按钮显示「分析中…」后变「重新分析」，3 条 AI 建议替换规则建议，底部提示“不含案卷正文，仅本次查看”；0 JS 错误、无横向溢出； - 输入白名单只含阶段、案件类型/状态/办理阶段和结构化事实，未发送案卷正文、客户姓名、案号、电话； - 冷却返回 400、模型失败返回 502 的路径已实现，规则建议保留。
33. 客服客户信息误跳案件修复（API + UI 实测）： - 客服角色客户列表 14 条，客户记录 caseId=null、nextFollow=''； - 点击客户行打开「客户信息」资料卡，显示头像、客户/阶段/在办案件 pill、手机号、负责人、分所、来源、下一步、备注、标签和合规提示，不再出现“客服无权查看案卷”； - 1600×1000 实测弹窗 680px、四格两列、无横向溢出、0 JS 错误；来源 referral 显示为“转介绍”； - 承办律师点击同一行仍打开 ZA-2026-0324 案件；0 JS 错误。

测试数据：

• 员工演示账号：13800000001～13800000005（客服/客户经理/谈案/承办/管理者）；仅 ZHUOAN_DEMO_SEED=1 时创建。
• 客户演示手机号：13200008888（何某，1 案，H5 固定演示账号）、13800000000（张某家属，1 案）、13700002222（王某，0 案）。
• 演示登录仅在 ZHUOAN_DEMO_SEED=1 时启用；生产仍走短信验证码。

9. 当前边界与下一步

• 生产短信通道未接；客户登录目前仅演示（固定账号免验证码）；生产仍走 OTP。
• 客户 H5 已支持共享文书查看/确认、材料补充、预约申请/取消、服务消息、客户经理/律师联系人；电子签、支付、实时聊天、扫描件 OCR 回执未做。
• 谈案录音已支持人工转写、五维规则质检、主管复核与列表指标；质检结果已按上传人汇总到律师评定；真实 ASR/LLM worker、与案件质量分/律师评级的加权规则尚未做。
• zhuoan_case_work 是原型通用表，正式版按诊断/方案/复核/会诊/结案/回访拆表并迁移。
• 客户 H5 的“阶段时间线”只显示节点推进，不显示内部案程；后续可按客户公开级别开放更多动作。
• 客服已可做客户/线索级回访；仍不能看案件、案卷和内部工作底稿，服务端边界不变。
• 会诊参与人已可登记/邀请/接受/拒绝并写审计；短信/企微邀请通道、会诊纪要模板、结论回写诊断尚未做。
• 归档六类材料分类、借阅到期提醒/超期、批量归档尚未做；借阅审批已闭环。
• 日程待提醒队列已可用，reminder worker 的真实短信/企微/站内推送未接。
• 文书版本目前是台账级列表，正文级 diff/合并未做。
• Agent 副驾采用方案 B：当前对象 + 授权范围内显式跨案 + 审计；全所聚合/全量搜索仍禁止。case_manager 写方法已统一改为待律师确认动作；建案仍回到案件列表/管理台。
• Agent 已按 12 个节点提供建议卡和副驾快捷提示；规则引擎读取时限、清单、文书、复核、录音数据生成默认建议，另提供可选「AI 分析」调用当前模型生成最多 3 条结构化建议；建议不自动执行，采纳率按点击/转任务去重统计，并已提供按节点/按用户明细、业务对象闭环推断、人工“已处理”标记和建议转任务；任务完成可反哺闭环。AI 分析只发结构化事实、不持久化、不写案件，真实模型效果取决于所选模型。
• 手机号唯一性已做应用层校验；生产建议加数据库唯一索引并做存量清洗。
• 全量代码快照与本次文档已提交 Gitee zaclaw。
• 六个占位模块已完成“队列 + 筛选 + 动作 + 权限”原型；三级复核流转、日程新增/编辑与冲突提示、文书生成/版本/送复核、会诊转任务、归档快照/冻结/借阅审批、客户级回访已完成原型。