luo/one-pipe-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2308d82d0fa10f680c4c7527a5c0763a042e659e
one-pipe-system/openspec/changes/add-employee-collection/specs/employee-collection/spec.md
luo 2308d82d0f fix: 代理
2026-09-12 11:27:50 +08:00

9.9 KiB
Raw Blame History

ADDED Requirements

Requirement: 收款方式管理

超级管理员 MUST 能够维护线下收款方式，包括名称、编码、排序、状态与备注；普通员工只能看到启用的收款方式。收款方式列表接口 MUST 返回 { items, page, size, total }，并 MUST 支持 enabled 与 keyword 筛选。已被核销申请引用的收款方式 MUST NOT 被删除；引用后修改稳定编码 MUST 被后端拒绝，前端 MUST 展示错误提示。

Scenario: 超级管理员新增收款方式

  • GIVEN 超级管理员已登录并拥有收款方式新增权限
  • WHEN 其填写名称、唯一编码、排序、状态与备注并提交
  • THEN 系统 MUST 调用新增接口并在成功后刷新列表
  • AND 新增成功后 MUST 清空并关闭弹窗

Scenario: 删除被引用的收款方式

  • GIVEN 某收款方式已被业务引用
  • WHEN 超级管理员尝试删除该方式
  • THEN 前端 MUST 阻止删除或展示后端返回的业务错误
  • AND MUST 提示改为停用

Scenario: 修改收款方式编码

  • GIVEN 超级管理员打开编辑弹窗
  • WHEN 其修改稳定编码并提交
  • THEN 前端 MUST 提交最新编码
  • AND 若该方式已被核销申请引用，后端拒绝时前端 MUST 展示错误提示

Requirement: 员工代收款账单统计

账单页面 MUST 展示应收金额、已核销金额、未核销金额与待处理账单数量四项统计，数据 MUST 来自 GET /api/admin/employee-collection-bills/statistics，字段为 receivable_total、received_total、unsettled_total、pending_bill_count；前端 MUST NOT 通过遍历当前分页数据自行计算。

Scenario: 加载账单统计

  • GIVEN 用户进入员工代收款账单页面
  • WHEN 页面初始化或筛选条件变化
  • THEN 前端 MUST 调用账单统计接口
  • AND MUST 将后端返回的「分」按元格式化后展示应收、已核销与未核销金额

Requirement: 员工代收款账单列表与详情

账单列表响应 MUST 为 { items, total, page, size }，前端 MUST 兼容 items / list / records 等列表字段。列表 MUST 支持按来源（source_type）、来源单号（source_no）、账单状态、客户/店铺（customer_id）与创建时间（created_from / created_to，YYYY-MM-DD）筛选，并展示账单编号、来源、关联单号、负责员工、客户/店铺、应收金额、已核销金额、未核销金额与状态。账单状态 MUST 为数字枚举：0 待核销、1 部分核销、2 已核销、3 已关闭，展示 MUST 优先使用后端 status_name。账单详情响应 MUST 为 { bill, refunds, allocations, applications }：refunds MUST 展示退款金额、冲减应收、冲销前应收与处理结果，applications MUST 可展开查看该申请的审批尝试记录。

Scenario: 普通员工查看账单

  • GIVEN 普通员工已登录
  • WHEN 其打开账单列表
  • THEN 列表 MUST 只展示后端返回的本人账单数据
  • AND MUST NOT 展示仅超管可见的操作入口

Scenario: 打开账单详情

  • GIVEN 用户拥有账单详情权限
  • WHEN 其点击账单号或详情操作
  • THEN 前端 MUST 跳转账单详情页并加载对应账单（详情数据取自 data.bill）
  • AND 详情 MUST 展示退款冲销、核销分摊与关联核销申请

Requirement: 关闭账单

超级管理员 MUST 能够关闭账单，且关闭原因必填（最多 500 字符）。仅待核销或部分核销账单可关闭；存在审批中的核销申请（approval_pending 为真）时，账单 MUST NOT 被关闭。

Scenario: 存在审批中申请时关闭账单

  • GIVEN 账单存在审批中的核销申请
  • WHEN 用户查看该账单操作
  • THEN 关闭入口 MUST 被禁用或不可见
  • AND MUST 展示不可关闭的原因提示

Scenario: 关闭原因必填

  • GIVEN 账单可关闭
  • WHEN 超级管理员打开关闭弹窗并留空原因提交
  • THEN 前端 MUST 阻止提交并提示填写原因

Requirement: 创建核销申请

员工 MUST 能够使用一笔线下收款核销 1～N 张账单。创建申请 MUST 提交收款方式 payment_method_id、付款金额 paid_amount（分，大于 0）、付款方名称 payer_name、付款时间 paid_at（带时区 RFC3339）、外部交易流水号 external_transaction_no、付款凭证 payment_voucher_keys（1～5 个对象 Key）与账单分摊 allocations。超级管理员代办时 MUST 填写 acting_reason，本人办理 MUST NOT 提交该字段。提交成功后系统 MUST 自动发起企业微信审批。

Scenario: 一笔收款核销多张账单

  • GIVEN 用户选择了多张可核销账单
  • WHEN 其录入各账单核销金额、选择收款方式并填写付款事实后提交
  • THEN 前端 MUST 校验各账单核销金额大于 0 且不超过账单未核销余额
  • AND MUST 以 allocations: [{ bill_id, amount }] 提交账单分摊明细

Scenario: 付款金额小于核销合计

  • GIVEN 用户已录入各账单核销金额
  • WHEN 其填写的付款金额小于核销合计即提交
  • THEN 前端 MUST 阻止提交并提示付款金额不能小于核销合计

Scenario: 缺少付款凭证

  • GIVEN 用户已选择账单与收款方式
  • WHEN 其未上传任何付款凭证即提交
  • THEN 前端 MUST 阻止提交并提示上传付款凭证

Scenario: 缺少付款事实

  • GIVEN 用户已选择账单与收款方式
  • WHEN 其未填写付款方名称、付款时间或外部交易流水号即提交
  • THEN 前端 MUST 阻止提交并提示补齐必填项

Scenario: 超管代办未填写原因

  • GIVEN 超级管理员以代办身份创建申请
  • WHEN 其未填写 acting_reason 即提交
  • THEN 前端 MUST 阻止提交并提示填写代办原因

Scenario: 企微审批场景未配置

  • GIVEN 企业微信审批场景尚未配置
  • WHEN 用户提交核销申请
  • THEN 前端 MUST 展示后端返回的 503 提示「企微审批场景未配置，请联系管理员」
  • AND MUST 保留用户已填写的内容且不产生申请数据

Requirement: 核销申请列表与详情

核销申请列表响应 MUST 为 { items, page, size, total }，MUST 支持按状态、收款方式与创建时间筛选；列表项 MUST 包含 payment_method_name、paid_amount、status、status_name 与 created_at，状态 MUST 优先展示后端 status_name。申请详情响应 MUST 为 { application, allocations, attempts }；attempts MUST 按提交顺序展示全部审批尝试记录，包含付款金额、付款方、流水号、付款凭证与审批意见。

Scenario: 查看审批历史

  • GIVEN 申请存在多次审批尝试记录
  • WHEN 用户打开申请详情
  • THEN 详情 MUST 按提交顺序展示每次尝试的提交材料与审批状态
  • AND 历史材料 MUST NOT 因重新提交而被覆盖

Requirement: 核销申请重新提交

仅已驳回（status 为 2）的申请 MUST 允许修改并重新提交；重新提交 MUST 生成新的企业微信审批实例，且历史审批记录 MUST NOT 被覆盖。重新提交入口 MUST 位于核销申请列表的操作列，详情页 MUST 只读且 MUST NOT 展示业务操作按钮（仅保留返回导航）。

Scenario: 重新提交被驳回申请

  • GIVEN 申请状态为已驳回
  • WHEN 用户在核销申请列表点击「修改并重新提交」并修改账单分摊、收款方式、付款事实或付款凭证后提交
  • THEN 前端 MUST 调用修改接口重新提交
  • AND 成功后 MUST 刷新详情并展示新的审批实例状态

Scenario: 非驳回申请不可修改

  • GIVEN 申请处于审批中或已通过
  • WHEN 用户查看核销申请列表
  • THEN 修改并重新提交入口 MUST 不可见或不可用

Scenario: 详情页只读

  • GIVEN 用户打开账单详情或核销申请详情
  • WHEN 页面渲染完成
  • THEN 页面 MUST NOT 展示创建核销申请、关闭账单或修改并重新提交等业务操作按钮
  • AND MUST 只保留返回导航

Requirement: 企业微信审批场景配置

企业微信审批场景 MUST 支持 employee_collection_approval 业务类型，复用既有的应用列表、模板控件同步、业务字段查询与字段映射保存接口。

Scenario: 配置员工代收款审批场景

  • GIVEN 超级管理员打开企微审批场景页面
  • WHEN 其选择业务类型「员工代收款审批」
  • THEN 前端 MUST 使用 employee_collection_approval 调用模板同步、字段查询与保存接口

Requirement: 附件预签名展示

附件接口 MUST 只返回对象存储 Key（payment_voucher_keys）；前端 MUST 通过系统既有的预签名下载接口获取实际访问地址后再展示。

Scenario: 查看付款凭证

  • GIVEN 申请包含付款凭证 Key
  • WHEN 用户点击查看付款凭证
  • THEN 前端 MUST 先批量换取预签名地址
  • AND 图片 MUST 支持预览，非图片 MUST 支持查看或下载

Requirement: 订单付款凭证规则调整

由平台账号（user_type 为 1 或 2）操作、实际收款金额大于 0 且非赠送的线下订单会生成员工代收款账单；该场景 payment_voucher_key MUST 变为非必填，付款凭证改在核销申请中提交，订单字段结构 MUST 保持不变。其余线下订单 MUST 继续要求付款凭证。

Scenario: 线下订单生成代收款账单

  • GIVEN 当前登录账号为平台账号，所选套餐非赠送且实际收款金额大于 0，支付方式为线下支付
  • WHEN 用户创建该订单
  • THEN 前端 MUST 不再强制要求上传付款凭证
  • AND MUST 提示付款凭证将在核销申请中提交

Scenario: 赠送套餐或非平台账号的线下订单

  • GIVEN 所选套餐为赠送套餐，或当前账号非平台账号，或实际收款金额为 0
  • WHEN 用户以线下支付方式创建订单
  • THEN 前端 MUST 继续要求上传付款凭证
Reference in New Issue View Git Blame Copy Permalink