用 TOC 提供业务入口

TOC（Table of Contents）是 Aras 客户端的导航结构。它帮助不同角色找到 ItemType、页面或业务入口，但不负责授予数据权限。一个按钮消失不代表数据被保护；一个按钮出现也不代表用户能够查询或创建 Item。

本章把 acme_equipment 放入“设备管理”分类，并用普通测试账号验证。

适用范围

操作模型以 R31《Configuring Solutions Student Guide》的 TOC 单元为基线。
编辑器入口、按钮名称和 CUI 集成会随 Release 变化。
本章只讨论 TOC 导航；命令栏、右键菜单和按钮行为见 CUI。

前置检查

在配置 TOC 前，确认：

acme_equipment 已保存且可以由管理员打开；
目标 Group Identity 已存在；
该 Identity 有需要的 Can Add 与 Permission；
新增定义会被加入正确的 Package Definition。

如果权限尚未完成，先阅读 Identity 和 Permission。

第 1 步：打开 TOC Editor

以 R31 英文训练环境为例，从管理配置区域打开 TOC Editor。若你的菜单路径不同，使用管理员搜索或目标 Release 帮助查找，而不要新建一个同名自定义入口。

打开后先确认当前编辑的是开发环境，并记录目标父分类和排序方式。

第 2 步：创建分类

在计划的父节点下创建 Category。
Label 设为“设备管理”。
配置目标用户可见的 Access/Identity 范围。
设置与现有分类一致的图标和排序。
保存并重新打开编辑器，确认层级没有意外移动。

优先把访问主体设置为业务 Group Identity，而不是个人 Alias Identity。人员变化时，只需维护组成员关系。

第 3 步：添加 ItemType 入口

在“设备管理”下添加 ItemType 入口：

配置	值
ItemType	`acme_equipment`
Label	设备
Access	设备维护角色对应的 Group Identity
Icon	项目统一的受支持图标资源

将入口与分类一起加入 Package Definition。不要只打包 ItemType；否则目标环境可能有数据模型，却没有导航入口。

不要写死“Access 只能配置一个 Identity”

TOC 元数据和编辑器表达方式可能随 Release 变化。若多个角色需要同一入口，优先通过上层 Group Identity 聚合成员，并在目标系统实际检查生成的访问关系。

第 4 步：用真实账号验证

使用不属于 Administrators 的测试账号执行：

登录后能看到“设备管理 → 设备”。
点击入口可以打开正确的搜索/列表页面。
现有设备是否可见符合 Discover/Get。
New 是否可用符合 Can Add。
直接访问 Item URL 时，权限结果与从 TOC 进入一致。

编辑器的预览或 View As 功能适合快速检查，但不能代替真实登录。嵌套 Identity、缓存、客户端状态和数据 Permission 都需要端到端验证。

可见性与授权的关系

text

TOC Access     决定“入口是否出现在导航中”
Can Add        决定“能否创建该 ItemType”
Permission     决定“能否发现、读取、更新、删除具体 Item”
CUI            决定“命令和按钮如何出现或执行”
Server logic   强制额外业务规则

只隐藏 TOC 的后果是：用户可能仍能通过搜索、链接、API 或其他关系进入数据。安全评审必须从具体 Item 的服务器权限出发。

分类与入口怎么组织

好的 TOC 按用户任务组织，而不是照搬技术对象清单：

“我的工作”放待办和高频入口；
“设备管理”放设备、校准计划和文档；
低频管理员定义放在单独受限区域；
同一 ItemType 可以因角色任务不同出现在不同位置，但要避免重复和名称歧义。

不要把所有自定义 ItemType 平铺在一个巨大分类中。TOC 是用户的信息架构，也是培训和权限排错的第一入口。

图标问题如何排查

旧资料把“TOC icon 不显示”直接归因于 URL 长度，并建议把 IIS 限制放大到极端值、覆盖整个 web.config。这种处理没有证据且会扩大攻击面，不应使用。

正确顺序：

在浏览器 Network 中记录图标请求 URL、HTTP 状态和响应类型。
检查资源是否存在、当前用户是否可读、CSP/代理是否拦截。
对照 IIS/Kestrel 日志确认是 404、401/403、414 还是其他错误。
对照目标 Release 安装指南和已知问题。
只有确认请求限制是根因时，才用最小 XDT/配置变换修改，并准备回滚。

不要复制包含 Windows Authentication、连接信息或巨大 maxQueryString 的整份配置文件。

打包与升级验证

TOC 调整至少应包含：

Category/入口定义；
引用的 ItemType；
Access 使用的自定义 Identity（若属于解决方案）；
自定义图标资源；
相关 CUI 配置。

导入到空白验证环境后，用相同角色重新测试，避免开发环境中“恰好已有”的依赖掩盖问题。

TOC 验收清单

[ ] 导航按用户任务组织
[ ] Access 使用稳定的 Group Identity
[ ] 普通账号实际登录验证
[ ] Can Add 与数据 Permission 单独验证
[ ] 直接 URL/API 不能绕过数据权限
[ ] 图标资源与 CUI 依赖已打包
[ ] 未通过覆盖整份服务器配置解决显示问题
[ ] 导入干净环境后复测

下一步

依据

Aras Training, Configuring Solutions Student Guide Innovator R31, TOC 与 CUI 单元
Aras Documentation Library
Aras Innovator 35 Configurable User Interface Administrator Guide

用 TOC 提供业务入口 ​

前置检查 ​

第 1 步：打开 TOC Editor ​

第 2 步：创建分类 ​

第 3 步：添加 ItemType 入口 ​

第 4 步：用真实账号验证 ​

可见性与授权的关系 ​

分类与入口怎么组织 ​

图标问题如何排查 ​

打包与升级验证 ​

下一步 ​

依据 ​