feat(reimbursement-small-team-form-validation): 完善付款批次核对与回单预览
这个提交包含在：
@@ -514,6 +514,7 @@ const label = status === "draft" ? "草稿" : status;
|
||||
- A reviewed bank batch with no active receipt distinguishes no order vs order generated; an active receipt changes guidance to registration. Payment-order count affects copy only when `requiresBankReceipt=true`.
|
||||
- `failed` uses `exception`. A cancellation before review makes the review stage `exception` and payment stage `terminated`; a cancellation after review completes review and makes payment `exception`. `terminated` is a neutral stopped state, not pending, completed or failed.
|
||||
- `actorSource=creator|reviewer|executor|canceller` is an internal semantic reference. The shared service never queries employees; each response assembler resolves only a nullable actor name and never exposes actor IDs inside progress.
|
||||
- When an authorized reimbursement has entered a batch, its processing progress exposes at most one batch link. `draft` and cancellation before review attach it to `付款复核`; `reviewed|executed|failed` and cancellation after review attach it to `付款完成`. Unauthorized actors receive neither link.
|
||||
|
||||
### 4. Validation & Error Matrix
|
||||
|
||||
@@ -537,6 +538,7 @@ const label = status === "draft" ? "草稿" : status;
|
||||
- Pure table-driven unit tests cover all five statuses, both cancellation positions, bank/non-bank channels, order count, receipt count and actorSource.
|
||||
- A structural test extracts both route assembler functions and rejects route-local payment status matrices or duplicate `付款复核` / `付款完成` label definitions.
|
||||
- Route tests assert actor name/time projection, list/detail field separation and absence of snapshot, bank ciphertext and actor IDs inside progress.
|
||||
- Reimbursement route tests assert the five batch statuses, both cancellation positions and the no-permission case never produce duplicate batch links.
|
||||
- PC/mobile E2E uses synthetic responses for all five states, verifies `terminated`, bank/non-bank copy, one visible primary action per viewport and upload-to-register in-place switching.
|
||||
- Reimbursement E2E asserts the four-block order and that submit, print, remind, withdraw and delete retain their state/permission, reason/confirmation, request and refresh contracts after action-panel migration.
|
||||
|
||||
|
||||
@@ -915,3 +915,92 @@ const needsReceipt = batches.filter((batch) =>
|
||||
batch.items.some((item) => (item.paymentChannelOverride ?? batch.defaultPaymentChannel) === "bank"),
|
||||
).length;
|
||||
```
|
||||
|
||||
## Scenario: Payment Batch Expense Evidence And Receipt Preview
|
||||
|
||||
### 1. Scope / Trigger
|
||||
|
||||
- Trigger: changing the reimbursement facts shown in payment-batch detail or
|
||||
the authenticated online-view path for bank receipts.
|
||||
- This is a read-only evidence surface. It must not change reimbursement totals,
|
||||
frozen batch amounts, payment state, maker-checker rules or receipt upload policy.
|
||||
|
||||
### 2. Signatures
|
||||
|
||||
- `GET /api/payment-batches/:id` adds item-level `expenseItems`,
|
||||
`expenseItemsTotal` and `expenseItemsAmountMatches` only in the detail DTO.
|
||||
- Each expense item contains only `id`, `expenseTypeName`, `expenseDate`,
|
||||
`description` and money-string `amount`.
|
||||
- `GET /api/payment-batches/:id/receipt-attachments/:attachmentId/file?mode=preview`
|
||||
returns an authenticated Blob response; omitted mode remains download.
|
||||
|
||||
### 3. Contracts
|
||||
|
||||
- Load reimbursement items and expense types once for all entities in the
|
||||
selected batch. List, create, review, execute and cancel responses do not add
|
||||
expense evidence fields.
|
||||
- `PaymentBatchItem.amount` remains the frozen payment fact. Expense item totals
|
||||
are reconciliation evidence; a mismatch produces a warning and never rewrites
|
||||
either source.
|
||||
- Payment detail orders each card as reimbursement summary, expense evidence and
|
||||
subtotal, payment information, then result/receipt. It links back to the source
|
||||
reimbursement instead of copying invoice or attachment operations.
|
||||
- Historical `travel_order` batches keep their own title and payment facts. They
|
||||
do not render reimbursement expense evidence or a fabricated reimbursement link.
|
||||
- Preview uses the fixed server purpose `付款批次内在线预览`, audits before bytes,
|
||||
and permits only revalidated PDF/JPEG/PNG/WebP. Download still requires a user
|
||||
purpose when governance policy is `reason_required`.
|
||||
- The client fetches the preview through the authenticated API, displays the Blob
|
||||
in the existing dialog and revokes every object URL on close, replacement or
|
||||
unmount.
|
||||
|
||||
### 4. Validation & Error Matrix
|
||||
|
||||
- Batch/list reader lacks permission or department scope -> existing `403`/scope
|
||||
rejection; no expense or receipt bytes.
|
||||
- Reimbursement has no readable items -> detail returns an empty array and `0.00`;
|
||||
UI shows the missing-evidence warning but not a second mismatch warning.
|
||||
- Expense subtotal differs from frozen item amount ->
|
||||
`expenseItemsAmountMatches=false`; UI directs the reviewer to the source form.
|
||||
- Receipt is voided, quarantined, missing, oversized, corrupt or has unsupported
|
||||
preview MIME -> no bytes; existing blocked audit/error contract applies.
|
||||
- Preview audit write fails -> non-success response with no file body.
|
||||
|
||||
### 5. Good/Base/Bad Cases
|
||||
|
||||
- Good: one batch detail query loads three reimbursements' items in one batched
|
||||
read and displays each subtotal beside its masked payment facts.
|
||||
- Base: normal totals match and no warning is shown; an authorized PDF receipt
|
||||
opens inline while its later download asks for a purpose.
|
||||
- Base: a historical travel-order batch remains readable without an empty
|
||||
reimbursement-evidence warning or a link to `/reimbursements/:id`.
|
||||
- Bad: label masked payee facts as “报销明细”, attach expense arrays to the batch
|
||||
list, trust stored MIME without byte validation, or expose a storage URL.
|
||||
|
||||
### 6. Tests Required
|
||||
|
||||
- Route tests assert detail DTO fields, batched loading, money totals, mismatch,
|
||||
empty evidence and privacy-negative fields; list and write responses must omit
|
||||
expense evidence.
|
||||
- Receipt route tests assert PDF/image inline MIME, fixed-purpose preview audit,
|
||||
download-purpose rejection, permission/scope, void/quarantine/size/content and
|
||||
audit-before-send failures.
|
||||
- Frontend typecheck/build and focused Playwright assert responsive expense cards,
|
||||
subtotal/source link, empty/mismatch copy, preview without a purpose dialog,
|
||||
download with a purpose dialog and object-URL cleanup behavior.
|
||||
|
||||
### 7. Wrong vs Correct
|
||||
|
||||
#### Wrong
|
||||
|
||||
```js
|
||||
return mapBatch(batch, { expenseItems: await loadItemsForEveryListRow() });
|
||||
```
|
||||
|
||||
#### Correct
|
||||
|
||||
```js
|
||||
return mapBatchForResponse(prisma, batch, riskFlags, config, {
|
||||
includeExpenseItems: true, // detail route only
|
||||
});
|
||||
```
|
||||
|
||||
@@ -276,9 +276,11 @@ return decryptStringOrThrow(config, encrypted);
|
||||
- Browser downloads of OA-stored attachments must use a currently
|
||||
authenticated request, preferably an API-local `POST` with optional JSON
|
||||
`{ "reason": "..." }`, rather than a query bearer URL. The only approved
|
||||
exception is the at-most-120-second, purpose/object/actor-bound grant used by
|
||||
the official WeCom `previewFile` native layer; follow `wecom-boundary.md` and
|
||||
do not reuse that grant for ordinary browser downloads or other integrations.
|
||||
query-grant exception is the at-most-120-second, purpose/object/actor-bound
|
||||
grant used by the official WeCom `previewFile` native layer; follow
|
||||
`wecom-boundary.md` and do not reuse that grant for ordinary browser downloads
|
||||
or other integrations. Payment-batch receipt preview is a separate,
|
||||
authenticated domain route described below; it never uses a bearer query URL.
|
||||
|
||||
### 3. Contracts
|
||||
|
||||
@@ -313,6 +315,15 @@ return decryptStringOrThrow(config, encrypted);
|
||||
query-token download routes. The WeCom-native reimbursement invoice/attachment
|
||||
exception retains the domain-specific `inline` response and must still audit
|
||||
before bytes, use no-store/no-referrer and reject expired or mismatched grants.
|
||||
- The only ordinary-browser inline exception is
|
||||
`GET /api/payment-batches/:id/receipt-attachments/:attachmentId/file?mode=preview`.
|
||||
It remains batch- and department-authorized, revalidates bounded actual bytes,
|
||||
accepts only PDF/JPEG/PNG/WebP, writes `PAYMENT_BATCH_RECEIPT_PREVIEWED` with
|
||||
fixed reason `付款批次内在线预览` before sending bytes, and returns the validated
|
||||
MIME with `inline`, `nosniff`, private no-store, no-referrer, sandbox CSP and
|
||||
same-origin resource policy. Default/download mode keeps forced binary download
|
||||
and reason-required audit behavior. Do not generalize this exception into a
|
||||
reusable file-center preview route.
|
||||
|
||||
### 4. Validation & Error Matrix
|
||||
|
||||
@@ -330,6 +341,8 @@ return decryptStringOrThrow(config, encrypted);
|
||||
- Explicitly quarantined, missing, oversized, corrupt or unverifiable stored
|
||||
object -> do not return file bytes; write a fixed blocked-reason audit where
|
||||
possible.
|
||||
- Payment receipt preview with a MIME outside PDF/JPEG/PNG/WebP -> blocked audit
|
||||
with fixed reason code; no inline bytes.
|
||||
- Successful-download audit write fails -> return 5xx before download headers
|
||||
or file bytes.
|
||||
|
||||
@@ -337,6 +350,8 @@ return decryptStringOrThrow(config, encrypted);
|
||||
|
||||
- Good: a bank receipt upload returns `confidential`, `receipt`,
|
||||
`reason_required`; download first asks for用途 and writes an audit log.
|
||||
- Good: an authorized payment-detail preview uses the fixed server purpose and
|
||||
writes its preview audit; downloading the same receipt still asks for用途.
|
||||
- Base: a reimbursement supporting material upload defaults to `internal`,
|
||||
`supporting_material`, `standard` and remains downloadable by authorized
|
||||
participants.
|
||||
@@ -364,6 +379,9 @@ return decryptStringOrThrow(config, encrypted);
|
||||
before storage/DB writes, current authentication and object authorization,
|
||||
historical revalidation, blocked-audit reasons, audit-before-send and the
|
||||
complete forced-download header contract.
|
||||
- Payment receipt tests additionally assert preview MIME/disposition/security
|
||||
headers, fixed-purpose audit-before-send, PDF/image allowlist, blocked files,
|
||||
and that default download still rejects a missing reason.
|
||||
- Frontend typecheck/build after API type changes.
|
||||
- Focused UI verification for pages that add attachment governance labels or
|
||||
download-reason interactions.
|
||||
|
||||
@@ -0,0 +1,166 @@
|
||||
# 小团队报销填报与校验完善：技术设计
|
||||
|
||||
## 1. Design boundary
|
||||
|
||||
本任务在现有报销详情、预检和付款批次详情链路内增量实现，不新增数据库表，不建设通用规则引擎，不改变审批、付款写状态机和资产状态机。
|
||||
|
||||
核心数据流：
|
||||
|
||||
```text
|
||||
明细/发票/附件数据库事实
|
||||
-> reimbursement precheck 聚合
|
||||
-> GET detail / POST precheck API
|
||||
-> PC 与手机详情呈现
|
||||
-> submit 事务重新汇总
|
||||
-> 现有审批规则、预算与工作流
|
||||
```
|
||||
|
||||
服务端负责金额、日期和证据状态的权威判断；前端只负责输入约束、可理解呈现和刷新。
|
||||
|
||||
## 2. Contracts
|
||||
|
||||
### 2.1 Runtime configuration
|
||||
|
||||
- 在 `server/src/config.js` 增加 `reimbursementMaxAgeDays`。
|
||||
- 环境变量：`REIMBURSEMENT_MAX_AGE_DAYS`。
|
||||
- 默认：`365`；允许：`180 | 365`；非法值在启动时失败，不静默回退。
|
||||
- 配置只影响警告阈值，不改变数据、审批或付款状态。
|
||||
|
||||
### 2.2 Reimbursement precheck extension
|
||||
|
||||
在现有预检响应中追加向后兼容字段：
|
||||
|
||||
```ts
|
||||
type ReimbursementEvidenceSummary = {
|
||||
invoiceCount: number;
|
||||
attachmentCount: number;
|
||||
items: Array<{
|
||||
itemId: string;
|
||||
linkedInvoiceCount: number;
|
||||
invoiceState: "linked" | "unlinked";
|
||||
}>;
|
||||
};
|
||||
|
||||
type ReimbursementTimelinessCheck = {
|
||||
itemId: string;
|
||||
expenseDate: string;
|
||||
ageDays: number;
|
||||
maxAgeDays: 180 | 365;
|
||||
overdue: boolean;
|
||||
crossCalendarYear: boolean;
|
||||
};
|
||||
|
||||
type ReimbursementAssetHint = {
|
||||
required: boolean;
|
||||
itemCount: number;
|
||||
};
|
||||
```
|
||||
|
||||
- 新字段缺失时旧客户端继续使用既有预检字段。
|
||||
- 超期、跨年度、明细未关联发票和资产候选通过现有 `warnings`/`nextActions` 合并，并保留结构化摘要供 UI 定位。
|
||||
- 明细未关联发票是警告而非新阻断，因为当前存在整单发票、OCR 未完成和合法无票差旅补助等兼容场景。
|
||||
|
||||
### 2.3 Amount validation
|
||||
|
||||
- 手工 item POST/PATCH 将 `amount=0` 视为无效。
|
||||
- 模板/差旅创建仍可内部写入零金额草稿，不经过手工 item POST 门禁。
|
||||
- submit 在同一事务和行锁内读取所有明细：无明细或任一金额 `<= 0` 时返回定位明确的校验错误。
|
||||
- 校验通过后调用现有重算逻辑，将返回值写回本次提交上下文；后续预算和审批规则只使用该值。
|
||||
- 不依赖前端合计，不接受客户端提交整单总额。
|
||||
|
||||
### 2.4 Header editing
|
||||
|
||||
- 扩展前端 API 为通用 `updateReimbursement`，旅行摘要函数可继续包装或迁移到该函数，避免重复 HTTP 合同。
|
||||
- PC 与手机复用小型编辑块：报销日期、报销事由、保存、取消。
|
||||
- 保存成功后刷新 detail、list 和 precheck 查询；使用现有未保存编辑保护模式，避免刷新丢失。
|
||||
|
||||
### 2.5 Totals and evidence UI
|
||||
|
||||
- PC 表格 footer 显示条数与 `detail.totalAmount`；手机列表尾显示相同事实。
|
||||
- 概况标签统一为“报销总额”。打印页保留现有合计行。
|
||||
- 证据提示在明细与材料区使用同一预检摘要，不在前端重新推导业务规则。
|
||||
- 当 OCR off 或发票金额为空时，不显示误导性的“发票金额差额”；本任务只展示数量和关联状态。
|
||||
|
||||
### 2.6 Asset reminder
|
||||
|
||||
- 服务端基于明细费用类型 `category=assets` 生成结构化提示。
|
||||
- UI 只显示候选数量、人工核对说明和授权后的资产模块入口。
|
||||
- 不调用资产创建 API，不保存报销侧资产状态。
|
||||
|
||||
## 3. Compatibility and migration
|
||||
|
||||
- 无 Prisma schema 或数据库迁移。
|
||||
- API 仅新增可选响应字段并收紧非法普通报销提交，现有合法报销兼容。
|
||||
- 历史草稿中的零金额明细可以继续查看和修改，但必须修正后才能提交。
|
||||
- 已提交、已通过和已付款记录保持只读，不回填时效或资产状态。
|
||||
- 现有报销附件仍为整单材料，发票绑定、OCR、查重和连续预览不变；付款回单只增加授权在线查看，不改变上传、作废和下载审计边界。
|
||||
|
||||
## 4. Risks and mitigations
|
||||
|
||||
- **日期偏移**：使用既有 date-only 工具和 `APP_TIMEZONE`，测试阈值当天、闰年和跨年边界。
|
||||
- **预检字段重复计算**：在服务端一次加载报销证据上下文，避免 PC/手机各自实现规则。
|
||||
- **模板回归**：只在手工明细接口和提交阶段收紧正金额，保留模板草稿零金额。
|
||||
- **既有未绑定发票**：只警告不阻断，保持现有整单至少一张发票门禁。
|
||||
- **资产权限泄露**：资产入口按现有权限决定，预检不返回资产卡或敏感字段。
|
||||
- **提交总额竞争**：继续使用报销行锁，并在同一事务内重算后再做预算和审批规则选择。
|
||||
|
||||
## 5. Rollout and rollback
|
||||
|
||||
- 部署前明确 `REIMBURSEMENT_MAX_AGE_DAYS`；缺省为 365。
|
||||
- 先部署服务端兼容字段和校验，再部署前端展示；旧前端可继续工作。
|
||||
- 回滚前端不会破坏服务端数据；回滚服务端仅移除新提示和正金额收紧，无迁移回滚。
|
||||
- 公网验收覆盖普通办公用品、宽带/技术服务、IT 硬件三类合成记录，不使用真实票据内容。
|
||||
|
||||
## 6. Follow-up: reason and payment-batch information architecture
|
||||
|
||||
### 6.1 Travel reason display
|
||||
|
||||
- 继续用现有 `isTravelReimbursement(detail)` 判断差旅单，不新增数据库字段或另一套分类条件。
|
||||
- `ReimbursementHeaderEditor` 增加明确的显示模式：普通报销编辑日期和报销事由；差旅报销只编辑报销日期。
|
||||
- `ReimbursementTravelSummary` 继续独占差旅事由、地点和日期范围。PC 与移动端使用同一条件，避免一端去重、另一端仍重复。
|
||||
- `description` 与 `travel_purpose` 不互写、不迁移。工作流标题、列表搜索和既有通知仍消费原字段；本轮只收敛详情页面向用户的主事由。
|
||||
|
||||
### 6.2 Single payment-batch link
|
||||
|
||||
- 共享付款语义仍负责 `review/payment` 两阶段 state，不新增第二套状态 switch。
|
||||
- 报销详情组装层先填充两个阶段事实，再把 `targetHref` 只赋给一个阶段：
|
||||
- `review=current|exception` 且 `payment=pending|terminated` 时挂到付款复核；
|
||||
- 其他已有批次状态挂到付款完成，包括 reviewed、executed、failed 和复核后取消。
|
||||
- 无付款批次读取权限时两个阶段均无链接；付款批次详情自身不生成自指链接。
|
||||
|
||||
### 6.3 Payment-batch detail DTO
|
||||
|
||||
- 付款批次列表 DTO 保持现状；只有 `GET /payment-batches/:id` 的详情 DTO 为每个报销批次项增加 `expenseItems`。
|
||||
- `expenseItems` 只返回 `id / expenseTypeName / expenseDate / description / amount`，按发生日期与稳定 ID 排序；不返回发票、附件、OCR、完整账号、密文或原始快照。
|
||||
- 详情路由按本批次全部 reimbursement entity ID 一次批量读取报销明细和费用类型，组装到对应批次项，避免逐项查询。
|
||||
- 批次冻结金额继续以 `PaymentBatchItem.amount` 为付款权威值；费用明细只作复核证据。服务端同时给出明细合计，测试锁定其与正常报销单金额一致；若历史异常不一致，页面显示警告，不自动改写批次或报销数据。
|
||||
|
||||
### 6.4 Payment-batch UI
|
||||
|
||||
- 主章节标题改为“本批次报销单”。每张卡按“报销单摘要 → 费用明细 → 付款信息 → 付款结果/风险”排列，并增加返回原报销详情的链接。
|
||||
- 费用明细使用移动优先的响应式卡片/紧凑列表：PC 可按列对齐，移动端改为纵向事实，不引入会横向溢出的宽表。
|
||||
- 每张报销单显示费用条数和明细小计；批次顶部继续显示整批总金额。明细为空或读取失败时显示明确降级提示，不伪装成零费用。
|
||||
- 查看原报销单、查看回单和下载按钮保持至少 44px 触控高度、可见焦点和加载反馈。
|
||||
|
||||
## 7. Follow-up: bank-receipt preview and governance
|
||||
|
||||
### 7.1 Server contract
|
||||
|
||||
- 复用现有回单文件路由和完整验证链，增加受控 `mode=preview`；默认仍为 download，保持旧调用兼容。
|
||||
- download 模式继续要求用户提供非空用途，写 `PAYMENT_BATCH_RECEIPT_DOWNLOADED`，返回附件下载响应。
|
||||
- preview 模式不接受用户用途，服务端固定记录“付款批次内在线预览”，写独立 `PAYMENT_BATCH_RECEIPT_PREVIEWED` 审计；仍执行批次读取权限、部门范围、作废、隔离、大小、存储存在性和内容校验。
|
||||
- preview 只允许校验后的 PDF/JPEG/PNG/WebP，按安全 MIME 返回 `inline`；HTML、SVG 和其他主动内容不进入预览。响应保持 `private, no-store`、`nosniff`、严格 CSP 和同源策略。
|
||||
|
||||
### 7.2 Client interaction
|
||||
|
||||
- 回单卡增加“在线查看”和“下载”两个明确动作。在线查看不弹用途框；下载继续复用现有用途对话框。
|
||||
- 在线查看通过认证 API 获取 Blob，在现有 Dialog 内展示 PDF 或图片；加载中、失败和关闭都有明确反馈，弹窗具备标题、关闭按钮、焦点管理和 Escape 退出。
|
||||
- 图片提供与文件名等价的替代文本；PDF 提供文件名和无法内嵌时的下载提示。对象 URL 在关闭、切换文件或组件卸载时立即 revoke。
|
||||
- 通用治理徽标把“需填用途”改为“下载需说明用途”。这只是文案澄清，不改变合同、采购等其他附件的下载策略。
|
||||
|
||||
## 8. Follow-up compatibility, rollout and rollback
|
||||
|
||||
- API 只为付款批次详情增加字段并为文件路由增加可选 mode，旧客户端和列表接口兼容；无 Prisma 迁移。
|
||||
- 先部署服务端兼容字段与 preview，再部署前端。若前端回滚，服务端新增能力无人调用但不影响下载。
|
||||
- 第一回滚点是回单在线查看与 preview mode；第二回滚点是付款详情费用明细；第三回滚点是两个纯展示条件。回滚均不修改付款、报销或附件数据。
|
||||
- 公网检查只使用脱敏合成文件或既有授权测试材料摘要，不在截图、日志或任务文档保留真实回单和银行信息。
|
||||
@@ -0,0 +1,129 @@
|
||||
# 小团队报销填报与校验完善：实施计划
|
||||
|
||||
## 已交付基线（2026-08-04）
|
||||
|
||||
以下 1–6 节已由原任务实施、验证和部署；本次恢复任务后只需回归，不重复开发。
|
||||
|
||||
## 1. Backend contracts and focused tests
|
||||
|
||||
- [x] 在配置层增加并测试 `REIMBURSEMENT_MAX_AGE_DAYS=180|365`，默认 365，非法配置启动失败。
|
||||
- [x] 在报销预检服务增加证据摘要、时效检查和资产提示，复用 date-only/金额工具。
|
||||
- [x] 为默认期限、180 天、阈值边界、跨年度、未关联发票、整单附件和 `assets` 类别补单测。
|
||||
|
||||
## 2. Authoritative amount validation
|
||||
|
||||
- [x] 收紧手工 item POST/PATCH：金额必须大于零，返回可定位错误。
|
||||
- [x] submit 行锁事务读取明细，拒绝空明细和非正金额明细。
|
||||
- [x] submit 在预算与审批规则前重新汇总并使用权威总额。
|
||||
- [x] 补充空单、零金额模板草稿、修改后提交、陈旧总额修复和审批金额选择回归测试。
|
||||
|
||||
## 3. Shared frontend API and header editing
|
||||
|
||||
- [x] 扩展 reimbursement API 类型与通用 PATCH 函数。
|
||||
- [x] PC 草稿/驳回详情增加报销事由和日期编辑。
|
||||
- [x] 手机草稿/驳回详情增加适合小屏的同等编辑能力。
|
||||
- [x] 保存后刷新 detail/list/precheck，并验证非编辑状态和无权限用户只读。
|
||||
|
||||
## 4. Totals, evidence and asset hints
|
||||
|
||||
- [x] PC 明细表尾增加条数与报销总额，概况标签改为“报销总额”。
|
||||
- [x] 手机明细列表尾增加条数与报销总额。
|
||||
- [x] PC/手机展示明细发票关联状态、整单附件数、时效警告和资产人工建卡提醒。
|
||||
- [x] 资产入口沿用现有权限；打印页合计不回归。
|
||||
|
||||
## 5. Validation and review gates
|
||||
|
||||
- [x] `cd server && npm run prisma:validate`
|
||||
- [x] `cd server && node --check src/config.js && node --check src/services/feeControl.js && node --check src/routes/reimbursements.js`
|
||||
- [x] 运行本任务新增的后端 Vitest 及现有 reimbursement detail/create/expense-standard 聚焦回归。
|
||||
- [x] `cd client && npm run typecheck && npm run build`
|
||||
- [x] 运行 PC 与 mobile/wecom 报销详情 E2E，覆盖合计、编辑、时效、证据和资产提醒。
|
||||
- [x] 运行 `node scripts/qa/check-process-contract.mjs --baseline --json`。
|
||||
- [x] 运行 `node scripts/qa/audit-docs.mjs --check-registry` 和 `node scripts/qa/check-trellis-governance.mjs`。
|
||||
- [x] `git diff --check`
|
||||
- [x] 因提交校验和跨层预检发生变化，实施后进行一次只读 review，重点检查金额竞争、模板兼容和权限边界。
|
||||
|
||||
## 6. Documentation, deployment and rollback
|
||||
|
||||
- [x] 仅在形成稳定规则时更新现有报销事实源或 Trellis spec，不新建平行文档。
|
||||
- [x] 记录环境配置默认值、生产取值和回滚方式，不记录 Secret 或真实票据。
|
||||
- [x] 用户批准后启动任务；实现、检查、必要 spec 更新完成后使用中文 commit，并引用任务名。
|
||||
- [x] 若需用户线上测试，完成部署、公网健康检查和合成数据关键路径冒烟后再通知。
|
||||
|
||||
## 本次后续复核实施计划（待批准）
|
||||
|
||||
## 7. 事由与付款批次入口
|
||||
|
||||
- [x] PC、移动报销详情复用 `isTravelReimbursement`：普通报销显示日期和报销事由，差旅报销只在头部编辑日期并由差旅摘要独占出差事由。
|
||||
- [x] 核对列表、打印、搜索、工作流标题和通知对 `description/travel_purpose` 的消费，保证本轮不迁移、不丢失既有数据。
|
||||
- [x] 报销进度组装完成两阶段语义后，只给实际当前/终止/最终付款阶段设置付款批次链接。
|
||||
- [x] 增加普通/差旅 PC 与移动断言，以及 draft/reviewed/executed/failed/cancelled、取消前后和无权限的链接矩阵测试。
|
||||
|
||||
## 8. 付款批次费用明细
|
||||
|
||||
- [x] 扩展付款批次详情查询，一次批量加载批次内报销费用明细及费用类型；列表接口保持轻量。
|
||||
- [x] 详情 DTO 增加最小 `expenseItems` 和服务端明细合计，补隐私负向断言与历史空数据降级。
|
||||
- [x] 页面章节改为“本批次报销单”，每张卡依次显示报销摘要、费用明细/小计、付款信息、付款结果和原报销单入口。
|
||||
- [x] PC 使用紧凑对齐布局，移动端使用纵向事实卡；不得产生横向溢出，按钮保持触控尺寸和可见焦点。
|
||||
|
||||
## 9. 银行回单在线查看
|
||||
|
||||
- [x] 文件路由增加兼容的 preview mode：固定预览用途、独立审计动作、安全 inline MIME，同时保留下载用途门禁和既有下载响应。
|
||||
- [x] 复用并回归权限、部门数据范围、作废、隔离、文件不存在、大小、内容类型和存储校验；拒绝 HTML/SVG/未知主动内容。
|
||||
- [x] 前端增加认证 Blob 在线预览弹窗，支持 PDF/图片、加载/失败/关闭反馈、键盘与焦点管理，并可靠释放对象 URL。
|
||||
- [x] 下载继续弹用途框；通用徽标文案改为“下载需说明用途”，回归采购、合同、报销等既有消费者的语义和视觉。
|
||||
|
||||
## 10. 验证、只读审查与文档
|
||||
|
||||
- [x] 运行付款语义、报销详情、付款批次、回单附件治理聚焦 Vitest；记录并区分本机 BIFF8 固定 Python 依赖缺失基线。
|
||||
- [x] 运行 Prisma validate、所改 Node 文件语法检查、客户端 typecheck/build。
|
||||
- [x] 运行 PC/移动合成 E2E，覆盖事由去重、唯一批次入口、费用明细与小计、PDF/图片预览、下载用途和无权限/异常文件。
|
||||
- [x] 运行 Trellis task validate、流程合同、文档注册、Trellis 治理、敏感内容和 `git diff --check`。
|
||||
- [x] 按项目约束执行一次只读 review，重点检查付款状态投影、批次详情隐私、回单权限/审计与 PC/移动一致性；reviewer 不改代码。
|
||||
- [x] 仅将稳定规则更新到现有 `docs/报销发票附件规则.md`、`docs/产品设计规则.md` 或对应 Trellis spec，不新建平行文档。
|
||||
|
||||
## 11. Commit and deployment gate
|
||||
|
||||
- [x] 全部本地门禁通过后使用中文 commit，并引用 `reimbursement-small-team-form-validation`。
|
||||
- [ ] 本次规划不包含部署授权；代码完成后另行申请公网部署许可。
|
||||
- [ ] 获得部署授权后使用既有部署入口，验证 build、`/ready`、数据库无迁移、回单预览与付款详情脱敏冒烟；通过后才通知用户测试。
|
||||
|
||||
## Rollback points
|
||||
|
||||
- 配置/预检字段为第一回滚点：可独立移除，不影响数据库。
|
||||
- 正金额提交门禁为第二回滚点：若发现合法流程被误阻断，先回滚该提交校验，不绕过发票/权限门禁。
|
||||
- 前端编辑与提示为第三回滚点：可回滚 UI，服务端新增字段保持向后兼容。
|
||||
- 后续复核新增回滚点：先关闭前端回单预览，再回滚详情 DTO，再回滚纯展示条件；均不改写业务数据。
|
||||
|
||||
## 后续复核执行记录（2026-08-05）
|
||||
|
||||
- 差旅详情已收敛为单一“出差事由”；日期编辑请求不发送普通报销 `description`。报销进度的付款批次链接已按五状态和取消前后分支唯一投影。
|
||||
- 付款批次详情仅在详情 DTO 批量加载最小费用明细，列表及创建、复核、执行、取消响应不携带明细；空明细不重复显示金额不一致警告。
|
||||
- PDF 与 PNG 回单预览均通过实际内容复检、固定用途审计和安全 inline 响应验证；下载仍要求用途。前端 19 项 PC/移动合成 E2E 全部通过。
|
||||
- Prisma、Node 语法、前端 typecheck/build、Trellis task、流程、文档、治理、敏感信息和差异门禁通过。后端聚焦 80 项中 79 项通过；唯一失败为实施前已存在的 BIFF8 银行制单用例，本机缺固定 Python 依赖导致预期 200、实际 409，与本轮改动无关。
|
||||
- 已完成主会话只读复核并修正四处边界：写接口不附带费用明细、空明细不重复告警、差旅日期编辑不回传普通事由、历史差旅付款批次不冒充报销明细或生成错误报销入口。未执行部署、生产配置、真实数据或付款操作。
|
||||
|
||||
## 执行记录（2026-08-04）
|
||||
|
||||
- 服务端聚焦回归 9 个文件、86 个用例全部通过；Prisma 与所改 Node 文件语法检查通过。
|
||||
- 前端 `typecheck`、生产构建通过；R102 合成 API 浏览器回归覆盖 PC/手机合计、事由日期编辑和材料提示，原 5 个用例通过，新增/修正用例单独复跑通过。
|
||||
- 任务、环境契约、流程合同、文档注册、Trellis 治理、敏感内容和 `git diff --check` 均通过；文档注册保留既有 22 个未注册文件 warning，无新增错误。
|
||||
- 全量后端 1228 个用例中 1224 个通过；3 个既有付款 BIFF8 导出用例因本机未安装 `server/requirements/payment-order-biff8.txt` 固定 Python 依赖失败，另 1 个本任务引起的环境键计数已修正并复跑通过。
|
||||
- 已完成主会话只读复核，修正“已完成报销不显示资产提醒”和“超期且跨年只显示一个提示”两处跨层遗漏。
|
||||
- 未执行生产部署、生产配置写入或公网数据操作；如需线上测试，须按项目规则另行取得明确部署授权。
|
||||
|
||||
## 部署续办（2026-08-04，已授权）
|
||||
|
||||
- [x] 确认工作提交已发布到部署入口要求的上游分支，并执行已有部署只读预检。
|
||||
- [x] 按 `deploy-existing.sh` 发布已批准提交，不同步或覆盖生产 `.env`，不执行真实业务写入。
|
||||
- [x] 验证活动服务 build、`/ready`、公网只读 smoke、PC/手机关键页面及 180/365 配置生效状态。
|
||||
- [x] 记录脱敏结果与回滚边界；如应用发布成功但备份合同刷新失败，按既有部分成功分类处理，不重复部署应用。
|
||||
|
||||
### 部署结果
|
||||
|
||||
- 发布提交为 `3aebfc5e046d`；Git 来源已发布，部署前和部署后远端合同均为 13/13 PASS。
|
||||
- 生产 `.env` 未同步或覆盖；数据库无待执行迁移，初始化只保留既有配置和账号口令，不执行真实报销、审批或付款写入。
|
||||
- 应用、外部依赖、运行时功能开关、公网 build 标识和前端资源文案扫描通过；备份合同刷新完整通过，无部分成功状态。
|
||||
- 公网 `/ready` 返回当前 build；生产运行时 `REIMBURSEMENT_MAX_AGE_DAYS` 生效值为默认 365，业务时区已配置。
|
||||
- 公网基础 Playwright smoke 按企微 `ready` 状态复跑通过。管理员/员工登录态 smoke 因本机未配置专用 `LIVE_SMOKE_*` 凭据未执行；未读取、复制或输出生产账号密码。
|
||||
- PC/手机报销关键交互已由发布前合成 API 浏览器回归覆盖；公网部署后的对应前端资源已命中当前 build 并通过扫描。回滚继续使用既有部署入口切换到上一已发布提交，不修改数据库结构或生产环境文件。
|
||||
+48
-13
@@ -2,7 +2,7 @@
|
||||
|
||||
## Goal
|
||||
|
||||
面向公司内部 5–10 人使用场景，在不扩展为通用费控产品的前提下，完善普通报销填报、提交预检和证据提示，使员工容易填写、审批人看得懂、财务能够核对、付款后能够追溯。
|
||||
面向公司内部 5–10 人使用场景，在不扩展为通用费控产品的前提下，完善报销填报、提交预检、付款批次核对和回单查看，使员工容易填写、审批人看得懂、财务能够核对、付款后能够追溯。
|
||||
|
||||
## Background and confirmed facts
|
||||
|
||||
@@ -13,6 +13,8 @@
|
||||
- 发票已有可选明细关联；补充附件当前属于整单。本任务不引入发票多对多关系或附件明细关联。
|
||||
- 费用类型已有 `assets` 类别；资产事实源要求“资产候选 + 管理员人工建卡”，不得因报销提交、审批或付款自动生成资产卡。
|
||||
- 本轮讨论已决定不增加“历史费用补报”标识。票据新旧由费用日期、发票日期和提交日期推导。
|
||||
- 后续真实使用复核发现：差旅报销同时展示整单“报销事由”和“出差事由”；有权限用户在付款复核与付款完成两个阶段都看到同一付款批次链接；付款批次的“报销明细”实际只有报销单级付款摘要；银行回单只有强制下载路径。
|
||||
- 代码核实确认上述四项均由当前实现稳定产生，并非截图或浏览器偶发现象：前两项属于展示条件/阶段链接组装问题，后两项分别存在详情 API 数据缺口和附件查看能力缺口。
|
||||
|
||||
## Scope
|
||||
|
||||
@@ -22,6 +24,7 @@
|
||||
- 明细发票关联、整单附件数量的材料完整性提示。
|
||||
- `assets` 类别的人工资产建卡提醒和授权入口。
|
||||
- 所需的前后端类型、聚焦测试、现有事实源/spec 更新及部署配置说明。
|
||||
- 报销详情、付款批次详情和银行回单之间的只读信息展示与交互复核；不改变付款写状态机、maker-checker 或真实付款边界。
|
||||
|
||||
## Requirements
|
||||
|
||||
@@ -68,18 +71,48 @@
|
||||
- 不自动创建资产卡、不自动判断会计固定资产、不复制资产建卡表单到报销页。
|
||||
- 有资产台账查看权限的用户可从提醒进入资产模块；其他用户只看到下一步说明。
|
||||
|
||||
### R7 差旅报销事由单一主语义
|
||||
|
||||
- 普通报销继续展示并编辑“报销事由”。
|
||||
- 差旅报销以“出差事由”为唯一面向用户的主事由，不在同一区域重复展示空泛的“报销事由”。
|
||||
- 既有 `description` 与 `travel_purpose` 数据暂不迁移、不互相覆盖；打印、搜索、通知标题等非详情消费者需在设计阶段核对兼容语义。
|
||||
|
||||
### R8 付款批次入口只出现一次
|
||||
|
||||
- 有付款批次读取权限且报销已进入批次时，处理进度中只显示一个“查看所在付款批次”入口。
|
||||
- 入口随批次状态挂到实际承载当前或最终结果的阶段：待复核挂在“付款复核”，复核后、付款失败或付款完成挂在“付款完成”；取消状态挂在实际终止阶段。
|
||||
- 普通员工仍不获得付款批次读取权限或内部批次入口。
|
||||
|
||||
### R9 付款批次区分报销单与费用明细
|
||||
|
||||
- 付款批次中的一张卡片首先表示一张待付款报销单，应使用“本批次报销单”或同等准确标题，不把收款账户摘要冒充费用明细。
|
||||
- 每张报销单展示其费用明细的只读摘要，至少包含费用类型、发生日期、说明和金额，并显示明细合计；同时保留收款人、开户银行、脱敏账号、付款渠道和付款结果。
|
||||
- 付款批次提供返回原报销详情的入口；不在付款页复制发票、补充附件编辑和完整报销操作。
|
||||
- 费用明细只加入付款批次详情 DTO，列表响应继续保持轻量；不得返回完整银行账号、加密值或原始快照。
|
||||
|
||||
### R10 银行回单在线查看与用途治理
|
||||
|
||||
- PDF 和支持的图片回单在付款批次详情中提供在线查看；不再要求用户必须先下载到本地才能核对。
|
||||
- 在线查看继续经过服务端权限、批次数据范围、文件类型/大小/隔离状态校验，并写审计；不得直接暴露存储路径。
|
||||
- 回单继续标记为“保密”。授权人员在批次上下文内在线查看时使用系统固定用途并自动审计，不要求重复手填；下载到本地仍要求手填用途并写审计。
|
||||
- “需填用途”若仅针对下载，应改为更准确的“下载需说明用途”，避免误解为回单本身资料不完整。
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] AC1：PC 和手机的报销明细区域均显示与服务端 `totalAmount` 一致的明细数量和合计；新增、修改、删除后自动刷新。
|
||||
- [ ] AC2：手工新增/修改 `0` 金额明细被服务端拒绝；空明细或含非正金额明细的报销无法提交；模板零金额草稿仍可创建和编辑。
|
||||
- [ ] AC3：提交事务重新汇总权威总额，审批规则和后续提交结果不使用陈旧总额。
|
||||
- [ ] AC4：草稿/驳回报销可在 PC 和手机编辑报销事由和日期；其他状态不可编辑，权限边界不放宽。
|
||||
- [ ] AC5：默认 365 天配置有效，可切换为 180 天；超期和跨年度产生可理解警告但不阻断，date-only 边界无偏移。
|
||||
- [ ] AC6：预检及详情能显示每条明细的发票关联状态和整单附件数；现有整单发票门禁、OCR、查重和附件权限不回归。
|
||||
- [ ] AC7：`assets` 类别触发人工资产登记提醒，不产生任何资产卡写入；无权限用户不会获得资产数据或管理入口。
|
||||
- [ ] AC8：PC、手机和打印页使用一致的金额语义；普通用户页面不出现内部技术术语。
|
||||
- [ ] AC9：相关后端测试、前端 typecheck/build、PC/移动报销 E2E、Trellis 治理和 `git diff --check` 全部通过。
|
||||
- [ ] AC10：若改动面向公网用户，部署、公网冒烟和关键页面检查通过后才告知可以测试。
|
||||
- [x] AC1：PC 和手机的报销明细区域均显示与服务端 `totalAmount` 一致的明细数量和合计；新增、修改、删除后自动刷新。
|
||||
- [x] AC2：手工新增/修改 `0` 金额明细被服务端拒绝；空明细或含非正金额明细的报销无法提交；模板零金额草稿仍可创建和编辑。
|
||||
- [x] AC3：提交事务重新汇总权威总额，审批规则和后续提交结果不使用陈旧总额。
|
||||
- [x] AC4：草稿/驳回报销可在 PC 和手机编辑报销事由和日期；其他状态不可编辑，权限边界不放宽。
|
||||
- [x] AC5：默认 365 天配置有效，可切换为 180 天；超期和跨年度产生可理解警告但不阻断，date-only 边界无偏移。
|
||||
- [x] AC6：预检及详情能显示每条明细的发票关联状态和整单附件数；现有整单发票门禁、OCR、查重和附件权限不回归。
|
||||
- [x] AC7：`assets` 类别触发人工资产登记提醒，不产生任何资产卡写入；无权限用户不会获得资产数据或管理入口。
|
||||
- [x] AC8：PC、手机和打印页使用一致的金额语义；普通用户页面不出现内部技术术语。
|
||||
- [x] AC9：相关后端测试、前端 typecheck/build、PC/移动报销 E2E、Trellis 治理和 `git diff --check` 全部通过。
|
||||
- [x] AC10：若改动面向公网用户，部署、公网冒烟和关键页面检查通过后才告知可以测试。
|
||||
- [x] AC11：普通报销显示“报销事由”，差旅报销详情只显示一个主事由入口且沿用“出差事由”；既有差旅数据不丢失。
|
||||
- [x] AC12：同一报销的处理进度最多出现一个付款批次入口，五种批次状态及取消前后分支均落在正确阶段，权限边界不放宽。
|
||||
- [x] AC13：付款批次明确区分报销单、费用明细和付款信息；费用明细金额合计与报销单金额一致，并可返回原报销详情。
|
||||
- [x] AC14：PDF/图片银行回单可在授权页面在线查看且自动记录固定用途；下载到本地仍要求手填用途，隔离、作废、超限和无权限文件不可查看或下载。
|
||||
|
||||
## Out of Scope
|
||||
|
||||
@@ -87,10 +120,12 @@
|
||||
- 通用费用政策中心、复杂预算、银企直连、自动付款、自动记账或完整电子会计档案系统。
|
||||
- 发票与明细多对多、补充附件关联具体明细、发票验真能力扩展。
|
||||
- 自动创建资产卡、折旧/残值/会计科目判断。
|
||||
- 改造采购流程、付款状态机、审批角色或权限模型。
|
||||
- 改造采购流程、付款写状态机、审批角色或权限模型。
|
||||
- 把发票、补充附件编辑或完整报销详情复制进付款批次，或新增通用文档预览中心。
|
||||
|
||||
## Test Plan
|
||||
|
||||
- Backend：Prisma validate、`node --check`、报销详情/创建/费用标准相关 Vitest，并补充本任务聚焦用例。
|
||||
- Frontend：`npm run typecheck`、`npm run build`、PC 和 mobile/wecom 报销详情 E2E。
|
||||
- Frontend：`npm run typecheck`、`npm run build`、PC 和 mobile/wecom 报销详情及付款批次详情 E2E。
|
||||
- Process：Trellis task validate、流程合同、治理、文档注册审计和 `git diff --check`。
|
||||
- Follow-up focused：差旅/普通报销事由显示、付款批次入口五状态矩阵、付款批次详情 DTO 隐私负向断言、费用明细合计、回单 PDF/图片在线查看及用途/审计/隔离回归。
|
||||
+3
-3
@@ -2,8 +2,8 @@
|
||||
"id": "reimbursement-small-team-form-validation",
|
||||
"name": "reimbursement-small-team-form-validation",
|
||||
"title": "小团队报销填报与校验完善",
|
||||
"description": "完善小团队内部报销的明细合计、正金额校验、事由编辑、票据时效提示、材料完整性提示和资产登记提醒。",
|
||||
"status": "completed",
|
||||
"description": "完善小团队内部报销填报，并复核报销详情、付款批次和银行回单之间的信息展示与交互。",
|
||||
"status": "in_progress",
|
||||
"dev_type": "feature",
|
||||
"scope": "server/client/docs/tests",
|
||||
"package": null,
|
||||
@@ -22,5 +22,5 @@
|
||||
"relatedFiles": [],
|
||||
"notes": "",
|
||||
"meta": {},
|
||||
"completedAt": "2026-08-04"
|
||||
"completedAt": null
|
||||
}
|
||||
@@ -1,112 +0,0 @@
|
||||
# 小团队报销填报与校验完善：技术设计
|
||||
|
||||
## 1. Design boundary
|
||||
|
||||
本任务在现有报销详情和预检链路内增量实现，不新增数据库表，不建设通用规则引擎，不改变审批、付款和资产状态机。
|
||||
|
||||
核心数据流：
|
||||
|
||||
```text
|
||||
明细/发票/附件数据库事实
|
||||
-> reimbursement precheck 聚合
|
||||
-> GET detail / POST precheck API
|
||||
-> PC 与手机详情呈现
|
||||
-> submit 事务重新汇总
|
||||
-> 现有审批规则、预算与工作流
|
||||
```
|
||||
|
||||
服务端负责金额、日期和证据状态的权威判断；前端只负责输入约束、可理解呈现和刷新。
|
||||
|
||||
## 2. Contracts
|
||||
|
||||
### 2.1 Runtime configuration
|
||||
|
||||
- 在 `server/src/config.js` 增加 `reimbursementMaxAgeDays`。
|
||||
- 环境变量：`REIMBURSEMENT_MAX_AGE_DAYS`。
|
||||
- 默认：`365`；允许：`180 | 365`；非法值在启动时失败，不静默回退。
|
||||
- 配置只影响警告阈值，不改变数据、审批或付款状态。
|
||||
|
||||
### 2.2 Reimbursement precheck extension
|
||||
|
||||
在现有预检响应中追加向后兼容字段：
|
||||
|
||||
```ts
|
||||
type ReimbursementEvidenceSummary = {
|
||||
invoiceCount: number;
|
||||
attachmentCount: number;
|
||||
items: Array<{
|
||||
itemId: string;
|
||||
linkedInvoiceCount: number;
|
||||
invoiceState: "linked" | "unlinked";
|
||||
}>;
|
||||
};
|
||||
|
||||
type ReimbursementTimelinessCheck = {
|
||||
itemId: string;
|
||||
expenseDate: string;
|
||||
ageDays: number;
|
||||
maxAgeDays: 180 | 365;
|
||||
overdue: boolean;
|
||||
crossCalendarYear: boolean;
|
||||
};
|
||||
|
||||
type ReimbursementAssetHint = {
|
||||
required: boolean;
|
||||
itemCount: number;
|
||||
};
|
||||
```
|
||||
|
||||
- 新字段缺失时旧客户端继续使用既有预检字段。
|
||||
- 超期、跨年度、明细未关联发票和资产候选通过现有 `warnings`/`nextActions` 合并，并保留结构化摘要供 UI 定位。
|
||||
- 明细未关联发票是警告而非新阻断，因为当前存在整单发票、OCR 未完成和合法无票差旅补助等兼容场景。
|
||||
|
||||
### 2.3 Amount validation
|
||||
|
||||
- 手工 item POST/PATCH 将 `amount=0` 视为无效。
|
||||
- 模板/差旅创建仍可内部写入零金额草稿，不经过手工 item POST 门禁。
|
||||
- submit 在同一事务和行锁内读取所有明细：无明细或任一金额 `<= 0` 时返回定位明确的校验错误。
|
||||
- 校验通过后调用现有重算逻辑，将返回值写回本次提交上下文；后续预算和审批规则只使用该值。
|
||||
- 不依赖前端合计，不接受客户端提交整单总额。
|
||||
|
||||
### 2.4 Header editing
|
||||
|
||||
- 扩展前端 API 为通用 `updateReimbursement`，旅行摘要函数可继续包装或迁移到该函数，避免重复 HTTP 合同。
|
||||
- PC 与手机复用小型编辑块：报销日期、报销事由、保存、取消。
|
||||
- 保存成功后刷新 detail、list 和 precheck 查询；使用现有未保存编辑保护模式，避免刷新丢失。
|
||||
|
||||
### 2.5 Totals and evidence UI
|
||||
|
||||
- PC 表格 footer 显示条数与 `detail.totalAmount`；手机列表尾显示相同事实。
|
||||
- 概况标签统一为“报销总额”。打印页保留现有合计行。
|
||||
- 证据提示在明细与材料区使用同一预检摘要，不在前端重新推导业务规则。
|
||||
- 当 OCR off 或发票金额为空时，不显示误导性的“发票金额差额”；本任务只展示数量和关联状态。
|
||||
|
||||
### 2.6 Asset reminder
|
||||
|
||||
- 服务端基于明细费用类型 `category=assets` 生成结构化提示。
|
||||
- UI 只显示候选数量、人工核对说明和授权后的资产模块入口。
|
||||
- 不调用资产创建 API，不保存报销侧资产状态。
|
||||
|
||||
## 3. Compatibility and migration
|
||||
|
||||
- 无 Prisma schema 或数据库迁移。
|
||||
- API 仅新增可选响应字段并收紧非法普通报销提交，现有合法报销兼容。
|
||||
- 历史草稿中的零金额明细可以继续查看和修改，但必须修正后才能提交。
|
||||
- 已提交、已通过和已付款记录保持只读，不回填时效或资产状态。
|
||||
- 现有附件仍为整单材料，现有发票绑定、OCR、查重和连续预览不变。
|
||||
|
||||
## 4. Risks and mitigations
|
||||
|
||||
- **日期偏移**：使用既有 date-only 工具和 `APP_TIMEZONE`，测试阈值当天、闰年和跨年边界。
|
||||
- **预检字段重复计算**：在服务端一次加载报销证据上下文，避免 PC/手机各自实现规则。
|
||||
- **模板回归**：只在手工明细接口和提交阶段收紧正金额，保留模板草稿零金额。
|
||||
- **既有未绑定发票**：只警告不阻断，保持现有整单至少一张发票门禁。
|
||||
- **资产权限泄露**：资产入口按现有权限决定，预检不返回资产卡或敏感字段。
|
||||
- **提交总额竞争**：继续使用报销行锁，并在同一事务内重算后再做预算和审批规则选择。
|
||||
|
||||
## 5. Rollout and rollback
|
||||
|
||||
- 部署前明确 `REIMBURSEMENT_MAX_AGE_DAYS`；缺省为 365。
|
||||
- 先部署服务端兼容字段和校验，再部署前端展示；旧前端可继续工作。
|
||||
- 回滚前端不会破坏服务端数据；回滚服务端仅移除新提示和正金额收紧，无迁移回滚。
|
||||
- 公网验收覆盖普通办公用品、宽带/技术服务、IT 硬件三类合成记录，不使用真实票据内容。
|
||||
@@ -1,78 +0,0 @@
|
||||
# 小团队报销填报与校验完善：实施计划
|
||||
|
||||
## 1. Backend contracts and focused tests
|
||||
|
||||
- [ ] 在配置层增加并测试 `REIMBURSEMENT_MAX_AGE_DAYS=180|365`，默认 365，非法配置启动失败。
|
||||
- [ ] 在报销预检服务增加证据摘要、时效检查和资产提示，复用 date-only/金额工具。
|
||||
- [ ] 为默认期限、180 天、阈值边界、跨年度、未关联发票、整单附件和 `assets` 类别补单测。
|
||||
|
||||
## 2. Authoritative amount validation
|
||||
|
||||
- [ ] 收紧手工 item POST/PATCH：金额必须大于零，返回可定位错误。
|
||||
- [ ] submit 行锁事务读取明细，拒绝空明细和非正金额明细。
|
||||
- [ ] submit 在预算与审批规则前重新汇总并使用权威总额。
|
||||
- [ ] 补充空单、零金额模板草稿、修改后提交、陈旧总额修复和审批金额选择回归测试。
|
||||
|
||||
## 3. Shared frontend API and header editing
|
||||
|
||||
- [ ] 扩展 reimbursement API 类型与通用 PATCH 函数。
|
||||
- [ ] PC 草稿/驳回详情增加报销事由和日期编辑。
|
||||
- [ ] 手机草稿/驳回详情增加适合小屏的同等编辑能力。
|
||||
- [ ] 保存后刷新 detail/list/precheck，并验证非编辑状态和无权限用户只读。
|
||||
|
||||
## 4. Totals, evidence and asset hints
|
||||
|
||||
- [ ] PC 明细表尾增加条数与报销总额，概况标签改为“报销总额”。
|
||||
- [ ] 手机明细列表尾增加条数与报销总额。
|
||||
- [ ] PC/手机展示明细发票关联状态、整单附件数、时效警告和资产人工建卡提醒。
|
||||
- [ ] 资产入口沿用现有权限；打印页合计不回归。
|
||||
|
||||
## 5. Validation and review gates
|
||||
|
||||
- [ ] `cd server && npm run prisma:validate`
|
||||
- [ ] `cd server && node --check src/config.js && node --check src/services/feeControl.js && node --check src/routes/reimbursements.js`
|
||||
- [ ] 运行本任务新增的后端 Vitest 及现有 reimbursement detail/create/expense-standard 聚焦回归。
|
||||
- [ ] `cd client && npm run typecheck && npm run build`
|
||||
- [ ] 运行 PC 与 mobile/wecom 报销详情 E2E，覆盖合计、编辑、时效、证据和资产提醒。
|
||||
- [ ] 运行 `node scripts/qa/check-process-contract.mjs --baseline --json`。
|
||||
- [ ] 运行 `node scripts/qa/audit-docs.mjs --check-registry` 和 `node scripts/qa/check-trellis-governance.mjs`。
|
||||
- [ ] `git diff --check`
|
||||
- [ ] 因提交校验和跨层预检发生变化，实施后进行一次只读 review，重点检查金额竞争、模板兼容和权限边界。
|
||||
|
||||
## 6. Documentation, deployment and rollback
|
||||
|
||||
- [ ] 仅在形成稳定规则时更新现有报销事实源或 Trellis spec，不新建平行文档。
|
||||
- [ ] 记录环境配置默认值、生产取值和回滚方式，不记录 Secret 或真实票据。
|
||||
- [ ] 用户批准后启动任务；实现、检查、必要 spec 更新完成后使用中文 commit，并引用任务名。
|
||||
- [ ] 若需用户线上测试，完成部署、公网健康检查和合成数据关键路径冒烟后再通知。
|
||||
|
||||
## Rollback points
|
||||
|
||||
- 配置/预检字段为第一回滚点：可独立移除，不影响数据库。
|
||||
- 正金额提交门禁为第二回滚点：若发现合法流程被误阻断，先回滚该提交校验，不绕过发票/权限门禁。
|
||||
- 前端编辑与提示为第三回滚点：可回滚 UI，服务端新增字段保持向后兼容。
|
||||
|
||||
## 执行记录（2026-08-04）
|
||||
|
||||
- 服务端聚焦回归 9 个文件、86 个用例全部通过；Prisma 与所改 Node 文件语法检查通过。
|
||||
- 前端 `typecheck`、生产构建通过；R102 合成 API 浏览器回归覆盖 PC/手机合计、事由日期编辑和材料提示，原 5 个用例通过，新增/修正用例单独复跑通过。
|
||||
- 任务、环境契约、流程合同、文档注册、Trellis 治理、敏感内容和 `git diff --check` 均通过；文档注册保留既有 22 个未注册文件 warning，无新增错误。
|
||||
- 全量后端 1228 个用例中 1224 个通过；3 个既有付款 BIFF8 导出用例因本机未安装 `server/requirements/payment-order-biff8.txt` 固定 Python 依赖失败，另 1 个本任务引起的环境键计数已修正并复跑通过。
|
||||
- 已完成主会话只读复核，修正“已完成报销不显示资产提醒”和“超期且跨年只显示一个提示”两处跨层遗漏。
|
||||
- 未执行生产部署、生产配置写入或公网数据操作；如需线上测试，须按项目规则另行取得明确部署授权。
|
||||
|
||||
## 部署续办（2026-08-04，已授权）
|
||||
|
||||
- [x] 确认工作提交已发布到部署入口要求的上游分支，并执行已有部署只读预检。
|
||||
- [x] 按 `deploy-existing.sh` 发布已批准提交，不同步或覆盖生产 `.env`，不执行真实业务写入。
|
||||
- [x] 验证活动服务 build、`/ready`、公网只读 smoke、PC/手机关键页面及 180/365 配置生效状态。
|
||||
- [x] 记录脱敏结果与回滚边界；如应用发布成功但备份合同刷新失败，按既有部分成功分类处理，不重复部署应用。
|
||||
|
||||
### 部署结果
|
||||
|
||||
- 发布提交为 `3aebfc5e046d`；Git 来源已发布，部署前和部署后远端合同均为 13/13 PASS。
|
||||
- 生产 `.env` 未同步或覆盖；数据库无待执行迁移，初始化只保留既有配置和账号口令，不执行真实报销、审批或付款写入。
|
||||
- 应用、外部依赖、运行时功能开关、公网 build 标识和前端资源文案扫描通过；备份合同刷新完整通过，无部分成功状态。
|
||||
- 公网 `/ready` 返回当前 build；生产运行时 `REIMBURSEMENT_MAX_AGE_DAYS` 生效值为默认 365，业务时区已配置。
|
||||
- 公网基础 Playwright smoke 按企微 `ready` 状态复跑通过。管理员/员工登录态 smoke 因本机未配置专用 `LIVE_SMOKE_*` 凭据未执行；未读取、复制或输出生产账号密码。
|
||||
- PC/手机报销关键交互已由发布前合成 API 浏览器回归覆盖；公网部署后的对应前端资源已命中当前 build 并通过扫描。回滚继续使用既有部署入口切换到上一已发布提交，不修改数据库结构或生产环境文件。
|
||||
在新工单中引用
屏蔽一个用户