Skip to content

refactor(platform): 平台连接层按领域容器化重构（里程碑 #6）#123

Merged
huhamhire merged 20 commits into
devfrom
refactor/platform-layer
Jun 24, 2026
Merged

refactor(platform): 平台连接层按领域容器化重构（里程碑 #6）#123
huhamhire merged 20 commits into
devfrom
refactor/platform-layer

Conversation

@huhamhire

@huhamhire huhamhire commented Jun 24, 2026

Copy link
Copy Markdown
Owner

对应里程碑 #6 平台连接层抽象重构统一。把单一约 20 方法的 PlatformAdapter 巨接口重构为按业务领域拆分、契约与传输解耦的服务容器。行为等价——各平台适配器契约测试全程不变通过，全仓 lint / typecheck / test / build 全绿。

主要变更

契约层 @meebox/platform-core（新增）

  • 传输端口 PlatformTransport：三平台同构的最小连接能力（JSON 读写 + 分页）；二进制等平台特有方法为端口外扩展。
  • 领域接口 + 抽象基类：PlatformConnection / PullRequestService / CommentService / MediaService 及对应 Base*（承载跨平台逻辑）、PlatformDomainService、ConnectionContext、组合器 composePlatformAdapter、可选传输 helper。
  • 统一状态码 MergeVetoCode：后台不拼面向用户的本地化文案。

各平台（GitHub / GitLab / Bitbucket）

  • 单体适配器拆为四个领域服务（各 extends 对应 Base*），共享一份连接上下文。
  • 连接配置归连接层自管：client 实现传输端口、自管鉴权 / 分页 / host 推导 / clone / 代理解析。
  • 公共响应类型抽到 types.ts、跨领域工具放 utils.ts、领域映射作各服务私有方法。

连接层与消费方

  • 代理配置统一进连接层：连接配置携带 proxy，一次解析，收口各调用点手拼 fetch。
  • 业务层约 25 处调用迁移到领域容器（adapter.comments.list(...) / adapter.prs.listPending(...)）；退役扁平接口与门面委托；领域字段定名 prs。

去后台中文状态文案

  • 合并否决原因、Bitbucket 版本不支持原因改为中性错误码，前端按码 i18n（zh-CN / en-US / ja-JP / de-DE）。

文档

  • docs/arch/01 同步新架构并补层级类图；按本仓约定移除已落地的过程性设计草案。

验证

  • 18 个提交，每个独立四步全绿、行为等价。
  • 全仓 lint(15) / typecheck(15) / test(10) / build 全绿。

🤖 Generated with Claude Code

huhamhire and others added 18 commits June 24, 2026 14:32
@huhamhire @claude
docs(platform): 新增平台连接层抽象重构设计草案
b4b1fa0 
对应里程碑 #6。三层切分：core 只声明业务契约（领域接口 + 各领域抽象基类 +
传输端口 + 可选 helper），连接 / 传输实现归各平台包自负；按 PR 操作 / 评论 /
用户媒体 / 连接拆分领域并组装到根 client；可降级方法就近声明、根聚合出对外能力
描述符。含代理配置统一进连接层、对外形状「内部分组 + 外部扁平」取舍与分阶段落地。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
refactor(platform): 新增 @meebox/platform-core 连接层契约与传输端口
babc64b 
重构 Phase 0。新增内部包 @meebox/platform-core，作为平台连接层的契约层：
- 定义传输端口 PlatformTransport（get/post/put/del/paginate/getBinary 等
  三平台同构的最小连接能力）与统一连接配置 PlatformConnectionConfig；
- 连接配置统一携带 proxy，经注入的 ProxyFetchFactory 一次解析有效 fetch，
  替代各调用点手拼，core 不依赖 undici；
- 提供可选传输 helper（buildUrl / fetchWithTimeout / parseNextLink / collect /
  extractApiMessage / resolveConnectionFetch），供平台传输实现按需组合。
在 desktop 依赖与 electron-vite internalPackages 登记新包。暂未改动各平台
实现，行为零变化。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
refactor(platform-github): GitHub 传输层实现 PlatformTransport、复用 core helper
4330347 
重构 Phase 1（GitHub）。GitHubClient 改为 implements PlatformTransport，通用样板
（超时 / URL 拼接 / 错误消息提取 / Link 分页 / 有效 fetch 解析）复用 @meebox/platform-core
helper；GitHub 特有部分（鉴权头 / 限流提示 / 可信资产域 / search / patch）保留。
GitHubClientOptions 改为统一连接配置别名。公开方法签名不变，GitHubAdapter 零改动，
适配器测试全过，行为等价。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
refactor(platform): GitLab/Bitbucket 传输层实现 PlatformTransport，收敛端口
a6d06b9 
重构 Phase 1（GitLab + Bitbucket）。两平台 client 改为 implements PlatformTransport，
通用样板（超时 / URL 拼接 / 有效 fetch 解析；GitLab 另含错误消息提取 / Link 分页）复用
@meebox/platform-core helper；平台特有部分保留（GitLab：PRIVATE-TOKEN / 资产 host 鉴权
模式 / API 二进制端点；Bitbucket：start/limit 分页 / avatar 路径二进制 / 附件协议解析）。
ClientOptions 改为统一连接配置别名，公开方法签名不变、各 Adapter 零改动，适配器测试全过。

同时收敛传输端口：getBinary 从 PlatformTransport 移除——三平台二进制信任模型迥异
（Bitbucket 路径式 + 附件协议、GitHub/GitLab 各自白名单），不属同构最小连接能力，留作
平台传输扩展、由后续 MediaService 领域基类抽象。端口现为纯 JSON 读写 + 分页。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
refactor(platform): 代理配置统一进连接层，收口各调用点手拼 fetch
a6fd82a 
重构 Phase 1（代理统一）。统一连接配置新增 proxyFetch 注入口（由组合根 desktop 提供
undici 实现）；resolveConnectionFetch 据 config.proxy + baseUrl host 一次解析有效 fetch。
adapters.ts 不再在 buildOne / buildDraftAdapter 各自 proxyFetchForHost(proxy, host) 预拼
fetch 注入，改为透传 proxy 配置与工厂，由连接层解析——「一个连接 = 一份连接配置（含代理）
= 一次解析」。行为等价（loopback 直连 / 否则挂代理不变），四步全绿。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
refactor(platform-core): 新增领域接口、领域基类与适配器组合器
0dd217e 
重构 Phase 2a（领域契约层）。在 platform-core 定义按业务领域拆分的接口
（PlatformConnection / PullRequestService / CommentService / MediaService）与领域服务
容器 PlatformAdapter；新增共享连接上下文 ConnectionContext（持统一连接封装实例 + 当前
用户缓存）与各领域抽象基类（BaseConnection 等，PlatformDomainService 向子类暴露 transport，
BaseConnection 的用户缓存读写为跨平台共享实现）；composePlatformAdapter 把四个领域服务组装
成根容器。纯新增、暂未接线，各平台与消费方零改动。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
refactor(platform-core): 领域层按 features 拆分到独立文件
02debd3 
把 domains.ts 拆分为可独立维护的文件：context.ts（ConnectionContext /
PlatformDomainService）、features/{connection,pull-request,comment,media}.ts（各领域
接口 + 基类）、adapter.ts（容器 + composePlatformAdapter）。index.ts 对外导出不变，
纯文件组织调整，避免单文件随基类共享逻辑增长而膨胀。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
refactor(platform-github): 适配器按领域拆分为四个服务
76c578a 
重构 Phase 2b（GitHub）。把单体 GitHubAdapter 拆为四个领域服务（GitHubConnection /
GitHubPullRequestService / GitHubCommentService / GitHubMediaService，各 extends
platform-core 领域基类），共享一份连接上下文（MutableConnectionContext）；GitHubAdapter
退化为薄门面，过渡期委托扁平方法给对应领域服务并暴露 .connection/.pulls/.comments/.media，
消费方迁移前保持可用。

- 连接配置归连接层自管：移除 env 间接层，client（统一连接封装实例）自管 base 归一、
  clone 协议与 web/git host 派生，并提供 getCloneUrl；各服务只持 client。
- 映射就近维护：领域专属映射下沉为各服务私有方法，公共响应类型抽到 types.ts，
  跨领域 mapUser 留在 mappers.ts。

公开方法签名不变、适配器测试全过、desktop typecheck 通过，行为等价。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
refactor(platform): 合并否决原因改为中性码，前端按码 i18n
212abca 
后台业务内部不再硬编码中文状态文案。platform-core 新增统一否决原因码 MergeVetoCode；
MergeVeto 改用 code（中性、不本地化）承载派生原因，summary 退为服务端直给文案（如
Bitbucket）的可选回退。GitHub / GitLab 把派生的合并否决原因归一到码，前端在各 locale
（zh-CN / en-US / ja-JP / de-DE）按 `mergeVeto.<code>` 本地化。GitHub 发往远端的评审
正文 / 撤销说明改用英语中性文案。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
refactor(platform-github): 公共工具文件改名 utils，review 态映射改常量表
534bcc5 
mappers.ts → utils.ts（承载跨领域公共工具方法 mapUser）。PR 领域内 review 决断态到活动
事件类型 / reviewer 状态的嵌套三元 / if-else 改为常量 Record 映射表（ACTIVITY_KIND_BY_STATE
/ REVIEWER_STATUS_BY_STATE），更易读、易维护。行为等价。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
refactor(platform-gitlab): 适配器按领域拆分为四个服务
e65b079 
重构 Phase 2c（GitLab）。把单体 GitLabAdapter 拆为四个领域服务（GitLabConnection /
GitLabPullRequestService / GitLabCommentService / GitLabMediaService，各 extends
platform-core 领域基类），共享一份连接上下文；GitLabAdapter 退化为薄门面，过渡期委托
扁平方法并暴露 .connection/.pulls/.comments/.media。

- 连接配置归连接层自管：client 自管 base 归一、clone 协议、web/git host 派生与
  getCloneUrl；edition 探测态 approvalsAvailable 落在 client 上，供连接（capabilities）
  与 PR（审批拉取）领域共读。
- 映射就近维护：领域专属映射下沉为各服务私有方法，公共响应类型抽到 types.ts，
  跨领域 mapUser / projectId 放 utils.ts。

公开方法签名不变、适配器测试全过、desktop typecheck 通过，行为等价。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
docs(platform): features 领域类与方法补全多行 JSDoc
bf1084e 
为 platform-core / platform-github / platform-gitlab 的 features 领域层（连接 / PR /
评论 / 媒体）及 core 的连接上下文、组合器补全多行 JSDoc：每个领域接口、领域基类、平台
服务类及其方法（含私有映射方法）均给出必要的块注释，单行注释一并展开为多行块。纯注释
改动，无代码变更，四步全绿。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
refactor(platform-bitbucket-server): 适配器按领域拆分为四个服务
019330d 
重构 Phase 2c（Bitbucket）。把单体 BitbucketServerAdapter 拆为四个领域服务
（BitbucketServerConnection / BitbucketPullRequestService / BitbucketCommentService /
BitbucketMediaService，各 extends platform-core 领域基类），共享一份连接上下文；
BitbucketServerAdapter 退化为薄门面，过渡期委托扁平方法并暴露 .connection/.pulls/
.comments/.media。

- 连接配置归连接层自管：client 自管 clone 协议、webBase 与 getCloneUrl；各服务只持 client。
- 映射就近维护：领域专属映射下沉为各服务私有方法（版本比较、合并状态、评论 / 锚点映射等），
  公共响应类型抽到 types.ts，跨领域 mapUser 放 utils.ts。
- review 决断态 / 活动 action 映射改常量表，方法补多行 JSDoc。

公开方法签名不变、适配器测试全过、desktop typecheck 通过，行为等价。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
style(platform-core): 领域接口与基类成员间补空行
9b7fcde 
为 platform-core 领域接口（PlatformConnection / PullRequestService / CommentService /
MediaService）、连接上下文接口及各领域基类的方法 / 成员之间补必要空行，提升可读性。纯格式，
无代码与行为变更。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
refactor(platform): 消费方迁移至领域容器，退役扁平适配器接口
1b75881 
重构 Phase 2d（消费方翻转）。业务层调用从扁平 adapter.method(...) 迁移到领域容器
adapter.<domain>.<method>(...)：connection（ping / 当前用户 / 能力 / clone）、prs（PR 操作）、
comments（评论）、media（头像 / 附件）。涉及 pr.ts / poller / app & comments 服务 /
pr-service / repo-mirror / connections-runtime / autopilot 等约 25 处调用点与 FakeAdapter 测试桩。

- 领域字段定名 `prs`（贴合应用「PR」术语，较 `pulls` 更清晰）。
- 退役过渡层：删除三个适配器门面的扁平委托方法、移除 @meebox/shared 的扁平 PlatformAdapter
  接口；各适配器改为 implements @meebox/platform-core 的容器 PlatformAdapter。
- poller 依赖加 @meebox/platform-core；FakeAdapter 改为容器形态（仅实现所测领域）。
- 同步设计草案的字段命名。

公开行为不变，全部契约测试与 poller 测试通过，desktop typecheck/lint/build 全绿。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
refactor(platform-bitbucket-server): 版本不支持原因改错误码，前端按码 i18n
6ff10ce 
清除后台最后一处中文状态文案。Bitbucket 连接探测对低于支持下限的版本不再返回中文 reason
字符串，改以错误码 CF_UNSUPPORTED_VERSION + meta（实际版本 / 最低要求）承载；连接测试结果
经 formatBackendError 解码、前端按 errors.ECF0001 本地化（zh-CN / en-US / ja-JP / de-DE，
带 version / min 插值）。后台业务内部不再含面向用户的中文文案。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
docs(arch): 平台适配文档同步领域容器新架构，设计草案归档
5622115 
重构 Phase 3（收尾·文档）。arch/01 由旧的单一巨接口叙述更新为新架构：契约层
@meebox/platform-core（领域接口 + 领域基类 + 传输端口 PlatformTransport + 组合器）、
各平台实现层（统一连接封装实例 + 四领域服务）、根领域服务容器（connection / prs /
comments / media）；补能力描述符新增字段、合并否决中性码与连接错误码、按新结构的新增平台
步骤、代理统一进连接层。设计草案标记为已落地并归档，指向 arch/01。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
docs(arch): 平台适配补层级类图，移除已落地的设计草案
cce076d 
为 arch/01 §1 增补 mermaid 类图，归纳「领域接口 + 抽象基类」契约层与 GitHub / GitLab /
Bitbucket 三平台扩展点（*Adapter 实现容器接口、*Client 实现传输端口）的继承 / 实现关系，
图说要点分条列出。

按本仓约定（过程性设计文档落地后移除、结论沉淀进各篇核心设计——参见 docs/adr 的处理）
删除 docs/design/platform-layer-refactor.md；arch/01 去掉对草案的链接，platform-core
注释（transport.ts / codes.ts）对草案章节的引用改指 arch/01 对应小节。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire huhamhire added the refactor 代码重构（不改运行行为） label Jun 24, 2026
huhamhire and others added 2 commits June 24, 2026 22:04
@huhamhire @claude
docs(changelog): 记录平台连接层领域化重构
edfe6b5 
Unreleased 增 Changed 一条（按要点缩进）：代码平台接入层基于领域设计重构（行为不变），
按四领域拆分、连接与代理配置统一收口、连接状态提示本地化。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire @claude
Merge branch 'dev' into refactor/platform-layer
69d8925 
合并 dev（含 #122 配置面板左右分区布局），CHANGELOG 的 Unreleased 两条 Changed 并列保留。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@huhamhire huhamhire merged commit d4c39c3 into dev Jun 24, 2026
1 check passed
@huhamhire huhamhire deleted the refactor/platform-layer branch June 24, 2026 14:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

refactor 代码重构（不改运行行为）

Projects

None yet

Milestone

平台连接层抽象重构统一

Development

Successfully merging this pull request may close these issues.

1 participant

@huhamhire