放在 common 而不是 service：提交接口（T3）、只读态判定（T7 前端要的字段）、 + * 限次登记（fill_quota 的 limit_key）都要同一份口径，写进 service 就会被复制两遍。
+ */ +public final class FormRuntimeRules { + + /** 管理员只选日期时的当日收尾时刻（方案 §5.4："datetime 粒度，只选日期默认当日 23:59:59"） */ + public static final java.time.LocalTime DEADLINE_TIME_OF_DAY = java.time.LocalTime.of(23, 59, 59); + + private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd"); + private static final DateTimeFormatter DATE_TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); + + private FormRuntimeRules() { + } + + /** + * 截止时间解析：{@code yyyy-MM-dd} → 当日 23:59:59；{@code yyyy-MM-dd HH:mm:ss} → 原样； + * 空串/null → null（不限）。其它形态直接拒绝（不让"2026/10/1"这种悄悄进库变成解析歧义）。 + */ + public static LocalDateTime parseDeadline(String raw) { + if (raw == null || raw.trim().isEmpty()) { + return null; + } + String value = raw.trim(); + try { + if (value.length() <= 10) { + return LocalDate.parse(value, DATE).atTime(DEADLINE_TIME_OF_DAY); + } + return LocalDateTime.parse(value, DATE_TIME); + } catch (DateTimeParseException e) { + throw new BizException(ErrorCode.PARAM_ERROR, + "截止时间格式应为 yyyy-MM-dd 或 yyyy-MM-dd HH:mm:ss：" + value); + } + } + + /** 是否已过截止（严格"晚于"才过期：23:59:59 当秒仍可提交，契约 §5 datetime 粒度） */ + public static boolean isDeadlineReached(Form form, LocalDateTime now) { + if (form == null || form.getDeadline() == null) { + return false; + } + return (now == null ? LocalDateTime.now() : now).isAfter(form.getDeadline()); + } + + /** + * 限一次的去重维度（方案 §5.4 v1.2 定死）：{@code subject_id} 非空按 subject 限，否则按 submitter 限。 + * 代填时按 submitter 限会出"一人两份"，而"一人一份"（家访/体检/学籍）要的恰恰是按学生限。 + */ + public static FormEnums.LimitScope limitScope(Form form, Integer subjectId) { + if (form == null || !FormEnums.FillLimit.once(form.getFillLimit())) { + throw new BizException(ErrorCode.PARAM_ERROR, "该表单未开启限填一次"); + } + return subjectId != null ? FormEnums.LimitScope.SUBJECT : FormEnums.LimitScope.SUBMITTER; + } + + /** + * fill_quota.limit_key（契约 §10："coalesce(subject_id, submitter_id) 字符串化"）。 + * 与幂等键是两个机制：幂等防双击重复，限次防多次提交。 + */ + public static String quotaKey(Integer subjectId, Integer submitterId) { + Integer key = subjectId != null ? subjectId : submitterId; + if (key == null) { + throw new BizException(ErrorCode.PARAM_ERROR, "限次键需要 subject_id 或 submitter_id"); + } + return String.valueOf(key); + } + + /** 生命周期是否可填报（方案 §5.4：停用=填报入口失效；草稿=未开放入口） */ + public static boolean isFillOpen(Form form) { + return form != null && form.getStatus() != null + && form.getStatus() == FormEnums.FormStatus.PUBLISHED.getCode(); + } +} diff --git a/src/main/java/com/yunhai/formcenter/common/FormSchemaValidator.java b/src/main/java/com/yunhai/formcenter/common/FormSchemaValidator.java new file mode 100644 index 0000000..4ba221a --- /dev/null +++ b/src/main/java/com/yunhai/formcenter/common/FormSchemaValidator.java @@ -0,0 +1,466 @@ +package com.yunhai.formcenter.common; + +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.yunhai.platform.apistd.BizException; +import com.yunhai.platform.utils.exception.ErrorCode; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.HashSet; +import java.util.Iterator; +import java.util.LinkedHashMap; +import java.util.LinkedHashSet; +import java.util.List; +import java.util.Map; +import java.util.Set; +import java.util.regex.Pattern; + +/** + * 表单 schema 契约校验器（契约 §2/§2.1，方案 §4.2/§4.3①②③⑤）。 + * + *与 svc-hall {@code FormValidator} 同源处：14 类控件命名一次冻结、一期放行 11 类、 + * {@code ^[A-Za-z0-9_]{1,64}$} 的 key 规则、属性白名单外一律拒绝（防"存库 JS/eval"类契约外语义渗入）。 + * 关键差异（新契约的三处硬修订）：
+ *本类只做纯静态校验（不碰库）：字典引用是否可解析属于跨表事实，在 + * {@code FormDictService#assertRefsResolvable} 发布路径上查。提交值校验（按钉住版本）属 T3。
+ */ +public final class FormSchemaValidator { + + /** 14 类控件命名一次冻结（契约 §2、方案 §4.2） */ + public static final Set依据：契约 §2"改 key = 换字段（视同删旧增新）"+ answer_index 按 type 收敛检索算子 + * （等值/区间/前缀，契约 §2）、{@code v_str/v_num/v_date} 三列分类型落值（契约 §10）。 + * 若允许同 key 换 type，历史索引行与新语义错配，V8"删字段后历史仍可筛"当场失效。 + * 删字段与新增字段都不受本检查约束（V8/V9 的正常路径）；label/options/required/searchable 可改。
+ */ + public static void assertFieldTypesStable(String oldSchemaJson, String newSchemaJson) { + Map红线复述（方案 §5.3）：状态是"标记"不是"流转"——不校验谁能从 A 到 B、无条件分支、 + * 无会签、无超时；需要流转去流程中心。所以这里只有"定义集合"的增删改，没有任何转移规则。
+ * + *契约纪律：
+ *纪律：
+ *为什么必须有头表（方案 §5.1）：uuid 要跨版本不变（V5）就不能长在版本行上；状态定义 + * "属于表单、会被改、不随版本快照"（§5.4）；"当前发布版本"指针是 form 级；草稿行与发布行是 + * 同一头表下两种生命周期的版本行。
+ * + *标识分工（契约 §1）：{@code id} 只做库内定位、绝不外露；{@code uuid}=数据面运行时身份； + * {@code code}=配置期引用 + 入口寻址，同校 + 同 {@code app_code} 内唯一、发布后不可改。
+ * + *表单级配置（audience/fill_limit/deadline/answer_no_enabled/status_defs/group_tag）不进版本 + * 快照——升版只换 schema 行，这些列原地可改（方案 §5.1/§5.4）。
+ */ +@Getter +@Setter +@Entity +@Table(name = "form", + uniqueConstraints = { + @UniqueConstraint(name = "uk_form_uuid", columnNames = "uuid"), + // app_code 必须进唯一键（方案 §5.1 D8）：中心同时装多个消费方的表单， + // 漏了命名空间则两个消费方同校同 code 直接撞（V6 的反面） + @UniqueConstraint(name = "uk_form", columnNames = {"sch_id", "app_code", "code"}) + }, + indexes = @Index(name = "idx_form_app", columnList = "sch_id, app_code, status")) +public class Form extends BaseEntity { + + private static final long serialVersionUID = 1L; + + /** 中心/平台级表单的归属 app_code（手册 §1：app_code=form-center） */ + public static final String CENTER_APP_CODE = "form-center"; + + /** 平台级行的租户键（契约 §1：域=会话校 ∪ 平台级 sch_id=0，本校遮蔽平台） */ + public static final long PLATFORM_SCH_ID = 0L; + + /** 数据面运行时身份：建草稿即生成、跨版本不变（契约 §1） */ + @Column(name = "uuid", nullable = false, length = 32, updatable = false) + private String uuid; + + /** 租户键；0=平台级表单（U5/U6，超管上下文建，学校可复制使用） */ + @Column(name = "sch_id", nullable = false, updatable = false) + private Long schId; + + /** 归属应用：中心/平台级挂 form-center，快应用挂其 app_code（契约 §1） */ + @Column(name = "app_code", nullable = false, length = 64) + private String appCode = CENTER_APP_CODE; + + /** 人可读编码，≤64，同校同 app_code 内唯一；发布后不可改（改=换表单，契约 §1） */ + @Column(name = "code", nullable = false, length = 64) + private String code; + + /** 表单名 */ + @Column(name = "name", nullable = false, length = 128) + private String name; + + /** 当前发布版本指针，null=从未发布（resolve 只认它，方案 §5.1） */ + @Column(name = "current_version") + private Integer currentVersion; + + /** 生命周期：0 草稿 / 1 已发布 / 2 停用（契约 §10） */ + @Column(name = "status", nullable = false, columnDefinition = "tinyint") + private Integer status = FormEnums.FormStatus.DRAFT.getCode(); + + /** 状态定义 JSON {@code [{code,label,is_deleted}]}，null=用默认"待处理/已处理"（V12，方案 §5.3） */ + @Column(name = "status_defs", columnDefinition = "text") + private String statusDefs; + + /** 面向人群：1 学生 / 2 教师（数据范围默认矩阵的输入，契约 §10） */ + @Column(name = "audience", nullable = false, columnDefinition = "tinyint") + private Integer audience = FormEnums.Audience.STUDENT.getCode(); + + /** 限填次数：0 不限 / 1 限一次（去重维度按 subject/submitter 推导，方案 §5.4） */ + @Column(name = "fill_limit", nullable = false, columnDefinition = "tinyint") + private Integer fillLimit = FormEnums.FillLimit.UNLIMITED.getCode(); + + /** 收集截止时间，datetime 粒度（管理员只选日期时默认当日 23:59:59，方案 §5.4） */ + @Column(name = "deadline") + private LocalDateTime deadline; + + /** 报名号开关（默认关；启用后 T3 提交生成 {code}-{YYYYMMDD}-{当日序号}，方案 §5.4） */ + @Column(name = "answer_no_enabled", nullable = false, columnDefinition = "tinyint") + private Integer answerNoEnabled = 0; + + /** 多表单快应用的菜单分组标签（方案 §5.1，可选） */ + @Column(name = "group_tag", length = 64) + private String groupTag; + + /** 软删标记——唯一删除形态，有答卷的表单禁物理删除（方案 §5.4） */ + @Column(name = "is_deleted", nullable = false, columnDefinition = "tinyint") + private Integer isDeleted = 0; +} diff --git a/src/main/java/com/yunhai/formcenter/entity/FormDict.java b/src/main/java/com/yunhai/formcenter/entity/FormDict.java new file mode 100644 index 0000000..18e5fba --- /dev/null +++ b/src/main/java/com/yunhai/formcenter/entity/FormDict.java @@ -0,0 +1,41 @@ +package com.yunhai.formcenter.entity; + +import lombok.Getter; +import lombok.Setter; + +import javax.persistence.Column; +import javax.persistence.Entity; +import javax.persistence.Table; +import javax.persistence.UniqueConstraint; + +/** + * 选项字典（契约 §2.1 / 方案 §4.3③b）：两级——{@code sch_id=0} 平台级（超管维护， + * 学校可见、可用、不可改），其余为校级（仅本校表单可引用，sch_id 天然隔离）。 + * + *{@code code} 是 schema 里 {@code options.source="dict:{code}"} 的引用键，因此建后不可改 + * （改 code=换字典，会打穿所有引用它的表单）。{@code is_deleted} 软删后不再可被新引用， + * 但历史 schema 的降级显示由读路径负责。
+ */ +@Getter +@Setter +@Entity +@Table(name = "form_dict", + uniqueConstraints = @UniqueConstraint(name = "uk_dict", columnNames = {"sch_id", "code"})) +public class FormDict extends BaseEntity { + + private static final long serialVersionUID = 1L; + + /** 0=平台级，其余=校级（契约 §2.1） */ + @Column(name = "sch_id", nullable = false, updatable = false) + private Long schId; + + /** 引用键，被 schema 以 {@code dict:{code}} 寻址，建后不可改 */ + @Column(name = "code", nullable = false, length = 64, updatable = false) + private String code; + + @Column(name = "name", nullable = false, length = 128) + private String name; + + @Column(name = "is_deleted", nullable = false, columnDefinition = "tinyint") + private Integer isDeleted = 0; +} diff --git a/src/main/java/com/yunhai/formcenter/entity/FormDictItem.java b/src/main/java/com/yunhai/formcenter/entity/FormDictItem.java new file mode 100644 index 0000000..a4d3b9e --- /dev/null +++ b/src/main/java/com/yunhai/formcenter/entity/FormDictItem.java @@ -0,0 +1,49 @@ +package com.yunhai.formcenter.entity; + +import lombok.Getter; +import lombok.Setter; + +import javax.persistence.Column; +import javax.persistence.Entity; +import javax.persistence.Index; +import javax.persistence.Table; +import javax.persistence.UniqueConstraint; + +/** + * 字典条目（契约 §2.1 / 方案 §4.3③b）：value 不可变、label 可改（D11 同款保护——字典改名 + * 不打穿历史答卷，这是字典机制能安全存在的前提）。 + * + *软删条目（{@code is_deleted=1}）：value 仍通过提交校验（旧答卷可原样重存，V38）， + * 仅设计器不可新选。因此本表对外有两个读取口径—— + * {@code 设计器可选=未删} 与 {@code 提交放行=含已删}，勿混用。
+ */ +@Getter +@Setter +@Entity +@Table(name = "form_dict_item", + uniqueConstraints = @UniqueConstraint(name = "uk_dict_item", columnNames = {"dict_id", "value"}), + indexes = @Index(name = "idx_dict_item_sort", columnList = "dict_id, sort")) +public class FormDictItem extends BaseEntity { + + private static final long serialVersionUID = 1L; + + /** 所属字典（逻辑外键） */ + @Column(name = "dict_id", nullable = false, updatable = false) + private Long dictId; + + /** 答案存的就是它；建一次即不可变（uk(dict_id,value) 兜住同名重写） */ + @Column(name = "value", nullable = false, length = 64, updatable = false) + private String value; + + /** 展示名，随便改 */ + @Column(name = "label", nullable = false, length = 128) + private String label; + + /** 展示顺序（升序；同值按 id 稳定排） */ + @Column(name = "sort", nullable = false) + private Integer sort = 0; + + /** 软删：设计器不可新选，提交校验仍放行 */ + @Column(name = "is_deleted", nullable = false, columnDefinition = "tinyint") + private Integer isDeleted = 0; +} diff --git a/src/main/java/com/yunhai/formcenter/entity/FormVersion.java b/src/main/java/com/yunhai/formcenter/entity/FormVersion.java new file mode 100644 index 0000000..b050624 --- /dev/null +++ b/src/main/java/com/yunhai/formcenter/entity/FormVersion.java @@ -0,0 +1,65 @@ +package com.yunhai.formcenter.entity; + +import lombok.Getter; +import lombok.Setter; + +import javax.persistence.Column; +import javax.persistence.Entity; +import javax.persistence.Index; +import javax.persistence.Table; +import javax.persistence.UniqueConstraint; +import java.time.LocalDateTime; + +/** + * 表单版本行（契约 §10 / 方案 §3.2）：{@code (sch_id, app_code, code, version)} 唯一确定一个 + * 永不改变的版本行——已发布行禁止就地修改，改版=新增行（V7）。 + * + *草稿行与发布行同表（方案 §5.1）：区分依据是"是否已发布过"，即 + * {@code publish_time != null}，以及头表 {@code form.current_version} 指针是否指到它。 + * 唯一可写的例外是未发布草稿行的 {@code schema_json}/{@code change_log}（草稿直改）， + * 发布动作只补 {@code publish_time}——发布后该行内容逐字节冻结，缓存声明才成立（方案 §3.2 + * "schema_json 内容不可变→可长缓存；resolve 结果会因升版失效→短 TTL"）。
+ * + *字典引用 {@code options.source="dict:{code}"} 原样存在 schema_json 里，不进快照展开 + * （方案 §4.3③b：活引用是它的价值，读接口下发时才内联展开）。
+ */ +@Getter +@Setter +@Entity +@Table(name = "form_version", + uniqueConstraints = @UniqueConstraint(name = "uk_form_ver", + columnNames = {"sch_id", "app_code", "code", "version"}), + indexes = @Index(name = "idx_ver_form", columnList = "form_id")) +public class FormVersion extends BaseEntity { + + private static final long serialVersionUID = 1L; + + /** 所属表单头表（逻辑外键，无物理 FK——方案 §7.7） */ + @Column(name = "form_id", nullable = false, updatable = false) + private Long formId; + + @Column(name = "sch_id", nullable = false, updatable = false) + private Long schId; + + @Column(name = "app_code", nullable = false, length = 64, updatable = false) + private String appCode; + + @Column(name = "code", nullable = false, length = 64, updatable = false) + private String code; + + /** 版本：只增不改（契约 §1） */ + @Column(name = "version", nullable = false, updatable = false) + private Integer version; + + /** schema 快照：{@code {"groups":[{key,label,fields:[…]}]}}，数组序即展示序（契约 §2） */ + @Column(name = "schema_json", nullable = false, columnDefinition = "longtext") + private String schemaJson; + + /** 升版改动说明（可空，≤500） */ + @Column(name = "change_log", length = 500) + private String changeLog; + + /** 发布时间；null=尚未发布（草稿行） */ + @Column(name = "publish_time") + private LocalDateTime publishTime; +} diff --git a/src/main/java/com/yunhai/formcenter/enums/FormEnums.java b/src/main/java/com/yunhai/formcenter/enums/FormEnums.java new file mode 100644 index 0000000..a300d7f --- /dev/null +++ b/src/main/java/com/yunhai/formcenter/enums/FormEnums.java @@ -0,0 +1,90 @@ +package com.yunhai.formcenter.enums; + +/** + * 定义域枚举（契约 §1/§10 + 方案 §5.1/§5.4，一期冻结）。 + * 列值直接用契约 §10 DDL 草案里的数字口径，避免库内值与文档两套。 + */ +public final class FormEnums { + + private FormEnums() { + } + + /** 表单生命周期：0 草稿 / 1 已发布 / 2 停用（停用=填报入口失效，数据可看可导，方案 §5.4） */ + public enum FormStatus { + DRAFT(0), PUBLISHED(1), DISABLED(2); + + private final int code; + + FormStatus(int code) { + this.code = code; + } + + public int getCode() { + return code; + } + + public static String nameOf(Integer code) { + if (code != null) { + for (FormStatus s : values()) { + if (s.code == code) { + return s.name(); + } + } + } + return null; + } + } + + /** 面向人群：1 面向学生 / 2 面向教师（数据范围默认矩阵的输入，方案 §6.4；只决定默认，授权仍看模块行） */ + public enum Audience { + STUDENT(1), TEACHER(2); + + private final int code; + + Audience(int code) { + this.code = code; + } + + public int getCode() { + return code; + } + + public static boolean valid(Integer code) { + if (code != null) { + for (Audience a : values()) { + if (a.code == code) { + return true; + } + } + } + return false; + } + } + + /** 限填次数：0 不限 / 1 限一次（去重键见 {@link LimitScope}，与幂等键是两个机制，方案 §5.4） */ + public enum FillLimit { + UNLIMITED(0), ONCE(1); + + private final int code; + + FillLimit(int code) { + this.code = code; + } + + public int getCode() { + return code; + } + + public static boolean once(Integer code) { + return code != null && code == ONCE.code; + } + } + + /** + * 限一次的去重维度（方案 §5.4 v1.2 定死，不是配置项而是推导结果）： + * {@code subject_id} 非空按 subject 限（代填场景"一人一份"），否则按 submitter 限。 + */ + public enum LimitScope { + SUBJECT, SUBMITTER + } +} diff --git a/src/main/java/com/yunhai/formcenter/model/FormModels.java b/src/main/java/com/yunhai/formcenter/model/FormModels.java new file mode 100644 index 0000000..c25dfb9 --- /dev/null +++ b/src/main/java/com/yunhai/formcenter/model/FormModels.java @@ -0,0 +1,196 @@ +package com.yunhai.formcenter.model; + +import com.fasterxml.jackson.annotation.JsonProperty; +import lombok.Getter; +import lombok.Setter; + +import java.util.List; + +/** + * 定义域出入参模型（契约 §1/§2/§10 的响应侧形状）。 + * + *响应体一律不带 {@code id}：契约 §1 把 id 定为"库内定位、绝不外露"，V5 要断言 + * "id 不出现在任何响应外层"。因此管理端与数据面都用 {@code uuid} 寻址表单；字典没有 uuid， + * 用 {@code (域, code)} 寻址、条目用 {@code (dictCode, value)}（value 建后不可变，天然是稳定键）。
+ */ +public final class FormModels { + + private FormModels() { + } + + /** 表单项（头表 + 版本指针，不含 schema 正文） */ + @Getter + @Setter + public static class FormView { + private String formUuid; + private Long schId; + private String appCode; + private String code; + private String name; + private Integer status; + /** DRAFT/PUBLISHED/DISABLED（枚举名，前端不必再映射数字） */ + private String statusName; + /** 当前发布版本，null=从未发布 */ + private Integer currentVersion; + /** 待发布的草稿版本号，null=无草稿 */ + private Integer draftVersion; + private Integer audience; + private Integer fillLimit; + /** yyyy-MM-dd HH:mm:ss，null=不限 */ + private String deadline; + private Integer answerNoEnabled; + private String groupTag; + private List