feat(trial): structured checkout-session error reason for FE toast (LES-1184)
背景
Reviewer P0 round-2 #3：把 TrialController.createCheckoutSession 的 3 个失败分支从「通用 code + 文案」升级为「结构化 reason」。前端按 reason 走具体 toast，不再吃通用 trial.checkout_failed 让用户和支持工单都看不出真实原因。
PM 在 评论 643976ac 中要求：
"CK2 错误码透传：TrialController.lookupEmail 空时返回的 400 + 文案，前端按 code 分支显示具体 toast，或后端把 reason 塞进 data 让前端读"
本 MR 实现"后端把 reason 塞进 data 让前端读"路径——Response.data 带 reason 透前端，HTTP 仍 200 与 fly_moon 全栈 code 约定一致。
改动清单
-
flymoon-agent-provider/.../web/controller/agent/TrialController.java—createCheckoutSession3 个失败分支统一走新增failWithReason()；返回类型由Response<TrialCheckoutSessionVO>改为Response<?>容纳异构 data；EMAIL_NOT_FOUND 多打一行 log -
flymoon-agent-provider/.../common/enums/TrialCheckoutErrorReason.java— 新增 enum（EMAIL_NOT_FOUND / NOT_ELIGIBLE / STRIPE_ERROR / UNKNOWN），与前端TrialCheckoutErrorReason字面一致 -
flymoon-agent-provider/.../domain/vo/TrialCheckoutErrorVO.java— 新增 VO {reason, detail}
【feature 专用】代码库理解
-
TrialController在 fly_moon_agent 内部（HTTP 适配层），不在 fly_moon_payment（Dubbo facade 层）。原因见 MR !93 描述：/sit-api/*网关后挂的是 agent，前端请求永远到不了 payment。 - 因此新枚举 + VO 放在 agent 自有
common.enums/domain.vo，不污染 payment-api 的 Dubbo 契约，无需向 fly_moon_payment 同步副本。 - 已确认
Response.warn(T data, int code, String msg)可保留Response.data不丢，且 code 任意（这里用 400/403）；与Response.fail(int, String)区别是后者强行抹掉 data。前端拦截器 (request.tsx:415) 看到非 200 code 时 reject{response, code, message}，前端能从err.response.data.data.reason拿 reason。 -
failWithReason是私有 helper，复用Response.warn不引入新 Response 工厂，最小修改面。
测试
-
mvn -DskipTests test-compile— BUILD SUCCESS -
mvn test— 豁免：AgentTranslationServiceImplTest12/13 失败但与本 PR 无关，在 origin/master 上同样失败（Spring context init 旧问题，需独立排障） -
与 Reviewer 上轮 MR !93 的 TrialController 源平起平坐：本分支基于
agent/claude-opus-4-7/13328219拉，未引入冲突
线下验证
- 环境：s1（fly_moon_agent 后端）
- Jenkins build: https://jenkins.deeplink.media/job/build_image_flymoon_agent/159/ (commit fd8a25bd, SUCCESS 68s)
- Jenkins deploy: https://jenkins.deeplink.media/job/DM_s1_flymoon_agent/131/ (SUCCESS 81s, upstream #159)
- 验证结果：build/deploy 成功；接口契约改动需配合前端 jennie MR 一起上 SIT 后才能跑端到端验证（Fifi 在 SIT 走 trial CTA → 故意触发各 reason）
合并顺序
依赖链：
- fly_moon_payment !84 (merged)（已开）— Eligibility enum + priceId gate 后端
- fly_moon_agent !93（已开）— TrialController HTTP 入口 + Dubbo facade 副本
- 本 MR（依赖 #2 因为基于其分支）— Checkout 错误结构化 reason
- jennie MR (本轮配套)— 前端消费 reason
相关
- Issue: LES-1184
- 上轮配套 MR: !84 (merged) (fly_moon_payment) / !93 (fly_moon_agent shadow)
- 配套 MR: jennie!270
- Agent-Task-Id: 20260515-les1184-p0-round2