weaver-work-cli 0.1.8 → 0.1.20

package/skills/weaver-e10-yepiaotong/references/reim-workflow.md

@@ -29,6 +29,26 @@
 
 ---
 
+## 报销共享常量（所有 reference 统一引用本节）
+
+以下常量在报销 reference 中多处出现，**统一以本节为准**，其余文件引用本节不再重复定义。
+
+| 常量 | 值 | 说明 |
+|------|-----|------|
+| 默认合同编号 | `"20260999"` | 快速路径 `template.build`/`auto-prepare` 与手工路径统一使用；CLI 0.1.19 起未传入时自动填充并产生 warning |
+| 非出差相关客户 | `"100504500000311504"` | 泛微上海；出差流程必须由用户提供具体客户 |
+| 兜底费用科目 | `"100502270000000104"` | 其他-管理费用；所有匹配策略均未命中时使用 |
+| 人民币币种 ID | `"100001050000000001"` | — |
+| 报销方式默认值 | optionValue `"7"` | 银行（个人报销） |
+| 全额红冲状态值 | `status = 8` | `comm_info.pro.status`；此类发票必须过滤，不允许报销 |
+| 相关凭证 typeCode | 17, 18, 57, 58 | 不能独立成行，必须与发票配对 |
+| directSuperior 取值 | `directSuperior.id` | ⚠️ **不是 `allSuperiors[0]`**（后者是上级链最高层） |
+| continuation 有效期 | 600 秒 | 过期后重新 prepare 即可，无需重新征询用户确认 |
+
+> **continuation 过期处理**：`prepare`/`auto-prepare` 签发的 continuation 有 600 秒有效期。中间若用户核对耗时过长导致过期（返回 `validation/continuation_expired`），**重新 `prepare` 后立即 `apply` 即可**（用户已确认过的内容无需重新征询）。不要重放旧 continuation。
+
+---
+
 ## 时间戳内联计算（零工具调用）
 
 > **所有日期 → 秒级时间戳的转换由 AI 直接计算，无需调用外部脚本。**
@@ -245,7 +265,10 @@ Step 6 (可选): invoice.reim.flow.update.prepare/apply → 用户修正
 | `date_begin` / `date_end` | 开票日期范围 | 默认使用 |
 | `create_tm_begin` / `create_tm_end` | 录入/创建日期范围 | 用户明确说"录入日期"/"创建日期"时 |
 
-**⚠️ 数据过滤：** `info.comm_info.pro.status == 8` 的发票为**全额红冲发票**，**必须过滤掉，不允许报销**
+**⚠️ 数据过滤（红冲票排除）：**
+- **快速路径**：`candidates.list` **自动过滤** `status=8` 的全额红冲发票（过滤张数在 `summary.filteredRedReversedCount` 中报告），无需手动处理。
+- **手动路径**：使用 `invoice.list` 获取发票后，**必须在进入任何后续流程前先过滤掉 `info.comm_info.pro.status == 8` 的发票**。过滤后向用户报告："已自动排除 N 张全额红冲发票"。
+- 全额红冲发票不允许报销，**两条路径都不能让红冲票进入匹配/组装环节**。
 
 关键返回字段映射见 [reim-api-reference.md](reim-api-reference.md#1-获取发票数据)。
 
@@ -294,6 +317,7 @@ Step 6 (可选): invoice.reim.flow.update.prepare/apply → 用户修正
 | 场景 | 筛选方式 |
 |------|----------|
 | 先有发票 → 筛选事前申请 | `cusCreateDateEnd` = 最晚 invoiceDate，`cusCreateDateStart` = 最早 invoiceDate - 90天 |
+| 先有发票 → **话费报销** | `cusCreateDateEnd` = 最晚 invoiceDate，`cusCreateDateStart` = 最早 invoiceDate - **1095天（3年）**，且加 `requestname="话费"` 缩小范围（见 [reim-phone-subsidy-rules.md](reim-phone-subsidy-rules.md)） |
 | 先有事前申请 → 筛选发票 | `date_begin` = 最早 createTime 秒时间戳 |
 | 并行获取 | 不做预筛选，Step 2 匹配时统一过滤 |
 
@@ -317,6 +341,27 @@ Step 6 (可选): invoice.reim.flow.update.prepare/apply → 用户修正
 ]
 ```
 
+### Step 2 匹配结果展示（推荐）
+
+匹配完成后，**建议向用户展示匹配结果**，而不是静默进入下一步。展示格式：
+
+```markdown
+发票与事前申请匹配结果：
+
+| # | 发票号码 | 金额 | 匹配到的事前申请 | 置信度 | 匹配原因 |
+|---|----------|------|------------------|--------|----------|
+| 1 | 36901189 | ¥108.20 | 交通费报销-后端开发111-2026-07-25 | ✅ 高 | 费用类型匹配、时间匹配 |
+| 2 | 36901201 | ¥380.00 | （未匹配） | — | 无匹配的事前申请 |
+
+确认后将自动进入后续填单流程。如需调整匹配关系，请告诉我。
+```
+
+- 匹配到 high 置信度的直接标记 ✅ 高
+- medium 置信度标记 ⚠️ 中（建议核实）
+- 未匹配的标记 —，说明将跳过事前申请关联
+- **只有全部都是 high 且用户已在 Step 1C 确认过 → 可以静默跳过本展示直接继续**
+- medium 或 low 出现时**必须展示并等用户确认**
+
 ---
 
 ## Step 2.5: 获取报销单工作流ID
@@ -335,8 +380,9 @@ Step 6 (可选): invoice.reim.flow.update.prepare/apply → 用户修正
 ### 发票 → 工作流匹配规则（按优先级）
 
 1. **事前申请绑定**：发票已匹配到事前申请 → 使用该事前申请对应的 workFlowId
-2. **发票费用类型匹配**：用 `expenseType` 与候选 `workFlowName` 做关键词匹配
-3. **通用兜底**：归入 workFlowName 含"日常"/"通用"/"报销"的；仍无法区分归入第一个
+2. **话费专项**：通讯/话费类发票优先匹配 `workFlowName` 含「话费补贴标准审批流程」或「话费报销」的工作流，命中后必须按 [reim-phone-subsidy-rules.md](reim-phone-subsidy-rules.md) 核算
+3. **发票费用类型匹配**：用 `expenseType` 与候选 `workFlowName` 做关键词匹配
+4. **通用兜底**：归入 workFlowName 含"日常"/"通用"/"报销"的；仍无法区分归入第一个
 
 每组独立执行 Step 3 → 3.5 → 3.6 → 4 → 5，不能省略任何字段。
 
@@ -378,7 +424,7 @@ Step 6 (可选): invoice.reim.flow.update.prepare/apply → 用户修正
 
 > **可缓存**：同一会话只需调用一次。
 
-- `allSuperiors[0].id` → "报销人上级" + "承担人直接上级"（⚠️ 必填）
+- `directSuperior.id` → "报销人上级" + "承担人直接上级"（⚠️ 必填。**注意不是 `allSuperiors[0]`** —— `allSuperiors[0]` 是上级链最高层，与直接上级不是同一人）
 - `allSuperiors` 全部 `id` 逗号拼接 → "承担人所有上级"（⚠️ 必填）
 
 ---
@@ -389,7 +435,9 @@ Step 6 (可选): invoice.reim.flow.update.prepare/apply → 用户修正
 > **费用科目匹配规则见 [reim-expense-subject-rules.md](reim-expense-subject-rules.md)**
 >
 > **⚠️ 费用类型（科目）字段必须有值。匹配不到时直接填兜底值 `"100502270000000104"`。**
+> **⚠️ 合同编号固定填 `"20260999"`**（除用户当次明确给出别的合同号）：主表 `合同号(100003720000001376)` 不能留空、不能放进 `unable_to_fill`；走快速路径 `template.build`/`auto-prepare` 时同样必须显式传 `contractNo`，否则该字段静默缺失。口径见 [reim-form-fill-rules.md](reim-form-fill-rules.md) 主表字段映射。
 > **⚠️ 出差流程相关客户规则见 Step 4.5。**
+> **⚠️ 话费补贴 / 话费报销必须遵守 [reim-phone-subsidy-rules.md](reim-phone-subsidy-rules.md)，见 Step 4.6。**
 
 核心结构概览：
 
@@ -408,7 +456,7 @@ Step 6 (可选): invoice.reim.flow.update.prepare/apply → 用户修正
 **关键约束：**
 - **发票 vs 相关凭证分类**：`invoiceTypeCode` 为 17/18/57/58 的是相关凭证，不能独立成行，必须与对应发票配对放在同一行明细中
 - 每行 `fields` 中有两个 `EinvoiceComponent` 字段：`single=false` 填**发票** `invoiceId`，`single=true` 填**配对凭证** `invoiceId`
-- `dataIndex` 从 1 递增，`subFormId` 只用 `subTables[0]` 的
+- `dataIndex` 从 1 递增，`subFormId` 用「费用明细」表的（按名称定位明细表，**不要机械取 `subTables[0]`** —— 总部费用报销的 `subTables[0]` 是「外包订单」，「费用明细」`100003690000000011` 排第 3）
 
 ---
 
@@ -425,12 +473,82 @@ Step 6 (可选): invoice.reim.flow.update.prepare/apply → 用户修正
 
 ---
 
+## Step 4.6: 话费补贴 / 话费报销必须按月度标准核算
+
+> **命中「话费补贴标准审批流程」或「话费报销」时，未齐备账单材料和岗位标准前，禁止进入 Step 5。**
+> 完整规则见 [reim-phone-subsidy-rules.md](reim-phone-subsidy-rules.md)。
+
+简要规则：
+- `workFlowName` 或事前申请名称含「话费补贴标准审批流程」「话费报销」，或用户明确说话费报销 → 先暂停
+- 必须提供本人实名制当月手机账单截图及账单构成
+- 必须确认岗位对应月度上限（350 / 200 / 100），禁止猜测岗位
+- 剔除手机设备赠送套餐、家庭宽带套餐后，实报金额 = `min(可报销账单金额, 上限)`
+- 低于标准按实际支付，超过上限按上限支付
+- 材料不齐 / 岗位未确认 / 用户拒绝 → **结束报销，禁止调用 `invoice.reim.flow.create.prepare`**
+
+---
+
+## Step 4.7: 预览展示规则 —— 字典类 ID 必须带中文名
+
+> **向用户展示单据预览、汇总、确认清单时，凡是字典/选择类 ID 值，一律渲染成 `中文名(ID)`，禁止只给裸 ID。**
+> 用户要靠中文名核对金额、科目、上级和客户；裸 ID 无法复核，属于无效展示。
+
+### 优先：直接用 CLI 已渲染好的展示字段（快速路径 / `auto-prepare` / `template.build`）
+
+`invoice.reim.template.build` 与 `invoice.reim.flow.create.auto-prepare` 的返回已包含渲染完成的展示数据。**返回里有 `preview.mainFields` / `labels` 就直接用，不要再自己调 `field.search` / `row-info` 查名。**
+
+| 返回字段 | 内容 | 怎么用 |
+| --- | --- | --- |
+| `preview.mainFields[]` | `{ fieldId, fieldName, value \| optionValue, text }` | **主表预览直接读 `text`**。人员/客户渲染成 `温明刚(6490972696771260615)`；选择类渲染成 `银行（个人报销）(optionValue=7)`；逗号列表（承担人所有上级）逐项带名 |
+| `preview.detailRows[]` | `{ dataIndex, invoiceId, invoiceNumber, amount, expenseNote, subject, currency }` | **明细表预览直接读 `subject` / `currency`**，已带中文名 |
+| `labels` | `employees` / `subjects` / `currencies` / `customers` / `selectOptions` / `customer` / `detailSubForm` / `workflow` | 需要自己拼其它展示时取字典 |
+| `labels.unresolved`、`preview.unresolvedLabels` | 未取到中文名的 ID 清单 | 非空时按下方兜底口径如实展示，并放进 `need_user_confirm` 提醒用户核对 |
+
+相关客户只给名称也能用：传 `relatedCustomerName`（不传 ID 时 CLI 会自动反查 ID；ID 与名称同时传则不额外请求，只用于渲染）。
+
+### 兜底：返回里没有上述字段时（旧版 CLI、或手工组装路径）按来源表自查
+
+| 展示项 | 中文名来源 | 兜底 |
+| --- | --- | --- |
+| 费用类型（科目） | `invoice.reim.row-info` 的 `subjectName`（与 `subjectId` 同源，**同一行数据直接取**） | 用 `reim-expense-subject-rules.md` 查找表反查；仍无则保留 `未知科目(ID)` |
+| 币种 | `invoice.reim.row-info` 的 `bz[].name` | `人民币(100001050000000001)` |
+| 申请人 / 提单人员 / 承担主体 | `invoice.reim.employee-superiors` 的 `currentEmployee.name` | — |
+| 报销人上级 / 承担人直接上级 | 同命令 `directSuperior.name` | — |
+| 承担人所有上级 | 同命令 `allSuperiors[].name`，按原顺序逗号拼接，**每个都带 ID** | — |
+| 报销方式等 Select 字段 | `invoice.reim.form.structure` 主表该字段 `options` 里 `optionValue` → `optionName` | 保留 `optionValue=7` |
+| 相关客户 | `invoice.reim.field.search` 返回项的 `name` | 见下方警告 |
+
+⚠️ **相关客户无法用 ID 反查**（实测）：`invoice.reim.field.search` 把待查的那个 ID 当 `keywords` 传，一律返回 `[]`（例如 `keywords="100504500000311504"` → 空）。必须改用**关键词模糊搜索**再按 `id` 匹配：
+
+```text
+keywords="泛微"  →  命中 {"name":"泛微上海","id":"100504500000311504"}
+```
+
+关键词取不准时按 2-3 个候选词依次试（公司字号、简称）；仍查不到就显示 `未知来源(100504500000311504)` 并放进 `need_user_confirm` 让用户核对，**禁止编造名称**。
+
+展示格式示例：
+
+```markdown
+| 项目 | 值 |
+| --- | --- |
+| 相关客户 | 泛微上海(100504500000311504) |
+| 报销人上级 / 承担人直接上级 | 温明刚(6490972696771260615) |
+| 承担人所有上级 | 熊学武(8005823778783571762), 章宏武(4270809363797382452), 周军锋(9080972482706531342), 温明刚(6490972696771260615), 韦利东(8005823776035471761) |
+| 报销方式 | 银行（个人报销）(optionValue=7) |
+| 费用科目（每行） | 日常消费(1256664958132969489) |
+```
+
+纯数值/文本字段（金额、日期、张数、费用说明）保持原样，不加 ID。
+
+---
+
 ## Step 5: 生成报销单流程
 
 通过 `invoice.reim.flow.create.prepare` → 用户确认 → `invoice.reim.flow.create.apply` 完成。
 
 > **⚠️ 禁止重复调用：同一组发票数据只能调用一次。调用成功后，修改已创建的报销单使用 Step 6 的 update。**
 > **⚠️ 出差流程拦截：相关客户未由用户提供具体信息前，禁止调用。**
+> **⚠️ 话费报销拦截：账单截图、账单构成或岗位标准未确认前，禁止调用。**
 
 ### 创建成功后
 
@@ -470,6 +588,7 @@ CLI 返回 `requestId` 和 `viewUrl`，**用结构化汇总信息展示给用户
 **需暂停询问用户的情况：**
 - 发票列表为空 → 提示"未找到未报销的发票"，结束
 - 出差/差旅流程缺少相关客户 → 见 Step 4.5
+- 话费报销缺少账单截图、账单构成或岗位标准 → 见 Step 4.6
 - 模糊搜索返回多结果 → 放入 `need_user_confirm` 让用户选择
 
 **严禁重复调用：**
@@ -491,4 +610,5 @@ CLI 返回 `requestId` 和 `viewUrl`，**用结构化汇总信息展示给用户
 - [reim-matching-rules.md](reim-matching-rules.md) - 发票与事前申请匹配逻辑
 - [reim-form-fill-rules.md](reim-form-fill-rules.md) - 表单字段填充策略与填单 JSON 组装规则
 - [reim-expense-subject-rules.md](reim-expense-subject-rules.md) - 费用科目自动匹配规则（JSON 查找表）
+- [reim-phone-subsidy-rules.md](reim-phone-subsidy-rules.md) - 话费补贴 / 话费报销月度标准与实报金额
 - [reim-examples.md](reim-examples.md) - 完整端到端示例