one-pipe-system/openspec/changes/add-bulk-purchase-upload-task/specs/bulk-purchase-task/spec.md

ADDED Requirements

Requirement: Bulk Purchase Creation Form

The admin frontend SHALL provide a bulk purchase form that binds one uploaded batch to one shop and one payment method.

Scenario: Select batch purchase inputs

• GIVEN 用户打开批量订购入口
• WHEN 用户填写批量订购表单
• THEN 页面 MUST require a target shop, one payment method, and an Excel file
• AND 页面 MUST NOT provide a way to mix payment methods within the same batch

Scenario: Show voucher upload for offline payment

• GIVEN 用户选择线下支付
• WHEN 页面渲染批量订购表单
• THEN 页面 MUST show the batch voucher upload control
• AND 页面 MUST require a completed voucher upload before task creation

Scenario: Hide voucher upload for wallet payment

• GIVEN 用户选择代理钱包支付
• WHEN 页面渲染或提交批量订购表单
• THEN 页面 MUST NOT submit a voucher file
• AND 页面 MUST clear or ignore a voucher selected before switching to wallet payment

Requirement: Bulk Purchase File Upload And Creation

The admin frontend SHALL create a bulk purchase task through POST /api/admin/bulk-purchases using multipart form data.

Scenario: Create bulk purchase task

• GIVEN 用户已选择代理商、支付方式并完成文件上传
• WHEN 用户确认创建批量订购任务
• THEN 系统 MUST submit multipart fields shop_id, payment_method, file, and request_id
• AND 系统 MUST submit voucher_file when the payment method is offline
• AND 系统 MUST save the returned task_id and task_no

Scenario: Prevent creation during upload

• GIVEN Excel 文件或线下支付凭证仍在上传
• WHEN 用户点击创建任务
• THEN 页面 MUST prevent task creation
• AND 页面 MUST show the upload-in-progress state until all required uploads finish

Scenario: Download static template

• GIVEN 用户打开批量订购表单
• WHEN 用户点击模板下载
• THEN 页面 MUST download the packaged frontend static Excel template
• AND 页面 MUST NOT require a template-generation API request

Requirement: Bulk Purchase Task Summary And Status

The admin frontend SHALL display the server-provided bulk purchase task summary and use the shared five-state async task semantics.

Scenario: Display task summary

• GIVEN 批量订购任务创建成功或详情接口返回任务
• WHEN 页面展示任务详情
• THEN 页面 MUST display task ID or task number, status, total count, success count, failed count, and returned amount summaries
• AND 页面 MUST use server-provided values without recalculating amounts or counts from the uploaded file

Scenario: Treat partial success as terminal completion

• GIVEN 任务已处理完成且同时存在成功行和失败行
• WHEN 页面展示任务状态
• THEN 页面 MUST display the task as a completed terminal task
• AND 页面 MUST display success and failed counts separately
• AND 页面 MUST NOT introduce a separate partial-success status

Scenario: Handle wallet insufficiency without rollback

• GIVEN 代理钱包余额不足导致部分或后续行无法创建订单
• WHEN 页面展示任务结果
• THEN 页面 MUST show the affected rows as failed with their returned reasons
• AND 页面 MUST preserve and display rows that were already successful
• AND 页面 MUST NOT attempt a frontend rollback

Requirement: Bulk Purchase Task Recovery And Polling

The admin frontend SHALL recover a bulk purchase task by task_id and poll its summary while it is active.

Scenario: Query task summary

• GIVEN 用户需要加载批量订购任务
• WHEN 页面查询任务摘要
• THEN 系统 MUST call GET /api/admin/bulk-purchases/{task_id}
• AND 页面 MUST update the task summary from the response

Scenario: Recover task after refresh

• GIVEN 页面存在已保存的 active task_id
• WHEN 用户刷新页面或重新进入批量订购任务页
• THEN 页面 MUST query the existing task by task_id
• AND 页面 MUST NOT create another bulk purchase task

Scenario: Stop polling at terminal state

• GIVEN 批量订购任务状态为已完成、已失败或已取消
• WHEN 页面收到任务摘要
• THEN 页面 MUST stop automatic polling
• AND 页面 MUST retain the terminal summary and failure counts for viewing

Requirement: Bulk Purchase Item Results

The admin frontend SHALL provide paginated and status-filterable row results for a bulk purchase task.

Scenario: Query item results

• GIVEN 用户打开批量订购任务结果
• WHEN 页面加载逐行结果
• THEN 系统 MUST call GET /api/admin/bulk-purchases/{task_id}/items
• AND 系统 MUST support page, size, and optional status query parameters

Scenario: Display failed item details

• GIVEN 逐行结果接口返回失败行
• WHEN 页面渲染结果表格
• THEN 页面 MUST display row number, asset identifier, package code, and safe error reason
• AND 页面 MUST NOT expose raw backend stack traces or technical error details

Requirement: Bulk Purchase Permissions

The admin frontend SHALL gate bulk purchase creation, task viewing, item-result viewing, and template download with explicit permissions.

Scenario: Hide unauthorized bulk purchase operations

• GIVEN 当前用户缺少某项批量订购权限
• WHEN 页面渲染对应入口或操作
• THEN 页面 MUST NOT display or enable that operation
• AND direct API failure MUST NOT be treated as permission to continue