Design

关键决策

1. 为什么用 capability spec 而不是只改 baseline

project-baseline.md 现状是「指路 + 锚点 + 子项目清单」，纯结构指引。R1~R7 是代码组织约束（行为规则），属于 capability 层面。新建 client-service-layering capability spec 后：

baseline 只加一行锚点指向新 spec
权威正文进共享 mjava-baseline.md（跨仓库引用）
仓库内 spec 用 ## ADDED Requirements 段落对齐 OpenSpec 模式

这样 baseline 保持「薄」，规则改动走 capability spec 的 propose/archive 流程，演进路径清晰。

2. R5 命名：为什么选 `Impl` 后缀

仓内现状：

后缀：宜搭 3 文件（YDClient_FormImpl/YDClient_ProcessImpl/YDClientImpl/YDServiceImpl）
后缀：北森 4 文件（BSClient_AttendanceImpl/BSClient_EmployeeImpl/BSClientImpl/BSServiceImpl）
后缀：其他 6 个产品所有 impl（EKB/FXK/CY/VK/XBB/TB/INTP/ALY 共 ~10 文件）
中缀：钉钉 14 文件（DDImplClient + DDImplClient_X×12 + DDImplService）

14 文件中缀 vs ~17 文件后缀 —— 后缀是事实多数派。R5 选后缀，钉钉作为少数派改名，影响面已知（钉钉 14 文件 + @Qualifier 字面引用）。

3. R7 准入条件：为什么是「≥2 个客户子项目复用」

mjava 基座的价值是「多客户复用的二次封装」。单客户编排放基座会污染共享层：

客户 A 的特殊错误码翻译进 XxxService → 客户 B 调用时被强加上
客户 A 的特定字段映射进 Service → 客户 B 的字段被误转

阈值定 2 是最低门槛：第 2 个复用方出现 = 抽象有市场。第 1 个复用方需要时，先在自己客户子项目里写编排；第 2 个想用时再上提到基座 Service。

实操：第 1 个复用方写代码时，可以在子项目放在 service/{product}/ 下用同样命名，后续上提时一份代码两边引用。

4. R4 变更确认：grep 范围

当前阶段（基础建设期）：mjava-ai 是纯基础建设项目，无实际客户子项目依赖本仓基座 jar，grep 范围 = mjava-ai 本仓。

客户接入后：当某客户独立仓（如未来 akds / 光明独立仓 / 新客户）开始依赖 mjava-ai 发布的基座 jar 时，由用户在 ACK 流程中显式补充该仓库路径，扫描范围随之扩展。

历史背景：光明独立仓 /Users/malk/server/cur/mjava-guangming/ 自维护了一份 mjava 基座的分叉副本（独立 git 仓），不依赖 mjava-ai；akds 同样独立仓。这些客户仓的 R4 grep 由各自仓内自行执行，不与 mjava-ai 的 R4 流程联动。

grep 模板：

# 接口签名
grep -rE "\.{methodName}\(" --include="*.java" {repo}

# 类名引用（迁移/重命名）
grep -rE "(import|extends|implements)\s+.*\.{ClassName}" --include="*.java" {repo}

报告格式：

方法/类: com.malk.service.dingtalk.DDClient.foo
mjava-ai: 3 处
  - mjava-mcli/src/.../Boot.java:42
  - mjava-pro/src/.../Xxx.java:88
  - mjava/src/.../impl/DDImplClient.java:156（自定义，不计）
akds: 1 处
  - apps/web/src/.../Yyy.java:33
光明独立仓: 0 处

5. O3 ALYConf 内容

ALYInvoiceImpl 内 4 个 URL 字面量：

https://fapiao.market.alicloudapi.com/v2/invoice/pdf      → URL_INVOICE_PDF
https://fapiao.market.alicloudapi.com/v2/invoice/query    → URL_INVOICE_QUERY
https://fapiao.market.alicloudapi.com/v2/invoice/qrcode   → URL_INVOICE_QRCODE
https://invoice.market.alicloudapi.com/v2/invoice/ocr     → URL_INVOICE_OCR

ALYConf 不用 @ConfigurationProperties（appcode 是调用方传参，不进 yml），只放 public static final String 常量。

6. 为什么 O1 钉钉改名拆独立 change

文件改动量大（14 文件 + Bean 名 + Qualifier 字面引用扫）
跨仓引用扫范围至少 4 个仓库（mjava-ai/akds/光明/其他客户）
失败回滚成本：1 个文件改坏可能拖累整个钉钉栈

独立 change rename-dingtalk-impl-suffix 让改名风险隔离，可按文件批次推进。

拒绝的方案

直接进 mjava-baseline.md 不建仓库 spec — 拒绝。OpenSpec 是仓内单一事实源，跨仓库共享文档需仓内 spec 作锚点
R7 阈值定 1（只要有 1 个复用就上提）— 拒绝。会鼓励过早抽象
R5 选中缀 — 拒绝。事实多数派是后缀
同时改名钉钉 12 文件 — 拒绝。爆炸半径过大，单独 change 隔离

design.md 4.4 KB Geçmiş Ham