## 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** 操作日志只返回对象键引用、编码与名称摘要,不返回凭证内容或完整收款文本