wx/hl-api-changelog

派生 0

文件

T

Mimingguang 41160bbfad

changelog-filename-gate / validate (push) Failing after 3s

详情

docs(changelog): #7411 frontmatter 回写 not_required

2026-09-10 15:32:32 +08:00

27 KiB

原始文件 永久链接 Blame 文件历史

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	7411	团期核单共享成本三端点补判权：读走 group-batch:finance:view、写走 group-batch:finance:advance（此前零判权）	admin	wx(GIT)	修改接口	deployed	not_required	not_required	mmg				not_required 2026-09-10 mmg: 三端点请求/响应结构零改动,仅补判权(读 finance:view/写 finance:advance,不持码 589507 HTTP200)。实证两点:①前端惯例从不按 group-batch 权限码显隐(orderV2Batch.js:59 注释 589507 由拦截器统一弹;同码 groupBatchFinance.js 财务总览/预支端点亦可见即可点+589507 兜底),不新增显隐;②结算共享成本三端点(settlement/cost、settlement/summary)前端根本无封装/无消费方(grep 仅命中 groupBatchFinance.js 注释),纯后端收紧,无既有调用方会撞 589507。589507 由 request 拦截器透后端 message 自动弹出。后端建议的按码隐藏 UI 与本项目「可见即可点」惯例冲突,且三端点暂无前端入口,不接线。	2026-09-10	dev-v3

团期模块：核单共享成本三端点补判权（此前零判权，含一个写端点）

服务: hl-order-service-v3 PR: #7447 Issue: #7411 日期: 2026-09-10 影响范围: 管理后台团期看板「结算」Tab 下的成本录入 / 成本明细 / D2 汇总三个端点（含一个写端点）

⚠️ 关键变化

三个端点的请求参数与响应结构均完全不变，网关路由零改动，本次只做一件事：给 GroupBatchSettlementController 三个此前零判权的端点补上平台权限码校验。

POST /v3/admin/order/group-batch/{groupBatchId}/settlement/cost（录入团期共享成本，写端点）现在要求当前角色持权限码 group-batch:finance:advance（GroupBatchPermissionGuard.java:64，常量 PERMISSION_FINANCE_ADVANCE）。修复前任何能登录后台的账号（不区分角色）都能给任意团期写入一笔共享成本，直接抬高该团总成本与人均分摊。
GET /v3/admin/order/group-batch/{groupBatchId}/settlement/cost（成本明细列表）与 GET /v3/admin/order/group-batch/{groupBatchId}/settlement/summary（核单 D2 汇总）现在要求当前角色持权限码 group-batch:finance:view（GroupBatchPermissionGuard.java:61，常量 PERMISSION_FINANCE_VIEW）。修复前任何账号都能越权读到整团毛利（subOrderTotalProfit）、团期预支（groupAdvanceApproved/groupAdvancePending）等敏感经营数据。
权限码与同包 GroupBatchFinanceController（团期财务总览等既有端点）口径一致，均为「金额数据用 finance:view、资金写动作用 finance:advance」；不是 group-batch:view（团期详情的一般查看权），持 group-batch:view 但未持 group-batch:finance:view 的账号调这三个端点同样会被拒。
不持有对应权限码 → 业务错误码 589507（GROUP_BATCH_PERMISSION_DENIED，message：「无操作权限（非团期管理员 / 非本定制师名下）」，HTTP 恒 200，data=null）；判权在 Controller 方法体第一行执行，先于任何业务逻辑与 Service 调用——被拒时零副作用，写端点不会落库、幂等键不会被占用（见「八、测试环境已验证」单测证据）。
判权是纯角色判定，没有「本人 / 本定制师名下」之类的归属兜底（与 #7316 全团需求汇总同一套 GroupBatchPermissionGuard.require()），adminId 或角色（X-Admin-Role）缺失同样 fail-closed 直接拒绝 589507，不发 Feign；判权服务（user-service）Feign 异常 / 非成功响应 / 空值同样一律按无权限处理。

前端应如何处理（详见「四、契约约束与正确调用方式」）：

「结算」Tab 的成本录入表单与成本明细/汇总卡片建议按权限码 隐藏对应按钮/区块（角色不持 group-batch:finance:view 就不请求这三个端点，不持 group-batch:finance:advance 就隐藏「录入成本」按钮），而不是等后端 589507 才提示——判权本来就先于业务逻辑，前端提前隐藏能省一次无意义请求。
兜底仍必须做：直接调用/绕过前端隐藏的场景，后端会返回 589507，前端需按通用错误码展示（HTTP 200，判 code，不是判 HTTP 状态）。
若某角色此前能用这三个端点、上线后被拒，处置办法是去 hl-user-service 给该角色补 group-batch:finance:view / group-batch:finance:advance 权限码种子，不是后端代码问题（与 #7316 定案 10 同一处置口径）。

一、背景

#7316 给团期看板「全团需求汇总」只读端点补 group-batch:view 判权时，顺带发现隔壁的 GroupBatchSettlementController 三个端点一个判权都没有，其中 POST .../settlement/cost 还是写端点，写入的金额直接进团期总成本与人均分摊公式。#7411 专治这个缺口：给三个端点分别接上 GroupBatchPermissionGuard，读侧复用既有的 group-batch:finance:view（GroupBatchFinanceController 同码），写侧复用既有的 group-batch:finance:advance（此前唯一调用点是团期预支单 GroupBatchActionController.java:142，语义是「资金写动作」而非「预支单专用」，故复用而非新增权限码）。本次不新增权限码、不动 hl-user-service 的 Flyway 或角色授权种子。

已查证的排除项：三个路径经全仓 grep 零 Feign 客户端、零服务间调用方，只出现在 GroupBatchSettlementController 自身与前端契约文档；source=FLEET_CALLBACK 的成本回填走的也是同一个 /admin/ 端点（人工触发或运营后台调用，不是服务间直连），因此加判权不会打断任何内部服务链路。

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	录入团期共享成本	POST	`/v3/admin/order/group-batch/{groupBatchId}/settlement/cost`	行为修改	新增权限码 `group-batch:finance:advance` 校验，请求/响应结构不变
2	团期共享成本明细列表	GET	`/v3/admin/order/group-batch/{groupBatchId}/settlement/cost`	行为修改	新增权限码 `group-batch:finance:view` 校验，响应结构不变
3	团期核单 D2 汇总	GET	`/v3/admin/order/group-batch/{groupBatchId}/settlement/summary`	行为修改	新增权限码 `group-batch:finance:view` 校验，响应结构不变（与 `#7316` 落地时字段一致）

三、接口详情

1. 录入团期共享成本 `POST /v3/admin/order/group-batch/{groupBatchId}/settlement/cost`

VO: RecordBatchCostReqVO → Result<Long>

使用场景

团期看板「结算」Tab，团期管理员 / 财务录入整团共享成本（大巴、领队、摄影师等）。调用前端必须持有权限码 group-batch:finance:advance，否则拿到 589507，且成本行不会落库。

入参字段表

字段	位置	类型	必填	约束	说明
`groupBatchId`	Path	Long	是	团期主键（雪花 ID）	团期 ID
`costType`	Body	String	是	枚举 `BUS`/`LEADER`/`PHOTOGRAPHER`/`OTHER`，非法值 589502（`SETTLEMENT_COST_TYPE_INVALID`）	成本类型
`amount`	Body	BigDecimal	是	`>= 0.00`	成本金额
`source`	Body	String	否	`MANUAL`/`FLEET_CALLBACK`，缺省按 `MANUAL` 处理	成本来源
`sourceRefNo`	Body	String	否	`FLEET_CALLBACK` 时应传，作幂等键（同 `groupBatchId`+`costType`+`sourceRefNo` 三元组命中即直接返回已有 ID，不重复插入）	来源单据号
`remark`	Body	String	否	≤255 字符	备注

（字段与约束取自 RecordBatchCostReqVO.java:18-36、GroupBatchSettlementService.addCost javadoc :67-88；权限校验行为本次新增，其余入参约束均为既有行为，未改动。）

出参字段表 `Result<Long>`

字段	类型	说明
`data`	Long（前端应按 String 处理避免精度丢失）	新建成本明细行 `batchSettlementId`；幂等命中时返回已存在记录的 ID

请求示例

POST /v3/admin/order/group-batch/10/settlement/cost
Authorization: Bearer <持 group-batch:finance:advance 的管理端 token>

{ "costType": "BUS", "amount": "1200.00", "source": "MANUAL", "remark": "大巴费用" }

（示例取自单测 GroupBatchSettlementControllerPermissionTest#recordCost_hasFinanceAdvancePermission_delegatesToService，非真实网关调用。）

响应示例

{ "code": 200, "message": "成功", "success": true, "data": "9001" }

空数据 / 降级响应

无空数据场景（写操作，成功即返回新行 ID 或幂等命中的既有 ID）。

错误响应

{ "code": 589507, "message": "无操作权限（非团期管理员 / 非本定制师名下）", "success": false, "data": null }

{ "code": 589500, "message": "团期不存在", "success": false, "data": null }

{ "code": 589501, "message": "团期状态不允许当前操作", "success": false, "data": null }

（589501 是既有行为，非本次改动：只有团期处于 REVIEWING 状态才允许录入共享成本，GroupBatchSettlementService.java:97-101；本次仅新增 589507 分支，且判权先于该状态守卫执行。589502=SETTLEMENT_COST_TYPE_INVALID，costType 非枚举白名单值时触发，同样是既有行为。）

业务边界

权限校验在 Controller 方法体第一行执行（GroupBatchSettlementController.recordCost 先调 permissionGuard.require(...) 再调 Service），先于成本类型校验、状态守卫、幂等查重与落库，满足 CODE_RULES §9「事务内禁同步 Feign」。
判权被拒时零副作用：不查库、不落库、不占用 FLEET_CALLBACK 幂等键（单测 recordCost_missingFinanceAdvancePermission_throwsDeniedAndSkipsService 用 verifyNoInteractions(groupBatchSettlementService) 钉死）。
判权用的权限码是精确值 group-batch:finance:advance，不是「group-batch:view 或 finance:view 二选一放行」——毛利/预支类金额数据不能靠一般查看权带过（GroupBatchPermissionGuard.java:56-64 javadoc）。
此前唯一使用 group-batch:finance:advance 的端点是团期预支单发起（GroupBatchActionController.java:142），本次为记团期成本复用同一码，未新增权限码、未动 hl-user-service Flyway。

2. 团期共享成本明细列表 `GET /v3/admin/order/group-batch/{groupBatchId}/settlement/cost`

VO: 无请求体 → Result<List<BatchCostRespVO>>

使用场景

团期看板「结算」Tab，查看整团已录入的共享成本逐笔明细（按 create_time 升序）。调用前端必须持有权限码 group-batch:finance:view，否则拿到 589507。

入参字段表

字段	位置	类型	必填	约束	说明
`groupBatchId`	Path	Long	是	团期主键（雪花 ID）	团期 ID

无 Body、无 Query 参数。

出参字段表 `Result<List<BatchCostRespVO>>`

字段	类型	说明
`data[].id`	String（Long ToString）	成本明细 ID
`data[].costType`	String	成本类型（`BUS`/`LEADER`/`PHOTOGRAPHER`/`OTHER`）
`data[].costTypeDesc`	String	成本类型展示标签（如「整团大巴」）
`data[].amount`	String（BigDecimal ToString）	成本金额
`data[].source`	String	成本来源（`MANUAL`/`FLEET_CALLBACK`）
`data[].sourceRefNo`	String	来源单据号
`data[].remark`	String	备注
`data[].createTime`	LocalDateTime	录入时间

（字段取自 BatchCostRespVO.java:17-44，响应结构本次零改动。）

请求示例

GET /v3/admin/order/group-batch/10/settlement/cost
Authorization: Bearer <持 group-batch:finance:view 的管理端 token>

响应示例

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": [
    { "id": "8001", "costType": "LEADER", "costTypeDesc": "领队费用", "amount": "800.00",
      "source": "MANUAL", "sourceRefNo": null, "remark": null, "createTime": "2026-09-10T10:00:00" }
  ]
}

（结构取自单测 GroupBatchSettlementControllerPermissionTest#listCost_hasFinanceViewPermission_delegatesToService 夹具，非真实网关调用。）

空数据 / 降级响应

团期尚无录入的共享成本时，data 为空数组，返回 200（GroupBatchSettlementService.listByGroupBatchId 对空结果直接返回空 List，不抛错）。

错误响应

{ "code": 589507, "message": "无操作权限（非团期管理员 / 非本定制师名下）", "success": false, "data": null }

业务边界

权限校验在 Controller 方法体第一行执行，先于 Service 调用；被拒时不发起任何查询（单测 verifyNoInteractions 覆盖）。
⚠️ 已发现且如实记录的既有行为（非本次改动，本次未处理）：GroupBatchSettlementService.listByGroupBatchId（GroupBatchSettlementService.java:140-148）不调用 requireById，即不校验 groupBatchId 对应的团期是否存在——传入一个不存在的 groupBatchId 不会得到 589500，只会得到空数组。这与同一 Controller 内 recordCost/summary 均先 requireById 的行为不一致，是本次代码复核顺带发现的既有缺口，未在 #7411 范围内修复，前端不应依赖「团期不存在时本端点会报错」这一假设。

3. 团期核单 D2 汇总 `GET /v3/admin/order/group-batch/{groupBatchId}/settlement/summary`

VO: 无请求体 → GroupBatchSettlementSummaryRespVO

使用场景

团期看板「结算」Tab，查看整团核单进度（已核单户数 / 在团户数）与成本、毛利、共享成本、预支汇总。调用前端必须持有权限码 group-batch:finance:view，否则拿到 589507。

入参字段表

字段	位置	类型	必填	约束	说明
`groupBatchId`	Path	Long	是	团期主键（雪花 ID）	团期 ID

无 Body、无 Query 参数。

出参字段表 `Result<GroupBatchSettlementSummaryRespVO>`

字段	类型	说明
`data.settledOrderCount`	int	已核单子订单数
`data.totalActiveOrderCount`	int	在团子订单总数（仅排除 `CANCELLED`）
`data.subOrderTotalActualCost`	String（BigDecimal ToString）	子订单实际成本合计
`data.subOrderTotalProfit`	String（BigDecimal ToString）	子订单毛利合计——本次新增判权重点保护的字段之一
`data.sharedCostTotal`	String（BigDecimal ToString）	团期共享成本合计
`data.sharedCostByType`	Array<SharedCostByTypeVO>	团期共享成本按类型明细
`data.sharedCostByType[].costType`	String	成本类型
`data.sharedCostByType[].costTypeDesc`	String	成本类型展示标签
`data.sharedCostByType[].total`	String（BigDecimal ToString）	该类型成本合计
`data.groupAdvanceApproved`	String（BigDecimal ToString）	整团已拨付预支——本次新增判权重点保护的字段之一
`data.groupAdvancePending`	String（BigDecimal ToString）	整团待审批预支
`data.grandTotalCost`	String（BigDecimal ToString）	团期总成本
`data.actualTravelerCount`	int	实际出行人数
`data.perPersonSharedCost`	String（BigDecimal ToString）	人均共享成本

（字段取自 GroupBatchSettlementSummaryRespVO.java:20-91，与 #7316 落地时的字段结构完全一致，本次零改动，只是新增了权限门槛。）

请求示例

GET /v3/admin/order/group-batch/10/settlement/summary
Authorization: Bearer <持 group-batch:finance:view 的管理端 token>

响应示例

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "settledOrderCount": 3,
    "totalActiveOrderCount": 4,
    "subOrderTotalActualCost": "30000.00",
    "subOrderTotalProfit": null,
    "sharedCostTotal": "2000.00",
    "sharedCostByType": [],
    "groupAdvanceApproved": null,
    "groupAdvancePending": null,
    "grandTotalCost": "32000.00",
    "actualTravelerCount": 15,
    "perPersonSharedCost": "133.33"
  }
}

（结构取自单测 GroupBatchSettlementControllerPermissionTest#summary_hasFinanceViewPermission_delegatesToService 夹具，非真实网关调用；完整字段的真实网关取值见 #7316 changelog 第八节。）

空数据 / 降级响应

同 #7316 落地时行为，本次未改动：团期无在团子订单时各计数/金额字段为 0，共享成本合计独立计算不受影响，perPersonSharedCost 出行人数为 0 时为 null。

错误响应

{ "code": 589507, "message": "无操作权限（非团期管理员 / 非本定制师名下）", "success": false, "data": null }

{ "code": 589500, "message": "团期不存在", "success": false, "data": null }

业务边界

权限校验在 Controller 方法体第一行执行，先于 groupBatchService.requireById 与汇总计算；被拒时不做任何汇总运算（单测 verifyNoInteractions 覆盖）。
判权用的权限码与「## 2. 成本明细列表」同码 group-batch:finance:view，避免出现「明细看不到、汇总能看到」的旁路（GroupBatchSettlementController.java:93-98 javadoc）。

四、契约约束与正确调用方式

端点	场景	结果
`POST .../settlement/cost`	✅ 持 `group-batch:finance:advance`	200，成功落库
`POST .../settlement/cost`	❌ 不持 `group-batch:finance:advance`	589507，零落库
`GET .../settlement/cost`	✅ 持 `group-batch:finance:view`	200，返回明细
`GET .../settlement/cost`	❌ 不持 `group-batch:finance:view`	589507
`GET .../settlement/summary`	✅ 持 `group-batch:finance:view`	200，返回汇总
`GET .../settlement/summary`	❌ 不持 `group-batch:finance:view`	589507
三端点	❌ 未经网关鉴权（`X-Admin-Id`/角色缺失）	589507（fail-closed，不发 Feign 判权）
三端点	❌ 仅持 `group-batch:view`（团期一般查看权），未持 `finance:view`/`finance:advance`	589507——这是本次最容易被前端漏判的场景，「能看团期详情」≠「能看/改团期财务」

三个端点均无请求体结构变化，前端不需要调整已有的请求/响应处理代码，只需在调用前补权限判断，或对 589507 做通用错误展示。
若某角色此前能用这三个端点、上线后被拒，处置办法是去 hl-user-service 给该角色补对应权限码种子，接口本身不提供角色开关。

切换状态时的必要动作

无状态机切换，本次纯判权补齐，不涉及任何状态字段的写入方式变化。

五、数据库行为

POST .../settlement/cost 写 order_batch_settlement 表（GroupBatchSettlementDO，@TableName("order_batch_settlement")），本次判权改动不改变其写入逻辑、幂等键（groupBatchId+costType+sourceRefNo 三元组）或状态守卫（仅 REVIEWING 状态可写）；判权被拒时该表零写入。
两个 GET 端点均只读，无写操作。
权限判定读 hl-user-service 的角色权限码（Feign roleHasPermission），非本服务库表；远端异常按失败关闭处理，不放行。

六、边界行为

未持对应权限码调用三端点中任一个 → 589507（fail-closed，先于业务逻辑，零副作用）。
团期不存在：recordCost/summary → 589500；listCost 不校验（既有行为，见「## 2.」业务边界的既有缺口记录）。
权限服务（user-service）不可用时同样按无权限处理，不因下游故障放宽判权。
判权失败与业务失败（如 589500/589501/589502）不会同时出现在同一次调用——判权在最前面，任何一个判权失败必然先于业务校验拦下。

六.5、枚举 / 数据字典

权限码字面量（来源：`GroupBatchPermissionGuard.java`）

所属字段: Controller 入口 permissionGuard.require(adminId, roleKey, ...) | 类型: 平台权限码字符串

权限码常量	字符串字面量	用于	出处
`PERMISSION_FINANCE_VIEW`	`group-batch:finance:view`	`GET .../settlement/cost`、`GET .../settlement/summary`	`GroupBatchPermissionGuard.java:61`
`PERMISSION_FINANCE_ADVANCE`	`group-batch:finance:advance`	`POST .../settlement/cost`	`GroupBatchPermissionGuard.java:64`

（对照：group-batch:view 是团期详情一般查看权，#7316 已接线到「全团需求汇总」端点，不是本次三端点使用的码。）

`costType`（`RecordBatchCostReqVO.costType` / `BatchCostRespVO.costType`）

所属字段: data.costType / data.sharedCostByType[].costType | 类型: String

值	含义
`BUS`	整团大巴
`LEADER`	领队费用
`PHOTOGRAPHER`	摄影师费用
`OTHER`	其他

（枚举白名单来自 GroupBatchSettlementService.parseCostType，非法值抛 589502，本次未改动。）

六.6、修改前后对比

字段级对比

字段	改前	改后
三端点权限要求	无（任意能过网关鉴权的后台账号均可调用）	`POST .../cost` 需 `group-batch:finance:advance`；两个 `GET` 需 `group-batch:finance:view`；否则 589507
三端点请求参数	—	完全不变
三端点响应结构（字段名/类型/嵌套）	—	完全不变

行为级对比

行为	改前	改后
不持任何团期相关权限码的账号调 `POST .../settlement/cost`	200，成功写入 `order_batch_settlement`，抬高该团总成本与人均分摊	589507，零落库
不持任何团期相关权限码的账号调两个 `GET` 端点	200，能读到 `subOrderTotalProfit`（毛利）、`groupAdvanceApproved`/`groupAdvancePending`（预支）等敏感经营数据	589507，拒绝读取
仅持 `group-batch:view`（无 `finance:view`/`finance:advance`）的账号调三端点	200（此前零判权）	589507

六.7、影响评估

是否破坏向后兼容：是（预期内的收紧）——此前任意能过网关的后台账号都能调这三个端点，现在非持对应 finance:view/finance:advance 的角色会从 200 变 589507。这是本单修复的安全缺口本身，不是意外副作用。
前端是否必须同步上线：否，但强烈建议同步——不同步页面仍可用：权限拒绝会走通用错误展示后端 message；请求/响应结构零改动，无需前端配合即可正常渲染已授权账号的数据。但若前端此前对所有登录后台账号都展示「结算」Tab 的成本录入/明细/汇总，上线后无权限角色会看到大量 589507 报错而非空白/隐藏状态，体验不佳，建议同步按权限码隐藏对应 UI。
需要确认的角色矩阵：上线前应先确认哪些角色持有 group-batch:finance:view / group-batch:finance:advance（与 GroupBatchFinanceController 既有端点共用同一套授权），避免误挡当前正在使用「结算」Tab 的角色。此步骤由管理者在部署前执行，结果将回填本篇 frontmatter 与状态说明。

七、不影响范围

三个端点的请求参数、响应结构（字段名、类型、嵌套层级）本次完全不变，只新增鉴权分支。
GroupBatchFinanceController（团期财务总览、预支记录等既有端点）判权口径本就是 finance:view/finance:advance，不受本次影响。
#7316 已接线的 requirement-summary 端点（group-batch:view）不受本次影响，两组端点权限码互不复用。
团期需求确认 / 打回相关端点（group-batch:demand:confirm）不受本次影响。
无 Flyway、无表结构变更、无新端点、网关路由零改动（/v3/admin/order/group-batch/** 通配路由已存在），只涉及 hl-order-service-v3 单模块。
不新增权限码、不改动 hl-user-service 的角色授权种子数据。

八、测试环境已验证

当前状态：代码已合入 dev-v3（HEAD 353f4b2d6），测试服部署与网关实测待管理者安排，部署后回写本节与 frontmatter。

已完成的验证（单测/编译层面，不等价于网关实测）：

场景	用例	结果
`recordCost` 持 `finance:advance`	`GroupBatchSettlementControllerPermissionTest#recordCost_hasFinanceAdvancePermission_delegatesToService`	精确 verify 判权入参为 `PERMISSION_FINANCE_ADVANCE`，正常委托 Service 并返回新建 ID
`recordCost` 缺 `finance:advance`	`...recordCost_missingFinanceAdvancePermission_throwsDeniedAndSkipsService`	抛 589507，`verifyNoInteractions(groupBatchSettlementService)`——零落库
`listCost` 持 `finance:view`	`...listCost_hasFinanceViewPermission_delegatesToService`	精确 verify 判权入参为 `PERMISSION_FINANCE_VIEW`，正常返回明细
`listCost` 缺 `finance:view`	`...listCost_missingFinanceViewPermission_throwsDeniedAndSkipsService`	抛 589507，零查询
`summary` 持 `finance:view`	`...summary_hasFinanceViewPermission_delegatesToService`	精确 verify 判权入参为 `PERMISSION_FINANCE_VIEW`，正常返回汇总
`summary` 缺 `finance:view`	`...summary_missingFinanceViewPermission_throwsDeniedAndSkipsService`	抛 589507，零汇总计算

以上六条均用 Mockito 精确实参 verify（而非 anyString()）钉死判权用的权限码字面量，避免改错码测试仍然通过；GroupBatchSettlementControllerTest（路由与响应结构切片测试）已同步 mock 新注入的 GroupBatchPermissionGuard 以保证 @WebMvcTest 能正常装配。

待补（部署后由管理者执行并回填）：测试服网关实测三端点的 200/589507 两种路径、角色矩阵 SQL 结果、ArchTest 门禁结果。

十、相关文档

团期看板权限地基 #6902：group-batch:list / group-batch:view / group-batch:export 三权限码首次注册。
团期财务总览与预支 #7154：group-batch:finance:view / group-batch:finance:advance 首次注册并接线到 GroupBatchFinanceController（GB-ADM-040/042/043）。
团期全团需求汇总补权限码 #7316：同一 GroupBatchPermissionGuard，group-batch:view 接线示例；该篇正文两处涉及本端点判权状态的历史描述已随本单更正（见 10_7316_*.md）。

关联 / 联系人

链接

Issue: #7411
PR: #7447（合并提交 856ab69bf）

联系人

后端负责人: wx
待确认对象（前端 hl-ui）: mmg——建议「结算」Tab 按权限码隐藏成本录入/明细/汇总的按钮与区块，并确认现有账号角色矩阵是否已持有 group-batch:finance:view / group-batch:finance:advance

27 KiB 原始文件 永久链接 Blame 文件历史 Unescape Escape

团期模块：核单共享成本三端点补判权（此前零判权，含一个写端点）

⚠️ 关键变化

一、背景

二、变更接口清单

三、接口详情

1. 录入团期共享成本 POST /v3/admin/order/group-batch/{groupBatchId}/settlement/cost

使用场景

入参字段表

出参字段表 Result<Long>

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

2. 团期共享成本明细列表 GET /v3/admin/order/group-batch/{groupBatchId}/settlement/cost

使用场景

入参字段表

出参字段表 Result<List<BatchCostRespVO>>

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

3. 团期核单 D2 汇总 GET /v3/admin/order/group-batch/{groupBatchId}/settlement/summary

使用场景

入参字段表

出参字段表 Result<GroupBatchSettlementSummaryRespVO>

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

四、契约约束与正确调用方式

切换状态时的必要动作

五、数据库行为

六、边界行为

六.5、枚举 / 数据字典

权限码字面量（来源：GroupBatchPermissionGuard.java）

costType（RecordBatchCostReqVO.costType / BatchCostRespVO.costType）

六.6、修改前后对比

字段级对比

行为级对比

六.7、影响评估

七、不影响范围

八、测试环境已验证

十、相关文档

关联 / 联系人

链接

联系人

27 KiB

原始文件永久链接 Blame 文件历史

1. 录入团期共享成本 `POST /v3/admin/order/group-batch/{groupBatchId}/settlement/cost`

出参字段表 `Result<Long>`

2. 团期共享成本明细列表 `GET /v3/admin/order/group-batch/{groupBatchId}/settlement/cost`

出参字段表 `Result<List<BatchCostRespVO>>`

3. 团期核单 D2 汇总 `GET /v3/admin/order/group-batch/{groupBatchId}/settlement/summary`

出参字段表 `Result<GroupBatchSettlementSummaryRespVO>`

权限码字面量（来源：`GroupBatchPermissionGuard.java`）

`costType`（`RecordBatchCostReqVO.costType` / `BatchCostRespVO.costType`）