crm-backend-matt/.scratch/opportunity-bugfix/issues/10-bruno-sync.md

10: bruno-sync 文档更新（修复后契约变更 + 新增端点 → E:\code\crm-api-docs）

Type: task Status: resolved Blocked by: 09

任务

用 skill: bruno-sync 把修复后的接口变化同步到 Bruno 集合 E:\code\crm-api-docs：

1. 新增端点入集合（票 04 的 6 个：customer/add、customer/search、customer/set-primary、team/add、team/delete、team/update + 票 07/08 若有新模块端点）。
2. 契约变更同步：ownerDeptId 服务端生成（票 03）、board 过滤参数（D-15）、detail 联动字段补齐（D-16）、versions 输出 DTO 化（D-22）、校验错误码变化（D-14）等——对应 .bru 的参数/示例块更新。
3. 机制纪律（上轮票 06 已研究定论，直接沿用）：合并式 sync 手改安全；铁律「结构听源码，表述听人」——手改的实参值/说明再生时逐字保留；保持 tags:[generated] + 首行对账钥匙（METHOD+路径）勿动；新 .bru 对齐既有 4 目录树分组（按菜单）。
4. 示例真实化：新端点的请求示例用票 09 回归后的真实测试数据（seed 数据 + 真实响应值），支撑前端直接联调。
5. 对账：跑/写 verify 脚本确认「源码端点 ↔ 集合钥匙」双零差集（上轮 verify_sync.py 的模式：71 唯一钥匙全命中）。

验收

• 集合中商机模块 + 规则族端点与源码 Controller 完全对齐（双零差集）。
• 6 个新端点 .bru 齐备且示例为真实可复现值（含至少一个真实响应体）。
• sync 重跑（若有）确认手改内容不丢。
• 变更摘要记入 Answer（新增 N 个 .bru / 更新 M 个 / 目录树变化）。

Answer

交付：新增 6 / 更新 22，patch 129 处锚全命中、0 fail（t10-apply.py）

• 新增 6 个 .bru：商机详情/客户/添加关联客户、候选客户搜索、设为主要意向客户 + 商机详情/团队/批量添加团队成员、编辑团队成员、移除团队成员（tag 分组挂页面文件夹，meta generated + 表单参数 + docs 四段，seq 接既有目录序；示例值用 seed 造数口径）。
• 更新 22 个 .bru：
  • 看板阶段卡片/汇总 ×6：body+参数表+示例+desc 增 viewType（D-15），按文件夹口径赋值：商机公海=PUBLIC_POOL、商机管理=MANAGE、销售机会=MINE。
  • 三族版本列表 ×3：表/示例剥 creatorId/updaterId/deleted，声明句改「出参 DTO 白名单化（D-22）」；createTime/updateTime 保留（对齐 VersionDTO 实码）。
  • 领取/批量领取：删 ownerNameSnapshot/ownerDeptId（body+表+示例裁尾），desc 追加快照服务端（D-13）+禁领 66014（D-09；批量版注明全量预检，源码 TransitionController L56 实锤）。
  • 分配/批量分配：toUserId→userId + 删两快照；移交：toUserId→newOwnerUserId + 删两快照（D-13，HandoverCmd 实锤）。
  • 暂缓：remark → pauseReason/pauseExpectedRestartDate(ISO yyyy-MM-dd)/pauseRemark（Controller 三参均 required=false，服务层无必填校验实锤）。
  • 关闭/批量关闭：closeReason 是→否、remark→closeRemark；抛公海：poolReason 是→否（源码签名实锤）。
  • 新建商机：body 6→9 行、参数表 15→14 行六必填标记（D-14：opportunityName/oppSource/bidForm/provinceCode/cityCode/localityType；oppType 非必填对齐 CreateOpportunityRequest）；desc 改「负责人=当前登录人，快照服务端生成（D-13）」+六必填 66001。
  • 编辑商机：desc 追加「名称字段为 oppName（新建为 opportunityName）；必填校验对合并后终值执行（D-14）」。
  • 新增附件：bizType 否→是 + 四值封闭说明（D-21，SubController L192 实锤「缺省也进 66001」）。
  • 团队成员列表：表+示例补 duty（负责人行仅可改此列）。
• 表述听人：三族版本列表示例为实测摘录（仅随结构删审计字段行，值未动）、团队成员列表实测摘录保留；一切既有说明/实参值逐字保留。

对账（t10-verify.py，全仓口径）

• 源码 157 把钥匙 ↔ 集合 153 把：EXTRA=0、UNRECOGNIZED=0；商机模块+规则族端点与源码完全对齐 ✅。
• MISSING 4 = 历史遗漏（非本次变更引入）：GET /api/rule/region/list、GET /api/rule/region/level（RegionController，省市级联数据源，新建商机/线索弹窗前端强依赖，真实欠账）；POST /api/system/sync/dingtalk、POST /api/system/users/admin-role（SystemController，@PreAuthorize ADMIN 运维接口）。根因：这 4 个接口无页面 tag，历次按 tag 范围的同步从未覆盖。未扩票处理（超出票 10 商机域范围），是否补齐请拍板；若补，region 两个优先。

工具链与坑

• t10-apply.py：锚点式 patch（sub1/drop_re 锚不恰好命中 1 次即记 fail 不动该处，幂等可重跑）；6 个载荷由 t10-payloads/ 复制（已存在跳过）。
• 坑 1：Write 工具对大 CJK 载荷序列化丢载荷（team-add 三连 "reason: unknown"）→ 全部改「echo ASCII 锚点 + SearchReplace 灌入」（本会话 SearchReplace 大 CJK 零失败）。
• 坑 2：apply save() 双 CR bug（CRLF 文件被整体 replace 成 \r\r\n）→ t10-fixcrlf.py 全仓扫描还原 22 文件（行数与原一致、内容完好）；apply 的 load 已补归一留档。
• 坑 3（08-31 补录时新证）：Write 对 .bru 扩展名一律拒绝（45405/unknown），大 CJK+Markdown 载荷在 .md 上也非确定性丢载荷（同内容重试可过、17 行也会败）；SearchReplace 现已拒绝 workspace 外路径（票 10 时代可用）。本次降级链终点＝「.py 程序化生成落盘」（.py 载体稳定：unicode escape 建中文目录 + 模板拼内容），m4-gen.py 留档 auth-perms。
• 环境坑沿 AGENTS.md：Bash 实为 cmd（无 heredoc）、py -c 禁用、盘外写入靠脚本。
• docs 仓变更 22 M + 6 ?? 全部留在工作区，未做任何 git 操作（铁律 3），待 git diff 审查后自行提交。

MISSING 4 拍板与补录（2026-08-31）

拍板：用户选 A——全补 4 个。落点：region 2 个进新顶级目录「公共依赖-行政区划」（@Tag「公共依赖/行政区划」→ 目录名 /→-，对齐「数据字典-分组」直映惯例）；system 2 个进「系统管理/运维/」子目录（子目录无 folder.bru，对齐「权限点管理」形态；非页面端点入集合有「调试(验证专用)/签发调试token」先例）。

交付：新增 5 文件 0 修改——公共依赖-行政区划/（folder.bru seq 5 + 按上级查子区划 + 按层级查区划）+ 系统管理/运维/（钉钉组织同步 + 管理员角色配置）。region 两示例为真实返回摘录（省 34 / 市 342 实测，parentId=北京市→市辖区 110100）；ADMIN 两个不宜真实执行（真触发钉钉同步/真改角色），示例标注非真实返回。

对账：t10-verify.py 全仓口径 161↔161 双零差集 ✅（源码钥匙 157→161 的 +4 即本次补录）。

环境变更备注：docs 仓已迁盘 E:\ → D:\code\crm-api-docs（本票上文所有 E: 路径引用按迁移后位置读）；留置尾巴①（22M+6??）已由用户自行审查提交（f159691），工作区现存与本票无关的新目录 商机模块/商机详情/工作计划/。

验收对照：双零差集 ✅（4 个范围外历史遗漏已留拍板）；6 新端点齐备+示例可复现 ✅；手改不丢 ✅（本票 patch 即按此语义锚定）；变更摘要 ✅。