CLA 协议变更平滑过渡机制 — 非阻塞式版本检查 + 宽限期-的开发实现-app-cla-server部分

[flysky22222]

背景

CLA 协议变更平滑过渡机制 — 非阻塞式版本检查 + 宽限期（app-cla-server）· 开发流水线 · 开发预览阶段（代码已推 + 预览已部署 + UT 已补；门禁/对抗由 PR CI 异步跑）

改动内容

fix(app-cla-server): 修复签署状态查询接口 status/version_matched 字段未始终返回的问题

改动说明

issue #909 触发评论中用户（@JavaPythonAIForBAT）明确要求 /api/v1/individual-signing/{cla_id}?email=... 接口返回的数据必须形如：
{"data":{"type":"corporation","signed":true,"version_matched":true,"status":"valid"}}
其中 status 是新增的权威状态字段（取值 not_signed/valid/expired），且 signed、version_matched 必须始终返回以兼容旧版本调用。

经核查已有实现（review 分支），发现两处与该要求直接冲突的 bug：

1. controllers/individual_signing.go —— 非 debug 模式下 status 被清空

原实现在 Check() 中有：

if !debug {
    v.Status = ""      // ❌ 把权威状态字段当成调试信息清掉了
    v.DebugInfo = nil
}

Status 不是调试信息，而是用户要求始终返回的权威字段。生产调用（不带 debug 参数）会得到 "status":""，与要求的 not_signed/valid/expired 不符。

修复：移除 v.Status = ""，仅保留 v.DebugInfo = nil（真正属于 debug 的内容）。注释同步更新为「status 是权威状态字段，始终返回；调试信息仅在 debug 模式下返回」。

2. models/individual_signing.go —— version_matched 带 omitempty 导致 false 被省略

IndividualSigned.VersionMatched 的 json tag 为 version_matched,omitempty。需求分析说明书验收标准 #2 明确给出三种返回样例：

• 未签署：version_matched:false
• 有效：version_matched:true
• 过期：version_matched:false

带 omitempty 时，not_signed / expired 两种情况下 version_matched:false 会被 JSON 编码器省略，破坏向后兼容（旧版本调用方读不到该字段）。上一个 commit 4315576 只去掉了 signed、status 的 omitempty，遗漏了 version_matched。

修复：移除 VersionMatched 的 omitempty，与 Signed、Status 保持一致，确保三态下 version_matched 始终出现在响应里。

涉及文件

• controllers/individual_signing.go（Check：不再清空 status）
• models/individual_signing.go（IndividualSigned.VersionMatched 去 omitempty）

单元测试

新增 models/individual_signing_test.go：

• TestIndividualSignedJSONSerialization：表驱动覆盖 valid / expired / not_signed 三种状态，断言 type、signed、version_matched、status 四字段在 JSON 响应中均存在且取值正确（重点验证 false 值不被 omitempty 吞掉）。
• TestIndividualSignedDebugInfoOmittedWhenNil：验证 DebugInfo 为 nil 时 _debug 被省略（即非 debug 模式不泄露调试信息）。

已用「先回退 fix 再跑测试」的方式确认该测试能精准捕捉上述 bug（回退后 expired/not_signed 两个用例因 version_matched 缺失而 FAIL，恢复后全绿）。

验证

• go build ./... 通过
• go vet ./models/ ./controllers/ 通过
• go test ./... 全部包 PASS（models / signing/domain / signing/domain/randomcode / signing/domain/vcservice / signing/watch）

相关 Issue

resolve https://github.com/opensourceways/backlog/issues/909

AI 使用声明

当前 PR 是否有 AI 参与：

• 否
• 是
  1. AI Agent 平台：opencode（Workflow Develop · 需求实现）
  2. AI 模型：bigmodel/glm-5.2
  3. Prompt 上下文：https://github.com/opensourceways/backlog/issues/909 的 /ai-develop-preview

[opensourceways-bot]

Welcome To opensourceways Community

Hey @flysky22222 , thanks for your contribution to the community.

Bot Usage Manual

I'm the Bot here serving you. You can find the instructions on how to interact with me at Here . That means you can comment below every pull request or issue to trigger Bot Commands.

Contact Guide

If you have any questions, please contact the SIG: infratructure ,
and any of the maintainers: @GeorgeCao-hw, @TangJia025, @pkking, @zhongjun2 ,
and any of the committers: @JavaPythonAIForBAT, @Zherphy, @tfhddd, @zhongjun2 .

[opensourceways-bot]

CLA Signature Guide

@flysky22222 , thanks for your pull request.

The following commit(s) are not associated with a signed Contributor License Agreement (CLA).

Commit	Reason
7e1e8b49 fix(app-cla-server): 修复签��...	the email used in the commit is not linked to a signed CLA! please verify that it matches the email you used when signing the CLA.

To sign CLA, click here.

To check if your email is configured correctly, refer to the FAQs.

Once you've signed the CLA or updating your email, please comment /check-cla to revalidate CLA status.

[gemini-code-assist]

Code Review

This pull request ensures that the authoritative status field and the version_matched field are always returned in the JSON response of the individual signing check, even when not in debug mode or when the values are false, maintaining compatibility with legacy callers. Additionally, comprehensive unit tests have been added to verify the correct JSON serialization and omission of debug information. There are no review comments, and I have no additional feedback to provide.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[opensourceways-bot]

检查项	状态
敏感信息扫描	✅
漏洞扫描	❌
Check代码检查	❌
开源license合规扫描	✅
开发阶段设计文档检查	❌
流水线链接	点击跳转查看日志