修复报销附件上传与中文文件名（07-28-travel-reimbursement-guide）
这个提交包含在：
@@ -473,6 +473,98 @@ const TRAVEL_TRANSPORT_EXPENSE_TYPE_CODES = { bus: "travel_bus" };
|
||||
// model and fee-control service both support eligible-day multiplication.
|
||||
```
|
||||
|
||||
## Scenario: Reimbursement Attachment Batch And UTF-8 Filename Boundary
|
||||
|
||||
### 1. Scope / Trigger
|
||||
|
||||
- Trigger: changing reimbursement supporting-material upload limits, multipart
|
||||
parsing, attachment/invoice file responses or tests that register multipart.
|
||||
- Purpose: preserve the global one-file safety default while supporting the
|
||||
reimbursement UI's bounded multi-file request and legal Chinese file names.
|
||||
|
||||
### 2. Signatures
|
||||
|
||||
- Upload: `POST /api/reimbursements/:id/attachments`, multipart field `files`,
|
||||
one to five PDF/JPG/PNG/WebP files per request.
|
||||
- Route parser: `request.parts({ limits: { files: 5, fileSize } })`; the global
|
||||
`@fastify/multipart` registration remains `limits.files=1`.
|
||||
- Download headers: `buildAttachmentContentDisposition(name, {
|
||||
disposition: "inline" })` for reimbursement attachments and invoice PDFs.
|
||||
- Client constant: `MAX_REIMBURSEMENT_ATTACHMENT_FILES=5` is shared by PC and
|
||||
mobile reimbursement detail pages.
|
||||
|
||||
### 3. Contracts
|
||||
|
||||
- Do not relax the application-wide multipart file count. Only the
|
||||
reimbursement supporting-material route overrides it to five.
|
||||
- Parse the complete multipart request before storage/database writes so a
|
||||
sixth file cannot leave a partial five-file upload.
|
||||
- `FST_FILES_LIMIT` maps to `400 VALID_001` with
|
||||
`{ file: "too_many_files", maxFiles: 5 }`; PC and mobile show the same
|
||||
bounded message. Generic error mapping must not assume every module has the
|
||||
reimbursement limit when `maxFiles` is absent.
|
||||
- Preserve the original name in the database. HTTP `Content-Disposition` uses
|
||||
an ASCII `filename` fallback plus RFC 5987 UTF-8 `filename*`; never place raw
|
||||
Chinese, CR/LF, quotes, path separators or control characters in the legacy
|
||||
quoted parameter.
|
||||
- Reimbursement attachments and invoice PDFs retain `inline`; purchase,
|
||||
employee and payment receipt downloads keep their existing default
|
||||
`attachment` behavior through the same shared builder.
|
||||
|
||||
### 4. Validation & Error Matrix
|
||||
|
||||
- One to five allowed files -> parse and persist all files.
|
||||
- Six or more files -> `400 VALID_001 / file=too_many_files`, with zero storage,
|
||||
database and audit writes.
|
||||
- Unsupported MIME, empty file or oversized file -> existing stable file
|
||||
validation error; no partial persistence.
|
||||
- Chinese name -> `inline; filename="attachment.<ext>"; filename*=UTF-8''...`.
|
||||
- Invalid disposition value -> `TypeError`; callers may use only `inline` or
|
||||
`attachment`.
|
||||
|
||||
### 5. Good/Base/Bad Cases
|
||||
|
||||
- Good: PC selects five payment screenshots; the route succeeds even though
|
||||
the test app and production app both register global `files=1`.
|
||||
- Base: one ASCII PDF keeps an ASCII fallback and an equivalent `filename*`.
|
||||
- Bad: set the test-only global limit to five, which hides a missing route
|
||||
override; or interpolate a Chinese database name directly into a Node header.
|
||||
|
||||
### 6. Tests Required
|
||||
|
||||
- Register multipart with the production global `files=1` in reimbursement
|
||||
route tests, then assert five files succeed.
|
||||
- Send six files and assert `400`, `VALID_001`, `too_many_files`, and no
|
||||
attachment/audit writes.
|
||||
- Download an existing Chinese-name reimbursement attachment and invoice PDF;
|
||||
assert `inline`, ASCII `filename`, percent-encoded `filename*`, and no raw
|
||||
Chinese in the header.
|
||||
- Cover CR/LF, quote and path cleanup in the shared Content-Disposition helper,
|
||||
while retaining existing purchase `attachment` regression tests.
|
||||
- Run backend full tests and frontend typecheck/build because the limit and
|
||||
error message cross API and both UI variants.
|
||||
|
||||
### 7. Wrong vs Correct
|
||||
|
||||
#### Wrong
|
||||
|
||||
```js
|
||||
await fastify.register(multipart, { limits: { files: 5 } }); // test-only drift
|
||||
reply.header("content-disposition", `inline; filename="${originalName}"`);
|
||||
```
|
||||
|
||||
#### Correct
|
||||
|
||||
```js
|
||||
for await (const part of request.parts({ limits: { files: 5, fileSize } })) {
|
||||
// Buffer and validate the bounded request before persistence.
|
||||
}
|
||||
reply.header(
|
||||
"content-disposition",
|
||||
buildAttachmentContentDisposition(originalName, { disposition: "inline" }),
|
||||
);
|
||||
```
|
||||
|
||||
## Scenario: Payment Batch Receipt Attention Count
|
||||
|
||||
### 1. Scope / Trigger
|
||||
|
||||
@@ -68,6 +68,15 @@
|
||||
- 当前 `ReimbursementItem` 没有天数或数量字段，`ExpenseStandard.per_unit=day` 也不会在费用控制中乘以天数。因此本轮不创建 100/80 元 block 或 warn 标准，员工分别新增补助明细，以“天数 × 单价”人工算出总额并在说明写明计算式，由主管和财务复核。
|
||||
- 自动带出差旅起止日、计算符合条件的补助天数以及按天校验属于后续产品能力，不阻塞本次真实报销。
|
||||
|
||||
## 报销附件上传与中文文件名
|
||||
|
||||
- 生产复现显示 PC 一次发送多个补充附件时触发 `FST_FILES_LIMIT`：全局 multipart 合同为 `files=1`，而报销附件路由、PC/手机页面和既有测试均按多文件设计。测试曾把全局上限改成 5，掩盖了生产差异。
|
||||
- 保持全局 `files=1`，仅在报销附件 `request.parts()` 调用传入 `limits.files=5` 和既有文件大小限制；捕获 `FST_FILES_LIMIT` 并映射为 `VALID_001 / file=too_many_files`。
|
||||
- 客户端共享 `MAX_REIMBURSEMENT_ATTACHMENT_FILES=5`，PC 与手机选择后先拦截超限并显示相同提示；API 仍接受数组，单次请求最多 5 个。
|
||||
- 生产还复现了中文附件打开失败：原实现仅替换 CR/LF/引号，仍把中文直接放进 `filename="..."`，Node 以 `ERR_INVALID_CHAR` 拒绝响应头。
|
||||
- 把现有采购附件的安全 Content-Disposition 构造能力提炼/扩展为可选 `attachment` 或 `inline` 处置类型，生成安全 ASCII `filename` 与 RFC 5987 UTF-8 `filename*`。报销附件与发票 PDF 使用 `inline`；采购、回单等既有 `attachment` 调用保持不变。
|
||||
- 不改变文件原名在数据库中的业务展示值，不重写已上传文件；修复部署后既有中文名附件即可正常打开。
|
||||
|
||||
## 失败与回退
|
||||
|
||||
- adapter 聚焦测试、配置 smoke、腾讯调用或任一真实样票验证失败：停止开放真实票据，不继续制造 pending/retry 数据。
|
||||
|
||||
@@ -70,6 +70,22 @@
|
||||
- [x] 明确当前由员工按“天数 × 单价”人工填写总额；不配置会误判多日补助的单条费用标准。
|
||||
- [x] 重新生成并检查一页版差旅报销 PDF。
|
||||
|
||||
## 5.2 真实首笔报销附件阻断修复
|
||||
|
||||
- [x] 报销附件路由显式支持单次最多 5 个文件，并稳定映射 `FST_FILES_LIMIT`。
|
||||
- [x] PC/手机共享最多 5 个文件的选择限制、提示和客户端拦截。
|
||||
- [x] 报销附件与发票 PDF 使用安全 ASCII fallback + RFC 5987 UTF-8 文件名响应头。
|
||||
- [x] 测试恢复生产全局 `files=1`，覆盖路由级 5 个成功、6 个失败、中文名及头注入清理。
|
||||
- [x] 完成后端、前端、流程、文档、敏感内容和 Trellis 门禁；提交后另行取得生产部署批准。
|
||||
|
||||
## 2026-07-30 报销附件阻断修复验证
|
||||
|
||||
- 生产日志根因已由聚焦回归锁定：PC 多文件请求触发全局 `FST_FILES_LIMIT`，中文原名直接进入响应头触发 `ERR_INVALID_CHAR`；手机并非独立后端链路。
|
||||
- 报销附件路由保持生产全局 `files=1` 基线并局部覆盖为 5；第 6 个文件返回 `400 VALID_001 / too_many_files`，且附件和审计写入均为 0。
|
||||
- 报销附件与发票 PDF 已统一使用安全 `inline` Content-Disposition；采购、员工附件和付款回单仍保持默认 `attachment`。
|
||||
- 聚焦测试 3 个文件/47 项、后端全量 169 个文件/1082 项、Prisma validate、前端 typecheck/build、流程合同、文档审计、Trellis governance、敏感内容、task validate 与 `git diff --check` 均通过；文档审计仅保留 22 个既有未注册文档 warning。
|
||||
- 本地修复尚未提交、推送或部署；只有部署并完成公网与 PC/手机实测后，才能通知用户重新验收。
|
||||
|
||||
## 6. 验证与审查
|
||||
|
||||
- [x] 静态核对页面/API 上传格式、明细绑定和员工/财务字段边界。
|
||||
|
||||
@@ -27,6 +27,7 @@
|
||||
- 配置并正式启用生产腾讯 OCR，完成配置门禁、受控发布、公网检查和授权 PDF 样票验证。
|
||||
- 在现有腾讯 provider 内改用通用票据识别高级版，补齐住宿电子普通发票和铁路电子客票的安全归一化、质量门禁、大小限制和测试。
|
||||
- 固化公司差旅补助规定，补齐不与城际大巴费用混淆的费用类型，并同步员工指南和报销事实源。
|
||||
- 修复真实首笔报销暴露的 PC 多附件上传与中文文件名打开失败，保持 PC/手机和生产 multipart 合同一致。
|
||||
|
||||
## Requirements
|
||||
|
||||
@@ -54,6 +55,10 @@
|
||||
- 公司或其他单位已直接承担餐食或车辆费用的，不重复领取相应补助；城际交通、住宿及其他经批准的必要差旅费用凭有效材料实报实销。
|
||||
- 当前报销明细没有天数字段，两项补助分别作为独立明细人工填写总额和计算式，例如“伙食补助费：3 天 × 100 元”；不得把现有 `per_unit=day` 费用标准直接配置为 100/80 元，因为当前校验不会按天数乘算，会误判多日补助。
|
||||
- `travel_bus` 保留为城际大巴车票费用；市内交通补助使用独立费用类型，不得共用代码或混同展示。
|
||||
- 报销补充附件在 PC 与手机端均允许单次选择 1–5 个文件；服务端必须在该路由显式覆盖全局单文件 multipart 上限，第 6 个文件进入稳定的 `VALID_001` 错误，不得退化成 `SYS_001`。
|
||||
- PC 与手机选择器均显示“单次最多 5 个”，并在请求前拦截超过 5 个文件的选择；客户端限制只改善体验，服务端仍是最终边界。
|
||||
- 报销附件和发票 PDF 的中文原文件名不得直接进入 HTTP 响应头；`Content-Disposition` 使用安全 ASCII fallback 与 RFC 5987 `filename*`，同时清理控制字符、路径和响应头注入字符。
|
||||
- 报销附件继续使用 `inline` 语义，发票 PDF 继续支持当前预览/下载流程；修复不得改变附件权限、用途留痕、审计或存储内容。
|
||||
- 文档不放真实票据、支付截图、账号、订单号、银行信息或完整业务数据。
|
||||
|
||||
## Acceptance Criteria
|
||||
@@ -71,12 +76,16 @@
|
||||
- [x] 未配置会把多日补助误判为超标的 100/80 元单条费用标准；指南要求员工按天数人工计算并在说明中写出算式。
|
||||
- [x] 在真实 OCR 验收完成前不得仅因指南已完成就通知杨俊可以提交。
|
||||
- [x] 全程不把真实票据、支付截图、完整账号、银行资料、Secret 或原始 payload 写入仓库、任务或聊天。
|
||||
- [x] PC 与手机均可一次上传 1–5 个报销补充附件；选择第 6 个时客户端提前提示，绕过客户端直调服务端仍返回稳定 `VALID_001` 而非 500。
|
||||
- [x] 中文文件名的报销附件和发票 PDF 均返回合法 `Content-Disposition`，保留 `inline` 与 UTF-8 文件名语义且无响应头注入。
|
||||
- [x] 聚焦测试使用与生产一致的全局 `files=1` 基线，证明路由级覆盖有效，并覆盖 5 个成功、6 个失败、中文名和恶意文件名。
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- 新增第二个 OCR provider、开放图片发票、自动验真或增加人工发票字段。
|
||||
- 本轮不做通用发票平台或覆盖全部票种；仅支持现有住宿 VAT/电子普通发票和电子发票（铁路电子客票）主路径。
|
||||
- 修改报销页面、上传格式、审批规则或自动按天计算；本轮只调整差旅相关费用类型名称并新增独立的市内交通补助类型，不配置 100/80 元费用标准。
|
||||
- 改变全局 multipart 单文件默认值，或放宽发票上传“一份请求一张正式票据”的边界。
|
||||
- 代替杨俊上传票据、创建报销、提交审批，或代替主管/财务处理。
|
||||
- 制定覆盖所有费用类别的完整财务制度；本轮只收口首笔差旅的实报实销材料和两项包干补助。
|
||||
|
||||
|
||||
在新工单中引用
屏蔽一个用户