docs/平台客户层级与权限契约.md

平台、客户层级与权限契约

产品层级

• 当前产品只面向“平台、客户（企业）”两级，不把“租户”作为用户可见或需要运营选择的产品层级；多租户产品能力后续另行设计。
• Admin 页面、菜单、筛选、表单和提示统一使用“客户”或“企业”文案，不新增“租户选择器”“目标租户”等交互。
• 平台仓库属于平台公共主数据，不与客户绑定。托盘、库位等仓储资源页面应能独立查询全部客户和全部仓库，客户筛选不得控制仓库候选范围。
• 后端仍存在 tenantId 等字段时，只作为现阶段接口隔离细节保留在 API 适配层，不据此扩展用户可见产品层级；改动真实隔离模型前仍需单独确认。

Admin 菜单与只读权限

• 统一语义是“列表权限包含详情只读访问，操作权限独立”。存在正式列表页时，以稳定的 *:list 权限作为菜单、列表路由、详情路由、列表接口、详情接口及只读辅助接口的主权限。
• create、edit、delete、status、approve、review、export、upload、complete 等会改变数据、状态或产生文件的操作继续使用各自独立权限，不得因拥有 list 自动放行。
• 当前尚未上线；同一资源已有 *:list 时，不保留或新增独立 *:view 兼容分支。前端不得使用 permissionAnyOf 接受旧 view，后端不得使用 hasAnyAuthority(list, view)，初始化 SQL 应停用或删除旧 view 资源及其角色关联。
• 供应商固定使用 platform:supplier:list 作为菜单、列表和详情唯一只读权限；platform:supplier:view 必须停用或移除，不得在导航、路由、页面、Controller、OpenAPI 或 SQL 中恢复兼容。

Admin 菜单结构与显示

• 一级、二级菜单的名称、分组和顺序以当前确认原型及当前对话确认为准，唯一代码入口为 apps/admin-web/src/core/navigation/adminNavigation.ts。一级结构为首页数据看板、客户管理、国内头程、货柜管理、海外尾程、预约管理、车辆管理、海外业务、客户服务、财务管理、自营业务、通用、系统管理；二级菜单统一在该入口维护，实际显示继续由权限过滤。
• 自营业务的经营总览、销量分析、库存分析、数据采集四个页面统一使用 platform:self-operated-analytics:list，包括任务详情只读和运行辅助查询；重试独立使用 platform:self-operated-analytics:sync，库存周转后台导出使用独立 platform:self-operated-analytics:export，下载中心创建、下载及重试均校验该导出权限和非代登录平台身份。IAM 菜单管理资源不替代上述实际读写授权，不能仅凭采集写权限打开只读页面。
• 已实现菜单继续使用正式路由及服务端权限，不因改名、移动或仅调整菜单结构改变接口、状态和操作资格。当前原型未展示的既有入口通过 hidden 退出侧栏，正式路由和权限仍按现行合同管理；角色权限设置仍保留这些正式页面及操作的可分配权限。
• 供应商列表按当前确认保留在“通用”分组，使用正式路由 /suppliers 与 platform:supplier:list，不因原型未展示而隐藏；新增、编辑及其他写操作继续使用各自独立权限。
• 尚无正式页面的菜单不显示，不保留禁用占位或空分组，不接入原型假数据、虚构权限码或新增业务接口。后续功能实现时再核对正式页面、权限与服务端合同。

跨层同步

• 菜单结构、路由权限、页面按钮、Controller @PreAuthorize、OpenAPI 权限说明及 IAM 初始化/统一增量 SQL 必须同步核对，不能以局部测试通过替代跨层一致性。
• 业务功能任务只维护所属页面与接口，不得根据局部旧上下文覆盖共享导航、根路由装配、IAM 菜单权限初始化或统一增量脚本中的已确认语义。
• 发现共享文件与本契约冲突时，保留现有其他任务改动并交由对应总控统一收口；只有用户当前明确改变本契约时才能调整。

维护入口

• 前端执行入口：../apps/admin-web/AGENTS.md、../apps/client-web/AGENTS.md。
• 后端执行入口：../baiyue-firstleg/iam/AGENTS.md、../baiyue-firstleg/auth/AGENTS.md 及目标业务服务最近的 AGENTS.md。
• 本文件维护稳定产品语义；具体权限码、菜单路径、Controller 和 SQL 路径由最近的项目或模块索引维护。