校验基准是答卷钉住的那个版本的 schema（{@code answer.version}）， + * 而不是表单的最新版本——升版窗口旧版仍可填（P20），新 schema 的字段不会凭空出现在旧数据上， + * 旧 schema 已删的字段也不会被新校验误拒（编辑回显同口径，方案 §5.4"编辑按钉住 version 校验"）。
+ * + *与 {@link FormSchemaValidator} 的分工：那个管定义（发布期，白名单/类型/options 形状）， + * 这个管数据（提交期，值形状与取值域）。两者都只用声明式规则， + * 严禁存库 JS / eval（旧 CustomForm 反面先例）。
+ * + *取值域（P18/P19 定稿）：内联 options 的 value 集合 ∪ 字典条目的 value 集合， + * 其中字典侧必须走 {@code FormDictService#allowedValues}（含软删条目）—— + * 旧答卷原样重存的放行口径（契约 §2.1）。
+ */ +public final class FormValueValidator { + + /** 全局兜底：单文件 ≤50MB（方案 §7.7） */ + public static final long MAX_FILE_SIZE_BYTES = 50L * 1024 * 1024; + /** 全局兜底：每字段 ≤9 个附件（字段级 maxFiles 只能更严，不能放宽） */ + public static final int MAX_FILES_PER_FIELD = 9; + + private static final Pattern DATE_STRICT = Pattern.compile("^\\d{4}-\\d{2}-\\d{2}$"); + /** uuuu + STRICT：拒绝 2023-02-30 这类"格式对但日期不存在"的值（yyyy 在 STRICT 下会被宽松处理） */ + private static final DateTimeFormatter DATE_PARSER = + DateTimeFormatter.ofPattern("uuuu-MM-dd").withResolverStyle(ResolverStyle.STRICT); + + private static final Set这里没有编辑/删除的"填表人版本"接口——填表人可用的动作只有提交（V29"无编辑/撤回接口可用" + * 的实现形态就是不存在这些端点，加上管理权守卫给出的 403）。改状态同理：填表人在接口层即被拒（V14）。
+ * + *也不提供列表/详情读接口：那四条读出路径（列表/详情/统计/导出）必须共用同一个 scope 构造器 + * （方案 §6.4 红线，V27/V30），归 T4 一次建成，避免本轮先写一个没有范围过滤的读接口、T4 再补一遍。
+ * + *{@code schId} 参数只是超管跨校的目标域（校级传别的值即拒，同 {@link FormAdminController} 口径）； + * 答卷定位按 {@code (域, uuid)}，跨校答卷查不到。
+ */ +@RestController +@RequestMapping("/api/form/admin/data") +@RequiredArgsConstructor +public class FormAnswerAdminController { + + private final FormAdminGuard adminGuard; + private final AnswerAdminService adminService; + + /** 编辑值文档：按该答卷钉住的 version 校验（V8 同族），写 answer_op_log，索引同步重建 */ + @PostMapping("/edit") + public void edit(BoaUser user, + @RequestParam(required = false) Long schId, + @RequestBody AnswerModels.EditRequest body) { + Long domain = adminGuard.requireAdmin(user, schId); + adminService.edit(domain, user.getId(), body); + } + + /** 软删（唯一删除形态，无物理删除接口——V30）；同步删索引行并释放限次名额 */ + @PostMapping("/softDelete") + public void softDelete(BoaUser user, + @RequestParam(required = false) Long schId, + @RequestParam("answerId") String answerId) { + Long domain = adminGuard.requireAdmin(user, schId); + adminService.softDelete(domain, user.getId(), answerId); + } + + /** 改状态：填表人不可用（V14）；写 status_log，系统内无任何转移规则校验（V15） */ + @PostMapping("/changeStatus") + public void changeStatus(BoaUser user, + @RequestParam(required = false) Long schId, + @RequestBody AnswerModels.ChangeStatusRequest body) { + Long domain = adminGuard.requireAdmin(user, schId); + adminService.changeStatus(domain, user.getId(), body); + } + + /** 批量软删：逐条单条校验与留痕，每条独立事务，结果逐条返回 */ + @PostMapping("/batch/softDelete") + public List契约纪律：
+ *三条钉死的事实：
+ *{@code values_json} 用 MEDIUMTEXT：TEXT 的 64KB 会被长文本答卷顶爆（方案 §5.1）。 + * 值形状见契约 §3，其中附件只存 {@code {id,fileName,key}}（key=相对路径，绝不含绝对 URL）。
+ */ +@Getter +@Setter +@Entity +@Table(name = "answer", + uniqueConstraints = { + @UniqueConstraint(name = "uk_answer_uuid", columnNames = "uuid"), + @UniqueConstraint(name = "uk_answer_idem", columnNames = "idempotency_key") + }, + indexes = { + @Index(name = "idx_answer_form", columnList = "sch_id, code, status, id"), + @Index(name = "idx_answer_submitter", columnList = "sch_id, submitter_id"), + @Index(name = "idx_answer_subject", columnList = "subject_id") + }) +public class Answer extends BaseEntity { + + private static final long serialVersionUID = 1L; + + /** 数据面运行时身份（详情 URL / 嵌入地址 / L2 引用都用它，契约 §1） */ + @Column(name = "uuid", nullable = false, length = 32, updatable = false) + private String uuid; + + @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; + + /** 钉住的 schema 版本（提交时解析到的发布版本，之后不随升版改变） */ + @Column(name = "version", nullable = false, updatable = false) + private Integer version; + + /** 谁提交的（CAS 会话推导） */ + @Column(name = "submitter_id", nullable = false, updatable = false) + private Integer submitterId; + + /** 关于谁（管理员/教师代填时=被代填人；普通用户只能=自己，方案 §6.3） */ + @Column(name = "subject_id") + private Integer subjectId; + + /** 轻状态位：字符串 code，取值域=表单状态定义（一等列，方案 §5.3） */ + @Column(name = "status", nullable = false, length = 64) + private String status; + + /** 值文档 {@code {key:value}}（契约 §3 值形状） */ + @Column(name = "values_json", nullable = false, columnDefinition = "mediumtext") + private String valuesJson; + + /** 报名号 {@code {code}-{YYYYMMDD}-{当日序号}}；表单级开关默认关（契约 §5） */ + @Column(name = "answer_no", length = 64) + private String answerNo; + + /** 客户端幂等键（库级唯一） */ + @Column(name = "idempotency_key", nullable = false, length = 64, updatable = false) + private String idempotencyKey; + + /** 软删=唯一删除形态（无物理删除接口，P22/V30）；同步删 answer_index 行、释放 fill_quota 名额 */ + @Column(name = "is_deleted", nullable = false, columnDefinition = "tinyint") + private Integer isDeleted = 0; +} diff --git a/src/main/java/com/yunhai/formcenter/entity/AnswerIndex.java b/src/main/java/com/yunhai/formcenter/entity/AnswerIndex.java new file mode 100644 index 0000000..33967b3 --- /dev/null +++ b/src/main/java/com/yunhai/formcenter/entity/AnswerIndex.java @@ -0,0 +1,77 @@ +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 java.math.BigDecimal; +import java.time.LocalDate; + +/** + * 索引值表（契约 §10 / 方案 §5.2）：一答卷的一个 searchable 字段值一行， + * 同时支撑筛选与分组统计；零 DDL 加字段、类型正确（{@code v_date} 区间、{@code v_num} 数值）。 + * + *四条纪律：
+ *列选择按该答卷钉住版本的 schema 判定：只有该版本声明 searchable 的字段才有行。
+ */ +@Getter +@Setter +@Entity +@Table(name = "answer_index", + indexes = { + @Index(name = "idx_ai_str", columnList = "sch_id, code, field_key, v_str, answer_id"), + @Index(name = "idx_ai_num", columnList = "sch_id, code, field_key, v_num, answer_id"), + @Index(name = "idx_ai_date", columnList = "sch_id, code, field_key, v_date, answer_id"), + @Index(name = "idx_ai_answer", columnList = "answer_id") + }) +public class AnswerIndex extends BaseEntity { + + private static final long serialVersionUID = 1L; + + /** utf8mb4 下 InnoDB 索引列上限 767 字节 = 191 字符（契约 §10 定死） */ + public static final int MAX_V_STR_LEN = 191; + + @Column(name = "answer_id", nullable = false, updatable = false) + private Long answerId; + + @Column(name = "sch_id", nullable = false, updatable = false) + private Long schId; + + @Column(name = "code", nullable = false, length = 64, updatable = false) + private String code; + + @Column(name = "field_key", nullable = false, length = 64, updatable = false) + private String fieldKey; + + /** 文本/选项类：等值与前缀模糊；超长截断 */ + @Column(name = "v_str", length = MAX_V_STR_LEN) + private String vStr; + + /** 数值类：区间与分组统计；DECIMAL(20,6) 与 precision ≤6 的白名单约束同口径 */ + @Column(name = "v_num", precision = 20, scale = 6) + private BigDecimal vNum; + + /** 日期类：{@code YYYY-MM-DD} 落 DATE 列（禁字典序比日期，方案 §4.3④/V4） */ + @Column(name = "v_date") + private LocalDate vDate; + + /** 超长截断只在入索引这一处发生，值文档本身不动（三态空值与降级显示读的是 values_json） */ + public static String truncateForIndex(String value) { + if (value == null) { + return null; + } + return value.length() <= MAX_V_STR_LEN ? value : value.substring(0, MAX_V_STR_LEN); + } +} diff --git a/src/main/java/com/yunhai/formcenter/entity/AnswerOpLog.java b/src/main/java/com/yunhai/formcenter/entity/AnswerOpLog.java new file mode 100644 index 0000000..d4fb20a --- /dev/null +++ b/src/main/java/com/yunhai/formcenter/entity/AnswerOpLog.java @@ -0,0 +1,59 @@ +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; + +/** + * 操作留痕（契约 §10 / 方案 §5.4）：管理员编辑、软删、批量操作逐条一行。 + * + *批量与单条同形（方案 §5.4"批量逐条走单条校验与留痕"）：一条答卷一行日志、同一操作人、 + * 同一时间口径；op 用 {@code batch_*} 前缀标出来自批量通道（契约 §10 注释的 + * {@code edit/soft_delete/batch_…} 形态），批次上下文写在 summary 里。
+ * + *填表人没有编辑/撤回接口可用（V29）——所以本表里不会出现"填表人自己 edit"的行。
+ */ +@Getter +@Setter +@Entity +@Table(name = "answer_op_log", indexes = @Index(name = "idx_ol_answer", columnList = "answer_id")) +public class AnswerOpLog extends BaseEntity { + + private static final long serialVersionUID = 1L; + + /** 管理员原地修正值文档（按钉住版本校验，方案 §5.4） */ + public static final String OP_EDIT = "edit"; + /** 软删（唯一删除形态） */ + public static final String OP_SOFT_DELETE = "soft_delete"; + /** 改状态（非填表人；细节同时进 status_log） */ + public static final String OP_CHANGE_STATUS = "change_status"; + /** 批量软删中的某一条 */ + public static final String OP_BATCH_SOFT_DELETE = "batch_soft_delete"; + /** 批量改状态中的某一条 */ + public static final String OP_BATCH_CHANGE_STATUS = "batch_change_status"; + + @Column(name = "answer_id", nullable = false, updatable = false) + private Long answerId; + + @Column(name = "op", nullable = false, length = 32, updatable = false) + private String op; + + @Column(name = "operator_id", nullable = false, updatable = false) + private Integer operatorId; + + /** 摘要（改了哪些字段/批次上下文等），≤500 */ + @Column(name = "summary", length = 500) + private String summary; + + public static String summarize(String summary) { + if (summary == null || summary.trim().isEmpty()) { + return null; + } + String clean = summary.trim(); + return clean.length() > 500 ? clean.substring(0, 500) : clean; + } +} diff --git a/src/main/java/com/yunhai/formcenter/entity/FillQuota.java b/src/main/java/com/yunhai/formcenter/entity/FillQuota.java new file mode 100644 index 0000000..f0a37aa --- /dev/null +++ b/src/main/java/com/yunhai/formcenter/entity/FillQuota.java @@ -0,0 +1,36 @@ +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; + +/** + * 限填登记（契约 §10 / 方案 §5.4 v1.4 并发兜底）：{@code (form_id, limit_key)} 唯一键， + * 提交事务内插入、撞键即拒——两个并发提交不可能都通过 count 检查。 + * + *为什么需要这张表：契约 §3 把 image/upload 的值形状定死为 + * {@code [{id, fileName, key}]}——那个 {@code id} 必须是中心侧可定位的附件行主键， + * 否则"值里存 id"无从解析（管理员编辑重存、附件审计、后续 GC 都按它）。 + * 契约 §10 九表草案未列本表 → 见问题单（本轮按值契约补齐最小落档结构，不扩语义）。
+ * + *环境解耦纪律（方案 §4.3② v1.1 修订）：只存 {@code store_key}=相对存储路径， + * 绝不存绝对 URL——{@code FILE_WEB_PATH} 是环境注入项，绝对地址进答卷=换域名历史附件全断。 + * 访问地址由渲染期拼接；一期显式假设"key=不可猜测随机串即访问控制"（方案 §7.7，鉴权接口二期）。
+ */ +@Getter +@Setter +@Entity +@Table(name = "form_file", + uniqueConstraints = @UniqueConstraint(name = "uk_form_file_key", columnNames = "store_key"), + indexes = @Index(name = "idx_form_file_sch", columnList = "sch_id, id")) +public class FormFile extends BaseEntity { + + private static final long serialVersionUID = 1L; + + /** 上传时的会话校（归属留档；跨校不可读由读路径负责） */ + @Column(name = "sch_id", nullable = false, updatable = false) + private Long schId; + + /** 用户上传时的原始文件名（展示用；存储名另生成，防路径穿越与同名覆盖） */ + @Column(name = "file_name", nullable = false, length = 255) + private String fileName; + + /** + * 相对存储 key（{@code FILE_PATH} 下），形如 {@code form/2026/10/{32位随机}.{ext}}。 + * 列宽取 191：本列上有唯一键，utf8mb4 下 191×4=764 字节刚好落在 InnoDB 单列索引 767 上限内 + * （方案 §7.7 要求 MySQL 5.7 兼容；实际 key 只有 ~50 字符，191 已留足余量）。 + */ + @Column(name = "store_key", nullable = false, length = 191, updatable = false) + private String storeKey; + + /** 字节数（上限校验在上传时执行；留档供后续配额/GC 判断） */ + @Column(name = "file_size", nullable = false) + private Long fileSize; + + /** 归一化小写扩展名（不含点），黑名单判定结果留档 */ + @Column(name = "ext", nullable = false, length = 16) + private String ext; +} diff --git a/src/main/java/com/yunhai/formcenter/entity/StatusLog.java b/src/main/java/com/yunhai/formcenter/entity/StatusLog.java new file mode 100644 index 0000000..bf50b02 --- /dev/null +++ b/src/main/java/com/yunhai/formcenter/entity/StatusLog.java @@ -0,0 +1,35 @@ +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; + +/** + * 状态留痕（契约 §10 / 方案 §5.3④）：改状态写一行，一期不做通知。 + * + *红线复述：状态是"标记"不是"流转"——本表只记"谁在什么时候把这条答卷标成了什么"， + * 系统里不存在任何转移规则校验（V15）。需要流转走流程中心。
+ */ +@Getter +@Setter +@Entity +@Table(name = "status_log", indexes = @Index(name = "idx_sl_answer", columnList = "answer_id")) +public class StatusLog extends BaseEntity { + + private static final long serialVersionUID = 1L; + + @Column(name = "answer_id", nullable = false, updatable = false) + private Long answerId; + + /** 状态 code（取值域=表单 status_defs，含已废弃 code 的历史痕迹） */ + @Column(name = "status_code", nullable = false, length = 64, updatable = false) + private String statusCode; + + /** 操作人（CAS 会话用户 id；填表人改状态在接口层即被拒，方案 §5.3③/V14） */ + @Column(name = "operator_id", nullable = false, updatable = false) + private Integer operatorId; +} diff --git a/src/main/java/com/yunhai/formcenter/model/AnswerModels.java b/src/main/java/com/yunhai/formcenter/model/AnswerModels.java new file mode 100644 index 0000000..0ac79a5 --- /dev/null +++ b/src/main/java/com/yunhai/formcenter/model/AnswerModels.java @@ -0,0 +1,113 @@ +package com.yunhai.formcenter.model; + +import com.fasterxml.jackson.databind.JsonNode; +import lombok.Getter; +import lombok.Setter; + +import java.util.List; + +/** + * 答卷域出入参模型（契约 §3/§5/§7 的响应侧形状）。 + * + *三条对外纪律：
+ *