卓安Claw 数据对象与状态机 v0.1

版本：v0.1（草案，待评审）
日期：2026-11-06
适用范围：卓安Claw V1 领域模型、状态机、业务不变量、编号规则
依据：《卓安Claw 业务流蓝图 v0.1》《卓安Claw 角色与权限矩阵 v0.1》、卓安需求文档
状态：需求讨论稿，不改代码；本文是逻辑模型，不是最终数据库 DDL

---

0. 结论摘要

1. 领域分为 7 块：组织权限、客户线索、诊疗主线、案件办理、商务财务、知识文档、审计协同。
2. 核心对象是 客户（Customer）→ 案件（Case）→ 诊疗记录（Encounter/Diagnosis/CarePath）；一个客户可以有多个案件，一个案件有多个阶段。
3. 客户五阶段与诊疗状态是两条独立状态轴；案件状态机是诊疗主线的执行态。
4. 所有关键对象带 org_id / branch_id / dept_id / version / data_class，支持多分所、权限、同步、分级。
5. 关键不变量：先冲突后建案、清单勾选不自动推进、结案归档五项齐全、支付/退款不超限、阶段历史只追加。
6. 所有金额用整数分存储；所有时间用 ISO 8601 + Asia/Shanghai；所有删除为软删除。

---

1. 建模原则

1. 逻辑模型优先：先定对象、关系、状态、不变量，不先定表结构。
2. 客户与案件分离：客户是长期关系，案件是一次委托/服务；一个客户可有多个案件。
3. 两条状态轴：客户阶段（邀约/谈案/签约/交付/维护）与诊疗状态（预约→随访）分开。
4. 事件留痕：状态推进、关键字段修改、文件上传、审批、Agent 调用都写事件。
5. 软删除 + 版本：不物理删除；关键对象有 version，冲突可检测。
6. 数据分级：每个对象/字段标 A/B/C/D，C 类默认不出私有云。
7. 可配置：字典、清单模板、审批流、分诊规则、报表不写死在代码里。

---

2. 领域划分与实体清单

2.1 组织与权限

实体	用途	关键字段	关系
Org	卓安租户	id, name, status	1→n Branch
Branch	分所	id, org_id, name, code, status	1→n Department
Department	部门	id, branch_id, name, type	1→n User
User	员工/账号	id, wecom_userid, name, phone, branch_id, dept_id, status	n→n Role
RoleAssignment	角色与数据范围	user_id, role, scope_type, scope_id	n→1 User
AdminGrant	管理员形态	user_id, admin_type, board_scope, channel_scope	n→1 User
CaseMember	案件团队成员	case_id, user_id, team_role, permissions	n→1 Case

2.2 客户与线索

实体	用途	关键字段	关系
Lead	线索	id, name, phone, source, region, status, owner_id, pool_reason	n→1 Customer（转化后）
Customer	客户主档	id, name, type, phone, region, stage, owner_chain, health	1→n Contact / Case / Contract
Contact	联系人	id, customer_id, name, relation, phone, id_no	n→1 Customer
Person	涉案人员（跨所共享）	id, name, id_no, role_tags, branch_scope	n→n Case
Appointment	预约/挂号	id, customer_id/lead_id, time, channel, lawyer_id, status	n→1 Customer/Lead
Triage	分诊	id, case_id/appointment_id, recommended_lawyer, reason, status	n→1 Case/Appointment
Encounter	接诊	id, case_id, lawyer_id, chief_complaint, facts, evidence_status, status	n→1 Case

2.3 诊疗主线

实体	用途	关键字段	关系
Case	案件	id, customer_id, case_no, matter_type, program_stage, stage, branch_id, lead_lawyer_id, contract_id, data_class	1→n Encounter/Diagnosis/Plan/CarePath/CaseLog
CaseStageHistory	阶段历史	id, case_id, from_stage, to_stage, actor, trigger, summary, version	n→1 Case
DiagnosticOrder	检查申请	id, case_id, type, items, assignee, due_at, status	n→1 Case
DiagnosticReport	检查报告	id, order_id, result, conclusion, files, reviewer, status	n→1 DiagnosticOrder
Diagnosis	诊断结论	id, case_id, version, elements, disputes, gaps, risk_level, defense_theory, status	n→1 Case
ServicePlan	服务方案	id, case_id, version, fees, scope, stages, risks, status	1→n PlanVersion
Consent	知情同意/风险告知	id, case_id, plan_id, type, signed_at, signer, evidence	n→1 Case/Plan
CarePath	标准办案路径实例	id, case_id, template_id, product, stage, status, completion_rate	1→n CarePathItem
CarePathItem	路径项	id, care_path_id, name, mandatory, status, reason, owner, due_at	n→1 CarePath
CarePathVariance	变异记录	id, item_id, reason, owner, due_at, status	n→1 CarePathItem
CaseLog	办案动态/病程	id, case_id, type, content, actor, at, attachments, status	n→1 Case
Review	三级复核	id, case_id, level, reviewer, opinion, result, at	n→1 Case
Consultation	会诊	id, case_id, type, participants, opinions, result, at	n→1 Case
ClosingReport	结案报告	id, case_id, result, summary, lessons, status	n→1 Case
Archive	归档	id, case_id, materials, checks, finance_review, status	n→1 Case
QualityReview	质量评查	id, case_id, rubric, score, findings, status	n→1 Case
FollowUp	随访	id, case_id/customer_id, type, plan_at, result, next_action	n→1 Case/Customer

2.4 商务与财务

实体	用途	关键字段	关系
Contract	合同	id, customer_id, case_id, contract_no, amount, products, status	1→n Payment/Refund/Invoice
Payment	回款	id, contract_id, case_id, amount, method, voucher, status	n→1 Contract
Refund	退款	id, contract_id, case_id, amount, reason, status	n→1 Contract
Invoice	发票	id, contract_id, case_id, amount, type, status	n→1 Contract
AccountBook	分所账套	id, branch_id, name, period, status	1→n Payment/Invoice
Allocation	分配	id, case_id, lawyer_id, ratio, version	n→1 Case

2.5 知识、文档与协同

实体	用途	关键字段	关系
Document	文件元数据	id, owner_type, owner_id, name, mime, size, sha256, oss_key, data_class, version	n→1 Case/Customer/Knowledge
DocumentVersion	文件版本	id, document_id, version, oss_key, uploader, at	n→1 Document
Template	文书模板	id, name, type, fields, version, status	1→n Document
KnowledgeDoc	知识空间文档	id, title, category, version, status, acl	1→n KnowledgeVersion
Approval	OA 审批单	id, type, applicant, case_id, form_data, status	1→n ApprovalNode
ApprovalNode	审批节点	id, approval_id, approver, action, opinion, at	n→1 Approval
Notification	通知	id, user_id, type, payload, read_at	n→1 User
Task	待办	id, owner_id, type, due_at, status, ref	n→1 User
AuditLog	审计日志	id, actor, action, object_type, object_id, before, after, at	独立
AgentRun	Agent 调用	id, user_id, case_id, intent, data_class, model, status	1→n ModelCall
ModelCall	模型调用	id, agent_run_id, provider, model, tokens, cost, redaction_count, at	n→1 AgentRun
SyncEvent	同步事件	id, entity, entity_id, op, version, payload, status	独立

---

3. 核心关系图

Org 1─n Branch 1─n Department 1─n User
Customer 1─n Contact
Customer 1─n Case 1─n CaseMember
Customer 1─n Contract 1─n Payment / Refund / Invoice

Case 1─n Appointment? (预约在建档前，挂 Lead/Customer)
Case 1─n Encounter 1─n DiagnosticOrder 1─n DiagnosticReport
Case 1─1 Diagnosis (按阶段版本化)
Case 1─n ServicePlan 1─n PlanVersion 1─n Consent
Case 1─n CarePath 1─n CarePathItem 1─n CarePathVariance
Case 1─n CaseLog
Case 1─n Review / Consultation
Case 1─1 ClosingReport 1─1 Archive 1─1 QualityReview
Case 1─n FollowUp
Case 1─n Document 1─n DocumentVersion

KnowledgeDoc 1─n KnowledgeVersion
Approval 1─n ApprovalNode
AgentRun 1─n ModelCall

预约/分诊在客户建档前后都可能发生：允许“先挂号后建档”，但建案前必须完成客户主档与冲突检索。

---

4. 公共字段与命名规则

4.1 所有核心对象公共字段

字段	类型	说明
id	string	全局唯一，建议 ULID/UUID
org_id	string	租户，固定卓安
branch_id	string	分所；总部对象可为空
dept_id	string	部门，可空
status	enum	业务状态
version	int	乐观锁/同步版本
data_class	enum	A/B/C/D
created_at / created_by	datetime / user_id	创建
updated_at / updated_by	datetime / user_id	更新
deleted_at	datetime	软删除
source	enum	web/desktop/wecom/import/agent
sync_status	enum	synced/pending/conflict

4.2 金额与时间

• 金额：amount_cents 整数，单位分；币种 CNY；禁止浮点。
• 时间：ISO 8601，带时区 Asia/Shanghai；日期与时间分开存。
• 比例：整数万分比（basis points），避免浮点。
• 文件大小：字节整数；哈希用 SHA-256。

4.3 编号规则

对象	规则	示例
客户	C-YYYY-NNNN（全局序列）	C-2026-001
案件	ZA-YYYY-NNNN（全局序列）	ZA-2026-0318
线索	L-YYYY-NNNN	L-2026-1024
预约	AP-YYYYMMDD-NNN	AP-20261106-001
接诊	EN-YYYY-NNNN	EN-2026-0042
检查	DG-YYYY-NNNN	DG-2026-0088
诊断	DX-YYYY-NNNN	DX-2026-0031
方案	PL-YYYY-NNNN	PL-2026-0027
合同	分所模板；内部 HT-YYYY-NNNN	卓（2026）WPS0318
回款	PAY-YYYY-NNNN	PAY-2026-0156
退款	RF-YYYY-NNNN	RF-2026-0012
会诊	CS-YYYY-NNNN	CS-2026-0042
冲突	CF-YYYY-NNNN	CF-2026-0039
归档	AR-YYYY-NNNN	AR-2026-0018
知识	KB-YYYY-NNNN	KB-2026-0102
Agent 调用	ARUN-YYYYMMDD-NNNN	ARUN-20261106-0001

编号全局唯一；分所简称只用于合同编号，不用于主键。编号生成必须原子、可审计、不可复用。

---

5. 核心状态机

5.1 线索（Lead）

当前	事件	目标	触发角色	守卫	副作用
待分配	分配	跟进中	客服/主管	有归属地/负责人	分配留痕；首联时钟启动
待分配	退回公海	已入公海	客服	七理由之一	理由/时间不可删
跟进中	转客户	已转化	客户经理	有姓名/电话/来源	深拷贝跟进/通话
跟进中	退回公海	已入公海	客户经理	七理由之一	留痕；可再分配
已入公海	再分配	待分配/跟进中	客服/主管	未被占用	分配留痕
已转化	—	终态	—	—	保留关联

• 大客户 10 分钟首联：assigned_at + 10min，未首联红标。
• 电话按值全所查重；重复标红但不拦截保存。

5.2 客户（Customer）

邀约 → 谈案 → 签约 → 交付 → 维护
                  ↑         │
                  └── 二次转化回谈案 ┘

当前	事件	目标	触发角色	守卫
邀约	标记已邀约	谈案	客户经理	邀约方式/时间/到场人数/拟谈案律师
谈案	成交	签约	谈案律师	有谈案记录 + 选产品
谈案	未成交	谈案（复盘）	谈案律师	原因 + 计划；3 日复盘
签约	线上/线下签署	交付	谈案律师	合同生效
交付	结案归档	维护	承办律师/管理者	归档完成
交付	二次转化	谈案	管理者/谈案律师	程序性产品交付后

• 回款不是客户阶段。
• 客户阶段推进写 CaseStageHistory 或 CustomerStageHistory（建议独立表，避免混用）。

5.3 预约 → 分诊 → 接诊

预约：待确认 → 已预约 → 已签到 → 已分诊 → 已接诊
异常：已取消 / 爽约 / 改期

分诊：待分诊 → 已推荐 → 已确认 → 已接诊
异常：已退回 / 转诊

接诊：待接诊 → 接诊中 → 已完成
异常：取消 / 改期

对象	当前	事件	目标	守卫
Appointment	待确认	确认	已预约	时段/律师可用
Appointment	已预约	签到	已签到	到店/线上
Appointment	已签到	分诊	已分诊	有分诊单
Triage	待分诊	推荐	已推荐	有候选律师+理由
Triage	已推荐	确认	已确认	主管/管理者确认
Encounter	待接诊	开始	接诊中	律师/客户到场
Encounter	接诊中	完成	已完成	主诉/案情/证据/诉求/风险告知

• 分诊推荐要考虑：案由、程序阶段、地域、紧急度、复杂度、律师专长、负荷、冲突。
• 冲突高风险必须先复核，不能直接确认分诊。

5.4 案件诊疗主线（Case）

建档 → 分诊 → 接诊 → 检查 → 诊断 → 方案 → 治疗 → 结果 → 归档 → 随访 → 关闭

异常：退回 / 转诊 / 终止 / 二次转化

当前	事件	目标	触发角色	守卫
建档	分诊确认	分诊	客服主管/管理者	客户主档 + 冲突检索
分诊	接诊开始	接诊	谈案/承办律师	有分诊单
接诊	接诊完成	检查	承办律师	接诊记录 + 风险告知
检查	报告齐	诊断	承办律师	检查报告已回传
诊断	诊断确认	方案	承办/谈案律师	诊断结论已签字
方案	客户确认	治疗	谈案/承办律师	方案 + 知情同意 + 合同
治疗	治疗结束	结果	承办律师	交付清单完成/说明
结果	结案确认	归档	承办律师	结案报告 + 财务状态
归档	归档完成	随访	承办/管理者/财务	归档五项齐全
随访	关闭	关闭	客户经理	回访完成/转投诉/二次转化

• 阶段推进写 CaseStageHistory（操作人、时间、触发方式、摘要、版本校验）。
• 清单勾选不自动推进阶段；推进由承办律师确认。
• 终止/转诊必须写原因、责任人、客户确认。

5.5 服务方案（ServicePlan）与合同（Contract）

方案：草稿 → 内部审核 → 客户确认 → 已签约 → 已交接
异常：已拒绝 / 已失效 / 已修订

合同：草稿 → 待签署 → 签署中 → 已生效 → 履行中 → 已完结
异常：已解除 / 已作废

对象	当前	事件	目标	守卫
ServicePlan	草稿	提交审核	内部审核	费用/范围/风险齐全
ServicePlan	内部审核	通过	客户确认	审核人签字
ServicePlan	客户确认	签署	已签约	合同生效
ServicePlan	已签约	交接	已交接	承办律师确认
ServicePlan	任意	修订	草稿（新版本）	保留旧版本
Contract	草稿	发起签署	待签署	方案已确认
Contract	待签署	对方签署	签署中	签署人身份
Contract	签署中	本所用印	已生效	用印审批
Contract	已生效	开始履行	履行中	首笔回款/交付开始
Contract	履行中	结束	已完结	服务完成/结案

• 方案版本化：每次修订生成新版本；绑定合同的是“已确认版本”。
• 合同金额变更必须走审批；已生效合同不允许直接改金额。

5.6 回款（Payment）与退款（Refund）

回款：待登记 → 待审核 → 已通过 → 已入账
异常：已驳回 → 重新登记（关联原单）

退款：待登记 → 待审核 → 已通过 → 已退款
异常：已驳回

对象	当前	事件	目标	守卫
Payment	待登记	提交	待审核	合同/金额/凭证
Payment	待审核	通过	已通过	财务审核意见
Payment	待审核	驳回	已驳回	驳回原因
Payment	已通过	入账	已入账	银行流水匹配
Refund	待登记	提交	待审核	原因/金额/凭证
Refund	待审核	通过	已退款	原回款足够

• 待收 = 合同额 − 已通过回款合计；退款不参与。
• 退款不得超过已通过回款；超额需财务特批并留痕。
• 同一订单不可重复登记回款；幂等键 = 合同/订单 + 回款流水号。

5.7 办案路径（CarePath）与清单项

路径：未开始 → 进行中 → 已完成 → 已关闭
清单项：未开始 → 进行中 → 已完成
异常：不适用 / 未完成（需原因/责任人/补正期限） / 已验收

当前	事件	目标	守卫
未开始	启动	进行中	有模板/产品/阶段
进行中	全部完成	已完成	必做项完成或已说明
进行中	关闭	已关闭	终止/转诊/结案
清单项 未开始	开始	进行中	有责任人
清单项 进行中	完成	已完成	有完成证据
清单项 进行中	标不适用	不适用	条件项 + 原因
清单项 进行中	未完成	未完成	原因 + 责任人 + 补正期限
清单项 未完成	补正	已完成	有补正证据

• 清单勾选不自动推进案件阶段。
• 必做项未完成，结案/归档硬拦截。
• 变异原因分类：客户原因/法院原因/证据原因/律师原因/其他；统计变异率。

5.8 结案、归档、质量评查

结案：草稿 → 待审核 → 已通过 → 已归档
异常：已驳回

归档：待归档 → 材料检查 → 财务审核 → 质评 → 已归档
异常：已退回

质评：待评查 → 评查中 → 通过
异常：整改中 → 复核 → 通过 / 不通过

对象	当前	事件	目标	守卫
ClosingReport	草稿	提交	待审核	结案检查完成
ClosingReport	待审核	通过	已通过	管理者审核
Archive	待归档	材料检查	材料检查	六类材料
Archive	材料检查	财务审核	财务审核	归档检查合格
Archive	财务审核	质评	质评	财务归档审核通过
Archive	质评	归档	已归档	评查合格 + 是否成功案例
QualityReview	待评查	开始	评查中	评查人
QualityReview	评查中	通过	通过	评分/结论
QualityReview	评查中	整改	整改中	不符合项
QualityReview	整改中	复核	复核	整改材料

• 归档五项：结案评查合格、六类材料、归档检查、财务归档审核、是否成功案例。
• 质量评查独立；重复进入不覆盖已评结果。

5.9 审批（Approval）

草稿 → 待审批 → 审批中 → 已通过 / 已驳回 / 已撤回

• 审批类型：用章、报销、采购、费用、个人账发款；后续可扩展。
• 每个节点记录审批人、动作、意见、时间；不可跳节点。
• 驳回后可重新提交，关联原单；原单留痕。

5.10 Agent 调用（AgentRun）

待执行 → 执行中 → 已完成 → 已确认 / 已拒绝
异常：失败 / 超时 / 越权拒绝

• 记录：用户、案件、意图、数据级别、模型、输入哈希、输出哈希、token、成本、脱敏计数。
• C 类调用默认拒绝；例外需审批。
• Agent 输出默认草稿；确认后才写业务对象。

---

6. 关键业务不变量

编号	不变量	说明
INV-01	建案前必须有客户主档 + 冲突检索	高风险未复核不得建案
INV-02	同一客户同一委托不得重复建案	已有未归档案件时拦截；新委托需新合同
INV-03	阶段历史只追加	不修改、不删除；版本校验防覆盖
INV-04	清单勾选不自动推进阶段	推进由承办律师确认
INV-05	必做项未完成不得结案/归档	需原因/责任人/补正期限
INV-06	所函数 ≥ 办案动态数	结案/归档硬拦截
INV-07	归档五项齐全	缺一不可
INV-08	待收 = 合同额 − 已通过回款	退款不参与
INV-09	退款 ≤ 已通过回款	超额需特批
INV-10	合同金额变更必须审批	已生效合同不可直接改
INV-11	文件只增版本，不覆盖	旧版本可追溯
INV-12	审计日志只追加	不可修改、不可删除
INV-13	C 类数据默认不出私有云	外部模型调用需审批
INV-14	Agent 不审批、不签字、不付款	只能出草稿/建议
INV-15	软删除，不物理删除	删除需管理者；保留审计

---

7. 数据分级与保留

对象/字段	级别	说明
法条、模板、公开案例	A	可出域
客户姓名/电话/案由/阶段	B	脱敏后可出域
证据、笔录、录音、身份证、案卷全文	C	默认不出域
个人记忆、草稿	D	本机/加密，不共享
财务金额/发票	B/C	按角色与账套
审计日志	C	仅管理者/合规

• 保留年限：案卷 5/10/15 年待定；审计 5/10 年待定；财务按会计档案规定。
• 删除：到期归档/销毁需审批；销毁记录保留。

---

8. 同步与冲突

• 所有可同步对象带 version、updated_at、sync_status、etag。
• 客户端写操作带 idempotency_key；服务端去重。
• 冲突策略：
• 非关键字段：最后写入胜出（记录前值）。
• 关键字段（金额、状态、合同、方案、清单）：版本冲突，生成冲突副本，人工合并。
• 文件：只增版本，不覆盖；同名上传生成新版本。
• 删除：软删除墓碑，防“删除后复活”。
• 离线：本地队列 + 重连重放；冲突进入待处理列表。

---

9. 待确认事项

编号	事项	影响
TBD-D01	一个客户是否允许多个未归档案件	建案拦截规则、案件模型
TBD-D02	案件是否按“审级/程序阶段”拆子案件	一审/二审/执行的数据归属
TBD-D03	诊断是否按阶段版本化	一审/二审诊断分开
TBD-D04	方案版本与合同的绑定规则	合同变更、补充协议
TBD-D05	超额回款/退款规则	财务审核、特批
TBD-D06	归档是“按案件”还是“按委托/审级”	归档对象
TBD-D07	质量评查对象是案件还是律师	统计口径
TBD-D08	案卷/审计保留年限	存储、合规
TBD-D09	编号是否分所独立序列	编号冲突、迁移
TBD-D10	OA 历史审批单如何映射到 Approval	迁移字段

---

10. 下一步

1. 确认 TBD-D01～TBD-D10，尤其是 TBD-D01（多案件）、TBD-D02（审级拆分）、TBD-D08（保留年限）。
2. 本模型确认后，出《页面与交互清单 v0.1》和《接口清单 v0.1》。
3. 再进入技术设计与 POC；仍不改代码。

---

---

11. 补充：客户小程序对象（2026-11-06 新增）

实体	用途	关键字段	关系
PortalAccount	客户微信账号	id, openid, unionid, phone, status	1→n ClientBinding
ClientBinding	客户-合同/案件绑定	id, portal_account_id, customer_id, contract_id, case_id, role, scope, status	n→1 PortalAccount
QRToken	签约二维码	id, contract_id, case_id, token_hash, expires_at, used_at, status	n→1 Contract
CasePublication	案件公开档位	id, case_id, profile, status, published_by, expire_at	1→1 Case
ClientUpdate	客户版动态	id, case_id, title, fact, action, next_step, visibility, publish_at, expire_at, status	n→1 Case
SharedDocument	共享文书	id, document_id, case_id, visibility, watermark, expire_at	n→1 Document
PortalMessage	通知/留言	id, case_id, direction, content, status	n→1 Case
PortalAccessLog	客户访问审计	id, portal_account_id, binding_id, case_id, action, object, at, ip/device	独立

状态机：

绑定：待验证 → 待绑定 → 已绑定 → 已解绑 / 已撤销
公开：未公开 → 仅进度 → 标准 → 详细；任意 → 暂停 / 过期
动态：草稿 → 待审核 → 已发布 → 已撤回 / 已过期
二维码：有效 → 已使用 / 已过期 / 已撤销
文书：未共享 → 已共享 → 已撤回 / 已过期

关键不变量：

• 默认不公开；客户只看公开档位内内容。
• 客户版动态不是 CaseLog 原文；必须改写/审核。
• 合同号不得单独作为身份凭证。
• 客户只读；不能看其他客户/内部字段。
• 发布/撤回/访问全审计；文件带水印。

---

本文为需求讨论稿，不构成开发承诺；逻辑模型以最终评审版为准。