# GoodBuddy 接入边界

本文件记录 Product Issue 已提供的服务端契约。GoodBuddy 桌面端接入应在
生产域名确定后实现。

## 推荐调用链

```text
About 页面反馈表单
  → shared Zod contract
  → preload 显式方法
  → Main IPC handler
  → Main HTTPS client
  → POST /api/v1/feedback
```

不要从 Electron renderer 直接跨域调用公开 API，也不要向 renderer 暴露
通用网络能力。

## Renderer

- 在“关于”页面内提供反馈入口，不跳转 GitHub Issue。
- 字段包括类型、标题、描述、可选邮箱和可选截图。
- 发送前显示会提交的环境字段和隐私说明。
- 截图需要主动选择或粘贴，支持预览和移除。
- 失败时保留所有输入，成功时显示服务端反馈编号。
- 同一次提交重试必须复用 `clientRequestId`。

## Preload 与 IPC

- 在 `src/shared` 定义并复用 Zod 输入/输出 schema。
- 使用现有 trusted sender 校验。
- preload 只暴露一个用途明确的反馈提交方法。
- IPC 输入必须限制字符串长度、附件数量和字节数。
- 不传递文件系统路径给服务端。

## Main HTTPS client

- 固定并校验生产 HTTPS origin。
- 使用正常系统 TLS 校验，不允许忽略证书错误。
- 设置连接和总超时，支持取消。
- 禁止或严格限制重定向，避免把反馈发送到非预期 origin。
- 限制响应体大小并按公共响应 schema 验证。
- 不记录请求正文、邮箱、图片、installation ID 或响应凭据。

## 标识

- `installationId`：应用首次生成并持久保存的随机 UUID，不使用硬件序列号、
  用户名或设备指纹。
- `clientRequestId`：用户发起一条新反馈时生成；只有该次反馈的网络重试
  复用。
- `productKey`：GoodBuddy 固定使用 `goodbuddy`。

## 明确不自动附加

- 对话和提示词
- 日志
- 文件、项目或工作区路径
- API key、Token、Cookie、SSH 信息
- 模型、知识库和 Runtime 配置
- 剪贴板或屏幕内容

服务端完整字段与响应见 [公共 API 契约](api.md)。