如何配置linkedDocuments(pushpin)使ACC Viewer显示Issue定位？

核心问题分析 #

你创建的Issue能在自身应用的Viewer中显示，但ACC文档查看器仅能看到列表却无标记，核心原因大概率是请求体参数不符合ACC Issue系统的3D位置要求，尤其是缺失externalId以及可能的类型/参数不匹配。

具体解决方案思路 #

1. 获取并补充externalId #

externalId是模型元素的全局唯一标识，ACC需要它来关联Issue到具体模型构件。获取方式如下：

• 确保模型加载完成后（可监听Autodesk.Viewing.GEOMETRY_LOADED_EVENT事件），调用Viewer的异步方法获取ID映射：

// 模型加载完成后执行
viewer1.model.getExternalIdMapping().then(mapping => {
  const externalId = mapping[object_id]; // object_id是你拿到的dbId
  // 拿到externalId后补入请求体的details中
});

• 补充后的details结构：

details: {
  position: position,
  objectId: object_id,
  externalId: externalId, // 新增这个字段
  viewable: {
    id: viewer1.model.getDocumentNode().data.guid,
    name: viewer1.model.getDocumentNode().data.name,
    viewableId: viewer1.model.getDocumentNode().data.viewableID,
    is3D: true,
  },
  viewerState: state,
}

2. 修正Pushpin类型 #

你当前用的TwoDVectorPushpin是2D文档的标记类型，对于3D模型，应该改用ThreeDVectorPushpin类型，确保和is3D: true的设置匹配：

linkedDocuments: [
  {
    urn: urn,
    createdAtVersion: parseInt(result[1], 10),
    type: "ThreeDVectorPushpin", // 替换为3D类型
    details: { /* ... 其他参数 ... */ }
  }
]

3. 验证viewerState的完整性 #

viewerState需要包含ACC查看器能解析的视角信息，确保调用viewerState.getState()时，Viewer处于正确的视角状态。如果返回的state缺少关键参数（如相机位置、目标点），可以手动补充核心字段：

const state = viewer1.viewerState.getState();
// 确保state包含以下核心相机参数
const validState = {
  camera: state.camera,
  viewport: state.viewport,
  seedURN: state.seedURN,
  objectSet: state.objectSet
};

4. 确认createdAtVersion的正确性 #

createdAtVersion必须是当前文档的最新版本号，如果版本不匹配，ACC查看器可能无法关联到正确的模型版本，导致标记不显示。可以通过ACC API获取文档的最新版本号来验证。

测试步骤 #

1. 按上述步骤修正请求体参数，确保externalId正确、类型为ThreeDVectorPushpin、viewerState完整；
2. 重新调用Issue创建API；
3. 刷新ACC文档查看器，检查标记是否显示。

内容的提问来源于stack exchange，提问作者Gustavo da Costa e Silva