OrcGo@Cong — 2026.09.17
← Wiki 索引

房产SaaS签约全端开发设计规范

最后更新 · 2026/09/11

文档版本： v3.0
状态： 全端页面化精炼版，已清洗代码噪音，聚焦字段、操作状态与交互流程

目录

第一部分：全端页面规范与核心交互

第二部分：核心状态字典与流转逻辑

  1. 业务状态字典 （合同包、子合同、审批流、房源锁定状态）
  2. 核心机制流程说明 （三要素强阻断、用印安全锁、延期截止日计算）

第三部分：系统校验、权限与异常场景

  1. 全局表单校验总表
  2. 角色权限矩阵
  3. 异常场景清单

第四部分：联调验收、测试与设计交付

  1. 前后端业务联调时序图
  2. 可执行测试用例集
  3. UI设计交付物清单

第一部分：全端页面规范与核心交互

一、门店级电子签约配置页

1.1 页面基础信息

  • 页面路径：/admin/esign-config
  • 页面标题：门店电子签约配置
  • 权限要求：系统管理员
  • 页面布局：顶部标题区 + 门店列表表格

1.2 配置侧拉抽屉（子页面）

  • 展示形式：从页面右侧滑出，自适应响应式宽度。
  • 录入及展示字段：
    • 电子签约开关（启用/停用）
    • 可用签约主体（多选，来自已启用的丙方主体列表）
    • 买卖签署顺序模式（单选：先审后签/先签后审）
    • 买卖落章控制（单选：自动/手动；联动约束：当买卖签署顺序为“先签后审”时，落章控制强制置灰并锁定为“手动”）
    • 租赁签署顺序模式（单选：先审后签/先签后审）
    • 租赁落章控制（单选：自动/手动；联动约束：同买卖联动规则）
    • 签署有效期（整数输入，必须在 1 ~ 30 天之间，控制合同包的最长签署生存期）
    • 单日最大催签次数（整数输入，若填0则不允许催签）
    • 两次催签最小间隔（整数输入，固定锁死最低 2 小时）
    • 适用审批流规则（只读显示当前生效的签约、解约、变更审批流链路）

1.3 核心交互与操作状态

  • 加载与保存：点击门店“配置”按钮滑出抽屉，读取该店最新配置；点击“保存配置”时，前端与后端须双重校验“先签后审 + 自动落章”的冲突，违规时拦截保存并警告。

1.4 通用审批流规则配置页（可视化编排面板）

  • 页面路径：/admin/workflow-config
  • 页面标题：通用审批流配置
  • 字段录入及校验规则：
    • 审批类型（单选：签约审批/解约审批/补充协议审批）
    • 适用范围（下拉多选，可选“全局规则”或具体门店）
      • 门店唯一性限制：同类型审批流下，已被其他审批流占用的门店在下拉菜单中必须置灰禁用。若已存在该类型的“全局规则”，则所有门店和“全局规则”复选框在其他规则中均置灰禁用。
    • 审批人设置：
      • 部门角色：固定为“门店管理员”，隐藏角色选择下拉框。多人审批（或签/会签）单选框强制保留并启用。
      • 指定人员：下拉复选列表须根据所选“适用范围”过滤（全局则拉取全公司，门店则只拉取该门店人员）。若只勾选 1 人，隐藏多人审批选项；勾选 2 人及以上时展示多人审批选项。
    • 抄送人设置：
      • 仅保留“不抄送”和“指定人员”（已移除了“部门角色”）。
      • 选择“指定人员”时，展示包含全公司所有人员的复选框列表，且按组织架构（所属门店/部门）进行二级分组并支持折叠，允许跨店/跨部门多选抄送人员。
    • 联动清退：适用范围变更时，系统必须自动剔除已选审批人中不属于新范围的员工，防止越权；抄送人员因是全局多选且支持跨店，故不执行清退。

二、签约主体维护页

2.1 页面基础信息

  • 页面路径：/admin/signing-principals
  • 页面标题：签约主体维护
  • 权限要求：系统管理员
  • 页面布局：顶部标题区 + [新增主体]按钮 + 主体数据列表

2.2 新增主体弹窗（子页面）

  • 录入字段：
    • 企业名称（2-100字符，必须与e签宝企业主体一致）
    • 统一社会信用代码（18位，入库统一转换大写）
    • 法人姓名、法人电话、法人身份证（企业三要素，用于法人认证）
  • 授权盖章人维护区：
    • 可添加多名企业员工作为盖章人，字段包括：姓名、手机号、身份证号。
    • 盖章人状态控制：提供“激活/禁用”切换按钮，任何时候一个签约主体下只能有唯一一名“当前激活”状态的授权盖章人。

2.3 交互流程与主体状态

  • 法人确认激活流程：新增主体录入后，主体状态强制为“待法人确认”。系统将自动向法人发送激活短链，只有法人在短信中确认之后，主体状态方可启用为“已启用”。未启用的主体不可用于配置合同模板或发起签约。
  • 盖章人授权确认流程：所有新增授权盖章人提交后一律强制为“待法人确认”状态，系统向法人发送授权确认短信，法人点击确认后方才变更为“已授权”并允许切换激活。在列表中，系统为待法人确认的主体和盖章人提供“短信催办法人”的催办通道，以便在 Demo 中模拟法人的短信核验闭环。
  • 盖章人激活控制：提供“激活/禁用”切换按钮，任何时候一个签约主体下只能有唯一一名“当前激活”状态的授权盖章人。只有被添加且状态处于“当前激活”的盖章人，在“手动落章”时才拥有签署丙方公章的调用权限。

三、合同模板管理页

3.1 页面基础信息

  • 页面路径：/admin/contract-templates
  • 页面标题：合同模板管理
  • 权限要求：系统管理员
  • 页面布局：模板卡片列表 + 检索过滤栏 + [新增合同模板] 按钮。

3.2 模板列表项操作规范

每一项合同模板卡片/表格行提供操作下拉菜单，包含以下核心操作：

  1. 编辑模板：点击后进入模板编辑器页面，回显当前模板内容及配置。
  2. 复制模板：点击后直接在后台深度复制该模板，并自动命名为 [原模板名称]_副本，状态默认为“已停用”并加入列表首部。
  3. 启用/停用模板：状态切换按钮。已停用的模板将不可在“发起在线签约”时被检索到。
  4. 预览正文：点击后弹出遮罩窗口，以只读 HTML 形式渲染当前模板的合同文本以及关联主体、盖章人信息。
  5. 删除模板：危险操作，点击后须通过系统遮罩二次确认弹窗（Confirm），点击确定后执行物理删除。

3.3 模板编辑器与配置表单（子页面）

  • 路径格式：/admin/template-editor/:id
  • 录入配置字段：
    • 模板名称（必填，2-100字符，规范描述如“房屋租赁居间合同(简易版)”）
    • 合同类型（单选下拉框，包含：买卖居间合同、租赁居间合同、佣金确认书、贷款服务费确认书、补充协议书、解约协议书）
    • 适用范围（门店选择）：
      • 下拉多选复选框，包含“全部门店范围”以及各分店。
      • 门店选择规则：若勾选“全部门店范围”，其他各店复选框自动取消勾选；若勾选具体门店，则取消勾选“全部门店范围”选项。
  • 编辑器交互流程：
    1. 支持在富文本编辑区中直接拖拽系统内置标签（如甲方姓名、乙方姓名、房源地址、成交价等）。
    2. 必须明确设定签约文本中“签章占位符”（指定甲、乙、丙方在 PDF 中的落章位置坐标或关键字如 #甲方签字区#、#乙方签字区#、#丙方盖章区#）。若缺失关键字，保存时强制拦截并警告。
    3. 编辑完成后点击顶栏右侧的 [保存模板设置] 按钮。保存成功后自动提示并将数据同步至 SaaS 后台，返回模板列表页。

四、发起在线签约弹窗

4.1 基础信息

  • 触发方式：在房源成交页或待签约列表页点击“发起在线签约”激活模态弹窗。
  • 权限要求：经纪人或门店管理员。

4.2 输入字段与校验

  • 业务类型选择：买卖 / 租赁（根据选择动态展现下方表单项）。
  • 签约三要素（甲方 & 乙方）：
    • 姓名（必须真实）、手机号（11位）、身份证号（18位，若末位为X/x自动大写转换）。
  • 价格及佣金（金额数据统一保留2位小数）：
    • 成交总价（买卖） / 月租金（租赁）：必须大于0。
    • 甲方佣金 / 乙方佣金：必须大于或等于0。双方佣金均为0时允许正常提交发起（此时系统只生成主合同，不生成居间佣金确认书）。
  • 付款及服务选项：
    • 买卖模式下：付款方式（全款/贷款）。若选贷款，贷款金额为必填（大于0）；贷款服务费（选填，大于0时自动附加生成贷款服务确认书）。
    • 租赁模式下：合同租期起止时间（结束日期必须晚于开始日期）、付款周期（自定义输入或枚举选择）。

4.3 核心交互与校验阻断流程

  1. 核验阻断机制：点击提交时，系统实时触发e签宝三要素校验接口。若校验不通过（如身份证姓名不匹配、手机未实名等），弹窗强制拦截，展示具体失败信息，并且绝对不提供任何“强行提交/绕过校验”的勾选框或豁免接口。
  2. 房源状态联动：点击发起时，系统对房源进行锁定（预锁定 30 分钟，超时未提交则自动释放；提交成功后房源状态转为“已成交锁定”）。

五、合同管理中心页

5.1 页面基础信息

  • 页面路径：/contracts
  • 页面标题：合同管理中心
  • 权限要求：所有角色（根据组织架构和角色查看范围进行行级数据过滤）

5.2 合同详情抽屉（子页面）

  • 展现形式：右侧滑出，自适应宽度，使用“双域固顶”排版（基本信息和 Tab 导航固顶不滚动，文件与日志内容区可独立纵向滚动）。
  • 主切换页签：
    • 1. 合同预览和签署进度：提供 首次签署(first)、合同变更(modify)、合同解约(void) 三个子页签，根据合同生命周期状态自动显隐。当处于“合同变更”和“合同解约”时，文件展示区域严禁展示原始合同内容，仅渲染呈现对应的补充协议（可有多份）或解除协议。
    • 2. 审批进度：展示该合同关连的内部审批链（如首次发起审批、变更审批、解约审批的时间轴）。
    • 3. 操作记录和日志：展示详细的审计日志（包含操作人、动作、哈希存证对比状态等）。
  • 不同状态下的操作按钮矩阵：
    • 草稿(draft)：[编辑]、[删除]、[提交签约]
    • 三要素失败(auth_failed)：[修正三要素并提交]
    • 签约中(signing)：[催签]（频控校验：2小时内限催1次，达到单日限制时置灰）、[延期]、[撤回重签]（若已有一方签署，点击时强制弹出文本框，要求录入不少于5字撤回原因）
    • 已完成(completed)：[发起合同变更]（发起补充协议）、[发起合同解约]
    • 已撤销(revoked) / 已作废(voided) / 已驳回(rejected)：所有编辑修改类按钮隐藏，仅保留只读[预览]和[操作日志]

六、我的审批中心页

6.1 页面基础信息

  • 页面路径：/my-approvals
  • 页面标题：我的审批中心
  • 权限要求：审批流中相关审批人

6.2 审批详情抽屉（子页面）

  • 功能结构：右侧滑出自适应抽屉。展示审批基本信息、交易核心字段及对应的流程时间轴卡片。在变更/修改类审批详情下，“待签署的新协议文件”需依据关联合同包中勾选变更的子合同数据，动态渲染对应的多份补充协议卡片并分别提供独立的预览按钮。
  • 审批决策交互：
    • 审批人不可以在主页面直接输入意见。点击[通过]或[驳回]后，弹出模态决策弹窗。
    • 若选择[驳回]，审批意见为必填项（不得少于10字）；若选择[通过]，意见允许为空，系统默认填充“同意”。
  • 驳回联动规则（用印风锁联动）：
    • 在“先签后审”模式下，外部客户双签可能已经完成。若此时审批人驳回，系统自动拦截物理作废，并根据签署状态联动：若外部客户均已签署，禁止在后台直接一键物理清除合同，系统必须自动开启“解约协议审批”流程。

七、操作日志审计中心页

7.1 页面基础信息

  • 页面路径：/admin/audit-logs
  • 页面标题：操作日志审计中心
  • 权限要求：系统管理员
  • 页面布局：高危看板区 + 复合筛选区 + 日志数据表格区

7.2 功能设计与字段表现

7.2.1 高危审计看板卡片
  • 字段及指标展示：
    • 今日三要素失败阻断：展示今日因三要素核验失败导致的阻断总次数（AUTH_FAILED）。
    • 今日中途撤回重签：展示今日已被签署部分撤销的累计次数（REVOKE）。
    • 今日签约审批驳回：展示今日签约审批驳回的次数（REJECT）。
  • UI 交互：数值超过 5 次时，系统自动橙色警告；超过 10 次时红色警示，辅助管理员迅速关注潜在合规风险。
7.2.2 复合筛选字段与校验
  • 合同编号：输入框，支持模糊检索。
  • 操作人姓名：输入框，支持操作主体模糊检索。
  • 操作动作类型：下拉选择，包含 INITIATE、AUTH_FAILED、CORRECT_AUTH、APPROVE、REJECT、REVOKE、DELAY、SEAL 动作枚举。
  • 安全哈希校验：下拉选择，选项包括：全部状态、哈希检测通过、哈希检测异常。
7.2.3 审计日志表格列定义 (共 9 列)
  1. 日志ID：只读，自增。
  2. 操作时间：只读，精确到秒。
  3. 操作主体：只读，格式为：姓名 (工号) - 角色 · 部门。
  4. 关联合同包：只读，显示合同编号。
  5. 操作动作：只读，彩色标签。
  6. 状态跳变：只读，显示 before -> after。
  7. 操作终端 (IP/设备)：只读，展示客户端物理 IP 地址与系统/浏览器内核设备指纹。
  8. 详细描述：只读，包含事实描述。
  9. 防篡改哈希：只读。当 Hash 值匹配成功时，左侧显示 绿色盾牌；当匹配失败（检测到物理改写）时，行背景高亮浅红，左侧显示闪烁的 **红色警报 **。

7.3 操作日志审计流水内容清单与描述模板

7.3.1 基础展示字段
  • 操作时间：精确到秒（格式 YYYY-MM-DD HH:mm:ss）。
  • 操作主体（Operator）：部门 + 角色 + 姓名（如 平安路门店 - 经纪人 - 张三；若为系统触发则显示为 系统自动 或 e签宝回调）。
  • 动作类型（Action）：用于检索分类（如 INITIATE, AUTH_FAILED, APPROVE, DELAY, REVOKE, SIGN 等）。
  • 详细描述（Description）：详细的人类可读描述文案。
  • 状态变更（State Change）：记录流转变化，如 approving_new -> signing。
7.3.2 触发场景与具体描述文案模板
触发动作 (Action) 状态变更 (State Change) 详细描述文案模板
INITIATE (空) -> approving_new 或 signing 发起了在线签约申请，系统已自动锁定房源 [房源地址]。
AUTH_FAILED (空) -> auth_failed 三要素自动核验失败。失败原因：[e签宝返回的具体失败原因]。合同包转入三要素不一致状态。
CORRECT_AUTH auth_failed -> signing 修正了签署方三要素信息（[甲方/乙方] 手机号由 [旧号码] 修改为 [新号码]），重新核验通过并激活了新签署流程。
SUBMIT_APPROVE - 将合同包提交至审批流，当前等待 [节点审批人] 审批。
APPROVE approving_new -> signingapproving_void -> signing_voidapproving_modify -> signing_modify [审批人] 同意了该合同的 [签约/变更/解约] 申请。审批意见：[审批意见内容，若为空显示“同意”]。
REJECT approving_new -> rejected其他同上 [审批人] 驳回了该合同的 [签约/变更/解约] 申请。驳回原因：[审批人填写的驳回意见]。
ADD_SIGN - [当前审批人] 邀请了 [加签人] 进行 [前加签/后加签] 共同审批。
SIGN signing -> signing [甲方/乙方] 已通过e签宝完成电子签名。签署时间：[精确时间]。
REJECT_SIGN 首次签约：signing -> revoked/rejected补充/解除：signing_xxx -> completed [甲方/乙方] 拒绝了签署邀请。拒签原因：[客户填写的拒签理由]。
SEAL signing -> completed 丙方授权盖章人 [盖章人] 经人脸核验通过，成功加盖企业公章，完成最后落章归档。
DELAY signing -> signing 申请了对合同包的延期，延期天数：[X]天。新的签署截止日期为：[新日期]。
REVOKE signing -> revoked 撤销了该合同包的首次签署流程。撤销原因：[撤回原因]。系统将锁定该房源 2 小时以供重新发起。
EXPIRED signing -> signing 系统检测到已超过设定的签署截止时间 [截止时间]，客户签署链接已失效。
MODIFY_APPLY completed -> approving_modify 发起了合同变更申请。变更原因：[变动内容描述]。系统将生成补充协议签署流程。
VOID_APPLY completed -> approving_void 发起了合同解约申请。解约原因：[解约原因描述]。系统将生成解除协议签署流程。
VOID_COMPLETE signing_void -> voided 双方已完成解除协议签署。合同包正式作废，本地 PDF 副本已加盖“已解除VOID”防伪水印，房源锁定已自动释放。

八、移动端发起签约页

8.1 页面基础信息

  • 页面路径：/mobile/initiate
  • 页面布局：移动端全屏表单页，顶部包含返回导航标题栏。表单通过可滚动区域与底部固定操作按钮（[预览拟真合同协议] 和 [发起签约流程]）排版。

8.2 字段与交互设计规范

  • 交易类型切换：顶部切换 Tab（二手房买卖 / 房屋租赁），切换后表单字段动态显隐。
  • 通栏输入卡片与表单字段要求：
    • 基本与主体字段：
      • 签约主体 (丙方)：下拉选择框，展示当前门店已启用且法人激活的丙方主体。
      • 房源物理地址：单行文本输入框，必填，提示：“输入房源完整门牌地址”。
    • 客户三要素（甲乙方）：
      • 甲方 (卖方/房东) 与 乙方 (买方/租客)：采用姓名、手机号、身份证号的并列/通栏输入。
      • 字段校验：在用户离开焦点 (blur) 及最终提交时进行校验。姓名（2-20字，无数字符号）、手机号（11位大陆号码规范）、身份证号（18位，末位X校验，自动转大写）。
    • 合同签署方式：单选按钮组（电子合同 / 纸质合同），默认为电子合同。
    • 买卖专属字段：
      • 成交总价 (元)：必填，必须大于0。
      • 付款方式：下拉选择框（全款支付 / 商业贷款）。
      • 贷款信息：若选择“商业贷款”，动态展示“贷款金额 (元)”和“贷款服务费 (元)”输入框。贷款金额必填（大于0），贷款服务费选填（大于等于0，若大于0则联动生成贷款服务费确认书）。
      • 佣金比例/金额：甲方佣金 (元) 和 乙方佣金 (元)，默认 0，必填且大于等于0。
    • 租赁专属字段：
      • 月租金 (元) 与 押金金额 (元)：必填，必须大于0。
      • 租期起止时间：两个日期选择器（租期起止、租期结束）。结束日期必须晚于开始日期，系统将根据所选日期实时计算并以只读方式展示在“计算租期”文本框内（格式如：“X 个月”）。
      • 付款周期：下拉选择框，包含 押一付一、押一付三、押一付六、押二付三、自定义。选择“自定义”时，动态滑出“自定义付款周期描述”文本输入框。
      • 佣金金额：房东佣金 (元) 和 租客佣金 (元)，默认 0，必填且大于等于0。
    • 模板自定义动态字段：
      • 提供模板自定义扩展变量输入（如“交房宽限天数”、违约比例% 等）。

8.3 交互与拦截校验规范

  • 核验阻断机制：点击发起签约时，前台将数据提交至后端 API，并调用e签宝三要素核验服务。
    • 若三要素校验不通过（如身份证姓名不匹配、手机未实名等），前台拦截并实时在字段底部标红报错，弹出系统级阻断弹窗展示具体核验错误原因。
    • 核验容错豁免机制：若同一合同连续 3 次核验失败，前台需根据系统授权情况，对拥有“豁免权”的操作员或管理员展示“强制跳过校验直接下发”的豁免确认按钮，允许先建立合同包（注：SaaS 系统会通过日志审计追踪此类豁免高危行为）。
  • 拟真预览：点击“预览拟真合同协议”时，调用后台 PDF 生成引擎的模板插值，以 HTML H5 拟真渲染方式呈现合同正文及签字章预设区。

九、移动端合同管理中心页

9.1 页面基础信息与搜索过滤

  • 页面路径：/mobile/contracts
  • 布局规范：列表采用卡片流呈现，页面顶部提供复合检索和过滤区。
  • 搜索与筛选交互：
    • 全局搜索：支持房源地址、合同编号、甲方姓名、乙方姓名的模糊输入检索。
    • 筛选抽屉面板：点击右上角筛选按钮，向下展开筛选选项卡：
      • 合同类型：[全部类型]、[买卖]、[租赁] 快捷切片 (Filter Chip)。
      • 合同状态：[全部]、[审批中]、[签约中]、[已完成]、[已作废] 切片，点击后列表卡片流实时局部刷新。

9.2 移动端合同详情页（全屏子页面）

  • 展示要求：必须采用全屏跳转页面方式承载，严禁使用底部抽屉展示。顶部为返回主页导航与合同包编号。
  • 信息展示排版：
    • 交易核心信息卡片：包含房源物理地址、交易类型、合同金额、付款方式、签署方式、经办经纪人等。
    • 签署主体与状态组件：列出甲、乙、丙三方的主体类别、联系电话、身份证号及当前子文件的个人签署/盖章状态（待签署/已签署/待盖章）。
    • 审批及签署子 Tab 面板：包含“首次签署”、“合同变更”和“合同解约”子选项卡，显示该合同包所处生命周期各阶段的内部审批流节点时间轴、签署流进度和审计日志 Timeline。
    • 合同文件预览：提供所包含文件的轻量级卡片，点击即可全屏预览 HTML 生成的只读合同正文。

9.3 动态吸底操作按钮矩阵与核心逻辑

根据合同包所处的状态，详情页底部展示差异化的功能按钮组合：

  1. 签约中 (signing) / 变更签署中 (signing_modify) / 解除签署中 (signing_void)：
    • [催签]：触发催签请求。
      • 频控约束规则：点击时，前台将核验该合同包在本地/服务端的催签限制。两次催签的时间间隔必须大于或等于签约配置中的“催签间隔时间”（如最低 2 小时）；若未满 2 小时，点击时弹窗阻断并高亮提示“催签过于频繁，请于 X 分钟后再试”；若今日催签次数已达单日上限，则按钮置灰并显示“今日催签已达上限”。
    • [延期]：点击后底部弹出抽屉，提供 3天、7天、15天 快捷延期选项。
      • 30天上限控制：系统必须动态评估：当前截止日期 + 申请延期天数 - 首次发起时间 是否大于 30 天。若对于某些选项大于 30 天，则该天数按钮必须置灰并禁用；若全部天数均超限，则整体延期操作禁用。
    • [撤回签约] / [撤回重签]：
      • 若当前已有任何一方签署（甲方或乙方已签字），点击撤回时强制弹出意见录入框，要求录入不少于 5 字的撤回原因；点击确认后，系统作废原流程并将房源状态变更为“撤回重签锁定”，限制 2 小时内不得将房源移作他用。
  2. 三要素失败 (auth_failed)：
    • [修正三要素并重新发送]：点击后全屏跳转至修正子页面。
  3. 已完成 (completed)：
    • [变更协议]：启动合同变更，生成补充协议，关联原合同并提交内部变更审批流。
    • [解约协议]：启动合同解约，生成解除协议，提交内部解约审批流。
  4. 已作废 (voided) / 已撤销 (revoked) / 已驳回 (rejected)：
    • 不显示任何写操作按钮，详情页呈纯只读状态。

9.4 移动端修正三要素页（全屏子页面）

  • 业务场景：电子签约发起后，e签宝校验若返回三要素失败，详情页提供“修正三要素”入口。
  • 表单设计：全屏表单形式。顶部回显核验失败的具体原因（如“身份证与姓名不匹配”），下方展示之前录入的甲乙方信息，并对姓名、电话、身份证号字段提供可编辑的文本框。
  • 保存提交：点击确认保存时，前台校验格式并重新向后端提交核验。核验通过后，系统自动重置该合同包状态为“签约中”，并向纠正后的正确手机号重新推送签署短链。

十、移动端我的审批列表页

10.1 页面基础信息

  • 页面路径：/mobile/approvals
  • 页面布局：包含“我发起的”、“待我审批”、“我已审批”、“抄送我的”四个过滤维度以及状态过滤切片。列表使用分页卡片流展示审批单摘要。

10.2 移动端审批详情页（全屏子页面）

  • 打开方式：全屏页面跳转，顶部为标准返回及审批单名称。
  • 信息层级：
    • 审批摘要：显示审批类型（如“签约审批”、“补充协议审批”、“解约审批”）、关联的合同包编号及房源物理地址。
    • 交易明细：详细呈现交易核心数据（价格、佣金、交房天数、付款周期等）。
    • 可视化审批链：以垂直时间轴展示审批节点的处理状态（待处理、同意、驳回、加签）与处理意见。
  • 底栏动作与决策弹窗：
    • 处于“待我审批”状态下，页面底部固定悬浮展示 [通过] 和 [驳回] 按钮。
    • [通过] 交互：点击通过按钮，弹出全屏意见录入抽屉。审批意见为选填项，默认占位填充为“同意”，确认后可提交。
    • [驳回] 交互：点击驳回按钮，弹出全屏意见录入抽屉，审批意见为强制必填项，且长度不得少于 10 字。若输入未满足字数要求，点击“确认提交”时前台予以红字报错阻断，拒绝向后端发送请求。
    • 用印风控拦截（“先签后审”特例）：
      • 若当前签署模式为“先签后审”，在外部客户均已签署完毕、进入待丙方落章阶段时，若审批人在移动端执行了[驳回]操作，系统需实施用印锁拦截：强制阻断公章自动或手动加盖，并将状态标记为“已驳回”，房源根据配置进行联动解禁，限制对已签署合同的物理清除，必须走规范的解约或补充流程。

第二部分：核心状态字典与流转逻辑

十一、业务状态字典

11.1 合同包主状态流转 (contractPackage)

stateDiagram-v2
    [*] --> draft: 创建草稿
    draft --> approving_new: 提交签约 (先审后签)
    draft --> signing: 提交签约 (先签后审)
    approving_new --> signing: 审批通过
    approving_new --> rejected: 审批驳回
    
    signing --> auth_failed: e签宝三要素核验不通过
    auth_failed --> signing: 修正三要素重发通过
    
    signing --> completed: 各方均已完成签署/落章
    signing --> revoked: 发起人撤回重签
    
    completed --> approving_modify: 发起合同变更 (补充协议)
    approving_modify --> signing_modify: 变更审批通过
    approving_modify --> completed: 变更审批驳回
    signing_modify --> completed: 补充协议完成或拒签/超期撤销
    
    completed --> approving_void: 发起合同解约 (解除协议)
    approving_void --> signing_void: 解约审批通过
    approving_void --> completed: 解约审批驳回
    signing_void --> voided: 解除协议各方签署完毕
    signing_void --> completed: 解除协议超期/拒签撤销

11.2 子文件状态、审批状态与房源锁定状态说明

  • 子合同文件 (contractFile)：
    • pending_approval（待审批） -> pending_sign（待签署） -> partially_signed（部分签署） -> sealed_pending（已签待丙方落章） -> completed（已完成）。
  • 审批单 (approvalBill)：
    • pending（待处理） -> processing（审批中） -> approved（已同意） / rejected（已驳回）。
  • 房源锁定 (houseLock)：
    • available（可成交） -> pre_locked（发起中预锁定，30分钟时效） -> sold_locked（已成交锁定） -> resign_locked（撤回重签锁定，2小时时效，期满未发起则释放为 available）。

十二、核心机制流程说明

12.1 三要素核验拦截与纠错机制

  • 发起提交后，系统将姓名、手机号、身份证号推送校验。
  • 阻断流程：一旦核验失败，系统拦截签约流推进，合同包状态转为 auth_failed，并在详情页暴露“三要素修正”入口。
  • 纠错重发：发起人修改错误信息后重新提交，通过后系统自动作废原e签宝流程，并以上送的正确信息生成全新签署任务下发客户。

12.2 用印安全锁机制 (先签后审手动落章)

  • 当选择“先签后审”模式时，前端强制将盖章模式设为“手动落章”且禁用“自动”选项。
  • 客户双签完成后，系统回调得到 sealed_pending（待落章）状态。
  • 校验防线：拥有落章权限的盖章人在点击“加盖公章”时，后端接口必须强行验证该合同对应的“内部审批单”状态。若审批单未终审通过，接口强制返回错误，绝对禁止向e签宝推送盖章请求。

12.3 延期截止日计算算法

  • 延期操作每次仅支持 “3天、7天、15天” 选项。
  • 30天绝对上限规则：合同的签署截至日期自“合同首次发起时间”起算，累计有效生存期不得超过 30 天。
  • 动态判断逻辑为：当前时间 + 申请延期天数 - 合同首次发起时间 <= 30天。若超出此公式，前端快捷天数选项必须隐藏，若全部超出则天数选项置灰禁用。

第三部分：系统校验、权限与异常场景

十三、全局表单校验总表

场景 字段名称 校验规则 错误/拦截提示
发起签约 甲方/乙方姓名 必填，2-20字符，过滤空白，不含数字特殊符 请输入真实姓名
发起签约 手机号码 必填，11位中国大陆手机号规范 手机号码必须是11位
发起签约 身份证号 必填，18位身份证，末位X校验，入库转大写 身份证号格式不正确
发起签约 成交总价/月租金 必填，大于0，数值型最多保留两位小数 金额必须大于0
发起签约 佣金金额 必填，大于或等于0，数值型保留两位小数 佣金金额不能为负数
门店配置 签署有效期 必须在 1 ~ 30 天的正整数之间 合同签署有效期必须在1-30天之间
门店配置 催签间隔时间 必须大于或等于 2 小时的正整数 两次催签最小间隔必须不低于2小时
撤回重签 撤回原因 已有人签署时必填，至少输入5个字符 请填写撤回原因（不少于5字）
审批流 审批意见 审批节点驳回时强制必填，至少10个字符 驳回时必须填写审批意见（不少于10字）

十四、角色权限矩阵

功能模块 系统管理员 门店管理员 经纪人(发起人) 审批人 盖章授权人
发起在线签约 √ √ ×
撤回/催签/延期 √ √（仅本人合同） ×
三要素修正 √ √（仅本人合同） ×
审批通过/驳回 × √（指定节点） × √ ×
手动落章盖印 × × √（当前激活者）
切换/激活盖章人 √ × ×
修改门店签约配置 √ √（仅本店） × ×
审计日志查看/导出 √ √（仅查看） × ×

十五、异常场景清单

  • e签宝服务超时：任何调用外部 API 接口（如核验三要素、新建流程等）的网络超时，系统均不得自动降级通过，必须阻断操作并提示“服务暂不可用，请稍后重试”，保持当前业务状态。
  • 签署人拒签：当接收到客户拒签回调时，首次签约流程合同包标记为已驳回并释放房源锁定；变更与解约的拒签则自动将主状态退回到 completed，确保原合同依然具有法律效力。
  • 部分签署后撤回：若客户中途发生撤回，必须检查是否已有人签字。若有，强制要求输入撤回原因并写入审计日志，同时将房源锁定 2 小时，防止高频恶意撤回占用房源。
  • 乱序 Webhook 回调：若“流程完成”回调先于“单人签署完成”到达，后端必须在完成流程的逻辑中合并处理所有未完结的签署状态，不得产生状态逆流。

第四部分：联调验收、测试与设计交付

十六、前后端业务联调时序图

16.1 首次签约：先审批后签约 (approve-first)

sequenceDiagram
    participant FE as 前端界面
    participant BE as SaaS后端
    participant AP as 审批模块
    participant ES as e签宝服务

    FE->>BE: 提交签约申请 (表单数据)
    BE->>ES: 校验签署方三要素
    ES-->>BE: 校验成功
    BE->>BE: 生成本地合同包与PDF文件
    BE->>AP: 发起首次签约审批流程
    BE-->>FE: 返回状态: approving_new (审批中)
    
    AP-->>BE: 终审通过回调
    BE->>ES: 上传PDF合同并绑定签署区/签署人
    BE->>ES: 开启e签宝签署流程
    BE-->>FE: 状态更新为: signing (签约中)

16.2 首次签约：先签约后审批 (sign-first)

sequenceDiagram
    participant FE as 前端界面
    participant BE as SaaS后端
    participant AP as 审批模块
    participant ES as e签宝服务

    FE->>BE: 提交签约申请 (表单数据)
    BE->>ES: 校验签署方三要素
    ES-->>BE: 校验成功
    BE->>ES: 直传PDF并创建/激活e签宝签署
    BE->>AP: 启动后台并行审批流程
    BE-->>FE: 返回状态: signing (签约中)
    
    ES-->>BE: 回调: 买卖双方均已签署完毕
    BE->>BE: 进入 sealed_pending (已签待盖章)
    
    note over BE: 触发手动落章安全锁校验
    AP-->>BE: 审批终审通过
    BE->>BE: 用印锁解除
    FE->>BE: 授权盖章人操作手动盖章
    BE->>ES: 推送丙方公章落印
    ES-->>BE: 签署流完成
    BE-->>FE: 状态归档为: completed (已完成)

十七、可执行测试用例集

用例编号 功能模块 测试前置条件 操作步骤 预期结果
TC-001 发起表单校验 租赁模式发起 填写月租金1000元，甲方佣金和乙方佣金皆输入为0并提交 核验通过，允许发起。系统正确生成租赁主合同，且不生成佣金确认书。
TC-002 贷款表单校验 买卖模式发起 付款方式选择“贷款”，贷款金额输入框保持空白并提交 前端拦截并红色高亮报错，提示“请输入贷款金额”。
TC-003 三要素失败 签约配置已启用 发起签约时故意填写错误的乙方身份证信息提交 表单提交被强行阻断并弹窗警示，合同状态变更为 auth_failed。
TC-004 延期生存控制 合同已发起20天 打开合同延期弹窗，选择“15天”延期选项 快捷天数面板中“15天”选项自动隐藏（因生存期 20+15=35天 超过30天限制）。
TC-005 用印安全锁 先签后审，客户已双签 内部审批单处于“处理中”状态，盖章人尝试点击手动盖章按钮 盖章按钮置灰不可点击，后端直接调用手动落章接口时返回校验未通过异常。

十八、UI设计交付物清单

  • 桌面端页面设计稿：
    • 门店级电子签约配置页（含配置抽屉响应式宽度排版稿）。
    • 签约主体维护页（包含新增主体弹窗、授权盖章人激活/禁用状态展示稿）。
    • 发起在线签约弹窗（买卖全款/买卖贷款/租赁表单状态，三要素核验失败阻断提示稿）。
    • 合同详情抽屉（首次签署/变更/解约子 Tab 的动态展示，流式日志以及双域滚动排版稿）。
  • 移动端页面设计稿：
    • 移动端发起签约页（通栏输入卡片与报错态表现）。
    • 移动端合同详情页（全屏界面，包含不同状态下底部吸底操作按钮卡片）。
    • 移动端延期快捷天数选择器浮层、意见驳回录入弹窗。
  • 组件级规范：
    • 状态标签（包含草稿、签约中、已完成、三要素失败、已超期等全状态色彩变量）。
    • 按钮状态（主操作、次操作、禁用、loading防重点击态）。

文档结束