界面定制契约

这份说明描述当前渲染器实际支持的结构，字段细节仍由 CPQ 服务端验证。

产品配置页（surface=configuration）

读取响应 data 是目录管理状态，含 version、publishedVersion、catalog、hasDraft。 编辑 catalog.configurationLayouts；必须保留目录其他字段和其他型号布局。保存／发布 body 为 {version,catalog}。 预览 body 为 {catalog,modelId,attributeValues?,arrayValues?,selection?,selectedProducts?,productQuantities?}。检查 errors、规则消息、layout 及计算结果；预览返回 HTTP 成功不代表所选配置没有业务错误。

布局包含 id,name,modelId,status,flowId,title,orientation,maxWidth,summaryAttributes,views。 status 为 active/internal/inactive，orientation 为 horizontal/vertical，maxWidth 为 600～2400。 modelId 必须来自目录型号；flowId 若有必须属于同一型号。

布局树：view → grid → row → column → 叶子或嵌套 grid。各节点的 id 在布局内唯一。 view 包含 key,name,status,children；grid 有 name,children；row 有 children；column 有 width,children。 叶子类型：attribute、array、section、action、bom、spacer、text、metadata、image、component、customUI。 引用节点的 ref 必须来自当前型号有效定义：属性／数组／动作使用 key，商品类别使用 section id。 必填属性、必填数组和必选类别必须保持在无日期限制的 active 视图中；不能通过隐藏布局绕过校验。

自定义 HTML/CSS/JavaScript

customUI 节点有 html,css,javascript,height,enabled,attributeAccess,actionAccess。 每段代码最多 50000 字符，height 为 80～1200；代码作为目录数据，在浏览器沙箱中执行。 HTML 不允许 script、iframe、form、外部资源、事件属性；脚本和样式使用独立字段。 示例授权：attributeAccess:[{key:"实际属性key",write:true}]，actionAccess:["实际动作key"]。 仅支持有效的独立、非签名属性；不可写只读属性。 脚本使用现有桥接 API，如 CPQJSReady(() => CPQJS.getAttributeVal("实际属性key"))。 不能用自定义组件直接调用内部服务、提升权限或修改服务端计算结果。

报价页（surface=quote）

读取响应 data 是管理状态，含 version,publishedVersion,data,standard,requiredBlocks,models,steps,groups,templates,people。 其中内层 data 为 {scenarios,layouts}。保存／发布 body 为 {version,data}。 预览 body 为 {data,quoteId,userId,stage?,stepId?,scenarioId?}，quoteId 来自已有报价，userId 来自启用账号。 只读预览以该账号的权限隐藏金额及字段，返回 quote.quoteLayout 与运行时数据。

每个布局有 id,name,active,priority,roles,groupIds,stages,stepIds,scenarioIds,modelIds,top,defaultTab,tabs,presentation。 先复制读取到的既有布局或 standard 再修改；standard 是保留 id，新布局必须换 id。 优先级数字小的先匹配。角色／用户组、状态、步骤、场景、型号决定匹配范围，不改变账号权限。 top 是顶部组件数组，tabs 是 {id,name,blocks} 数组，defaultTab 引用已有页签。 组件包括 customer、configurations、configuration、commerce、pricing、lines、totals、approval、documents、bom。 必须保留 requiredBlocks 中各项，每个组件只放置一次。

presentation 管理字段分组、明细列、动作位置、汇总位置及显示条件。沿用当前读取到的键和字段引用； 配置中的显示不等于授权。不要把报价页当作任意 HTML 页面上传：当前报价页由这些组件和元数据驱动。

验证生效

草稿预览不写报价。发布后 configuration 用 configure.run 检查实际 layout；quote 用 quotes.get 检查 quoteLayout。 历史产品定义、价格及商业快照仍由原 CPQ 机制保持；改界面不应自动重配或重算历史报价。