>() {
+ });
+ } catch (Exception e) {
+ log.warn("[question] schema 快照解析失败：{}", e.toString());
+ return java.util.Collections.emptyMap();
+ }
+ }
+}
diff --git a/src/main/java/com/yunhai/question/service/SchoolAdminGuard.java b/src/main/java/com/yunhai/question/service/SchoolAdminGuard.java
new file mode 100644
index 0000000..c5c5409
--- /dev/null
+++ b/src/main/java/com/yunhai/question/service/SchoolAdminGuard.java
@@ -0,0 +1,76 @@
+package com.yunhai.question.service;
+
+import com.yunhai.platform.utils.model.BoaUser;
+import com.yunhai.question.common.BizException;
+import org.springframework.stereotype.Service;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+
+/**
+ * 问卷管理面轻量守卫：超管 ∪ 校领导/管理员角色（roleId ∈ {2,7}，UserBase 平台标准角色，
+ * 语义对齐 FC FormAccessPolicy.SCHOOL_LEADER_ROLES）。
+ *
+ * 真正的创建权把关在 FC 侧 {@code POST /api/form/admin/create}（FormAdminGuard：超管∪校管理员
+ * ∪管理员两表）——问卷前端第一步直调 FC，被 FC 拒则三步都走不到。本守卫只兜问卷侧写端点；
+ * 若联调发现"仅进 FC 管理员两表、无 2/7 角色"的账号被本守卫误拦，再评估接平台目录查询
+ * （R1 已知缺口，记录于开发报告）。
+ */
+@Service
+public class SchoolAdminGuard {
+
+ /** UserBase UserTypeEnum.SUPER_ADMIN（同 FC FormAccessPolicy.SUPER_ADMIN_TYPE） */
+ static final int SUPER_ADMIN_TYPE = 1;
+ /** 平台标准角色：校领导(2)/管理员(7)——对齐 FC SCHOOL_LEADER_ROLES */
+ static final Set SCHOOL_LEADER_ROLES = new HashSet<>(Arrays.asList(2, 7));
+
+ /** 要求登录 + 校管理员/超管；返回会话学校域 */
+ public Long requireSchool(BoaUser user) {
+ if (user == null || user.getId() == null) {
+ throw new BizException("未登录");
+ }
+ if (!isSchoolAdmin(user)) {
+ throw new BizException("无问卷管理权：需要校管理员或超管");
+ }
+ Long schId = sessionSchId(user);
+ if (schId == null) {
+ throw new BizException("当前会话无学校上下文");
+ }
+ return schId;
+ }
+
+ public boolean isSchoolAdmin(BoaUser user) {
+ if (user == null) {
+ return false;
+ }
+ if (user.getType() != null && user.getType() == SUPER_ADMIN_TYPE) {
+ return true;
+ }
+ for (Integer roleId : identityRoleIds(user)) {
+ if (roleId != null && SCHOOL_LEADER_ROLES.contains(roleId)) {
+ return true;
+ }
+ }
+ return false;
+ }
+
+ static List identityRoleIds(BoaUser user) {
+ List ids = new ArrayList<>();
+ if (user.getRoleIds() != null) {
+ ids.addAll(user.getRoleIds());
+ }
+ Integer current = user.getCurrentRole() == null ? null : user.getCurrentRole().getRoleId();
+ if (current != null && !ids.contains(current)) {
+ ids.add(current);
+ }
+ return ids;
+ }
+
+ static Long sessionSchId(BoaUser user) {
+ Integer schId = user == null || user.getCurrentRole() == null ? null : user.getCurrentRole().getSchId();
+ return schId == null ? null : Long.valueOf(schId);
+ }
+}
diff --git a/src/main/java/com/yunhai/question/service/StatsService.java b/src/main/java/com/yunhai/question/service/StatsService.java
new file mode 100644
index 0000000..0b33fb2
--- /dev/null
+++ b/src/main/java/com/yunhai/question/service/StatsService.java
@@ -0,0 +1,221 @@
+package com.yunhai.question.service;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.yunhai.question.entity.Questionnaire;
+import com.yunhai.question.repository.AnswerProjectionRepository;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * 基础统计（任务书 §4.6，全部在投影上算）：
+ *
+ * - 回收量（未删行数）与状态分布；
+ * - 选项题（select/radio/checkbox/multiselect）按题分布——人数口径：
+ * 一份答卷对一题的一个选项最多计 1，多选按答卷去重后逐选项计数
+ * （与 FC answer_index 的"选次口径"刻意可区分，响应里双口径同时给出）；
+ * - 文本/数值题只提供明细列表（R1 不做分桶/均值）。
+ *
+ * 题干/选项 label 从发布时钉版的 schema 快照解析。
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class StatsService {
+
+ private static final Set OPTION_TYPES = new HashSet<>(Arrays.asList("select", "radio", "checkbox", "multiselect"));
+
+ private final AnswerProjectionRepository answerProjectionRepository;
+ private final QuestionnaireService questionnaireService;
+ private final ObjectMapper objectMapper;
+
+ public Map stats(Questionnaire q) {
+ Map out = new LinkedHashMap<>();
+ long total = answerProjectionRepository.countByFormUuidAndIsDeletedFalse(q.getFormUuid());
+ out.put("total", total);
+
+ List> byStatus = new ArrayList<>();
+ for (Object[] row : answerProjectionRepository.countGroupByStatus(q.getFormUuid())) {
+ Map s = new LinkedHashMap<>();
+ s.put("status", row[0] == null ? "" : String.valueOf(row[0]));
+ s.put("count", row[1]);
+ byStatus.add(s);
+ }
+ out.put("byStatus", byStatus);
+
+ // 选项题人数口径分布（一份答卷一选项最多计 1）
+ List> values = readValues(q.getFormUuid());
+ List> fields = schemaFields(q);
+ List> byField = new ArrayList<>();
+ List> textDetail = new ArrayList<>();
+ for (Map field : fields) {
+ String key = String.valueOf(field.get("key"));
+ String type = String.valueOf(field.get("type"));
+ String label = String.valueOf(field.get("label"));
+ if (OPTION_TYPES.contains(type)) {
+ byField.add(optionFieldStats(key, label, field.get("options"), values));
+ } else if (!"upload".equals(type) && !"image".equals(type)) {
+ // 文本/数值/日期/电话等：明细列表
+ Map d = new LinkedHashMap<>();
+ d.put("key", key);
+ d.put("label", label);
+ d.put("type", type);
+ d.put("items", textItems(key, values));
+ textDetail.add(d);
+ }
+ }
+ out.put("byField", byField);
+ out.put("textDetail", textDetail);
+ return out;
+ }
+
+ /** 单选题分布：items[{value,label,count,percent}] + distinctRespondents（有效答卷数） */
+ private Map optionFieldStats(String key, String label, Object optionsDef,
+ List> values) {
+ Map out = new LinkedHashMap<>();
+ out.put("key", key);
+ out.put("label", label);
+ out.put("caliber", "人数口径：一份答卷对一题的一个选项最多计 1（多选按答卷去重后逐选项计数）");
+
+ Map labelByValue = new LinkedHashMap<>();
+ List> optionList = new ArrayList<>();
+ if (optionsDef instanceof Iterable) {
+ for (Object o : (Iterable) optionsDef) {
+ if (o instanceof Map) {
+ String value = String.valueOf(((Map) o).get("value"));
+ String optLabel = String.valueOf(((Map) o).get("label"));
+ labelByValue.put(value, optLabel);
+ Map item = new LinkedHashMap<>();
+ item.put("value", value);
+ item.put("label", optLabel);
+ optionList.add(item);
+ }
+ }
+ }
+ Map countByValue = new LinkedHashMap<>();
+ long answeredSheets = 0;
+ for (Map sheet : values) {
+ Object raw = sheet.get(key);
+ Set picks = distinctPicks(raw);
+ if (picks.isEmpty()) {
+ continue;
+ }
+ answeredSheets++;
+ for (String v : picks) {
+ countByValue.merge(v, 1L, Long::sum);
+ }
+ }
+ for (Map item : optionList) {
+ long count = countByValue.getOrDefault(String.valueOf(item.get("value")), 0L);
+ item.put("count", count);
+ item.put("percent", answeredSheets == 0 ? 0
+ : Math.round(count * 1000.0 / answeredSheets) / 10.0);
+ }
+ // schema 外的杂值（理论不该有：FC 值校验闭集）也带出，防统计黑洞
+ for (Map.Entry e : countByValue.entrySet()) {
+ if (!labelByValue.containsKey(e.getKey())) {
+ Map item = new LinkedHashMap<>();
+ item.put("value", e.getKey());
+ item.put("label", e.getKey());
+ item.put("count", e.getValue());
+ item.put("percent", answeredSheets == 0 ? 0
+ : Math.round(e.getValue() * 1000.0 / answeredSheets) / 10.0);
+ optionList.add(item);
+ }
+ }
+ out.put("answeredSheets", answeredSheets);
+ out.put("items", optionList);
+ return out;
+ }
+
+ /** 一份答卷该题的去重选项集（值可能是标量或数组；非预期形态按空处理） */
+ static Set distinctPicks(Object raw) {
+ Set picks = new java.util.LinkedHashSet<>();
+ if (raw instanceof Iterable) {
+ for (Object v : (Iterable) raw) {
+ if (v != null) {
+ picks.add(String.valueOf(v));
+ }
+ }
+ } else if (raw != null) {
+ picks.add(String.valueOf(raw));
+ }
+ return picks;
+ }
+
+ private List textItems(String key, List> values) {
+ List items = new ArrayList<>();
+ for (Map sheet : values) {
+ Object raw = sheet.get(key);
+ if (raw == null) {
+ continue;
+ }
+ if (raw instanceof Iterable) {
+ List parts = new ArrayList<>();
+ for (Object v : (Iterable) raw) {
+ if (v != null) {
+ parts.add(String.valueOf(v));
+ }
+ }
+ if (!parts.isEmpty()) {
+ items.add(String.join("、", parts));
+ }
+ } else {
+ items.add(String.valueOf(raw));
+ }
+ }
+ return items;
+ }
+
+ private List> readValues(String formUuid) {
+ List> out = new ArrayList<>();
+ for (String json : answerProjectionRepository.findActiveValuesJson(formUuid)) {
+ try {
+ out.add(objectMapper.readValue(json, new TypeReference>() {
+ }));
+ } catch (Exception e) {
+ log.warn("[question] 投影 values 解析失败（跳过一行）：{}", e.toString());
+ }
+ }
+ return out;
+ }
+
+ @SuppressWarnings("unchecked")
+ private List> schemaFields(Questionnaire q) {
+ Map snapshot = questionnaireService.schemaSnapshot(q);
+ Object groups = snapshot.get("groups");
+ List> fields = new ArrayList<>();
+ if (groups == null) {
+ return fields;
+ }
+ JsonNode nodes = objectMapper.valueToTree(groups);
+ if (!nodes.isArray()) {
+ return fields;
+ }
+ for (JsonNode group : nodes) {
+ JsonNode fs = group.path("fields");
+ if (!fs.isArray()) {
+ continue;
+ }
+ for (JsonNode f : fs) {
+ Map field = new LinkedHashMap<>();
+ field.put("key", f.path("key").asText(null));
+ field.put("label", f.path("label").asText(null));
+ field.put("type", f.path("type").asText(null));
+ field.put("options", f.has("options") ? objectMapper.convertValue(f.get("options"), List.class) : null);
+ fields.add(field);
+ }
+ }
+ return fields;
+ }
+}
diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml
new file mode 100644
index 0000000..4313d24
--- /dev/null
+++ b/src/main/resources/application.yml
@@ -0,0 +1,88 @@
+server:
+ port: 8090
+ # 本地无 context-path（同 flow-center dev）；生产经 CONTEXT_PATH=/question 注入
+
+spring:
+ application:
+ name: question-center
+ datasource:
+ url: jdbc:mysql://localhost:3306/ysch_question?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
+ username: root
+ password: 123456
+ driver-class-name: com.mysql.cj.jdbc.Driver
+ hikari:
+ minimum-idle: 5
+ maximum-pool-size: 20
+ jpa:
+ hibernate:
+ # 开发期 update 自动建表（与 sql/question_r1.sql 对照校验）；生产建议 none + 脚本
+ ddl-auto: update
+ show-sql: false
+ open-in-view: false
+ database-platform: org.hibernate.dialect.MySQL5InnoDBDialect
+ properties:
+ hibernate:
+ jdbc:
+ time_zone: Asia/Shanghai
+ jackson:
+ date-format: yyyy-MM-dd HH:mm:ss
+ time-zone: Asia/Shanghai
+
+# ===== 基础平台 yh 配置（flow-center 同款三件套）=====
+yh:
+ auth:
+ enabled: true
+ sso:
+ # 本地全链测试指向 local-debug CAS（8443）；生产改回 sso.yunhaixingtong.com
+ server-url-prefix: http://localhost:8443
+ client-host-url: http://localhost:8090
+ allow-headers: all
+ allow-origins: all
+ # 用户面与管理面全在 /api/* 下；本应用无匿名面
+ url-pattern: /api/*
+ app-auth:
+ enabled: true
+ # 本应用自身身份（客户端签名用）——appKey=100020（svc-hall=100018、flow-center=100019、
+ # form-center=100021 顺延），已于 2026-10-22 在 UserBase 注册；FC 验签走 trust-registry
+ # 密钥链（trusted-apps→Redis→UserBase 兜底），FC 本地 trusted-apps 仅停摆兜底、可不配。
+ # secret 须与 UserBase 登记值一致，必须带引号且含字母
+ app-key: 100020
+ app-secret: "question-center-dev-secret-100020"
+ # 本应用自身无 /oapi 提供面（不对外），enforce-patterns 留空即可
+ trust-registry: true
+ trusted-apps: {}
+ open:
+ # 本地指向 local-debug 的 UserBase；生产由平台注入 YH_OPEN_BASE_HOST 覆盖
+ base-host: http://localhost:8060
+ base-path: ""
+ services:
+ # 问卷后端唯一的 FC 出站点（FormCenterClient）指向本地 FC 后端
+ form-center: http://localhost:8086
+
+# ===== 问卷应用专属配置 =====
+question:
+ # 答卷投影：定时全量扫描（每张收集中问卷按游标增量拉取）+ 手动触发
+ projection:
+ # 定时间隔毫秒（任务书 §4.5：约 30s；要"关闭"定时就设超大值，如 86400000）
+ fixed-delay-ms: 30000
+ # 单表单单次循环最多翻页数（防 FC 异常数据导致长循环）
+ max-pages-per-form: 200
+ # 每页 limit（FC 上限 2000，缺省 500）
+ page-limit: 500
+
+logging:
+ level:
+ com.yunhai.question: debug
+
+management:
+ endpoints:
+ web:
+ exposure:
+ include: health
+ endpoint:
+ health:
+ show-details: never
+ health:
+ redis:
+ # 引 data-redis 仅服务于平台密钥链；关健康指标防 Redis 停摆拉 DOWN /actuator/health
+ enabled: false
diff --git a/src/test/java/com/yunhai/question/fc/FormCenterClientTest.java b/src/test/java/com/yunhai/question/fc/FormCenterClientTest.java
new file mode 100644
index 0000000..2d7fc42
--- /dev/null
+++ b/src/test/java/com/yunhai/question/fc/FormCenterClientTest.java
@@ -0,0 +1,138 @@
+package com.yunhai.question.fc;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.yunhai.platform.openapi.core.YschOpenCall;
+import com.yunhai.platform.utils.exception.DException;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.util.Arrays;
+import java.util.HashMap;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyMap;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * FormCenterClient 单元测试（mock YschOpenCall）：
+ * ① 业务拒绝（DException=FC 信封 code!=0）不重试直接转 Reject；
+ * ② 网络/信封异常重试 2 次后转 Unavailable；③ answers 分页解析（rows/nextCursor/after 透传）。
+ */
+class FormCenterClientTest {
+
+ private YschOpenCall openCall;
+ private FormCenterClient client;
+
+ @BeforeEach
+ void setUp() {
+ openCall = mock(YschOpenCall.class);
+ client = new FormCenterClient(openCall, new ObjectMapper());
+ }
+
+ @Test
+ void fetchSchemaReturnsData() {
+ Map data = new HashMap<>();
+ data.put("formUuid", "U1");
+ data.put("version", 2);
+ data.put("groups", Arrays.asList(
+ group("base", field("q1", "你的性别", "radio",
+ option("男", "m"), option("女", "f")))));
+ when(openCall.get(anyString(), anyString(), anyMap(), eq(Map.class))).thenReturn(data);
+
+ Map got = client.fetchSchema(27L, "U1");
+
+ assertEquals("U1", got.get("formUuid"));
+ assertEquals(1, client.parseFields(got).size());
+ assertEquals("radio", client.parseFields(got).get(0).get("type"));
+ }
+
+ @Test
+ void fcBusinessRejectIsNotRetried() {
+ when(openCall.get(anyString(), anyString(), anyMap(), eq(Map.class)))
+ .thenThrow(new DException("表单尚未发布：q-001"));
+
+ FormCenterClient.FormCenterRejectException e = assertThrows(
+ FormCenterClient.FormCenterRejectException.class,
+ () -> client.fetchSchema(27L, "U1"));
+ assertTrue(e.getMessage().contains("表单尚未发布"));
+ verify(openCall, times(1)).get(anyString(), anyString(), anyMap(), eq(Map.class));
+ }
+
+ @Test
+ void networkFailureRetriesTwiceThenUnavailable() {
+ when(openCall.get(anyString(), anyString(), anyMap(), eq(Map.class)))
+ .thenThrow(new RuntimeException("connect refused"));
+
+ assertThrows(FormCenterClient.FormCenterUnavailableException.class,
+ () -> client.fetchSchema(27L, "U1"));
+ verify(openCall, times(FormCenterClient.MAX_ATTEMPTS))
+ .get(anyString(), anyString(), anyMap(), eq(Map.class));
+ }
+
+ @Test
+ @SuppressWarnings("unchecked")
+ void pullAnswersParsesRowsAndCursor() {
+ Map page = new HashMap<>();
+ page.put("rows", Arrays.asList(row("a1"), row("a2")));
+ page.put("nextCursor", "a2");
+ when(openCall.get(anyString(), anyString(), anyMap(), eq(Map.class))).thenReturn(page);
+
+ FormCenterClient.AnswersPage got = client.pullAnswers(27L, "U1", null, 500);
+
+ assertEquals(2, got.getRows().size());
+ assertEquals("a2", got.getNextCursor());
+ assertEquals("a1", got.getRows().get(0).get("answer_uuid"));
+ }
+
+ @Test
+ void pullAnswersEndOfWindowHasNullCursor() {
+ Map page = new HashMap<>();
+ page.put("rows", Arrays.asList());
+ page.put("nextCursor", null);
+ when(openCall.get(anyString(), anyString(), anyMap(), eq(Map.class))).thenReturn(page);
+
+ FormCenterClient.AnswersPage got = client.pullAnswers(27L, "U1", "a2", 500);
+
+ assertEquals(null, got.getNextCursor());
+ assertTrue(got.getRows().isEmpty());
+ }
+
+ private static Map row(String uuid) {
+ Map r = new HashMap<>();
+ r.put("answer_uuid", uuid);
+ r.put("is_deleted", 0);
+ return r;
+ }
+
+ static Map group(String key, Map... fields) {
+ Map g = new HashMap<>();
+ g.put("key", key);
+ g.put("fields", Arrays.asList(fields));
+ return g;
+ }
+
+ static Map field(String key, String label, String type, Map... options) {
+ Map f = new HashMap<>();
+ f.put("key", key);
+ f.put("label", label);
+ f.put("type", type);
+ f.put("options", Arrays.asList(options));
+ return f;
+ }
+
+ static Map option(String label, String value) {
+ Map o = new HashMap<>();
+ o.put("label", label);
+ o.put("value", value);
+ return o;
+ }
+}
diff --git a/src/test/java/com/yunhai/question/service/ProjectionServiceTest.java b/src/test/java/com/yunhai/question/service/ProjectionServiceTest.java
new file mode 100644
index 0000000..e59f068
--- /dev/null
+++ b/src/test/java/com/yunhai/question/service/ProjectionServiceTest.java
@@ -0,0 +1,208 @@
+package com.yunhai.question.service;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.yunhai.question.entity.PullCursor;
+import com.yunhai.question.entity.Questionnaire;
+import com.yunhai.question.fc.FormCenterClient;
+import com.yunhai.question.repository.AnswerProjectionRepository;
+import com.yunhai.question.repository.PullCursorRepository;
+import com.yunhai.question.repository.QuestionnaireRepository;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
+import org.springframework.transaction.PlatformTransactionManager;
+import org.springframework.transaction.support.TransactionTemplate;
+
+import java.util.Arrays;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * 投影服务单测（H2 真库 + mock FormCenterClient）——任务书点名的四件之二/三：
+ * 游标推进、投影幂等 upsert（重放同窗口不产生重复行、不重复累计 seen_count）、墓碑翻位。
+ */
+@DataJpaTest
+class ProjectionServiceTest {
+
+ private static final Long SCH_ID = 990001L;
+ private static final String FORM_UUID = "f0123456789abcdef0123456789abcde";
+
+ @Autowired
+ private QuestionnaireRepository questionnaireRepository;
+ @Autowired
+ private PullCursorRepository pullCursorRepository;
+ @Autowired
+ private AnswerProjectionRepository answerProjectionRepository;
+ @Autowired
+ private PlatformTransactionManager txManager;
+
+ private FormCenterClient fc;
+ private ProjectionService service;
+
+ @BeforeEach
+ void setUp() {
+ fc = mock(FormCenterClient.class);
+ service = new ProjectionService(questionnaireRepository, pullCursorRepository,
+ answerProjectionRepository, fc, new ObjectMapper(),
+ new TransactionTemplate(txManager), 10, 100);
+ }
+
+ private Questionnaire questionnaire(String formUuid) {
+ Questionnaire q = new Questionnaire();
+ q.setSchId(SCH_ID);
+ q.setFormUuid(formUuid);
+ q.setFormCode("q-001");
+ q.setTitleSnapshot("测试问卷");
+ q.setStatus(Questionnaire.STATUS_COLLECTING);
+ q.setAnonymous(false);
+ return questionnaireRepository.save(q);
+ }
+
+ /** FC 行（snake_case 闭集） */
+ private static Map fcRow(String uuid, boolean deleted, Object... valuePairs) {
+ Map values = new LinkedHashMap<>();
+ for (int i = 0; i + 1 < valuePairs.length; i += 2) {
+ values.put(String.valueOf(valuePairs[i]), valuePairs[i + 1]);
+ }
+ Map row = new HashMap<>();
+ row.put("answer_uuid", uuid);
+ row.put("form_uuid", FORM_UUID);
+ row.put("submitter_id", 101);
+ row.put("subject_id", null);
+ row.put("status", "待处理");
+ row.put("values", values);
+ row.put("create_time", "2026-10-21 10:00:00");
+ row.put("update_time", "2026-10-21 10:00:00");
+ row.put("is_deleted", deleted ? 1 : 0);
+ return row;
+ }
+
+ /** after=afterArg 的页（rows 可空） */
+ private void stubPage(String afterArg, String nextCursor, Map... rows) {
+ when(fc.pullAnswers(any(), anyString(), eq(afterArg), anyInt()))
+ .thenReturn(new FormCenterClient.AnswersPage(Arrays.asList(rows), nextCursor));
+ }
+
+ @Test
+ void advancesCursorAcrossPages() {
+ questionnaire(FORM_UUID);
+ stubPage(null, "a1", fcRow("a1", false, "q1", "m"));
+ stubPage("a1", "a2", fcRow("a2", false, "q1", "f"));
+ stubPage("a2", null);
+
+ service.pullOnce(SCH_ID, FORM_UUID);
+ assertEquals("a2", pullCursorRepository.findById(FORM_UUID).get().getCursor());
+ assertEquals(2, answerProjectionRepository.countByFormUuid(FORM_UUID));
+
+ // 第二轮：游标从 a2 起，只拉增量
+ stubPage("a2", "a3", fcRow("a3", false, "q1", "m"));
+ stubPage("a3", null);
+ int fresh = service.pullOnce(SCH_ID, FORM_UUID);
+ assertEquals(1, fresh);
+ assertEquals("a3", pullCursorRepository.findById(FORM_UUID).get().getCursor());
+ assertEquals(3, answerProjectionRepository.countByFormUuid(FORM_UUID));
+ // 增量轮从 a2 起——验证游标确已推进（a2 之前的窗口未再请求）
+ verify(fc, times(1)).pullAnswers(any(), anyString(), eq((String) null), anyInt());
+ verify(fc, times(1)).pullAnswers(any(), anyString(), eq("a1"), anyInt());
+ verify(fc, times(2)).pullAnswers(any(), anyString(), eq("a2"), anyInt());
+ }
+
+ @Test
+ void replaySameWindowIsIdempotent() {
+ questionnaire(FORM_UUID);
+ stubPage(null, "a1", fcRow("a1", false, "q1", "m"));
+ stubPage("a1", null);
+ service.pullOnce(SCH_ID, FORM_UUID);
+
+ // 模拟游标回拨（运维/异常后重放）：从头再拉同窗口 + 新行 a2——a1 重放不算新行
+ PullCursor rollback = pullCursorRepository.findById(FORM_UUID).orElseThrow(AssertionError::new);
+ rollback.setCursor(null);
+ pullCursorRepository.saveAndFlush(rollback);
+ stubPage(null, "a2", fcRow("a1", false, "q1", "m"), fcRow("a2", false, "q1", "f"));
+ stubPage("a2", null);
+ int fresh = service.pullOnce(SCH_ID, FORM_UUID);
+
+ assertEquals(1, fresh);
+ assertEquals(2, answerProjectionRepository.countByFormUuid(FORM_UUID));
+ PullCursor cursor = pullCursorRepository.findById(FORM_UUID).get();
+ assertEquals(2L, cursor.getSeenCount(), "重放行不重复累计 seen_count");
+ assertEquals("a2", cursor.getCursor());
+ }
+
+ @Test
+ void tombstoneFlipsIsDeletedWithoutDroppingRow() {
+ questionnaire(FORM_UUID);
+ stubPage(null, "a1", fcRow("a1", false, "q1", "m"));
+ stubPage("a1", null);
+ service.pullOnce(SCH_ID, FORM_UUID);
+ assertEquals(1, answerProjectionRepository.countByFormUuidAndIsDeletedFalse(FORM_UUID));
+
+ // FC 侧软删 → 墓碑行：同一 answer_uuid，is_deleted=1
+ stubPage("a1", null, fcRow("a1", true, "q1", "m"));
+ service.pullOnce(SCH_ID, FORM_UUID);
+
+ assertEquals(0, answerProjectionRepository.countByFormUuidAndIsDeletedFalse(FORM_UUID));
+ assertEquals(1, answerProjectionRepository.countByFormUuid(FORM_UUID), "墓碑不删行");
+ assertTrue(answerProjectionRepository.findByAnswerUuid("a1").getIsDeleted());
+ assertEquals(1L, pullCursorRepository.findById(FORM_UUID).get().getSeenCount(),
+ "墓碑是已见行的翻位，不计新行");
+ }
+
+ @Test
+ void updatedRowKeepsSingleRow() {
+ questionnaire(FORM_UUID);
+ stubPage(null, "a1", fcRow("a1", false, "q1", "m"));
+ stubPage("a1", null);
+ service.pullOnce(SCH_ID, FORM_UUID);
+
+ // 状态被 FC 侧更新后重放：同 uuid 更新而非插入
+ Map updated = fcRow("a1", false, "q1", "f");
+ updated.put("status", "已处理");
+ stubPage("a1", null, updated);
+ service.pullOnce(SCH_ID, FORM_UUID);
+
+ assertEquals(1, answerProjectionRepository.countByFormUuid(FORM_UUID));
+ assertEquals("已处理", answerProjectionRepository.findByAnswerUuid("a1").getStatus());
+ assertEquals(1L, pullCursorRepository.findById(FORM_UUID).get().getSeenCount());
+ }
+
+ @Test
+ void firstPullWithEmptyWindowInitializesCursor() {
+ questionnaire(FORM_UUID);
+ stubPage(null, null);
+
+ int fresh = service.pullOnce(SCH_ID, FORM_UUID);
+
+ assertEquals(0, fresh);
+ PullCursor cursor = pullCursorRepository.findById(FORM_UUID).get();
+ assertNull(cursor.getCursor(), "空窗口不推进游标（null=从未有行）");
+ assertEquals("OK", cursor.getLastStatus());
+ }
+
+ @Test
+ void reconciliationWarnsOnSeenCountDrift() {
+ questionnaire(FORM_UUID);
+ stubPage(null, "a1", fcRow("a1", false, "q1", "m"));
+ stubPage("a1", null);
+ service.pullOnce(SCH_ID, FORM_UUID);
+
+ // 模拟投影表被外部删行：seen_count=1 但投影总量=0 → 漂移告警路径（不抛错）
+ answerProjectionRepository.deleteAll();
+ service.checkReconciliation(FORM_UUID, pullCursorRepository.findById(FORM_UUID).get());
+ assertEquals(0, answerProjectionRepository.countByFormUuid(FORM_UUID));
+ }
+}
diff --git a/src/test/java/com/yunhai/question/service/QuestionnaireServiceTest.java b/src/test/java/com/yunhai/question/service/QuestionnaireServiceTest.java
new file mode 100644
index 0000000..c0a15cb
--- /dev/null
+++ b/src/test/java/com/yunhai/question/service/QuestionnaireServiceTest.java
@@ -0,0 +1,82 @@
+package com.yunhai.question.service;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.yunhai.question.entity.Questionnaire;
+import com.yunhai.question.fc.FormCenterClient;
+import com.yunhai.question.repository.QuestionnaireRepository;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
+
+import java.util.Arrays;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.mockito.Mockito.mock;
+
+/**
+ * 绑定登记幂等单测（H2 真库——uk form_uuid 是数据库级约束，mock 测不出真实行为）：
+ * 重复提交第三步不产生重复行；发布被 FC 拒（未发布）时拦截。
+ */
+@DataJpaTest
+class QuestionnaireServiceTest {
+
+ private static final Long SCH_ID = 990001L;
+
+ @Autowired
+ private QuestionnaireRepository questionnaireRepository;
+
+ private FormCenterClient fc;
+ private QuestionnaireService service;
+
+ @BeforeEach
+ void setUp() {
+ fc = mock(FormCenterClient.class);
+ service = new QuestionnaireService(questionnaireRepository, fc, new ObjectMapper());
+ }
+
+ @Test
+ void registerIsIdempotentOnFormUuid() {
+ Questionnaire first = service.register(SCH_ID,
+ "u0123456789abcdef0123456789abcde", "q-001", "食堂满意度调查", false, null);
+ Questionnaire second = service.register(SCH_ID,
+ "u0123456789abcdef0123456789abcde", "q-001", "食堂满意度调查", false, null);
+
+ assertSame(first, second, "重复登记返回既有行");
+ assertEquals(1, questionnaireRepository.count());
+ assertEquals(Questionnaire.STATUS_DRAFT, second.getStatus());
+ }
+
+ @Test
+ void registerKeepsSchoolsIsolated() {
+ service.register(SCH_ID, "u0123456789abcdef0123456789abcde", "q-001", "本校问卷", false, null);
+ service.register(990002L, "u1123456789abcdef0123456789abcde", "q-002", "他校问卷", false, null);
+
+ List mine = service.list(SCH_ID);
+ assertEquals(1, mine.size());
+ assertEquals("u0123456789abcdef0123456789abcde", mine.get(0).getFormUuid());
+ }
+
+ @Test
+ void myFillableIntersectsByFormCode() {
+ Questionnaire draft1 = service.register(SCH_ID, "u0123456789abcdef0123456789abcde", "q-001", "问卷一", false, null);
+ Questionnaire draft2 = service.register(SCH_ID, "u1123456789abcdef0123456789abcde", "q-002", "问卷二", false, null);
+ draft1.setStatus(Questionnaire.STATUS_COLLECTING);
+ draft2.setStatus(Questionnaire.STATUS_COLLECTING);
+ questionnaireRepository.save(draft1);
+ questionnaireRepository.save(draft2);
+
+ // FC fillable 只回了 q-002/q-999：交集后仅问卷二可见
+ List got = service.myFillable(SCH_ID, Arrays.asList("q-002", "q-999"));
+ assertEquals(1, got.size());
+ assertEquals("q-002", got.get(0).getFormCode());
+ }
+
+ @Test
+ void myFillableWithNoCodesReturnsEmpty() {
+ service.register(SCH_ID, "u0123456789abcdef0123456789abcde", "q-001", "问卷一", false, null);
+ assertEquals(0, service.myFillable(SCH_ID, java.util.Collections.emptyList()).size());
+ }
+}
diff --git a/src/test/java/com/yunhai/question/service/SchoolAdminGuardTest.java b/src/test/java/com/yunhai/question/service/SchoolAdminGuardTest.java
new file mode 100644
index 0000000..dc1f41a
--- /dev/null
+++ b/src/test/java/com/yunhai/question/service/SchoolAdminGuardTest.java
@@ -0,0 +1,52 @@
+package com.yunhai.question.service;
+
+import com.yunhai.platform.utils.model.BoaUser;
+import com.yunhai.question.common.BizException;
+import org.junit.jupiter.api.Test;
+
+import java.util.Arrays;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.mockito.Mockito.RETURNS_DEEP_STUBS;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/** 校管理员守卫单测：超管(type=1)/校领导(2)/管理员(7) 放行，普通教师/学生/未登录拒绝 */
+class SchoolAdminGuardTest {
+
+ private final SchoolAdminGuard guard = new SchoolAdminGuard();
+
+ private BoaUser user(Integer id, Integer type, Integer schId, Integer... roleIds) {
+ BoaUser user = mock(BoaUser.class, RETURNS_DEEP_STUBS);
+ when(user.getId()).thenReturn(id);
+ when(user.getType()).thenReturn(type);
+ when(user.getRoleIds()).thenReturn(roleIds.length == 0 ? null
+ : new java.util.ArrayList<>(Arrays.asList(roleIds)));
+ when(user.getCurrentRole().getSchId()).thenReturn(schId);
+ return user;
+ }
+
+ @Test
+ void superAdminPasses() {
+ assertEquals(990001L, guard.requireSchool(user(1, 1, 990001)));
+ }
+
+ @Test
+ void schoolLeaderAndAdminRolePass() {
+ assertEquals(990001L, guard.requireSchool(user(9, 2, 990001, 2)));
+ assertEquals(990001L, guard.requireSchool(user(10, 2, 990001, 1, 7)));
+ }
+
+ @Test
+ void plainTeacherAndStudentRejected() {
+ assertThrows(BizException.class, () -> guard.requireSchool(user(11, 2, 990001, 1)));
+ assertThrows(BizException.class, () -> guard.requireSchool(user(12, 2, 990001, 3)));
+ }
+
+ @Test
+ void anonymousAndNoSchoolContextRejected() {
+ assertThrows(BizException.class, () -> guard.requireSchool(user(null, null, null)));
+ assertThrows(BizException.class, () -> guard.requireSchool(user(13, 1, null, 2)));
+ }
+}
diff --git a/src/test/java/com/yunhai/question/service/StatsServiceTest.java b/src/test/java/com/yunhai/question/service/StatsServiceTest.java
new file mode 100644
index 0000000..3e8bf52
--- /dev/null
+++ b/src/test/java/com/yunhai/question/service/StatsServiceTest.java
@@ -0,0 +1,175 @@
+package com.yunhai.question.service;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.yunhai.question.entity.AnswerProjection;
+import com.yunhai.question.entity.Questionnaire;
+import com.yunhai.question.fc.FormCenterClient;
+import com.yunhai.question.repository.AnswerProjectionRepository;
+import com.yunhai.question.repository.QuestionnaireRepository;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
+
+import java.util.Arrays;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.mockito.Mockito.mock;
+
+/**
+ * 基础统计单测（H2 真库）——任务书点名的"人数口径统计"：
+ * 一份答卷对一题的一个选项最多计 1，多选按答卷去重后逐选项计数（与选次口径可区分）。
+ */
+@DataJpaTest
+class StatsServiceTest {
+
+ private static final String FORM_UUID = "s0123456789abcdef0123456789abcde";
+
+ @Autowired
+ private QuestionnaireRepository questionnaireRepository;
+ @Autowired
+ private AnswerProjectionRepository answerProjectionRepository;
+
+ private StatsService statsService;
+
+ @BeforeEach
+ void setUp() {
+ QuestionnaireService questionnaireService = new QuestionnaireService(
+ questionnaireRepository, mock(FormCenterClient.class), new ObjectMapper());
+ statsService = new StatsService(answerProjectionRepository, questionnaireService, new ObjectMapper());
+ }
+
+ private Questionnaire published() {
+ Questionnaire q = new Questionnaire();
+ q.setSchId(990001L);
+ q.setFormUuid(FORM_UUID);
+ q.setFormCode("q-001");
+ q.setTitleSnapshot("统计测试卷");
+ q.setStatus(Questionnaire.STATUS_COLLECTING);
+ q.setAnonymous(false);
+ q.setFormVersion(3);
+ // schema 快照：单选 q1(radio) + 多选 q2(checkbox) + 文本 q3(text)
+ q.setSchemaSnapshot("{\"formUuid\":\"" + FORM_UUID + "\",\"version\":3,\"groups\":[{\"key\":\"g1\",\"fields\":["
+ + "{\"key\":\"q1\",\"label\":\"年级\",\"type\":\"radio\",\"required\":true,\"options\":["
+ + "{\"label\":\"高一\",\"value\":\"g1v1\"},{\"label\":\"高二\",\"value\":\"g1v2\"}]},"
+ + "{\"key\":\"q2\",\"label\":\"喜欢的社团（多选）\",\"type\":\"checkbox\",\"options\":["
+ + "{\"label\":\"篮球\",\"value\":\"shetuan_basketball\"},{\"label\":\"合唱\",\"value\":\"shetuan_chorus\"},{\"label\":\"编程\",\"value\":\"shetuan_coding\"}]},"
+ + "{\"key\":\"q3\",\"label\":\"建议\",\"type\":\"textarea\"}"
+ + "]}]}");
+ return questionnaireRepository.save(q);
+ }
+
+ private void answer(String uuid, Object q1, Object q2, String q3) {
+ AnswerProjection p = new AnswerProjection();
+ p.setAnswerUuid(uuid);
+ p.setFormUuid(FORM_UUID);
+ Map values = new HashMap<>();
+ values.put("q1", q1);
+ values.put("q2", q2);
+ values.put("q3", q3);
+ try {
+ p.setValuesJson(new ObjectMapper().writeValueAsString(values));
+ } catch (Exception e) {
+ throw new IllegalStateException(e);
+ }
+ p.setSubmitterId(101);
+ p.setStatus("待处理");
+ p.setIsDeleted(false);
+ p.setFcCreateTime("2026-10-21 10:00:00");
+ answerProjectionRepository.save(p);
+ }
+
+ @Test
+ @SuppressWarnings("unchecked")
+ void multiSelectCountsDistinctRespondentsPerOption() {
+ published();
+ // 卷A：q2 选 [篮球,合唱]；卷B：q2 选 [合唱]；卷C：q2 未答
+ answer("a1", "g1v1", Arrays.asList("shetuan_basketball", "shetuan_chorus"), "很好");
+ answer("a2", "g1v2", Arrays.asList("shetuan_chorus"), null);
+ answer("a3", "g1v1", null, null);
+
+ Map stats = statsService.stats(questionnaireRepository
+ .findByFormUuidAndIsDeletedFalse(FORM_UUID).get());
+
+ assertEquals(3L, stats.get("total"));
+
+ List> byField = (List>) stats.get("byField");
+ Map q2 = byField.stream()
+ .filter(f -> "q2".equals(f.get("key"))).findFirst().get();
+
+ // 人数口径：篮球=1 人、合唱=2 人、编程=0 人；answeredSheets=2（a3 未答不计分母）
+ assertEquals(2L, q2.get("answeredSheets"));
+ Map counts = new HashMap<>();
+ for (Map item : (List>) q2.get("items")) {
+ counts.put(String.valueOf(item.get("value")), ((Number) item.get("count")).longValue());
+ }
+ assertEquals(1L, counts.get("shetuan_basketball"), "篮球：仅卷A计 1 人");
+ assertEquals(2L, counts.get("shetuan_chorus"), "合唱：卷A+卷B 各计 1 人（人数口径，非选次——选次也是 2）");
+ assertEquals(0L, counts.get("shetuan_coding"));
+ }
+
+ @Test
+ @SuppressWarnings("unchecked")
+ void multiSelectSameOptionTwiceInOneSheetCountsOnce() {
+ published();
+ // 一份答卷的 q2 里同选项出现两次（异常数据防御）：人数口径仍计 1
+ answer("a1", "g1v1", Arrays.asList("shetuan_basketball", "shetuan_basketball"), null);
+
+ Map stats = statsService.stats(questionnaireRepository
+ .findByFormUuidAndIsDeletedFalse(FORM_UUID).get());
+ List> byField = (List>) stats.get("byField");
+ Map q2 = byField.stream()
+ .filter(f -> "q2".equals(f.get("key"))).findFirst().get();
+ Map counts = new HashMap<>();
+ for (Map item : (List>) q2.get("items")) {
+ counts.put(String.valueOf(item.get("value")), ((Number) item.get("count")).longValue());
+ }
+ assertEquals(1L, counts.get("shetuan_basketball"), "同卷同选项去重后计 1");
+ }
+
+ @Test
+ @SuppressWarnings("unchecked")
+ void radioCountsByScalarAndTextDetailListed() {
+ published();
+ answer("a1", "g1v1", null, "建议一");
+ answer("a2", "g1v2", null, "建议二");
+
+ Map stats = statsService.stats(questionnaireRepository
+ .findByFormUuidAndIsDeletedFalse(FORM_UUID).get());
+ List> byField = (List>) stats.get("byField");
+ Map q1 = byField.stream()
+ .filter(f -> "q1".equals(f.get("key"))).findFirst().get();
+ Map counts = new HashMap<>();
+ for (Map item : (List>) q1.get("items")) {
+ counts.put(String.valueOf(item.get("value")), ((Number) item.get("count")).longValue());
+ }
+ assertEquals(1L, counts.get("g1v1"));
+ assertEquals(1L, counts.get("g1v2"));
+
+ List> textDetail = (List>) stats.get("textDetail");
+ Map q3 = textDetail.stream()
+ .filter(f -> "q3".equals(f.get("key"))).findFirst().get();
+ assertEquals(Arrays.asList("建议一", "建议二"), q3.get("items"));
+ }
+
+ @Test
+ @SuppressWarnings("unchecked")
+ void tombstoneRowsAreExcluded() {
+ published();
+ answer("a1", "g1v1", null, null);
+ AnswerProjection tombstone = new AnswerProjection();
+ tombstone.setAnswerUuid("a2");
+ tombstone.setFormUuid(FORM_UUID);
+ tombstone.setValuesJson("{\"q1\":\"g1v2\"}");
+ tombstone.setSubmitterId(102);
+ tombstone.setIsDeleted(true);
+ answerProjectionRepository.save(tombstone);
+
+ Map stats = statsService.stats(questionnaireRepository
+ .findByFormUuidAndIsDeletedFalse(FORM_UUID).get());
+ assertEquals(1L, stats.get("total"), "墓碑行不进统计");
+ }
+}
diff --git a/src/test/resources/application.yml b/src/test/resources/application.yml
new file mode 100644
index 0000000..9bcbdbc
--- /dev/null
+++ b/src/test/resources/application.yml
@@ -0,0 +1,21 @@
+# 单测环境：H2 内存库（MySQL 兼容模式），无 MySQL/Redis/FC 外部依赖
+spring:
+ datasource:
+ url: jdbc:h2:mem:questiontest;MODE=MySQL;DATABASE_TO_LOWER=TRUE;CASE_INSENSITIVE_IDENTIFIERS=TRUE
+ driver-class-name: org.h2.Driver
+ username: sa
+ password: ""
+ jpa:
+ hibernate:
+ ddl-auto: create-drop
+ database-platform: org.hibernate.dialect.H2Dialect
+ properties:
+ hibernate:
+ jdbc:
+ time_zone: Asia/Shanghai
+
+question:
+ projection:
+ fixed-delay-ms: 86400000
+ max-pages-per-form: 10
+ page-limit: 100