[需求] 优化CLA的协议更新比对文件-的开发实现-app-cla-server部分

[fly333sky]

背景

[需求] 优化CLA的协议更新比对文件（app-cla-server）· 开发流水线 · 开发预览阶段（代码已推 + 预览已部署 + UT 已补；门禁/对抗由 PR CI 异步跑）

改动内容

feat(app-cla-server): 优化 CLA 协议比对，忽略空格/全半角标点/换行等排版噪声

改动概览

按 issue #1482 与 design.md，在 app-cla-server/util/generate_diff.py 的 PDF 比对链路
中新增「文本归一化」前置环节并重写 token 切分，使比对文件只标记实质性文字增删改，
忽略 PDF 排版噪声（空格、全/半角标点、换行/换页）。命令行入参（3 个位置参数）与
HTML 输出契约（<pre> + span.removed/span.added）保持不变，Go 调用方
（signing/watch/cla_updated.go）、对外接口、Dockerfile、WebUI 均零改动。

改了哪些文件（均在子仓 app-cla-server 内）

• util/generate_diff.py（核心改动）

  • 新增 normalize(text)：unicodedata.normalize('NFKC') + CJK 标点全/半角映射表
    • re.sub(r'\s+', ' ', text) 合并所有空白（含换行/换页）为单空格。
    • NFKC 自动转换全角 ASCII 变体（，；：（）！？～［］ 等 FFxx 区）。
    • 显式映射表覆盖 NFKC 不处理的 CJK 表意标点：。→. 、→, 【→[ 】→] “→" ”→" ‘→' ’→'。
    • 有意不映射 《》→<>：<> 经 WebUI v-html 会被当成 HTML 标签导致内容从页面
      消失，直接违反验收标准 Dev #5「标记位置准确可读」；而两份 PDF 同用《》时本就相等、无需
      映射，混合用法极罕见，故保留《》原样（风险/收益更优，已在注释/此处说明）。
  • 重写 split_into_words(text)：re.findall(r'\w+|[^\w\s]', text)，只产出「词 + 单个
    有意义标点」token，不再产出纯空白 token（杜绝空格类误标，同时保留真实标点增删可被标记）。
  • compare_texts(text1, text2)：入口对两份文本各调一次 normalize 后再走原有行级+词级比对。
  • compare_pdfs(...)：比对后若结果不含任何 [-/{+ 标记（即无实质差异），写出
    0 字节空文件并返回（WebUI 侧 res.data==="" → 比对卡片隐藏＝「无实质改动」，
    且空文件已存在可避免 service.go/cla_updated.go 的重试风暴）；关键步骤补充 print 日志。
  • generate_word_level_diff / save_diff_report / save_diff_report1：保持现状
    （输出符号 [-...-]/{+...+} 与 HTML span 替换逻辑不变）。

• util/test_generate_diff.py（新增，pytest，27 个用例）

  • UT1 normalize：全/半角标点映射、空白/换行/制表符合并、全角数字、幂等、空串、CJK 内容保留。
  • UT2 split_into_words：无空白 token、纯空白/空串、纯标点、CJK 词 token。
  • generate_word_level_diff 四分支：equal/insert/delete/replace 全覆盖。
  • compare_texts：仅格式差异无标记、实质修改有标记、空输入。
  • IT1/IT3（acceptance Feature/support deploy #1/Dev #3）：testdata/same_text_relayout_* 与 testdata/only_format_diff_*
    同文异排版（全/半角标点 + 多空格 + 换行/换页）→ 输出 0 字节空文件，removed/added 计数=0。
  • IT2（acceptance Feature/support deploy #2）：testdata/real_edits_* 含 5 处真实词增删改 → 输出 HTML 含
    removed/added span 各 5，5 处人工标注全部命中（召回率 100%）。
  • 韧性：空文件分支写出「真实存在且 0 字节」文件（对应 Go 侧 IsFileNotExist 短路、防重试风暴）。
  • CLI 契约：__main__ 3 个位置参数写产物、参数个数不符 sys.exit(1)。
  • save_diff_report：[-...-]/{+...+} → span 包裹、<pre> 外壳。

• util/testdata/（新增固定样本 PDF + 生成器）

  • same_text_relayout_v1.pdf / same_text_relayout_v2.pdf：同文字、仅全/半角标点+空格+换行差异。
  • only_format_diff_v1.pdf / only_format_diff_v2.pdf：同文字、仅换页/换行/全角标点差异。
  • real_edits_v1.pdf / real_edits_v2.pdf：5 处真实修改（授予→授权给、签署→签订、
    法院→仲裁机构、免费→无偿、不可转让→可以转让）。
  • gen_fixtures.py：dev-only 固定样本生成器（仅用 reportlab 生成产物，不是运行时依赖；
    服务运行时只依赖已锁定的 pypdf@3.12.0，未改 Dockerfile）。testdata 仅用于测试，
    Dockerfile 仍只 COPY generate_diff.py，不进生产镜像。

对应需求功能点 / 验收标准

验收标准	实现
#1 同文异排版零误标	normalize+实质 token 比对；IT1 验证→0 字节空文件
#2 真实修改全召回(100%)	实质 token 比对保留真实增删改；IT2 验证→5/5 命中
#3 纯格式(空格/全半角/换行换页)零误标	归一化消除三类噪声；IT3 验证→0 字节空文件
#4 性能不劣化(≤1.2×)	归一化均为 O(n) 单遍字符串操作，相对 pypdf 提取与 difflib 可忽略（staging 计时为 TASK6）
#5 端到端可读	输出 HTML 契约不变，WebUI 零改即可消费；空差异→卡片隐藏（design 2.4）

相关 Issue

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

AI 使用声明

当前 PR 是否有 AI 参与：

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

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[opensourceways-bot]

Welcome To opensourceways Community

Hey @fly333sky , 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 Pass

fly333sky, thanks for your pull request. All authors of the commits have signed the CLA. 👍

[opensourceways-bot]

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