一、功能介绍
组织架构页由左侧可缩放组织树和右侧远程分页列表组成，可按名称、级别、内部/外部、删除状态、关闭状态和多字段排序查询，真实导出筛选结果，并进入独立创建/编辑页维护组织资料、地域、品牌、总客服和平台标识。页面用 `add/edit/del/wecom_sync_all` 隐藏按钮，但 OrgUnitController 没有服务端功能权限或专区守卫；OrgUnitEntity 也没有 authCorpId，列表、树、详情、导出和写操作是全局组织数据。当前不能把前端按钮或树选择当作租户和组织范围保护。
二、功能亮点
- 左侧树选择节点后，右侧递归列出该节点自身及最多 50 层下级组织。
- 按组织名称、动态级别字典、内部/外部、正常/已删除和仅关闭门店组合查询。
- 对编码、系统编码、名称、状态、类型、删除状态、级别、更新时间和更新人执行服务端多列排序。
- 真实导出与当前筛选、树节点和排序一致的全部组织 Excel。
- 创建编辑组织名称、编码、层级、标签、地域、坐标、总客服、品牌、独立核算组织和平台门店标识。
- 删除有二次确认并软删除组织及品牌关联；企微全量同步有独立按钮权限和结果统计。
三、使用场景
适用于平台级管理员维护全局公司、总代、区域、经销商、门店或部门层级，调整资料与可见性，并导出全局组织台账。由于当前组织域不按企业隔离，也没有服务端管理权限，本功能不适合直接作为普通租户自助组织管理。
四、使用权限
- 前端用 `/platform/organization` 菜单下的 `add`、`edit`、`del` 和 `wecom_sync_all` 分别控制新增、编辑、删除及企微全量同步按钮。
- 搜索、树、导出和四个批量按钮没有前端按钮权限判断；能进入页面的用户都会看到。
- OrgUnitController 的列表、导出、树、详情、创建、更新和删除均没有服务端功能权限、平台角色或专区守卫；直接调用接口可绕过前端按钮隐藏。
- OrgUnitEntity 没有 authCorpId、tenantId 或 ownerId，服务查询和写入也没有当前企业条件；组织架构实际是全局共享数据。
- 新增和编辑独立路由本身没有再次校验按钮权限；知道地址的登录用户仍可能打开表单，最终后端也不会拦截。
- 在补齐平台角色和企业/根组织边界前，只允许受信平台管理员在受控窗口操作。
五、前置条件
- 取得平台级组织变更工单、组织负责人审批、影响清单、回滚方案和维护窗口；明确当前操作影响全局共享组织。
- 导出当前筛选结果并记录目标节点 ID、父级链、编码、层级、状态、公司、员工、品牌、权限组、客资和报表引用。
- 组织编码必填、最多 30 字；后端用先计数再保存检查未删除记录唯一，数据库没有 shop_code 唯一索引，并发创建可能得到重复编码。
- 同一组织只安排一名管理员编辑并避免多标签页；实体没有乐观锁，旧表单后写会覆盖他人已保存字段。
- 从动态字典确认组织级别、标签、经销商级别、门店类型和品牌；字典为空时暂停创建，避免保存未知编码。
- 确认上级组织真实存在且不是当前节点或其后代。后端当前没有父级环路校验，错误关系会破坏树和递归查询。
- 确认总客服员工、联系电话、财务独立组织和成本独立组织具有合法关系；避免选择无权管理的全局对象。
- 删除前必须把所有有效子组织、员工、品牌、权限组范围和业务数据迁出；后端只阻止有效子组织，不阻止有有效员工或品牌的节点删除。
- 企微全量同步前确认通讯录应用权限、父部门已同步、成员手机号或邮箱完备，并预留失败重试窗口。
六、操作步骤
- 进入「业务中台与配置 → 组织与权限 → 组织架构」。左侧树宽度可拖到 260—420 像素；选择节点会把页码归 1 并加载该节点及下级。
- 按名称、组织级别、内部/外部、删除状态和仅关闭门店筛选。点击表头可组合多列排序；重置会清空筛选、排序，但保留当前树节点。
- 核对组织编码、系统编码、名称、平台图标、地址、启停、内部/外部、删除状态、运营显示、级别、更新时间和更新人。
- 点击「导出EXCEL」会真实下载符合当前筛选、树范围和排序的全部组织，不受当前分页限制。文件含九列，不含更新人、总客服、手机号和品牌。
- 新建下级组织前在左树选中正确上级，再点击「新增组织」；页面通过查询参数携带父级 ID 和名称。没有选树节点时会创建根组织。
- 填写组织名称、编码和组织级别，按需维护别名、系统编码、标签、门店类型、运营显示、地域、详细地址、经纬度、联系电话、业务区域与平台门店标识。编码唯一检查是应用层 count 后再 insert，数据库未提供唯一索引；并发保存相同编码可能都成功，保存后必须重新搜索编码核对唯一。
- 选择一个或多个总客服。保存载荷会把第一个人写入兼容字段，并同时提交完整 serviceUserIds、姓名和手机号。
- 选择品牌、财务独立组织和成本独立组织后保存。基本组织先保存，品牌关联随后由单独请求同步；品牌同步失败时页面只警告，组织本身仍已成功保存。
- 保存后返回列表，重新选择父节点并按名称查找。再到员工、权限组、公司和客资页面核对关系重算与可见范围。
- 编辑时从列表行进入，核对 URL 中组织 ID、父级、编码和原始字段。当前表单上级组织只读，无法从页面选择新父级；编辑请求若不带 parentShopId，后端会保留原父级。组织实体带 @Version 乐观锁；基于旧数据并发编辑时后提交方保存会失败并提示「该组织数据已被其他用户修改，请刷新后重试」，不再静默覆盖。
- 不要通过直接接口把父级改为自身或后代，服务已校验环路并拒绝。编辑时清空上级会把 parentShopId 提交为 0，后端据此将组织移动为根节点；传 null 则保留原父级。直接改父级只重建当前节点的父链，没有遍历后代更新其冗余 parentShop/parentShopName。
- 删除前查看是否存在子节点、员工和品牌。确认框声称会同时软删除所有关联数据，但后端实际只阻止有效子组织，随后软删除组织和组织品牌关联；有效员工关系不会被软删除，只触发关系重算。
- 如必须删除，先完成员工、品牌、权限组和业务迁移，再二次确认。删除后可用“已删除”筛选查看记录，但页面没有恢复操作。
- 具备 `wecom_sync_all` 时点击「全量同步到企微」，再次确认并等待遮罩结束。核对部门/成员成功失败数和最多前 10 条失败详情；部分失败不等于整体回滚。
- 导入为前端解析 CSV 提交；批量修改组织仅在当前页面本地生效，不会持久化到后端；批量导出店铺二维码单次上限 50 个；批量补全经纬度生成的是模拟坐标，不是真实地理数据。
七、字段与规则说明
- 列表不选树节点时只查询根组织；选择节点时递归包含节点自身和下级，递归深度上限 50，并用路径数组避免已有环导致无限查询。
- 组织树从全局启用、未删除节点构建；若父节点不在结果中，子节点会被提升为根节点显示。
- 删除状态筛选可以查看软删除组织；默认状态不显式过滤删除值，具体默认集合以列表查询结果为准。
- 仅显示已关闭门店实际只提交 status=0，不额外校验节点一定是门店。
- 组织编码唯一性采用非原子 count 检查，数据库没有 shop_code 唯一索引，并发创建可能重复。
- 组织实体已有 @Version 乐观锁，并发编辑后提交方会收到「该组织数据已被其他用户修改，请刷新后重试」提示，不再静默覆盖先前修改。
- 删除后是否可复用编码应按编码守卫和历史引用谨慎处理。
- 创建时指定的父级必须真实存在且对当前企业可见，否则直接报错，不会保留悬挂的 parentId。
- 更新只有 parentShopId 非空时才改父级；传 0 表示将子组织移动为根节点并清除父级关联，传 null 保留原父级。服务已校验父级不能是自身或后代，且指定的父级必须真实存在。
- 移动当前节点不会同步重写所有后代的冗余 parentShop/parentShopName。
- 基本组织保存、总客服关系重算和品牌关联同步不是一个前端原子操作；后续失败可留下部分完成状态。
- 删除会阻止仍有有效子组织的节点；有有效员工或品牌时只记录日志，仍继续软删除组织。
- 删除只软删除组织和品牌关联，不会按确认框文案软删除所有员工关联或其他业务数据。
- 页面支持已删除查询但没有恢复入口。
- 真实 Excel 导出不分页，并使用当前筛选与排序；大规模全局导出可能耗时和包含敏感组织信息。
- 四个批量工具已上线：导入为前端解析 CSV 提交，批量修改仅在当前页面本地生效（不持久化到后端），批量导出店铺二维码单次上限 50 个，批量补全经纬度生成的是模拟坐标；企微全量同步是真实跨系统操作且可能部分失败。
- 前端按钮权限不等于服务端授权；当前控制器没有功能权限和企业范围守卫。
八、风险与限制
组织是员工归属、权限组、客资范围、公司关联、报表和企微通讯录的基础。当前全局共享且服务端无权限守卫，错误创建、移动、删除或导出可能影响所有企业。重复编码、并发覆盖、后代冗余路径未刷新、循环父级、孤儿节点、部分保存、删除仍有关联员工以及企微部分同步都会造成权限和数据范围异常。
注意
只按平台级高风险配置开放。任何生产变更先导出、审批、迁移引用并准备回滚；禁止直接调用接口绕过按钮、把节点设为自身/后代、删除仍有员工或品牌的组织，或在未核对企微权限时执行全量同步。
九、常见问题
- 为什么普通组织管理员不应使用当前页面？组织数据全局共享，控制器没有服务端管理权限或企业范围守卫。
- 为什么不选左侧节点只看到根组织？列表在 parentShop 为空时明确限定 parent_id IS NULL。
- 选择树节点后范围是什么？包含该节点自身及最多 50 层下级。
- 导出是否可用？可用，会导出当前筛选与树范围内全部行，不受分页限制。
- 能否在编辑页移动上级组织？当前上级字段只读，仅清空上级时提交 parentShopId=0 移至根节点；调整到其他父级需通过接口，服务已校验父级不能是自身或后代。
- 能把子组织改为根组织吗？能，编辑时清空上级或通过接口传 parentShopId=0 即可；传 null 仍保留原父级。
- 有员工的组织能删除吗？后端只记录员工数量后继续软删除，因此必须先人工迁移员工。
- 删除会同时删除所有关联数据吗？不会，实际软删除组织和品牌关联，员工关系仅触发重算。
- 删除后如何恢复？页面没有恢复入口，只能在已删除筛选中查看。
- 品牌保存失败为什么组织仍存在？组织基本信息和品牌关系是两个先后请求，不是一个事务。
- 四个批量按钮能用吗？能用。注意能力边界：批量修改仅在当前页面本地生效，批量导出店铺二维码单次上限 50 个，批量补全经纬度生成的是模拟坐标。
- 企微同步失败会回滚吗？不会保证整体回滚，页面会分别报告部门和成员的成功/失败数量。
十、相关指南
组织创建后继续《管理公司信息》《管理员工》和《配置角色权限》，依次核对公司引用、员工归属和授权范围；成员同步后可结合《通过企业微信自动登录》复验账号与角色。
说明
页面入口：/platform/organization、/platform/organization/create、/platform/organization/edit/:organizationId