junhong_cmp_fiber/openspec/changes/archive/2026-09-18-close-august-iteration-gaps/proposal.md

Why

2026 年 8 月迭代的 20 个需求域已完成开发并归档，但按 111.md 原始需求逐条比对（约 950 个判定点）后，仍有一批「原文明确要求、实现未做或只做一半、且讨论稿与 change design 均无裁剪记录」的字段级与接口级缺口。它们集中在导出列缺失、企业微信审批材料不完整、必填校验缺失、列表与详情投影不全、优先轮询留痕不足、阈值命中无数字证据六类，直接影响财务对账、审批判断依据、安全基线与事后追溯，因此需要一次收口变更把它们补齐并固化为可验证契约。

What Changes

• 员工账单：列表补齐「账单编号」精确筛选、「核销通过时间」范围筛选，以及按员工姓名或账号、客户名称的模糊查询；明确区分「未核销金额」与「剩余可核销金额」两个口径；账单详情内嵌操作日志与来源订单快照。
• 商户池：列表返回启用/总商户数量、当前命中商户与最近配置更新时间；按统计周期区分「全部成员达标」语义，单成员池保持固定使用该成员；时间轮询在周期、起始时间或成员顺序变更后由服务端以保存成功时间重算起点。
• H5 运营弹窗：新增必填「弹窗类型（套餐政策推广/通用公告）」配置字段，并据此确定默认优先级分级。
• 退款：退款原因必填；申请新增申请人备注；详情返回原收款商户、原支付渠道交易流水号与商户退款能力校验结果；新增按订单类型返回可选退款方式的查询接口；退款单落「来源支付单号」与「原支付渠道交易流水号」，并支持登记线下退款处理流水号/凭证编号；企业微信退款审批材料带出当前退款套餐已用量与总量、资产类型与设备类型（含设备型号）以及原支付渠道交易流水号。
• 优先轮询：补齐队列持久化与读侧字段（资产标识、设备号、代理归属、尝试次数与上限、最近与下一次执行时间、执行耗时、接口请求/响应摘要引用）；支持人工关闭出队、有效期到期出队与失败后人工重触发；资产解析端点的卡与设备两个分支返回优先轮询状态；异常与重试记录按既有列表筛选可查。
• 运营商通道阈值：阈值命中事实持久化触发时累计流量、阈值数值、单位、判定时间与操作来源，并提供可查询投影。
• 代理：企业微信新增代理审批材料补齐「业务员」字段；店铺详情返回下级代理数量；提现申请记录当次生效资料资格版本与校验结果。
• 手机号—资产关联：后台查看返回手机号当前有效关联数量与最近解绑人；新增短信验证码校验失败次数限制（作用域覆盖注册、绑定、换绑与换证的全部短信验证码校验流程）。
• 报表：激活情况、套餐续费两张报表的导出补齐「序号」列（首列固定为序号，分组行按展示顺序连续递增，合计行序号列留空且不改合计行其他列的表示）。
• 时间筛选：本变更新增的三处时间范围筛选（员工账单核销通过时间、优先轮询项查询、通道阈值命中查询）统一纳入既有时间筛选契约——统一参数名、共享严格解析器、带时区 RFC3339 秒级闭区间；员工账单列表既有「产生时间」参数同批替换为统一参数名，不保留旧参数名与第二套解析。
• 端点与证据链：新增按订单查询可选退款方式、线下退款处理流水号补录、优先轮询人工关闭、优先轮询人工重触发、通道阈值命中查询五个受权限控制的入口（方法、路径与权限主体见 tasks.md 第 12 节），并同步主 Spec 可达操作索引与两份证据链 JSON。
• 口径登记（无行为变化）：不新增「运营管理员」命名角色，其职责由超级管理员与平台用户在其数据范围内承担，店铺分类口径仍由业务用户组推导。

Capabilities

New Capabilities

无新增能力：本次全部落在既有能力的行为契约上。

Modified Capabilities

• employee-collection-bill: 新增账单列表查询筛选与账单详情投影要求（含未核销金额口径）。
• merchant-payment-routing: 新增商户池列表投影要求；修改金额/笔数全达标与单成员池语义、时间轮询起点重算。
• h5-popup-notification: 修改运营弹窗匹配要求，加入弹窗类型与默认优先级分级。
• order-refund-exchange: 修改退款方式矩阵（新增可选方式查询）；新增退款原因必填与申请备注、退款展示与渠道标识字段、企业微信退款审批材料字段。
• phone-asset-association: 修改后台查看要求，加入手机号维度有效关联数量与最近解绑人；新增短信验证码校验失败次数限制要求（覆盖注册、绑定、换绑与换证的全部短信验证码校验流程）。
• export-time-filter: 修改受影响端点与旧格式替换要求，把员工账单列表、优先轮询项查询与通道阈值命中查询纳入统一时间筛选契约，并规定同一端点第二个时间字段的命名、解析与闭区间语义。
• priority-polling-queue: 修改优先项尝试与出队要求（人工关闭、有效期到期、人工重触发）；修改可追溯要求（补齐字段与异常重试查询）。
• asset-device: 新增资产解析端点（卡与设备两个分支）的优先轮询状态投影要求。
• carrier-channel-traffic-threshold: 新增阈值命中事实留痕要求。
• agent-distribution-withdrawal: 修改注册审批材料（业务员字段）与提现资料校验结果留痕；新增店铺下级代理数量投影。
• agent-funds-commission: 修改佣金明细导出列要求。
• operations-report: 修改报表导出要求，加入序号列。

Impact

• 受影响代码：internal/query（员工账单、退款、手机号关联、代理店铺、优先轮询、阈值命中）、internal/application（employeecollection、merchantpayment、h5popup、refundapproval、refund、prioritypolling、carrierthreshold、distributionwithdrawal）、internal/service（verification、refund、polling 优先队列、phone_asset_association）、internal/exporter（agentrecharge 佣金明细、operationsreport、operationsreport/refund 场景）、internal/routes 与 internal/handler/admin。复用既有 Handler，不修改文档生成装配。
• 受影响迁移：新增六对成对迁移（新顺序号，不修改既有迁移），逐对与 design.md 的「迁移计划」及 tasks.md 第 1 节一致：
  1. 000232：H5 弹窗配置加类型列（枚举两值、非空、默认通用公告），up 回填既有行为通用公告。
  2. 000233：退款主表加来源支付单号、原支付渠道交易流水号、线下退款处理流水号与登记时间、登记人列；退款审批尝试表加申请人备注列（逐次冻结；主表备注列已被审批备注占用，不得复用或改写）。
  3. 000234：优先轮询事实表加资产类型与资产 ID、设备号快照、代理归属、尝试上限（默认 3）、执行开始与结束时间、下次计划执行时间、出队时间、集成交互日志标识与有效期起算时间；重建状态 CHECK 以容纳「已关闭」与「已过期」两个终态（活动项部分唯一索引谓词保持不变）；为下次计划执行时间建部分索引；有效期起算时间在 up 中回填为迁移时刻。
  4. 000235：通道阈值锁表加命中累计流量、阈值数值、阈值单位、判定时间、触发来源、解锁时间与复机结果；判定时间回填创建时间、命中数值留空；新增按通道、卡与判定时间的查询索引。
  5. 000236：手机号—资产关联加最近解绑人名称快照列，列注释写明审计侧仍只写脱敏值。
  6. 000237：提现审批尝试表加资料资格版本标识、校验时间、是否通过、未通过稳定原因列。
• 无需 DDL 的缺口：员工账单（账单编号即账单主键标识，核销通过时间取自申请表既有审批终态时间）、商户池列表投影（池表已有更新时间列）、佣金明细导出列与报表序号列（导出执行期 join 补齐）。
• 回滚兼容：新列一律可空或带默认值，读侧对空值按「无」处理；既有优先轮询行的有效期起算时间非空但下次计划执行时间为空时，读侧 MUST NOT 据此判定已过期。
• 受影响外部契约：企业微信退款审批场景需新增控件（套餐已用量与总量、资产类型、设备类型与型号、原支付渠道交易流水号），代理注册审批场景需新增「业务员」控件；「控件缺失即明确失败」仅对本变更新增字段强制映射，既有未映射的可选控件保持静默跳过。提现的资格版本与校验结果冻结在本地审批尝试快照并在提现详情可查，不要求新增企业微信控件。模板控件映射仍由维护者在生产按既有场景接口配置，本变更不写入模板。
• 非目标（沿用既有已记录裁剪）：本期不做优先轮询 P0/P1/P2 分级与优先级配置、不恢复「普通轮询异常补偿」场景、不做换货佣金回溯、不实现自动续费「有余额不停机」、不实现按资产导入批次配置是否需要绑定手机号、不新增「财务」命名角色。
• 上线前置：本变更仅涉及两个需新增企微控件的场景——退款审批（套餐已用量与总量、资产类型、设备类型与型号、原支付渠道交易流水号）与代理注册审批（业务员）；其控件映射需由维护者确认后再启用，其余既有场景的控件映射不受本变更影响。