对接方集成说明
用途
把与外部对接方的零散约定收成可转发的一页集成说明，固定包含：
- 场景 — 业务目标、主流程与边界（不做）
- 字段 / 数据流 — 关键字段、方向、必填与映射（缺则待双方确认）
- 责任 — 我方 / 对方谁负责什么（轻量 R/A，非完整 RACI 系统）
- 联调窗口 — 时间窗口、环境、验收标准
- 待双方确认 — 未齐信息，禁止编造对方系统能力或已承诺的 SLA
本技能做业务对接共识稿，不做完整 OpenAPI/SDK 文档、不代替合同/法务条款、不代发邮件、不改对方系统配置。
破坏性 API 变更通知请用 api-consumer-notice；内部项目启动一页纸请用 kickoff-onepager。
空表见 references/brief-template.md。
适用场景
- 适合：联调前对齐；把聊天/会议笔记收成给对方的一页说明；实施/集成经理对外同步。
- 不适合：
- 完整 API 文档站或代码脚手架
- 已上线 API 的调用方破坏性变更通知（
api-consumer-notice） - 内部项目 kickoff 对内宣讲（
kickoff-onepager） - 合同条款、报价、法务意见
边界与差异
| 易混需求 | 本技能 | 不做什么 |
|---|---|---|
| API 变更通知 | 对接共识一页 | 不写废弃日/迁移步骤为主交付 |
| 接口文档生成 | 字段表 + 责任 + 窗口 | 不产出完整 reference |
| 项目启动一页纸 | 面向外部对接与联调 | 不写内部成功标准大全 |
怎么使用(普通用户)
在 AI 助手里直接说，例如：
- 「用对接方集成说明，把下面笔记收成一页给客户 IT」
- 「写集成 brief：场景、字段、谁负责、联调窗口」
- 「联调前要对齐 SSO 对接约定」
使用步骤
缺对接双方或目标场景时先追问；未知字段/窗口标「待双方确认」，禁止编造对方已承诺的能力或日期。
1. 澄清最少必要项
| 字段 | 说明 |
|---|---|
| 双方系统/组织 | 我方与对方是谁 |
| 目标场景 | 要打通什么业务 |
| 已知字段或接口线索 | 可缺，缺则待确认 |
| 联调意向时间 | 可缺 |
| 已知责任分工 | 可缺 |
2. 填写一页说明
严格按 references/brief-template.md 结构输出。
对方未确认的项不得写成「对方已同意」。
3. 责任与窗口
- 责任用轻量表：事项 + 我方 + 对方；不明则待确认。
- 联调窗口写计划区间与环境；无日期则待确认，并提示「补齐后再发给对方」。
4. 自检
- 是否误做成完整 OpenAPI？
- 是否误做成 API 变更通知？
- 是否出现用户未提供的对方 SLA/截止日？
示例
示例 1: 信息较全(可出对接共识稿)
输入:
我方: 某 SaaS HR 系统
对方: 客户 AD / IdP
目标: 员工 SSO 登录 + 组织架构每日同步
已知: 用 SAML；用户唯一键用工号；组织同步对方推 CSV 到 SFTP（细节未定）
联调: 希望下周三到周五预发环境
责任口头: 我方出 SAML 元数据；对方开 IdP 应用；SFTP 账号谁开未定
输出:
# 对接集成说明: HR SaaS × 客户 IdP（SSO + 组织同步）
| 项 | 内容 |
| --- | --- |
| 我方系统/产品 | HR SaaS |
| 对方系统/组织 | 客户 AD / IdP |
| 对接目标一句话 | 员工经 IdP SSO 登录，并每日同步组织架构 |
| 文档版本 / 日期 | 草案 v0.1 |
| 我方接口人 | （待填） |
| 对方接口人 | 待双方确认 |
## 1. 场景与主流程
- 业务场景: 客户员工用公司账号登录 HR SaaS；组织树保持与 AD 一致
- 主流程:
1) 用户访问 HR → 跳转 IdP → SAML 断言回传 → 建立会话
2) 组织同步: 对方按约定频率推送人员/部门数据 → 我方入库映射
- 边界(不做): 本页不定义完整 SAML 字段全集；不做密码托管；不替代合同 SLA
## 2. 关键字段 / 数据流
| 字段或数据 | 方向 | 必填 | 说明 / 映射 | 状态 |
| --- | --- | --- | --- | --- |
| SAML NameID / 工号 | 对方→我方 | 是 | 用户唯一键=工号 | 已定（口头） |
| 部门 / 上级 | 对方→我方 | 待定 | CSV 列定义未定 | 待双方确认 |
| SAML 元数据 | 我方→对方 | 是 | 我方提供 SP 元数据 | 已定（口头） |
## 3. 责任
| 事项 | 我方 | 对方 | 备注 |
| --- | --- | --- | --- |
| 提供/维护 SP 元数据 | R | — | |
| 在 IdP 创建应用并放行测试账号 | — | R | |
| SFTP 账号与目录 | 待双方确认 | 待双方确认 | 口头未定归属 |
| 联调排期与验收签字 | A（协调） | A（业务确认） | |
## 4. 联调窗口与验收
- 计划窗口: 下周三至周五（具体日期待填日历）
- 环境: 预发
- 验收标准: 测试账号可 SSO 登录；至少 1 次组织同步文件被成功解析（样例行待定）
- 回滚: 联调失败不影响生产；预发可关闭 IdP 应用
## 5. 待双方确认
1. CSV 列定义与推送频率
2. SFTP 账号由谁开通
3. 对方接口人与精确联调日历
4. 工号为空/离职账号的处理规则
## 6. 风险与假设
- 假设: 唯一键工号在双方一致且稳定
- 风险: 列定义未定则无法估同步开发量
示例 2: 字段极少(退化为信息索要清单，先别发给对方当约定)
只知道「要对接」而无任何技术细节时，一页说明不硬填字段表：结构照出但整表标待确认，交付重心转为分组的信息索要清单与一段可直接发出的问法。此稿用于收集信息，不能当作双方约定发给对方。
输入:
我方: 某订单系统
对方: 客户的 WMS（仓储系统）
目标: 销售说「订单要下发到客户 WMS」
已知: 无其他信息
输出:
# 对接集成说明: 订单系统 × 客户 WMS（信息收集稿）
| 项 | 内容 |
| --- | --- |
| 我方系统/产品 | 订单系统 |
| 对方系统/组织 | 客户 WMS（厂商与版本待确认） |
| 对接目标一句话 | 订单下发至客户 WMS（范围与触发时机待确认） |
| 文档版本 / 日期 | **信息收集稿 v0.1 —— 不构成任何约定** |
| 我方接口人 | （待填） |
| 对方接口人 | 待双方确认 |
## 1. 场景与主流程
- 业务场景: 仅知「订单下发」，具体是全量推送还是按状态触发**未知**
- 主流程: 待确认后补
- 边界(不做): 本稿不做任何字段或时序约定；不代表我方已接受对接范围
## 2. 关键字段 / 数据流
| 字段或数据 | 方向 | 必填 | 说明 / 映射 | 状态 |
| --- | --- | --- | --- | --- |
| （未提供） | — | — | 对方 WMS 字段规范未知 | 待双方确认 |
（本表在获得对方接口规范前不填写推测字段。）
## 3. 责任
| 事项 | 我方 | 对方 | 备注 |
| --- | --- | --- | --- |
| 提供接口规范 | 待双方确认 | 待双方确认 | 取决于以谁的接口为准 |
| 环境与账号开通 | 待双方确认 | 待双方确认 | |
| 联调排期 | 待双方确认 | 待双方确认 | |
## 4. 联调窗口与验收
- 计划窗口: 待确认（对方排期未知）
- 环境: 待确认
- 验收标准: 待确认
## 5. 待双方确认（本稿主交付）
**A. 对接形式**
1. 以谁的接口为准：我方提供 API 由对方调用，还是对方提供接口由我方推送？
2. 传输方式：HTTP API / 文件（SFTP）/ 消息队列？
3. WMS 厂商与版本，是否有标准对接文档？
**B. 数据范围**
4. 下发哪些订单：全部还是特定类型/仓库？
5. 触发时机：下单即推、支付后推，还是定时批量？
6. 是否需要回传（出库状态、物流单号）？
**C. 技术约定**
7. 鉴权方式与凭据发放流程
8. 幂等与重试规则；重复下发如何识别
9. 单次量级与频率上限
**D. 项目信息**
10. 对方技术接口人与联系方式
11. 联调环境是否具备，期望上线时间
## 6. 风险与假设
- **当前无任何可用假设**；上述 11 项未回收前无法评估工作量与排期
- 风险: 若销售已对客户口头承诺时间点，需尽快澄清，避免基于未知范围做承诺
## 下一步
将第 5 节 A–D 四组问题发给对方接口人；回收后本稿升级为对接共识稿（如示例 1）。
对照要点：示例 1 有已知字段与口头分工，可产出可转发的共识稿；示例 2 一无所知，不编造对方 WMS 的字段名或能力，而是把问题按对接形式、数据范围、技术约定、项目信息四组结构化。文档标题与版本处显著标注「信息收集稿，不构成任何约定」，避免被对方当成我方已认可的方案。
常见问题(FAQ)
- 和 API 调用方变更通知有什么区别？ 变更通知面向已对接调用方的破坏性变更与迁移窗口；本技能面向首次/业务对接共识（场景、字段、责任、联调）。
- 字段不全能不能出稿？ 可以，但必须标「待双方确认」，不能编造对方字段名或能力。
- 能当合同附件吗？ 仅作技术/实施对齐草案；法律效力以合同为准。
已知限制
- 不生成可运行的 SDK 或网关配置。
- 不代替安全评审（鉴权、加密细节需专项）。
- 对方未确认的承诺一律待确认，不写进「已定」。
变更说明
- 0.1.1: 补「字段极少」迷你对照示例，演示信息不足时字段表整表标待确认、主交付转为按对接形式/数据范围/技术约定/项目信息四组结构化的信息索要清单，并在版本处显著标注「信息收集稿，不构成任何约定」。
- 0.1.0: 首发。把零散对接信息整理成一页集成说明（场景、字段、责任、联调窗口）。
