package cn.iocoder.yudao.module.qcreport.dal.dataobject.version;
|
|
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
import lombok.Data;
|
|
import java.util.List;
|
import java.util.Map;
|
|
/**
|
* 报告模板 Schema —— 设计器产物，也是报告出件的唯一输入。
|
* <p>
|
* 模板不保存裸 HTML。保存的是「画布数据 + 业务语义」，由渲染引擎据此生成 HTML，
|
* 这样同一份模板在不同渲染环境下产物一致，也才有可能做服务端 Sanitization。
|
*
|
* <h3>字段分工</h3>
|
* <table>
|
* <tr><td>{@link #grapes}</td><td>GrapesJS 原始项目数据。设计器靠它无损还原画布，<b>渲染引擎也读它</b>（正文结构在这里）</td></tr>
|
* <tr><td>{@link #components}</td><td>质量组件业务语义清单。渲染不读，供设计器定位组件、供后续 AI 生成模板时理解结构</td></tr>
|
* <tr><td>{@link #rules}</td><td>判定规则。渲染前由判定器求值，决定每项 PASS/FAIL 与报告结论</td></tr>
|
* <tr><td>{@link #page}</td><td>纸张与页边距，渲染时换算成 CSS {@code @page}</td></tr>
|
* </table>
|
*
|
* <h3>语义层是<strong>有意的子集</strong>（重要）</h3>
|
* {@link #components} 只表达「用已注册的质量组件搭出来的扁平结构」，
|
* <b>不表达任意 HTML</b>——用户手工拖进画布的裸表格、自定义 div 不在其内。
|
* 这是有意收窄的边界，不是实现疏漏：有这条边界，AI 生成模板时才能被约束成
|
* 「只能用已注册组件当积木」，而不是吐一段谁也不敢渲染的 HTML。
|
* 任何「给语义层加个万能 customHtml 字段」的改动都在拆这条边界，需要先讨论。
|
*
|
* <h3>兼容性</h3>
|
* <p>
|
* {@code schema_json} 列里已经存着含 1.0 字段（dataSources / bindings / styles）的历史 JSON，
|
* 所以这里显式标注 {@link JsonIgnoreProperties} 容错。
|
* <p>
|
* 说明一句，免得后人以为它必不可少：<b>去掉这个注解，兼容性测试也是绿的</b>——
|
* 读库那条链路用的 {@code Jackson3TypeHandler} 自己 new 的 ObjectMapper，
|
* 而 Jackson 3 的 {@code FAIL_ON_UNKNOWN_PROPERTIES} 默认就是关的。
|
* 真正需要它防的是另外两条：Spring 反序列化请求体时用的 ObjectMapper（配置不受本模块控制），
|
* 以及将来有人给类型处理器换一个更严格的 Mapper。留着是把意图写明，不是摆设。
|
*
|
* <h3>版本历史</h3>
|
* <ul>
|
* <li><b>1.0</b>：初版。含 dataSources / bindings / styles 三个字段，但它们始终是空数组，
|
* 既无人写入也无人读取，属死数据。</li>
|
* <li><b>1.1</b>：删除上述三个死字段，{@code components} 由 {@code Map} 改为强类型
|
* {@link QualityComponentNode}。因死字段原本就恒为空数组，1.0 → 1.1 无需数据迁移。</li>
|
* </ul>
|
*/
|
@Data
|
@JsonIgnoreProperties(ignoreUnknown = true)
|
public class ReportTemplateSchema {
|
|
/**
|
* 当前 Schema 版本号。
|
* <p>
|
* 与前端 {@code designer/constants.ts} 的 {@code SCHEMA_VERSION} 必须一致：
|
* 两端各写一份是历史原因（后端不参与设计器构建），改这里就要同步改那边。
|
*/
|
public static final String SCHEMA_VERSION = "1.1";
|
|
/**
|
* Schema 版本，用于后续兼容升级
|
*/
|
private String schemaVersion;
|
/**
|
* 纸张与页边距配置
|
*/
|
private Page page;
|
/**
|
* GrapesJS 原始画布数据（保留以便设计器无损还原）
|
*/
|
private Map<String, Object> grapes;
|
/**
|
* 质量组件业务语义清单，按文档顺序排列
|
*/
|
private List<QualityComponentNode> components;
|
/**
|
* 判定规则定义。
|
* <p>
|
* 元素形状为 {@code {id, name, scope, expression, enabled}}，由
|
* {@code QualityRuleDefinition.from(Map)} 宽松读取——历史数据里可能有缺字段的规则，
|
* 读不动的跳过而不是让整份模板打不开。
|
*/
|
private List<Map<String, Object>> rules;
|
|
/**
|
* 纸张与页边距配置
|
*/
|
@Data
|
public static class Page {
|
|
/**
|
* 纸张尺寸：A3 / A4 / A5 / Letter
|
*/
|
private String size;
|
/**
|
* 纸张方向：portrait / landscape
|
*/
|
private String orientation;
|
/**
|
* 页边距，单位 mm
|
*/
|
private Margin margin;
|
|
}
|
|
/**
|
* 页边距，单位 mm
|
*/
|
@Data
|
public static class Margin {
|
|
private Double top;
|
private Double right;
|
private Double bottom;
|
private Double left;
|
|
}
|
|
/**
|
* 画布上的一个质量组件节点。
|
* <p>
|
* 只记「是谁、在哪、什么属性」，不记子节点——画布的嵌套结构以 {@link #grapes} 为准，
|
* 这里再存一份树就出现两个真相来源，迟早对不上。
|
*/
|
@Data
|
public static class QualityComponentNode {
|
|
/** 画布内组件 id */
|
private String id;
|
/** 组件在文档中的顺序，供绑定与定位使用 */
|
private Integer index;
|
/** 组件类型，即画布节点上的 data-quality-type */
|
private String qualityType;
|
/**
|
* 组件的业务属性。
|
* <p>
|
* 取值统一是 {@code data-qc-*} / {@code data-quality-type} 这类字符串属性，
|
* 用 Object 是因为 GrapesJS 的 getAttributes() 原样带出，可能有非字符串值。
|
*/
|
private Map<String, Object> attributes;
|
|
}
|
|
}
|
