发起设备分享（V1 视图）
验证状态：已源码核验、未联调（无 app 调用图）；services 基线：源码归纳 @ 2026-09-14
用途与场景
V1 retail 视图的分享发起端点，是第一代发起设备分享的增强入口：新增联系人三选一（用户名 / 邮箱 / 手机号自动识别）与分享数量上限校验，并返回解析后的目标用户名。App 分享页的「输入联系人（任意形态）→ 确认分享」交互推荐走本端点；受赠方确认、发起方撤销、受赠方解除仍分别走 confirm-share、cancel-share、lift-share（v1 无对应物）。
本页同时吸收旧文档站 retail 树 share.mdx（「添加共享」）的释义，过时处按下文「旧文甄别」标注。
App 现役依据
| 判定证据 | 内容 |
|---|---|
| 旧 app 文档收录记录 | 旧文档站 retail 树曾为 /main-api/v1/retail/device/data-acquisition-device/share 建页（本仓 git 历史 share.mdx），说明 App 新客户端已按 v1 路径对接分享发起 |
| 两代分工语义 | 本端点最终转调第一代 shareForPersonalSpace 同一 service 实现；新客户端读列表/详情与分享发起走 v1（响应裁剪 + 联系人三选一 + 分享上限），两代并存均为现役 |
| 后端持续维护迹象 | v1 行为由 DataAcquisitionDeviceControllerLegacyCompatibilityTest 等契约测试钉住并持续维护 |
端点
POST /main-service/main-api/v1/retail/device/data-acquisition-device/share — V1 retail 视图的分享发起端点。
端点全量事实（参数、请求/响应字段、错误码、权限点）见清单层 device · v1-retail 零售接口（v1）；业务语义（wire 惯例、限频、租户声明等）见设备业务 · v1-retail 零售接口（v1）。
动线与完成判据
status=200 且 data=true、extraData.targetUsername 为解析后的用户名，表示发起完成。后续判据与第一代一致（受赠方设备列表可见待确认条目、发起方分享记录可见 inviteTime）。
联系人三选一识别与分享上限：服务端只对 targetUsername 做形态识别（含 @ → 邮箱、纯数字 ≥7 位 → 手机号、其余 → 用户名），随后按用户名 → 邮箱 → 手机号顺序反查；分享上限（配置 device.share.limit，默认 10）只统计已确认分享、校验先于重复分享守卫，超限 extraData 携带数值上限与未插值模板。完整识别规则、反查失败错误与上限语义见设备业务 · v1-retail 零售接口（v1）。
错误与边界
业务失败均为业务拒绝族（判定口径见错误响应差异），完整错误码与触发条件清单（10 项，含超限 extraData 结构与 Bean Validation 出口）已收录设备业务 · v1-retail。识别歧义（含 @ 的字符串一律按邮箱处理，即使它同时也是合法用户名）由 App 侧输入约束消化。
旧文甄别（share.mdx 吸收结论）
本页吸收旧文档站 retail 树 share.mdx（80 行，git 历史）时的逐项甄别：
- 保留：请求路径、请求字段释义（
deviceId设备标识、三选一至少一个不为空的约束）、错误码中的Unable to share with oneself、The user corresponding to the shared username does not exist、Sharing users have no personal space、Device sharing already exists、The data collection device does not exist、The data collection device shared with the user already exists、Incorrect email、Incorrect phone number、At least one of targetUsername, targetEmail, and targetPhoneNumber is not empty——均与现源码相符。 - 修正：
deviceManage释义「共享者用户名」按后端 CONTEXT.md 术语修正为「设备管理标记（表示分享者用户名、用于展示与通知归属的非权威标记）」；错误码The user corresponding to the shared email does not exist/The user corresponding to the shared phone number does not exist现源码已不存在（全仓检索无对应实现），现行为Incorrect email/Incorrect phone number。 - 补录：分享上限错误
Device share limit reached, maximum N shares allowed及extraData结构为旧文未列、按现源码补录；联系人三选一的识别细则与反查顺序旧文未展开，按现源码补全。 - 弃用：页首 LinkCard 外部 OpenAPI 链接与 modao 原型链接不带入（按 spec 弃用外部链接组织模式）。
调用关系与资源清理
无客户端长连接资源需要释放。本端点为第一代分享发起的薄增强层，成功后的双方列表刷新语义与发起设备分享一致。
已知缺口
未执行真实联调：邮箱/手机号反查缓存的失效时延、上限计数在高并发发起下的竞态窗口均无 App 实测佐证。App 侧应对业务页错误清单之外保留未知码兜底分支。