fujian_water_biz_doc/specs/012-xlsx-export-unification/spec.md

Feature Specification: Excel 导出 xlsx 统一化与前端 CSV 替换

Feature Branch: 012-xlsx-export-unification Created: 2026-05-15 Status: Draft Input: User description: "前端也是 两个分任务一起工作" / "按这个方案做"

Document Scope & Sources (mandatory)

• Target repositories:
  • ../water-backend/
  • ../water-frontend/
• Primary source of truth:
  • ../water-backend/sw-framework/sw-spring-boot-starter-excel/src/main/java/cn/com/emsoft/sw/framework/excel/core/util/ExcelUtils.java
  • ../water-frontend/src/views/operatingCharges/redReversalRecord/index.vue
  • ../water-frontend/src/views/collection/bankCollection/index.vue
  • ../water-frontend/src/views/collection/bankCollection/detail.vue
  • ../water-frontend/src/views/collection/bankWithholding/index.vue
  • ../water-frontend/src/views/collection/realTimeBilling/index.vue
  • ../water-frontend/src/utils/download.ts
• Reference sources:
  • ../water-backend/AGENTS.md
  • ../water-frontend/AGENTS.md
  • ../water-docs/AGENTS.md
• Code baselines:
  • backend SHA: 82b2a4bb2
  • frontend SHA: 156fe74e
• Scope decision: In scope。本次工作聚焦两个并行子任务：一是后端统一 Excel 下载为标准 .xlsx 响应；二是前端将已确认的 5 个本地 CSV 导出页面改为调用后端真实导出接口。除为打通这 5 个页面所必需的最小接口补齐外，不扩展到其他页面重构或下载体系重写。

User Scenarios & Testing (mandatory)

User Story 1 - 后端统一 xlsx 下载口径 (Priority: P1)

作为系统维护人员，我希望后端公共 Excel 导出能力统一返回标准 .xlsx 文件及对应响应头，这样 Excel 客户端和浏览器不会再遇到“扩展名与文件格式不一致”的识别风险。

Why this priority: 公共 ExcelUtils 是后端导出统一入口，优先统一这里可以一次性消除全站 Excel 导出头信息不规范的问题。

Independent Test: 任选一个现有后端导出接口下载文件，审阅者无需阅读实现即可确认响应头与文件名后缀均为 .xlsx 语义，且文件可被 Excel 正常打开。

Acceptance Scenarios:

1. Given 某个使用 ExcelUtils.write(...) 的导出接口，When 用户触发下载，Then 响应 Content-Type 为 xlsx 对应值，文件名以后缀 .xlsx 下载。
2. Given 系统中其他依赖 ExcelUtils.write(...) 的导出接口，When 它们继续使用公共导出工具，Then 无需各自复制下载头逻辑即可继承统一的 xlsx 行为。

---

User Story 2 - 前端页面不再本地拼 CSV (Priority: P1)

作为业务用户，我希望“红冲记录、银行托收、托收明细、银行代扣、实时收费”这些页面的导出直接下载后端生成的 Excel 文件，而不是前端本地把当前列表拼成 CSV。

Why this priority: 这些页面当前导出逻辑与系统其他 Excel 导出路径不一致，且只导出前端内存数据，存在格式、口径和分页数据缺失风险。

Independent Test: 审阅者在这 5 个页面逐一点击导出，无需查看代码即可确认浏览器下载的是后端返回的 Excel 文件，而不是前端即时生成的 .csv 文件。

Acceptance Scenarios:

1. Given 用户在红冲记录页点击导出，When 请求发往后端导出接口，Then 浏览器下载后端生成的 Excel 文件，不再生成 .csv Blob。
2. Given 用户在银行托收、托收明细、银行代扣、实时收费页面点击导出，When 各页面调用对应后端接口，Then 下载文件由后端生成，文件内容以查询条件为准，而不是仅以当前页 list.value 为准。

---

User Story 3 - 前后端并行可交付 (Priority: P2)

作为项目执行人员，我希望本次改动能拆成后端 lane 与前端 lane 并行推进，并通过 worktree/分支隔离，便于先完成后端统一能力，再接线前端页面并做联调验证。

Why this priority: 本次涉及两个代码仓，若不提前明确并行边界与依赖顺序，容易造成前端等待后端、或后端改动无法快速联调。

Independent Test: 审阅者只查看规格与后续计划，即可明确 backend lane、frontend lane 各自修改范围、依赖顺序与最小验证要求。

Acceptance Scenarios:

1. Given 需要同时修改 water-backend 和 water-frontend，When 实施按计划推进，Then 两个 lane 的修改边界清晰，且能在同一 feature 闭环下联调。
2. Given 某个前端页面缺少现成导出接口，When 盘点后确认缺口，Then 仅补齐该页面所需最小后端导出接口，不扩大到无关页面。

---

Edge Cases

• 若后端 ExcelUtils 已统一为 .xlsx，但某些 controller 仍手工写死 .xls 文件名，则实施时必须一并盘点并修正受影响接口，避免公共工具与业务文件名口径冲突。
• 若某个前端页面尚无对应后端导出接口，则前端不能继续保留本地 CSV 兜底；必须在计划中明确“先补接口，再接前端”。
• 若前端查询条件包含日期区间、分页或详情上下文，导出请求必须复用页面实际查询条件，而不是重新拼装一套口径不一致的参数。
• 若后端返回流式文件下载，前端下载封装必须按文件流处理，不得再次包装为本地 CSV Blob。
• 若文件名包含中文、空格或特殊字符，后端响应头与前端下载链路必须保持统一编码策略，避免下载后文件名乱码。

Requirements (mandatory)

Functional Requirements

• FR-001: 后端公共导出工具 MUST 将 Excel 下载响应头统一为 .xlsx 语义，包括标准 xlsx Content-Type。
• FR-002: 后端公共导出工具 MUST 保证下载文件名以后缀 .xlsx 返回，避免继续暴露 .xls 与实际文件格式不一致的问题。
• FR-003: 本次前端 MUST 替换以下页面的本地 CSV 导出实现：
  • src/views/operatingCharges/redReversalRecord/index.vue
  • src/views/collection/bankCollection/index.vue
  • src/views/collection/bankCollection/detail.vue
  • src/views/collection/bankWithholding/index.vue
  • src/views/collection/realTimeBilling/index.vue
• FR-004: 以上 5 个页面 MUST 通过后端真实导出接口下载文件，不得继续使用 headers.join(',')、new Blob(... text/csv ...)、.csv 文件名等本地 CSV 方案。
• FR-005: 前端导出请求 MUST 复用页面当前查询条件或上下文参数，确保导出数据口径与页面筛选条件一致。
• FR-006: 实施前 MUST 盘点上述 5 个页面各自是否已有后端导出接口；若缺失，则仅补齐该页面所需最小后端导出接口。
• FR-007: 若某页面已有后端导出接口，前端 MUST 优先复用现有接口，不得新增平行接口。
• FR-008: 前端共享下载逻辑 MAY 继续复用现有下载工具，但最终下载对象 MUST 是后端返回的文件流，而不是前端自行生成的 CSV Blob。
• FR-009: 本次实施 MUST 采用前后端并行子任务组织：backend lane 聚焦公共导出工具与必要接口补齐，frontend lane 聚焦 5 个页面接线与移除 CSV 逻辑。
• FR-010: 本次实施 MUST 在 worktree/分支隔离下完成，避免直接在 develop 上混改。
• FR-011: 后端下载文件名与响应头中可编码的文件名部分 MUST 做统一编码处理，避免中文文件名在浏览器或跨端下载场景中出现乱码。
• FR-012: 验证 MUST 至少覆盖后端最小编译/导出验证、前端最小构建或类型验证，以及 5 个页面的关键导出 smoke。
• FR-013: 本次工作 MUST 保持最小闭环，不顺带重构无关下载工具、无关页面或导出权限体系。

Key Entities (include if feature involves data)

• 公共 Excel 导出工具: 后端 ExcelUtils.write(...)，是后端导出响应头与输出流写入的统一入口。
• 页面导出实现: 前端页面中 handleExport 一类导出逻辑，负责把页面查询条件映射到后端导出接口。
• 导出接口: 后端提供的下载型 HTTP 接口，负责根据查询条件生成 Excel 文件流。
• 导出查询条件: 页面当前筛选条件、详情页上下文参数或批次号等，用于保证导出口径一致。
• CSV 本地导出逻辑: 前端通过数组拼接、Blob(text/csv) 和 .csv 文件名直接下载的旧方案，需被移除。

Assumptions

• EasyExcel.write(...) 当前写出的实际文件格式可按 .xlsx 标准响应来承载，本次无需替换 Excel 写入库。
• 这 5 个页面当前仍处于本地假数据 / 本地 CSV 导出阶段，属于前端临时实现，需要切换到正式后端接口模式。
• 可能并非 5 个页面都已具备现成后端导出接口，因此计划阶段需要先完成接口盘点，再决定哪些接口复用、哪些最小补齐。
• 本次以 develop 为基线派生独立 worktree/分支进行实现，最终通过正常合并流程进入 develop。

Clarifications

Session 2026-05-15

• Q: 发现多个前端页面使用本地 CSV 导出时，期望改成哪种方式？ → A: 改成调用后端真实 Excel 导出接口。
• Q: 后端同步修改应做到哪个层级？ → A: 统一修改公共 ExcelUtils 为 .xlsx。
• Q: 前端与后端是顺序推进还是并行分任务推进？ → A: 采用前后端两个分任务一起工作。
• Q: 执行组织方式希望怎样落地？ → A: 先建立 worktree，并以分任务方式并行推进前后端修改。

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: 任一使用 ExcelUtils.write(...) 的后端导出接口下载后，文件后缀为 .xlsx，响应头为 xlsx 标准 MIME。
• SC-002: 上述 5 个前端页面代码中不再出现 text/csv、.csv 下载文件名、手工 csvContent 拼接逻辑。
• SC-003: 5 个页面点击导出时，网络面板可观察到真实后端导出请求，而不是仅在浏览器端生成 Blob 后本地下载。
• SC-004: 若存在缺失导出接口，计划与实现结果中可明确指出哪些页面复用了现有接口、哪些页面补齐了最小后端接口。
• SC-005: 前后端两个 lane 的修改范围可分别审查，且在同一 feature 闭环下完成联调验证。
• SC-006: 含中文的导出文件名在浏览器下载后不出现乱码。

Proposed Execution Lanes

Backend lane

• 基于 develop 派生独立 worktree/分支。
• 修改公共 ExcelUtils，统一 .xlsx 响应。
• 盘点 5 个页面所需后端导出接口，复用已有接口并补齐必要缺口。
• 完成最小编译与导出接口验证。

Frontend lane

• 基于 develop 派生独立 worktree/分支，或在同一 feature 下使用单独前端 worktree。
• 删除 5 个页面的本地 CSV 导出逻辑。
• 新增/调整对应 API 调用，改为下载后端返回文件流。
• 完成最小构建/类型检查与关键页面导出 smoke。

Out of Scope

• 其余未列入的前端页面导出改造。
• 对全站下载工具、权限系统或路由结构做额外重构。
• 新增与 .xlsx 统一无关的报表格式、模板样式或导出内容字段调整。
• 绕过分支审查流程直接修改 develop 的高风险操作。