diff --git a/changelogs-v2-mp/2026-06/23_4290_发票申请票种修正-修改接口-小程序端.md b/changelogs-v2-mp/2026-06/23_4290_发票申请票种修正-修改接口-小程序端.md index 0c9a5f1..2f96ea1 100644 --- a/changelogs-v2-mp/2026-06/23_4290_发票申请票种修正-修改接口-小程序端.md +++ b/changelogs-v2-mp/2026-06/23_4290_发票申请票种修正-修改接口-小程序端.md @@ -6,6 +6,8 @@ > ⚠️ **破坏性变更**：`invoiceType` 删除 `ELECTRONIC`、`email` 改为始终必填 + 格式校验、专票限公司抬头 + 必填五项、删除 `mailAddress` 字段。小程序开票页与详情页均需同步改动，上线时前后端须同步发布。 +> **勘误（截至 PR #4311 收口）**：抬头字段统一 `titleName`、金额 `amount` 改 JSON number（单位元，非分/x100）、票种仅 2 值（`VAT_NORMAL`/`VAT_SPECIAL`）、专票限公司抬头、入参和出参均无 `mailAddress`。关联 Issue [#4290](https://git.1814.love:8443/wx/HL/issues/4290) [#4296](https://git.1814.love:8443/wx/HL/issues/4296) [#4310](https://git.1814.love:8443/wx/HL/issues/4310) / PR [#4292](https://git.1814.love:8443/wx/HL/pulls/4292) [#4302](https://git.1814.love:8443/wx/HL/pulls/4302) [#4311](https://git.1814.love:8443/wx/HL/pulls/4311)。 + --- ## 接口背景 @@ -86,7 +88,7 @@ | `bankAccount` | string | `invoiceType=VAT_SPECIAL` 时必填 | 银行账号 | | `registAddress` | string | `invoiceType=VAT_SPECIAL` 时必填 | 注册地址 | | `registPhone` | string | `invoiceType=VAT_SPECIAL` 时必填 | 注册电话 | -| `amount` | integer | 始终必填 | 开票金额，单位**分**，须 > 0 且不超过订单总金额 | +| `amount` | number | 始终必填 | 开票金额，JSON number，单位**元**（如 `986.00`），须 > 0 且不超过订单总金额 | | `email` | string | 始终必填 | 收件邮箱，须通过邮箱格式校验 | | `remark` | string | 选填 | 备注 | @@ -167,7 +169,7 @@ Content-Type: application/json "titleType": "PERSONAL", "titleName": "张三", "taxNo": null, - "amount": 98600, + "amount": 986.00, "email": "zhangsan@qq.com", "remark": "旅游报销" } @@ -200,7 +202,7 @@ Content-Type: application/json "bankAccount": "1234567890123456", "registAddress": "上海市浦东新区XX路XX号", "registPhone": "021-88888888", - "amount": 298000, + "amount": 2980.00, "email": "finance@company.com" } ``` @@ -228,7 +230,7 @@ Content-Type: application/json "titleType": "PERSONAL", "titleName": "李四", "taxNo": null, - "amount": 50000, + "amount": 500.00, "email": "lisi@example.com" } ``` @@ -256,7 +258,7 @@ Content-Type: application/json - 管理后台代客申请走 admin 专属接口 **特殊边界** -- 金额单位：`amount` 为整数**分**，前端显示元时需在提交前 ×100 +- 金额单位：`amount` 为 JSON number，单位**元**（如 `986.00`），前端输入框以元为单位直接提交，无需 x100 - 一单一票：同一订单至多一张有效发票 - 专票抬头联动：选专票后，抬头类型需强制为单位，个人选项需禁用或隐藏 - 详情回显：`mailAddress` 字段已不存在，前端不应渲染邮寄地址块 @@ -319,7 +321,7 @@ Content-Type: application/json 2. 重开接口（reissue）入参字段矩阵与 apply 完全相同，改动同步适用 3. 专票五项（taxNo + 开户行 + 账号 + 注册地址 + 注册电话）在专票场景下全必填，缺一返回 581515 4. 详情页 `mailAddress` 字段已消失，老版本小程序读到 undefined 需做好空值守卫（不报错） -5. `amount` 单位为分，小程序展示/输入框以元为单位时，提交前须 ×100 +5. `amount` 为 JSON number，单位**元**（如 `986.00`），小程序输入框直接传元值，无需 x100 --- diff --git a/changelogs-v2/2026-06/23_4258_发票详情接口-新增接口-管理后台.md b/changelogs-v2/2026-06/23_4258_发票详情接口-新增接口-管理后台.md index 3b52de2..05e4a12 100644 --- a/changelogs-v2/2026-06/23_4258_发票详情接口-新增接口-管理后台.md +++ b/changelogs-v2/2026-06/23_4258_发票详情接口-新增接口-管理后台.md @@ -10,6 +10,7 @@ > 1. `invoiceType` 枚举已删除 `ELECTRONIC`（电子发票），只保留 `VAT_NORMAL`（增值税普通发票）和 `VAT_SPECIAL`（增值税专用发票） > 2. 出参已删除 `mailAddress` 字段（无纸质邮寄，全电子交付） > 3. `email` 字段始终有值（全电子交付），不再是"电子发票为 null" +> 4. `amount` 字段改为 JSON number（单位**元**，如 `986.00`），原「字符串/单位分」均已作废；边界示例专票 `email` 由 null 改为始终有值（全电子交付）。关联 PR [#4311](https://git.1814.love:8443/wx/HL/pulls/4311)，Issue [#4290](https://git.1814.love:8443/wx/HL/issues/4290) [#4310](https://git.1814.love:8443/wx/HL/issues/4310)。 ## 接口背景 @@ -77,7 +78,7 @@ | `bankAccount` | string / null | 银行账号，**仅专票**有值，其余 null | | `registAddress` | string / null | 注册地址，**仅专票**有值，其余 null | | `registPhone` | string / null | 注册电话，**仅专票**有值，其余 null | -| `amount` | string | 开票金额，单位**分**，字符串防精度丢失，如 `"98600"` | +| `amount` | number | 开票金额，JSON number，单位**元**（如 `986.00`） | | `email` | string | 收件邮箱（始终有值，全电子交付） | | `applyReason` | string / null | 备注（申请原因） | @@ -185,7 +186,7 @@ Authorization: Bearer "bankAccount": null, "registAddress": null, "registPhone": null, - "amount": "98600", + "amount": 986.00, "email": "finance@hulalv.com", "applyReason": "报销使用", "status": "REQUESTED", @@ -235,8 +236,8 @@ Authorization: Bearer "bankAccount": "6222 0000 0000 0001", "registAddress": "上海市浦东新区XX路XX号", "registPhone": "021-12345678", - "amount": "150000", - "email": null, + "amount": 1500.00, + "email": "finance@company.com", "applyReason": null, "status": "ISSUED", "statusText": "已开票（待推送）", @@ -292,14 +293,14 @@ Authorization: Bearer - 专票五项字段（`taxNo` / `bankName` / `bankAccount` / `registAddress` / `registPhone`）：taxNo 普票公司抬头也需填，专票四项仅 `invoiceType=VAT_SPECIAL` 时有值，前端按 invoiceType 决定是否展示 - 开票痕迹字段（`invoiceNo` / `fileUrl` / `pdfName` / `pdfSize` / `issuedBy` / `issuedAt`）：状态为 `ISSUED` 或 `PUSHED` 时有值，`REQUESTED` 和 `VOIDED` 时为 null - 推送痕迹字段（`pushedAt` / `pushedChannels`）：仅 `PUSHED` 时有值 -- `amount` 单位为**分**，前端展示时除以 100 转为元 +- `amount` 为 JSON number，单位**元**（如 `986.00`），前端直接渲染，无需除以 100 --- ## 注意事项 1. `id` / `orderId` 为 Long 雪花 ID，前端必须以**字符串**接收，不可用 JS number 类型（会丢失精度） -2. `amount` 单位为**分**，字符串格式，展示时除以 100 转为元 +2. `amount` 为 JSON number，单位**元**（如 `986.00`），前端直接渲染，无需除以 100 3. `pdfSize` 单位为**字节**，字符串格式，展示时自行换算为 KB / MB 4. `pushedChannels` 未推送时为 null，不是空数组 `[]`，前端判断时注意区分 diff --git a/changelogs-v2/2026-06/23_4265_发票列表page结构调整-修改接口-管理后台.md b/changelogs-v2/2026-06/23_4265_发票列表page结构调整-修改接口-管理后台.md index 5f07794..ccb0792 100644 --- a/changelogs-v2/2026-06/23_4265_发票列表page结构调整-修改接口-管理后台.md +++ b/changelogs-v2/2026-06/23_4265_发票列表page结构调整-修改接口-管理后台.md @@ -9,6 +9,8 @@ --- > **勘误（2026-06-23，#4292 #4302）**：`invoiceType` 枚举已删除 `ELECTRONIC`（电子发票），当前系统只有 `VAT_NORMAL`（增值税普通发票）和 `VAT_SPECIAL`（增值税专用发票）两种类型。列表行 `invoiceType` 字段不会出现 `ELECTRONIC` 值，前端发票类型筛选下拉也只保留普票/专票两项。 +> +> **同步修正（截至 PR [#4311](https://git.1814.love:8443/wx/HL/pulls/4311) 收口）**：records 行 `amount` 及 stats `amount` 均改为 JSON number（单位**元**，如 `986.00`），原「字符串/单位分」已全部作废。关联 Issue [#4290](https://git.1814.love:8443/wx/HL/issues/4290) [#4310](https://git.1814.love:8443/wx/HL/issues/4310)。 ## 接口背景 @@ -89,7 +91,7 @@ | `invoiceType` | string / null | 发票类型；NONE tab 行为 null | | `invoiceTypeText` | string / null | 发票类型中文名；NONE tab 行为 null | | `titleName` | string / null | 发票抬头；NONE tab 行为 null | -| `amount` | string / null | 开票金额（分），字符串；NONE tab 行为 null | +| `amount` | number / null | 开票金额，JSON number，单位**元**（如 `986.00`）；NONE tab 行为 null | | `status` | string | 发票状态；NONE tab 行固定为 `"NONE"` | | `statusText` | string | 发票状态中文名；NONE tab 行固定为 `"未申请"` | | `requestedAt` | string / null | 申请时间；NONE tab 行为 null | @@ -119,7 +121,7 @@ | `code` | string | 统计维度枚举值 | | `name` | string | 统计维度中文名（直接渲染，无需前端自行拼接） | | `count` | integer | 该维度数量 | -| `amount` | string | 该维度金额，单位分，字符串，保留两位小数，如 `"98600.00"` | +| `amount` | number | 该维度金额，JSON number，单位**元**（如 `986.00`） | --- ## 枚举 / 数据字典 @@ -200,7 +202,7 @@ Authorization: Bearer "invoiceType": "VAT_NORMAL", "invoiceTypeText": "增值税普通发票", "titleName": "呼籁科技有限公司", - "amount": "98600", + "amount": 986.00, "status": "REQUESTED", "statusText": "待开票", "requestedAt": "2026-06-20T14:30:00", @@ -222,10 +224,10 @@ Authorization: Bearer { "code": "ALL", "name": "全部", "count": 12 } ], "stats": [ - { "code": "REQUESTED", "name": "待开票", "count": 3, "amount": "1000.00" }, - { "code": "ISSUED", "name": "已开票·待推送", "count": 2, "amount": "98600.00" }, - { "code": "PUSHED", "name": "已推送", "count": 2, "amount": "50000.00" }, - { "code": "CURRENT_MONTH_ISSUED", "name": "本月已开票", "count": 4, "amount": "148600.00" } + { "code": "REQUESTED", "name": "待开票", "count": 3, "amount": 1000.00 }, + { "code": "ISSUED", "name": "已开票·待推送", "count": 2, "amount": 98600.00 }, + { "code": "PUSHED", "name": "已推送", "count": 2, "amount": 50000.00 }, + { "code": "CURRENT_MONTH_ISSUED", "name": "本月已开票", "count": 4, "amount": 148600.00 } ] } } @@ -278,10 +280,10 @@ Authorization: Bearer { "code": "ALL", "name": "全部", "count": 12 } ], "stats": [ - { "code": "REQUESTED", "name": "待开票", "count": 3, "amount": "1000.00" }, - { "code": "ISSUED", "name": "已开票·待推送", "count": 2, "amount": "98600.00" }, - { "code": "PUSHED", "name": "已推送", "count": 2, "amount": "50000.00" }, - { "code": "CURRENT_MONTH_ISSUED", "name": "本月已开票", "count": 4, "amount": "148600.00" } + { "code": "REQUESTED", "name": "待开票", "count": 3, "amount": 1000.00 }, + { "code": "ISSUED", "name": "已开票·待推送", "count": 2, "amount": 98600.00 }, + { "code": "PUSHED", "name": "已推送", "count": 2, "amount": 50000.00 }, + { "code": "CURRENT_MONTH_ISSUED", "name": "本月已开票", "count": 4, "amount": 148600.00 } ] } } @@ -318,7 +320,7 @@ Authorization: Bearer **特殊边界** - NONE tab 行是订单行，不是发票行：`id` 为 null，发票字段均为 null，`status` 固定为字符串 `"NONE"`，前端需按 status 判断是否展示发票操作按钮 - ALL tab 混合 NONE 行和发票行：遍历 records 时需按 `status === "NONE"` 区分行类型 -- `amount` 单位为分，字符串格式，前端展示时除以 100 转为元 +- `amount` 为 JSON number，单位**元**（如 `986.00`），前端直接渲染，无需除以 100 --- @@ -374,10 +376,10 @@ Authorization: Bearer ```json { "stats": [ - { "code": "REQUESTED", "name": "待开票", "count": 3, "amount": "1000.00" }, - { "code": "ISSUED", "name": "已开票·待推送", "count": 2, "amount": "98600.00" }, - { "code": "PUSHED", "name": "已推送", "count": 2, "amount": "50000.00" }, - { "code": "CURRENT_MONTH_ISSUED", "name": "本月已开票", "count": 4, "amount": "148600.00" } + { "code": "REQUESTED", "name": "待开票", "count": 3, "amount": 1000.00 }, + { "code": "ISSUED", "name": "已开票·待推送", "count": 2, "amount": 98600.00 }, + { "code": "PUSHED", "name": "已推送", "count": 2, "amount": 50000.00 }, + { "code": "CURRENT_MONTH_ISSUED", "name": "本月已开票", "count": 4, "amount": 148600.00 } ] } ``` @@ -430,7 +432,7 @@ Authorization: Bearer 1. `tabCounts` 和 `stats` **均已变为数组**，旧的扁平对象键名已全部废弃，前端读取方式必须更新 2. NONE tab 行中 `status` 是字符串 `"NONE"`，而不是 null，前端用 `status === "NONE"` 判断行类型 -3. `stats` 中的 `amount` 单位为**分**，字符串格式，保留两位小数，前端展示时除以 100 转为元 +3. `stats` 中的 `amount` 为 JSON number，单位**元**（如 `986.00`），前端直接渲染，无需除以 100 4. `ISSUED` 在 tabCounts 和 stats 中 `name` 不同，直接渲染 `name` 字段即可，不要自行拼接 5. `adultCount` / `childCount` / `youngChildCount` 为整数，0 的维度建议展示时省略 diff --git a/changelogs-v2/2026-06/23_4290_发票申请入参票种修正-修改接口-管理后台.md b/changelogs-v2/2026-06/23_4290_发票申请入参票种修正-修改接口-管理后台.md index 16de519..33d05cc 100644 --- a/changelogs-v2/2026-06/23_4290_发票申请入参票种修正-修改接口-管理后台.md +++ b/changelogs-v2/2026-06/23_4290_发票申请入参票种修正-修改接口-管理后台.md @@ -6,6 +6,10 @@ > ⚠️ **破坏性变更**：`invoiceType` 删除 `ELECTRONIC`、`email` 改为始终必填 + 格式校验、新增 `taxNo`/银行/注册信息专票五项校验、删除 `mailAddress` 字段、专票限 `COMPANY` 抬头。前端申请表单需同步改动，上线时前后端须同步发布。 +> **勘误（截至 PR #4311 收口）**：抬头字段统一 `titleName`、金额 `amount` 改 JSON number（单位元，非分/×100）、票种仅 2 值（`VAT_NORMAL`/`VAT_SPECIAL`）、专票限公司抬头、入参和出参均无 `mailAddress`。关联 Issue [#4290](https://git.1814.love:8443/wx/HL/issues/4290) [#4296](https://git.1814.love:8443/wx/HL/issues/4296) [#4310](https://git.1814.love:8443/wx/HL/issues/4310) / PR [#4292](https://git.1814.love:8443/wx/HL/pulls/4292) [#4302](https://git.1814.love:8443/wx/HL/pulls/4302) [#4311](https://git.1814.love:8443/wx/HL/pulls/4311)。 + +> **勘误（截至 PR #4311 收口）**：抬头字段统一 `titleName`、金额 `amount` 改 JSON number（单位元，非分/x100）、票种仅 2 值（`VAT_NORMAL`/`VAT_SPECIAL`）、专票限公司抬头、入参和出参均无 `mailAddress`。关联 Issue [#4290](https://git.1814.love:8443/wx/HL/issues/4290) [#4296](https://git.1814.love:8443/wx/HL/issues/4296) [#4310](https://git.1814.love:8443/wx/HL/issues/4310) / PR [#4292](https://git.1814.love:8443/wx/HL/pulls/4292) [#4302](https://git.1814.love:8443/wx/HL/pulls/4302) [#4311](https://git.1814.love:8443/wx/HL/pulls/4311)。 + --- ## 接口背景 @@ -65,7 +69,7 @@ | `bankAccount` | string | `invoiceType=VAT_SPECIAL` 时必填 | 银行账号 | | `registAddress` | string | `invoiceType=VAT_SPECIAL` 时必填 | 注册地址 | | `registPhone` | string | `invoiceType=VAT_SPECIAL` 时必填 | 注册电话 | -| `amount` | integer | 始终必填 | 开票金额，单位**分**，须 > 0 且 ≤ 订单总金额 | +| `amount` | number | 始终必填 | 开票金额，JSON number，单位**元**（如 `986.00`），须 > 0 且 ≤ 订单总金额 | | `email` | string | 始终必填 | 收件邮箱，全电子交付，须通过邮箱格式校验 | | `remark` | string | 选填 | 申请备注 | | `applyReason` | string | 选填 | 申请原因（与 remark 二选一或并用） | @@ -139,7 +143,7 @@ Content-Type: application/json "titleType": "PERSONAL", "titleName": "李四", "taxNo": null, - "amount": 98600, + "amount": 986.00, "email": "lisi@example.com", "remark": "报销使用" } @@ -172,7 +176,7 @@ Content-Type: application/json "bankAccount": "6222000000000001", "registAddress": "上海市浦东新区XX路XX号", "registPhone": "021-12345678", - "amount": 150000, + "amount": 1500.00, "email": "finance@company.com", "remark": null } @@ -201,7 +205,7 @@ Content-Type: application/json "titleType": "PERSONAL", "titleName": "张三", "taxNo": null, - "amount": 50000, + "amount": 500.00, "email": "zhangsan@example.com" } ``` @@ -230,7 +234,7 @@ Content-Type: application/json **特殊边界** - 一单一票：同一订单只允许一张有效发票（REQUESTED / ISSUED / PUSHED 状态），若已有则返回 581511，须先作废旧发票再申请 - 订单状态：仅 `COMPLETED`（已完成）状态订单可申请，其他状态返回 581510 -- 金额单位：`amount` 为整数**分**（不是元），前端输入元时需在提交前 ×100 +- 金额单位：`amount` 为 JSON number，单位**元**（如 `986.00`），>0，≤ 订单总金额；前端输入框以元为单位直接提交，无需 ×100 --- @@ -288,7 +292,7 @@ Content-Type: application/json 1. `ELECTRONIC` 枚举值已删除，前端下拉不可出现此选项；老订单历史数据如有该枚举值，出参展示时可显示「未知类型」或联系后端处理 2. `email` 无论票种均必填，前端不可根据票种做条件隐藏 3. 专票表单区块（税号 + 开户行 + 账号 + 注册地址 + 注册电话）共 5 个字段，在选专票时全部必填，不可缺任何一项 -4. `amount` 单位为**分**，前端展示/输入框单位通常为元，提交前须乘以 100 +4. `amount` 为 JSON number，单位**元**（如 `986.00`），前端输入框直接传元值，无需 ×100；后端已按元存储和校验 ---