break
5ed6b39deb
- 新增六对成对迁移 000232–000237：H5 弹窗类型、退款结算标识与申请人备注、优先轮询事实字段与两个新终态、通道阈值命中留痕、手机号最近解绑人、提现资格校验留痕 - 退款：原因必填与申请人备注、来源支付与渠道流水冻结、线下处理流水号补录审计、按订单查询可选退款方式、企微审批材料补齐且新增字段缺失映射即明确失败 - 优先轮询：人工关闭、有效期到期独立周期任务、失败与过期人工重触发、事实字段与异常重试查询、资产解析端点只读投影 - 通道阈值：命中事实同事务留痕与命中记录查询；员工账单：列表筛选与详情投影；商户池：列表投影与统计周期语义；H5：弹窗类型与类别排序 - 手机号：有效关联数量与最近解绑人、短信验证码失败次数限制；导出：佣金明细十五列与报表序号列 - 时间筛选：三处新增筛选纳入统一严格解析契约，员工账单产生时间参数改名 - 同步 12 份主 Spec 需求、两端点与异步任务证据链，门禁 context-health 与 OpenSpec 校验通过
5.4 KiB
Purpose
补齐员工代收款账单列表与详情在原始需求（111.md §5.2.1、§5.2.2）中要求、当前实现未提供的查询筛选与投影能力，并将「未核销金额」与「剩余可核销金额」两个口径显式区分，避免列表与统计口径混淆。
ADDED Requirements
Requirement: 员工账单列表查询与筛选
账单列表 SHALL 在既有可见性范围内支持以下筛选：账单编号（精确）、来源订单号（精确）、来源业务类型、账单状态、产生时间范围、核销通过时间范围、欠款人姓名或账号（模糊）、客户名称（模糊）。账单编号 MUST 为账单自身的唯一标识（即账单记录标识）；系统 MUST NOT 为满足本要求新增编号字段或编号生成规则。欠款人姓名或账号与客户名称的模糊匹配 MUST 由服务端按去空白后的子串匹配实现，MUST NOT 要求调用方先获得账号 ID 或客户 ID。
产生时间范围 MUST 使用统一参数名 start_time 与 end_time；核销通过时间范围 MUST 使用 decided_start_time 与 decided_end_time。两类时间参数 MUST 使用同一严格解析契约：取值为带显式时区的 RFC3339 秒级时间，解析结果归一为 UTC 瞬时，筛选区间为闭区间（含两端），开始时间晚于结束时间时拒绝请求；旧参数名与旧格式（含仅日期的取值）MUST 被拒绝，MUST NOT 保留静默兼容或别名。
核销通过时间 MUST 取该账单经「状态为已通过的分摊」关联到的申请表审批终态时间；账单从未存在已通过分摊时该筛选 MUST 不命中该账单。系统 MUST NOT 使用分摊记录的释放时间作为核销通过时间：该字段在既有实现中同时承担「审批通过转为已核销」与「驳回或释放预占」两种语义。
列表响应 SHALL 同时返回「未核销金额」与「剩余可核销金额」两个金额：未核销金额 MUST 为应收金额减已核销金额；剩余可核销金额 MUST 为应收金额减已核销金额再减审批中预占金额，已关闭账单两者均为零。已核销金额大于应收金额（异常数据）时，两个金额 MUST 均按 0 返回，MUST NOT 返回负数。列表 MUST NOT 因新增模糊筛选改变既有可见性规则：欠款人仅可见本人账单，超级管理员可见全部。
Scenario: 按账单编号精确查询
- WHEN 超级管理员以账单编号筛选账单列表
- THEN 系统返回该编号对应账单，且不返回其它账单
Scenario: 按核销通过时间筛选
- WHEN 调用方以核销通过时间范围筛选
- THEN 系统只返回在该范围内存在已通过分摊的账单，从未核销的账单不出现在结果中；筛选依据为该账单已通过分摊关联的申请表审批终态时间
Scenario: 拒绝旧时间参数与旧格式
- WHEN 调用方携带旧参数名或仅日期、无时区、带小数秒的时间取值请求账单列表
- THEN 系统以参数非法错误拒绝请求，且不返回任何账单
Scenario: 按员工姓名或客户名称模糊查询
- WHEN 调用方提交员工姓名子串或客户名称子串
- THEN 系统返回欠款人账号名称或客户名称包含该子串的账单，无需调用方提供账号 ID 或客户 ID
Scenario: 未核销金额与剩余可核销金额
- GIVEN 一张应收 100 元、已核销 30 元且存在审批中预占 20 元的账单
- WHEN 查询账单列表
- THEN 未核销金额返回 70 元，剩余可核销金额返回 50 元
Scenario: 已关闭账单两个金额为零
- WHEN 查询一张已关闭账单
- THEN 未核销金额与剩余可核销金额均返回零，已核销金额保持关闭时的值
Requirement: 员工账单详情投影
账单详情 SHALL 在既有账单、来源、客户与员工信息之外，返回该账单的操作日志与来源订单快照。操作日志 MUST 取该账单维度既有审计事实的投影，至少包含动作、操作账号名称、操作时间与变更前后摘要，MUST NOT 包含支付凭证内容、完整收款信息或其它敏感原文。来源订单快照 MUST 取来源订单或来源充值记录的既有只读字段投影，至少包含来源单号、来源业务类型、来源实收或充值金额、来源创建时间与资产标识；客户与员工信息 MUST 复用账单创建时冻结的快照。来源记录不可读或字段缺失时 MUST 返回空值 MUST NOT 阻断详情响应，MUST NOT 为此新增来源业务写入路径。
Scenario: 详情返回操作日志
- WHEN 授权账号查询一条存在创建、提交与审批终态的账单详情
- THEN 响应的操作日志按时间升序返回各次动作、操作账号名称、操作时间与前后值摘要
Scenario: 详情返回来源订单快照
- GIVEN 账单来源为后台线下套餐订单或代理线下充值
- WHEN 查询该账单详情
- THEN 响应返回来源单号、来源业务类型、来源金额、来源创建时间与资产标识
Scenario: 来源记录不可读
- GIVEN 账单来源记录已被物理删除或字段为空
- WHEN 查询该账单详情
- THEN 来源订单快照对应字段返回空值，详情其余内容正常返回
Scenario: 操作日志不含敏感原文
- WHEN 账单存在包含凭证上传与收款方式变更的操作
- THEN 操作日志只返回对象键引用、编码与名称摘要，不返回凭证内容或完整收款文本