千问办公旗舰版怎么同步飞书成员

　　飞书里的部门和成员资料，可以通过用户同步导入千问办公，省去逐个录入的操作。同步会读取企业自建应用有权访问的通讯录；应用是否发布、数据范围怎么设置，都会影响最终能导入哪些成员。

一次性申请清单

　　在「权限管理」中开通以下应用身份读取权限，并设置可访问的数据范围。下表按部门、成员及当前映射字段拆分，便于一次提交申请。

权限名称	权限代码	何时需要
获取通讯录基本信息	contact:contact.base:readonly	读取通讯录基础信息
获取部门基础信息	contact:department.base:readonly	部门标识和名称
获取部门组织架构信息	contact:department.organize:readonly	部门层级与上级关系
获取用户基本信息	contact:user.base:readonly	用户标识和姓名
获取用户组织架构信息	contact:user.department:readonly	成员所属部门
获取用户邮箱信息	contact:user.email:readonly	需要将邮箱同步到千问办公时申请
获取用户手机号	contact:user.phone:readonly	需要将手机号同步到千问办公时申请
获取用户受雇信息	contact:user.employee:readonly	需要将工号或在职状态同步到千问办公时申请
获取用户 user ID	contact:user.employee_id:readonly	需要使用飞书 user_id 作为千问办公的三方 ID 等身份字段时申请

　　请一次准备好以下信息：

　　企业与应用：企业名称、应用名称、App ID、App Secret。

　　权限与发布：权限开通结果、已发布的应用版本。

　　访问范围：通讯录数据权限设置为全部成员，并确认应用可用范围。

　　核验资料：一名普通成员的 user_id，以及预期同步的成员资料。

　　权限、通讯录数据范围和应用发布状态须同时生效。千问办公会从飞书根部门读取组织，因此通讯录数据权限必须选择「全部成员」。不要把应用可用范围当成通讯录数据权限，也不要只授权一个测试部门。

准备飞书应用

　　1. 进入飞书开放平台的【开发者后台】，创建或打开企业自建应用。

　　2. 打开「权限管理」，按权限代码搜索并申请：contact:contact.base:readonly、contact:department.base:readonly、contact:department.organize:readonly、contact:user.base:readonly、contact:user.department:readonly。对应名称见上方清单。

　　3. 若需要将飞书成员的邮箱同步到千问办公，则申请 获取用户邮箱信息（contact:user.email:readonly）。

　　4. 若需要将飞书成员的手机号同步到千问办公，则申请 获取用户手机号（contact:user.phone:readonly）。

　　5. 若需要将飞书成员的工号或在职状态同步到千问办公，则申请 获取用户受雇信息（contact:user.employee:readonly）。

　　6. 新建来源时，页面默认使用飞书 user_id 作为千问办公的三方 ID，因此申请 获取用户 user ID（contact:user.employee_id:readonly）。成员请求固定按 user_id 读取，即使改选其他 ID，也不能省略该权限。

　　7. 在「权限管理」中打开通讯录权限范围设置，选择「全部成员」并确认。当前实现从根部门读取，选择部分成员会造成组织和成员不完整。

　　8. 进入应用版本设置，打开「可用范围配置」，选择「全部成员」或覆盖所有实际使用该应用的成员。这里控制谁能使用应用，与上一步的数据读取权限不同。

　　9. 在「凭证与基础信息」记录 App ID 和 App Secret。

　　10. 在 版本管理与发布 → 版本管理 创建版本并发布。新增权限后，确认本次发布已包含这些权限。

　　千问办公从飞书读取通讯录。完成上述读取权限申请即可，无需申请通讯录写入权限。

建立飞书数据源

　　1. 在千问办公进入 用户与体验 → 用户管理 → 用户同步，点击【新增数据源】。

　　2. 选择「飞书」，点击【开始配置】，填写 App ID 和 App Secret。

　　3. 点击【测试并下一步】。新建时，成功后保存当前配置草稿并进入映射设置；编辑已有数据源时，仍需完成最后一步保存。该测试只交换访问令牌，不读取部门或成员，也不能证明通讯录权限和字段已经正确。

核对飞书 ID 和部门关系

　　核对飞书字段及 ID 类型后保存。成员的来源字段可从飞书支持的字段中选择，右侧目标固定；部门映射通常使用预设来源。删除可选行后，可在【添加映射】下拉重新选择目标，恢复对应的飞书预设字段。

配置页预设的来源字段	用途
user_id	默认对应第三方用户 ID；应与飞书 SSO 的身份关联保持一致
name、email、mobile	对应用户姓名、邮箱、手机号
employee_no、open_id	分别默认对应工号、账号，按企业实际资料检查
department_id	成员所属部门的第三方部门 ID
部门 open_department_id、parent_department_id	部门唯一标识和上级部门标识

　　检查成员返回的部门 ID 与部门列表使用的 ID 类型相同。飞书同时存在多种用户和部门 ID，不应仅因为字段名称相似就互换。邮箱默认读取 email。

　　必填映射确认后点击【下一步】。如果成员没有邮箱，先确认是否因权限导致；不要立即把空值当成成员未填写。

设置同步方式并核验结果

　　1. 在「同步范围」选择「全部」或「指定部门及后代」，并设置「新用户默认申请席位」。这里是千问办公实际应用的范围，飞书平台仍须提供全部成员的通讯录数据权限。

　　2. 选择“仅手动”；需要自动执行时，选择“定时同步”，再选“每天”并设置北京时间。通常先手动执行一次核对结果。

　　3. 在「删除处理」中选择仅停用、停用并回收席位，或删除并回收席位。设置告警阈值与邮箱后保存。

　　4. 在数据源列表启用飞书，点击【立即同步】。

　　5. 打开这次同步记录的【详情】，检查用户数量、部门层级和席位变化，再到「用户」页面抽查一个跨部门成员。

　　6. 在飞书修改一名核验成员的部门后再同步，确认更新的是原用户，没有新增重复账号。

维护与排障

　　只有部分部门导入： 对比飞书的通讯录数据范围、应用可用范围以及千问办公选择的范围。

　　部门关系错误： 检查 department_id 与 open_department_id 的实际值是否对应，补齐上级部门。

　　应用发布后仍缺字段： 检查新版本包含的权限，以及相关权限的数据范围。

　　离职处理数量异常： 停用数据源并查看同步详情，先排除权限收缩或字段缺失，再继续同步。

　　更新 App Secret 时，编辑原数据源、重新测试并保存。同步开关只控制数据同步；飞书登录在飞书 SSO单独配置。

与已有用户衔接

　　同步前，先核对来源中的三方 ID 与已有用户一致。

　　匹配用户： 只通过三方 ID 查找。账号、邮箱、手机号和工号用于冲突校验；三方 ID 未命中，但其中任一值已被占用时，本条同步失败。

　　更新成功： 保留原 QID，并将当前维护来源设为这份数据源。

　　锁定资料： 来源开启期间，该来源用户的姓名、邮箱、账号、手机号、三方 ID、工号均不可手动修改；部门和状态按映射锁定。

　　删除后再出现： 不恢复旧 QID。系统按当前飞书资料创建新用户和新 QID，计为“创建”；旧历史保留，三方 ID 改为关联新用户。新用户不继承旧角色、密码、用户组、管理员权限、席位或部门，默认席位按当前数据源设置处理。