test(invariants): Phase 23 Task 2.2 —— INV-011 显式行为守卫(9 用例 + 两次负向注入验证)

产出 Inv011EvidenceAccessGuardTest:非领取人 / 跨用户佐证 / 非 local_eligibility 任务一律拒绝,
且 successful 与 denied 两条路径都断言 sensitive_access_logs 真实落库(不用 mock 断言)。
另含 3 个结构性守卫(用户侧端点无用户可控 userId 入参、佐证读取入口的双重权限约束、
佐证读取不暴露可伪造 operatorId)与 1 个守卫自检(参数名反射可读,防断言静默永真)。

前置修复:schema-h2.sql 补 sensitive_access_logs 表 —— 该表此前在测试库完全不存在,
而它是「访问留痕」命题的唯一落点,缺失导致该命题根本无法断言(表漂移盲区,与 Phase 12/15/19 同族)。

负向注入两次,均精确命中:
① 停用 requireClaimOwner → 恰 1 红(非领取人用例),其余 8 绿
② 停用 catch 内 denied 审计 → 恰 2 红(非领取人 + 跨用户),第 3 条走 try 外的另一路径故正确未红
两次注入均已还原并复跑全绿(9/9);V11InvariantsTest 12/12 绿;UI 契约门禁 18/18 绿。

文档:Task 2.2 闭环记录 + 附 A 扩至 7 处校正(含对本文档初稿「机构创建 500 归因」的自我更正,
实测为 chk_org_status 违约而非 id 为空)+ 附 B 扩至 11 项新发现
(5 个 Mapper 方法声明了却无实现、隐私设置三方契约冲突 + 表/实体主键错配、
测试镜像 mvn -o 不可用、本机全量回归会卡住)。
This commit is contained in:
WorkBuddy
2026-09-19 14:02:52 +08:00
parent e666ee6f8a
commit b834fa86a0
4 changed files with 561 additions and 19 deletions
@@ -0,0 +1,388 @@
package com.danyang.match.platform.invariants;
import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.danyang.match.platform.audit.entity.SensitiveAccessLog;
import com.danyang.match.platform.audit.mapper.SensitiveAccessLogMapper;
import com.danyang.match.platform.local_eligibility.controller.LocalEligibilityController;
import com.danyang.match.platform.local_eligibility.entity.LocalEligibility;
import com.danyang.match.platform.local_eligibility.entity.LocalEligibilityEvidence;
import com.danyang.match.platform.local_eligibility.mapper.LocalEligibilityEvidenceMapper;
import com.danyang.match.platform.local_eligibility.mapper.LocalEligibilityMapper;
import com.danyang.match.platform.review.controller.ReviewController;
import com.danyang.match.platform.review.entity.ReviewTask;
import com.danyang.match.platform.review.mapper.ReviewTaskMapper;
import com.danyang.match.platform.review.service.ReviewService;
import com.danyang.match.platform.shared.constant.Constants;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.test.context.ActiveProfiles;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PatchMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import java.lang.annotation.Annotation;
import java.lang.reflect.Method;
import java.lang.reflect.Parameter;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.Map;
import java.util.UUID;
import static org.junit.jupiter.api.Assertions.*;
/**
* INV-011 显式行为守卫 —— 本地资格佐证「不可越权读取 + 访问必留痕」。
*
* <h3>为什么需要本文件</h3>
* INV-011 此前只有<b>常量口径 + 指针</b>(见 {@link V11InvariantsTest#inv011LocalEligibilityVocabulary}):
* 指向的两个测试类都不验证 INV-011 语义本身 ——
* {@code LocalEligibilityServiceTest} 测的是用户侧声明/上传流程,
* {@code LocalEligibilityStatusVocabularyGuardTest} 测的是状态词表。
* 于是「非授权角色能否读到他人本地资格佐证」「读取是否真的留痕」这两个 INV-011 的核心命题
* <b>在测试上完全悬空</b>,与本仓库反复出现的「名不副实的测试」同族。
*
* <h3>两条独立命题,分别咬住不同的落点</h3>
* <ol>
* <li><b>不可越权读取</b>:佐证没有独立的服务端读取入口。唯一入口是
* {@code POST /operator/reviews/{taskId}/evidences/{evidenceId}/access},
* 它有两级权限注解(类级 {@code review.view} + 方法级 {@code local_eligibility.evidence.view}),
* 业务层再由 {@code ReviewService.accessLocalEligibilityEvidence} 复核四件事:
* {@code purpose} 非空 → 任务类型为 {@code local_eligibility} → 领取人本人 →
* 佐证归属该任务用户的资格记录。权限与归属<b>都不允许</b>「换个 taskId 就读到别人的佐证」。</li>
* <li><b>访问必留痕</b>:成功与拒绝都写 {@code sensitive_access_logs}
* ({@code access_result = success | denied})。本文件的断言一律<b>回查真实落库</b>,
* 不复用 {@code ReviewServicePhase05Test} 那种 {@code verify(mapper).insert(...)} 的 mock 断言 ——
* mock 只能证明「调用了某个方法」,证明不了「审计真的进了库、字段真的对」。</li>
* </ol>
*
* <h3>与本文件同时补齐的一处测试基建缺口</h3>
* {@code sensitive_access_logs} 此前在 H2 测试库<b>完全不存在</b>(见 {@code schema-h2.sql}),
* 而该表是上面第 2 条命题的唯一落点 —— 表缺失直接导致这条命题无法被断言。
* 已按 V001 + V034 + V035 补齐,列定义与生产对齐。
*
* <h3>本文件<b>如实</b>固化而非粉饰的两处边界</h3>
* {@code purpose} 为空、{@code taskId} 不存在这两条早退路径<b>不写审计</b>。它们在业务上早于
* 「触及具体用户的数据」发生(前者连参数都不合法,后者根本定位不到用户),
* 因此不构成「读了却没留痕」;本文件把它们写成显式断言,是为了让这个边界成为<b>被声明的契约</b>,
* 而不是后人眼中的漏测。若后续产品要求「任何调用都留痕」,这两条断言会立刻变红,成为改动提示。
*/
@SpringBootTest
@ActiveProfiles("test")
@Transactional
class Inv011EvidenceAccessGuardTest {
@MockBean
private StringRedisTemplate stringRedisTemplate;
@Autowired private ReviewService reviewService;
@Autowired private ReviewTaskMapper reviewTaskMapper;
@Autowired private LocalEligibilityMapper localEligibilityMapper;
@Autowired private LocalEligibilityEvidenceMapper evidenceMapper;
@Autowired private SensitiveAccessLogMapper sensitiveAccessLogMapper;
/** 审核任务的领取人:唯一有权读取本任务佐证的运营。 */
private static final String CLAIM_OWNER = "op-inv011-claim-owner";
/** 另一名运营。即便他同样持有全部相关权限,也不得读取「非自己领取」任务的佐证。 */
private static final String OTHER_OPERATOR = "op-inv011-other";
private static final String USER_A = "u-inv011-a";
private static final String USER_B = "u-inv011-b";
// ==========================================================================
// 负向:越权读取一律拒绝,且必须留下 denied 审计
// ==========================================================================
@Test
@DisplayName("INV-011: 非领取人读取佐证 → 拒绝,且落库一条 denied 审计")
void inv011NonClaimantDeniedAndAudited() {
String eligibilityId = newEligibility(USER_A);
String evidenceId = newEvidence(eligibilityId);
String taskId = newTask(USER_A, Constants.REVIEW_TYPE_LOCAL_ELIGIBILITY, CLAIM_OWNER);
RuntimeException error = assertThrows(RuntimeException.class,
() -> reviewService.accessLocalEligibilityEvidence(
taskId, evidenceId, OTHER_OPERATOR, "例行核验"),
"非领取人读取他人佐证必须被拒绝");
assertTrue(error.getMessage().contains("领取"),
"拒绝理由应指向「领取人」约束,实得: " + error.getMessage());
SensitiveAccessLog audit = singleAudit(evidenceId);
assertEquals("denied", audit.getAccessResult(), "拒绝访问也必须留痕");
assertEquals(OTHER_OPERATOR, audit.getOperatorId(), "审计必须记录实际发起访问的运营");
assertEquals(USER_A, audit.getUserId(), "审计必须记录数据归属的用户");
assertEquals(Constants.SENSITIVE_DATA_TYPE_LOCAL_EVIDENCE, audit.getDataType());
}
@Test
@DisplayName("INV-011: 领取人用自己的 taskId 读他人佐证 → 拒绝,且落库 denied")
void inv011CrossUserEvidenceDeniedAndAudited() {
// 同为「领取人本人」的合法身份,但佐证属于另一个用户 —— 归属校验必须拦住
String eligibilityA = newEligibility(USER_A);
newEvidence(eligibilityA);
String eligibilityB = newEligibility(USER_B);
String evidenceBOfUserB = newEvidence(eligibilityB);
String taskOfUserA = newTask(USER_A, Constants.REVIEW_TYPE_LOCAL_ELIGIBILITY, CLAIM_OWNER);
assertThrows(RuntimeException.class,
() -> reviewService.accessLocalEligibilityEvidence(
taskOfUserA, evidenceBOfUserB, CLAIM_OWNER, "例行核验"),
"领取人只能读本任务用户的佐证,不得跨用户读取");
SensitiveAccessLog audit = singleAudit(evidenceBOfUserB);
assertEquals("denied", audit.getAccessResult());
assertEquals(CLAIM_OWNER, audit.getOperatorId());
}
@Test
@DisplayName("INV-011: 非 local_eligibility 类型的审核任务 → 拒绝,且落库 denied")
void inv011NonLocalEligibilityTaskDeniedAndAudited() {
String eligibilityId = newEligibility(USER_A);
String evidenceId = newEvidence(eligibilityId);
// 该任务是「资料审核」而非「本地资格审核」,同一套读取入口不得被复用去读佐证
String profileTaskId = newTask(USER_A, "profile", CLAIM_OWNER);
assertThrows(RuntimeException.class,
() -> reviewService.accessLocalEligibilityEvidence(
profileTaskId, evidenceId, CLAIM_OWNER, "例行核验"),
"佐证读取入口只服务于 local_eligibility 任务");
SensitiveAccessLog audit = singleAudit(evidenceId);
assertEquals("denied", audit.getAccessResult());
assertEquals(USER_A, audit.getUserId(), "即便任务类型不符,审计也应挂到任务所属用户");
}
// ==========================================================================
// 正向反证:授权路径必须真的能读到 —— 否则上面三条「拒绝」可能只是「全局拒绝」
// ==========================================================================
@Test
@DisplayName("INV-011: 领取人读取本任务佐证 → 放行,且落库 success(反证非全局拒绝)")
void inv011ClaimOwnerSucceedsAndAudited() {
String eligibilityId = newEligibility(USER_A);
String evidenceId = newEvidence(eligibilityId);
String taskId = newTask(USER_A, Constants.REVIEW_TYPE_LOCAL_ELIGIBILITY, CLAIM_OWNER);
Map<String, Object> result = reviewService.accessLocalEligibilityEvidence(
taskId, evidenceId, CLAIM_OWNER, "核验居住证明");
assertNotNull(result, "领取人应能读到佐证");
assertNotNull(result.get("url"), "应返回可用的签名地址,实得: " + result);
SensitiveAccessLog audit = singleAudit(evidenceId);
assertEquals("success", audit.getAccessResult(), "成功访问同样必须留痕");
assertEquals(CLAIM_OWNER, audit.getOperatorId());
assertEquals(USER_A, audit.getUserId());
assertEquals("核验居住证明", audit.getReason(), "审计必须留存访问目的");
}
// ==========================================================================
// 边界:两条早退路径不写审计 —— 作为「被声明的契约」固化,而非漏测
// ==========================================================================
@Test
@DisplayName("INV-011: purpose 为空 → 拒绝,且不产生审计(早退于触及任何用户数据之前)")
void inv011BlankPurposeRejectedWithoutAudit() {
String eligibilityId = newEligibility(USER_A);
String evidenceId = newEvidence(eligibilityId);
String taskId = newTask(USER_A, Constants.REVIEW_TYPE_LOCAL_ELIGIBILITY, CLAIM_OWNER);
RuntimeException error = assertThrows(RuntimeException.class,
() -> reviewService.accessLocalEligibilityEvidence(taskId, evidenceId, CLAIM_OWNER, " "),
"查看佐证必须填写访问目的");
assertTrue(error.getMessage().contains("目的"), "实得: " + error.getMessage());
assertEquals(0, auditsOf(evidenceId).size(), "参数非法即早退,未触及用户数据,故不留痕");
}
@Test
@DisplayName("INV-011: taskId 不存在 → 拒绝,且不产生审计(定位不到用户,无痕可言)")
void inv011UnknownTaskRejectedWithoutAudit() {
String eligibilityId = newEligibility(USER_A);
String evidenceId = newEvidence(eligibilityId);
String ghostTaskId = UUID.randomUUID().toString();
assertThrows(RuntimeException.class,
() -> reviewService.accessLocalEligibilityEvidence(
ghostTaskId, evidenceId, CLAIM_OWNER, "例行核验"),
"不存在的审核任务必须被拒绝");
assertEquals(0, auditsOf(evidenceId).size(),
"任务都不存在时无法定位数据归属,因此不写审计(边界契约,非漏测)");
}
// ==========================================================================
// 结构性守卫:INV-011 的「不越权」不只靠上面那几个 if,更靠入口形态本身
// ==========================================================================
@Test
@DisplayName("INV-011: 用户侧端点不接受任何用户可控的 userId 入参(身份只能来自 token)")
void inv011UserSideEndpointsTakeNoUserControllableUserId() {
Method[] handlers = declaredHandlerMethods(LocalEligibilityController.class);
assertTrue(handlers.length >= 4,
"本地资格用户侧端点应至少 4 个,实得 " + handlers.length + " 个 —— 端点被删改时本守卫应同步复核");
for (Method handler : handlers) {
for (Parameter parameter : handler.getParameters()) {
// 只要出现「非 principal 来源」的 userId 入参,用户就能自助读取他人资格
assertNotEquals("userId", parameter.getName(),
handler.getName() + " 暴露了用户可控的 userId 入参 —— "
+ "本地资格一律以 token 主体自限定,不得由请求指定用户");
}
assertTrue(Arrays.stream(handler.getParameters())
.anyMatch(p -> p.isAnnotationPresent(AuthenticationPrincipal.class)),
handler.getName() + " 必须从 @AuthenticationPrincipal 取用户身份,"
+ "否则无法保证「只能读自己」");
}
}
@Test
@DisplayName("INV-011: 佐证读取入口同时受类级与专用权限双重约束(缺一即失效)")
void inv011EvidenceReadEndpointRequiresDedicatedAuthority() {
PreAuthorize classLevel = ReviewController.class.getAnnotation(PreAuthorize.class);
assertNotNull(classLevel, "ReviewController 必须有类级权限约束");
assertTrue(classLevel.value().contains("review.view"),
"类级约束应要求 review.view,实得: " + classLevel.value());
Method accessEvidence = Arrays.stream(ReviewController.class.getDeclaredMethods())
.filter(m -> m.isAnnotationPresent(PostMapping.class))
.filter(m -> Arrays.stream(m.getAnnotation(PostMapping.class).value())
.anyMatch(path -> path.contains("evidences") && path.contains("access")))
.findFirst()
.orElseThrow(() -> new AssertionError(
"未找到佐证读取端点 —— 该端点若被改名/移除,INV-011 需重新评估"));
PreAuthorize methodLevel = accessEvidence.getAnnotation(PreAuthorize.class);
assertNotNull(methodLevel,
"佐证读取端点必须单独声明专用权限,不能只靠类级 review.view");
assertTrue(methodLevel.value().contains("local_eligibility.evidence.view"),
"佐证读取需要专用权限 local_eligibility.evidence.view,实得: " + methodLevel.value());
// 端点必须从 token 主体取运营身份,不得由请求体指定
assertTrue(Arrays.stream(accessEvidence.getParameters())
.anyMatch(p -> p.isAnnotationPresent(AuthenticationPrincipal.class)),
"佐证读取必须从 @AuthenticationPrincipal 取运营身份(审计与归属都依赖它)");
assertFalse(Arrays.stream(accessEvidence.getParameters())
.anyMatch(p -> p.getName().equals("operatorId")),
"佐证读取不得暴露可伪造的 operatorId 入参");
// purpose 由请求体携带 —— 它是审计的必要字段,端点必须读它
assertTrue(Arrays.stream(accessEvidence.getParameters())
.anyMatch(p -> p.isAnnotationPresent(RequestBody.class)),
"佐证读取必须通过请求体接收 purpose(审计留痕的前置条件)");
}
// ==========================================================================
// 夹具与辅助
// ==========================================================================
private String newEligibility(String userId) {
LocalEligibility eligibility = new LocalEligibility();
// 主键列是 VARCHAR(36)(对齐生产 UUID):只能用裸 UUID,加前缀会溢出。
eligibility.setId(UUID.randomUUID().toString());
eligibility.setUserId(userId);
eligibility.setEligibilityType(Constants.LOCAL_ELIGIBILITY_TYPE_HUKOU);
eligibility.setVerificationStatus("pending_review");
localEligibilityMapper.insert(eligibility);
return eligibility.getId();
}
private String newEvidence(String localEligibilityId) {
LocalEligibilityEvidence evidence = new LocalEligibilityEvidence();
evidence.setId(UUID.randomUUID().toString());
evidence.setLocalEligibilityId(localEligibilityId);
// file_key 列是 VARCHAR(256),用真实的对象存储路径形态(fileId 字段映射到 file_key)。
evidence.setFileId("user-photos/inv011/" + UUID.randomUUID() + ".jpg");
evidence.setEvidenceType("household_proof");
evidence.setStatus("submitted");
evidenceMapper.insert(evidence);
return evidence.getId();
}
private String newTask(String userId, String reviewType, String assignedOperatorId) {
ReviewTask task = new ReviewTask();
task.setId(UUID.randomUUID().toString());
task.setUserId(userId);
task.setReviewType(reviewType);
task.setStatus("processing");
task.setAssignedOperatorId(assignedOperatorId);
reviewTaskMapper.insert(task);
return task.getId();
}
/**
* 按 access_target 过滤本用例的审计 —— 每次 {@link #newEvidence} 都生成唯一 ID,
* 因此断言「恰好一条」不受其它用例/其它测试类的写入干扰。
*/
private List<SensitiveAccessLog> auditsOf(String evidenceId) {
return sensitiveAccessLogMapper.selectList(
new LambdaQueryWrapper<SensitiveAccessLog>()
.eq(SensitiveAccessLog::getAccessTarget, evidenceId));
}
private SensitiveAccessLog singleAudit(String evidenceId) {
List<SensitiveAccessLog> logs = auditsOf(evidenceId);
assertEquals(1, logs.size(),
"本次访问应恰好落库 1 条审计(实得 " + logs.size() + " 条)"
+ " —— 0 条说明审计缺失,多条说明重复记账");
return logs.get(0);
}
/** 取出该控制器声明的全部 HTTP 端点方法(含各类 Mapping 注解)。 */
private static Method[] declaredHandlerMethods(Class<?> controller) {
List<Method> handlers = new ArrayList<>();
for (Method method : controller.getDeclaredMethods()) {
if (method.getAnnotation(RequestMapping.class) != null
|| method.getAnnotation(GetMapping.class) != null
|| method.getAnnotation(PostMapping.class) != null
|| method.getAnnotation(PutMapping.class) != null
|| method.getAnnotation(DeleteMapping.class) != null
|| method.getAnnotation(PatchMapping.class) != null) {
handlers.add(method);
}
}
if (handlers.isEmpty()) {
throw new AssertionError(controller.getSimpleName()
+ " 未解析到任何端点 —— 注解改名时本守卫需同步更新,不得静默通过");
}
return handlers.toArray(new Method[0]);
}
/** 保留:便于后续核对端点是否被整体删除时按 HTTP 方法枚举。 */
@SuppressWarnings("unused")
private static RequestMethod[] allMethods() {
return RequestMethod.values();
}
@SuppressWarnings("unused")
private static String annotationName(Annotation annotation) {
return annotation.annotationType().getSimpleName();
}
/** 参数名断言的可读性依赖编译期 -parameters;此处做一次前置校验,避免守卫静默失效。 */
@Test
@DisplayName("INV-011 守卫自检: 测试编译保留参数名(否则上一个用例会静默失效)")
void inv011GuardSelfCheckParameterNamesAreReadable() {
Method[] handlers = declaredHandlerMethods(LocalEligibilityController.class);
boolean anyNamed = Arrays.stream(handlers)
.flatMap(m -> Arrays.stream(m.getParameters()))
.anyMatch(p -> p.getName().equals("principal") || p.getName().equals("req"));
assertTrue(anyNamed,
"反射读不到参数名(形如 arg0/arg1)时,「无 userId 入参」的断言会变成永远为真 —— "
+ "需确认编译参数含 -parameters,否则该守卫形同虚设");
}
}
@@ -63,8 +63,11 @@ class V11InvariantsTest {
// ==================== INV-011 ====================
@Test
@DisplayName("常量口径 INV-011: 本地资格类型取值固定(行为验证见 LocalEligibilityServiceTest / LocalEligibilityStatusVocabularyGuardTest)")
@DisplayName("常量口径 INV-011: 本地资格类型取值固定(行为验证见 Inv011EvidenceAccessGuardTest / LocalEligibilityServiceTest)")
void inv011LocalEligibilityVocabulary() {
// INV-011 的语义核心(越权读取被拒 + 访问必留痕)由同包 Inv011EvidenceAccessGuardTest
// 以真实落库断言固化;此处只守卫取值口径,并防止行为守卫被改名/删除后无人察觉。
assertBehaviorTestExists("com.danyang.match.platform.invariants.Inv011EvidenceAccessGuardTest");
assertBehaviorTestExists("com.danyang.match.platform.local_eligibility.LocalEligibilityServiceTest");
assertBehaviorTestExists("com.danyang.match.platform.account.LocalEligibilityStatusVocabularyGuardTest");
assertEquals("household_registration", Constants.LOCAL_ELIGIBILITY_TYPE_HUKOU);
+18
View File
@@ -255,6 +255,24 @@ CREATE TABLE local_eligibility_evidences (
created_at TIMESTAMP WITH TIME ZONE, updated_at TIMESTAMP WITH TIME ZONE, deleted_at TIMESTAMP WITH TIME ZONE
);
-- V001 + V034 + V035: sensitive_access_logs 敏感数据访问审计
-- INV-011 的「可核查」落点正是本表(access_result = success / denied)。
-- 本表此前在测试库**完全不存在**,而 ReviewService.logEvidenceAccess 一定会写它 ——
-- 后果:任何「审计真的落库了吗」的断言都无从编写,INV-011 只能退化成常量断言;
-- 生产上新接入的审计路径在测试期零覆盖。与 Phase 12 复验记录的
-- user_identities / review_tasks 缺失同族(表漂移盲区),此处补齐。
-- 列定义对齐:V001 建表(id/operator_id/user_id/data_type/reason/ip/created_at)
-- + V034(access_target/access_result)
-- + V035(BaseEntity 的 updated_at / deleted_at)。
-- 不建 FK:生产 REFERENCES operators(id) / users(id),而测试库无 operators 表;
-- 本库 review_tasks / local_eligibility_evidences 同样只保留列、不建 FK。
CREATE TABLE sensitive_access_logs (
id VARCHAR(36) PRIMARY KEY, operator_id VARCHAR(36), user_id VARCHAR(36),
data_type VARCHAR(64), reason VARCHAR(500), ip VARCHAR(64),
access_target VARCHAR(128), access_result VARCHAR(32),
created_at TIMESTAMP WITH TIME ZONE, updated_at TIMESTAMP WITH TIME ZONE, deleted_at TIMESTAMP WITH TIME ZONE
);
-- V019: home_banners 首页 Banner
CREATE TABLE home_banners (
id VARCHAR(36) PRIMARY KEY, title VARCHAR(200), subtitle VARCHAR(300), image_file_id VARCHAR(36),
@@ -18,7 +18,7 @@
| 项 | 状态 |
|---|---|
| Phase 01~22 | ✅ 复验关闭 |
| Phase 23 | ⚠️ **部分关闭** —— 44 个 `pass` 空壳已清、4 个真实 INV 行为守卫已补;**E2E 场景实现已完成(2026-09-19,见 Task 2.1)**,仅余 E2E 在 CI 上的首次实测绿 |
| Phase 23 | ⚠️ **部分关闭** —— 44 个 `pass` 空壳已清、4 个真实 INV 行为守卫已补;**E2E 场景实现已完成(2026-09-19,见 Task 2.1)**;**INV-011 已补真实行为守卫(2026-09-19,见 Task 2.2,9 用例 + 两次注入验证)**。仅余 E2E 在 CI 上的首次实测绿 |
| Phase 23B | ✅ E2E 测试基建重建(conftest + seed + CI e2e job,本机活栈 49 → **65 passed**) |
| 横向加固 | ✅ HTTP 语义(105 处真实状态码)+ 身份收敛 + 幂等键(30 端点,V045/V046)+ 端口/入口守卫 |
| 后端回归 | **669 / 0 failures / 0 errors / 3 skipped** |
@@ -36,7 +36,11 @@
- **禁止用 `rm` / `git rm` 删除文件** —— 本机有 safe-delete 钩子会把「删文件」放大为「删父目录」(2026-09-18 实测:`git rm` 单个文件导致整个 `docs/` 被移除)。需要移除内容时**一律原地重写**(Write/Edit)。
- 不修改业务规则、不扩大 V1 范围;新增能力必须走 Phase 顺序。
- 每批完成后跑 `node scripts/run-ui-contracts.mjs`(**守卫数量以执行器 `MIN_GUARDS` 为准;2026-09-19 实为 18 个,须 18/18 绿** —— 原文「14 个 / 14/14」已过期:2026-09-19 起相继新增 `wxml-structure-contracts`、`miniapp-self-method-contracts`、`wxss-component-selector-contracts`、`miniapp-api-client-behavior`)+ `ui-document-baseline-contracts.mjs`(含端口与 `/admin/` 子路径断言)。
- 后端改动跑离线容器 `mvn -o test`,必须 0 failures / 0 errors。
- 后端改动跑容器 `mvn test`(**2026-09-19 校正:不能用 `-o` 离线** ——
本机可用的测试镜像 `danyang-match-backend-test` 里缺 `surefire-junit-platform`,
离线模式必报 `BUILD FAILURE`;首次运行需联网下载该 provider,之后才有缓存。
原文「离线容器 `mvn -o test`」在本机**不可执行**),必须 0 failures / 0 errors。
命令见附 B-9。
- **E2E 改动跑 `pytest tests/e2e`**(需活栈;本机 `E2E_BASE_URL=http://localhost:8085/api/v1`、`E2E_OPERATOR_PASSWORD` 见 CI 变量),必须 0 failed。
本机复跑前若出现 `429 账号已锁定`,是 Redis 里的登录失败锁定键(`auth:operator_login_lock:<operatorId>`,TTL 15 分钟),
由前一轮失败登录累积触发 —— 删掉该键即可,不是业务缺陷。
@@ -148,16 +152,51 @@
`fileId` 必须属于该用户自己的 `user_photos`(`userPhotoMapper.findByUserIdOrderBySort`)。
- 测试基建:`@SpringBootTest @ActiveProfiles("test")`(H2,`schema-h2.sql`),参照 `V11InvariantsTest`。
- [ ] **Step 1:** 写负向测试:非授权角色读取他人本地资格佐证 → 必须 403/不可达。
(建议同时覆盖:非领取人、跨用户佐证、非 local_eligibility 任务、`purpose` 为空)
- [ ] **Step 2:** 确认真实落库路径(不是只断言常量,见 `CoreInvariantsTest` 的教训)——
即断言 `sensitive_access_logs` 真的新增了对应 `result` 的记录。
- [ ] **Step 3:** 负向注入验证守卫变红。
⚠️ 本机后端跑的是**当日构建的 jar**,改 Java 代码需重建镜像;注入应优先选
**不需要重建**的手段(如撤销 `local_eligibility.evidence.view` 的角色授予、
或直接改库内状态),否则该步骤成本极高。
- [x] **Step 1 / Step 2:** 写负向测试 + 真实落库断言 ✅(2026-09-19)
- [x] **Step 3:** 负向注入验证守卫变红 ✅(2026-09-19,**两次注入,均精确命中**)
**Acceptance:** INV-011 有真实行为守卫。
**产出**:`backend/src/test/java/.../invariants/Inv011EvidenceAccessGuardTest.java`(9 个用例,全绿)
**前置修复(必须先做,否则 Step 2 无从落地)**
- `backend/src/test/resources/schema-h2.sql` **原本没有 `sensitive_access_logs` 表** →
「审计真的落库了吗」这条断言在测试期根本无法编写。已按 V001 + V034 + V035 补齐
(不建 FK,因测试库无 `operators` 表;与 `review_tasks` 同风格)。详见附 B-8。
**9 个用例的分工(两条独立命题 + 一个反证 + 两个边界 + 三个结构性守卫)**
| 用例 | 咬住的命题 |
|---|---|
| `inv011NonClaimantDeniedAndAudited` | 非领取人 → 拒绝 + `denied` 落库 |
| `inv011CrossUserEvidenceDeniedAndAudited` | 领取人拿自己 taskId 读**他人**佐证 → 拒绝 + `denied` |
| `inv011NonLocalEligibilityTaskDeniedAndAudited` | 非 `local_eligibility` 任务 → 拒绝 + `denied` |
| `inv011ClaimOwnerSucceedsAndAudited` | **反证**:领取人读本任务佐证 → 放行 + `success`(排除「全局拒绝」假阳性) |
| `inv011BlankPurposeRejectedWithoutAudit` | 边界:`purpose` 空 → 拒绝且**不留痕**(早退于触及用户数据之前) |
| `inv011UnknownTaskRejectedWithoutAudit` | 边界:`taskId` 不存在 → 拒绝且**不留痕** |
| `inv011UserSideEndpointsTakeNoUserControllableUserId` | 结构性:用户侧 4 个端点**无用户可控 `userId` 入参**,身份只来自 `@AuthenticationPrincipal` |
| `inv011EvidenceReadEndpointRequiresDedicatedAuthority` | 结构性:佐证读取入口**类级 `review.view` + 方法级 `local_eligibility.evidence.view`** 双重约束,且不暴露伪造用 `operatorId` 入参 |
| `inv011GuardSelfCheckParameterNamesAreReadable` | 守卫自检:反射能读到参数名(否则上一条会**静默永真**) |
> 关于「403」的口径:两级 `@PreAuthorize` 在 HTTP 层给 403;业务层给 `RuntimeException`。
> 本测试**两层分别覆盖** —— 业务层走真实落库断言,HTTP 层走注解反射断言(见后两个结构性用例)。
**Step 3 负向注入记录(两次,均精确命中,无一误伤)**
| 注入 | 手段 | 预期 | 实测 |
|---|---|---|---|
| ① | 停用 `requireClaimOwner(task, operatorId)` | 归属校验失效 | **恰 1 红**:`inv011NonClaimantDeniedAndAudited`("Expected RuntimeException to be thrown, but nothing was thrown"),其余 8 绿 ✓ |
| ② | 停用 `catch` 块内的 `logEvidenceAccess(..., "denied")` | 拒绝路径不留痕 | **恰 2 红**:`inv011NonClaimantDeniedAndAudited`、`inv011CrossUserEvidenceDeniedAndAudited`("应恰好落库 1 条审计(实得 0 条)"),其余 7 绿 ✓ |
> 注入②中 `inv011NonLocalEligibilityTaskDeniedAndAudited` **正确地未变红** ——
> 它走的是 try 块**之外**的那条 `logEvidenceAccess`(任务类型不符的早退分支),
> 不受注入影响。这从侧面证明用例确实咬住了**两条不同的代码路径**,而不是重复断言同一处。
>
> 两次注入后均已还原并**复跑全绿**(9/9),`git diff` 中不存在 `ReviewService.java` → 无残留。
**与原文的一处校正**:Step 3 原注「改 Java 代码需重建镜像,成本极高」**不再成立** ——
镜像 `danyang-match-backend-test` 内含 JDK+Maven,挂载源码即可直接跑 surefire,
注入-验证-还原一轮约 3.5 分钟。详见附 B-9。
**Acceptance:** ✅ INV-011 已从「常量口径 + 指针」升级为**真实行为守卫**(9 用例 + 两次注入验证)。
### Task 2.3: E2E 进入 CI(**已决策并落地**,2026-09-18)
@@ -292,15 +331,34 @@
| Global Constraints / 验收纪律 / 当前停点 | UI 契约门禁 14 个、14/14 绿 | **18 个**(2026-09-19 相继新增 4 项守卫),基线 18/18 |
| Task 2.1 | `tests/e2e/**` 现为占位文件 | **仅 2 个文件**是占位;其余在 Phase 23B 已是真实用例 |
| 当前停点 | 本机活栈 E2E `49 passed` | 基线 49,Task 2.1 完成后 **65 passed** |
| Global Constraints | 后端改动跑**离线**容器 `mvn -o test` | 本机测试镜像缺 `surefire-junit-platform`,`-o` **必然 BUILD FAILURE**;须去掉 `-o` 联网跑(附 B-9) |
| Task 2.2 Step 3 | 「改 Java 代码需重建镜像,注入成本极高」 | 镜像 `danyang-match-backend-test` 内含 JDK 21 + Maven + 依赖缓存,**挂载源码即可跑 surefire**,一轮注入≈3.5 分钟(附 B-9) |
| 附 B-1(初稿) | 机构创建 500 因「从不给 `id` 赋值 → uuid 空串」 | **归因错误**。实测为 `violates check constraint "chk_org_status"`(status 被写成 `normal`);`id` 由 `AutoFillHandler` 补全,不会为空。已在 B-1 内留痕更正 |
### B. 新发现(不在本计划内,需另行处置)
1. **`POST /operator/organizations` 必然 500**(High)
`OrganizationService.createOrganization` 从不给 `id` 赋值,而 `BaseEntity` 用
`@TableId(type = IdType.INPUT)`、`organizations.id` 无 DB 默认值 →
`invalid input syntax for type uuid: ""`。且该接口**未校验 `type`**,
会撞生产 `chk_org_type`(白名单:`women_federation / trade_union / charity_center /
volunteer_team / civil_affairs_partner / other`),大概率在 PG 上再炸一次。
1. **`POST /operator/organizations` 必然 500 —— 根因是 status 取值,不是 id**(High)
`OrganizationService.createOrganization` 写 `org.setStatus(Constants.ACCOUNT_STATUS_NORMAL)`
即 `"normal"`,而 `organizations.type/status` 的 CHECK 白名单(V001)是
`chk_org_status: active / inactive` → **CHECK 违约**。
**2026-09-19 实测复核**(本机活栈,`e2e_admin` 打 `POST /api/v1/operator/organizations`,
`type` 取合法值 `charity_center`):
```
HTTP 500
{"success":false,"code":"SERVER_ERROR","message":"服务端内部错误,请联系管理员",...}
后端日志: Caused by: org.postgresql.util.PSQLException:
ERROR: new row for relation "organizations" violates check constraint "chk_org_status"
```
> **归因更正**(本条初稿有误,如实留痕):初稿写作「从不给 `id` 赋值 →
> `invalid input syntax for type uuid: ""`」。该归因**错误**:`OrganizationMapper` 是纯
> `BaseMapper`(无自定义 insert),`AutoFillHandler.insertFill` 会在 `id == null` 时补 UUID,
> 故 id 不会为空。真实根因是 status 取值不在白名单。**教训同附 A —— 代码级推断必须实测复核,
> 不能凭「读了实现」就下结论。**
仍成立的次要问题:该接口**未校验 `type`**,非白名单值会撞 `chk_org_type`
(`women_federation / trade_union / charity_center / volunteer_team /
civil_affairs_partner / other`)。
影响:运营端无法新建机构 → 无机构则**无法新建活动**(`activities.organizer_org_id` NOT NULL)。
2. **互选记录永不过期**(Medium,即批 3 Task 3.3 的 P16-T13)
`createMutualConsent` 从不写 `expires_at`(列无默认值),而
@@ -330,8 +388,83 @@
本机活栈若复用旧卷,口令会停在上一轮的值 → 大量 401。
本机已用 `UPDATE operators SET password_hash = crypt('<CI 口令>', gen_salt('bf',8)) WHERE username LIKE 'e2e\_%'`
对齐到 CI 口令。(这与 Task 2.3 顺带修的 CI 缺陷 #5 是同一根因的两面。)
8. **H2 测试库缺 `sensitive_access_logs` 表**(Medium,Task 2.2 顺手修复)
生产有该表(V001 建表 + V034 加 `access_target`/`access_result` + V035 补 `updated_at`/`deleted_at`),
而 `backend/src/test/resources/schema-h2.sql` **完全没有它**。而 `ReviewService.logEvidenceAccess`
在成功与拒绝两条路径上都必然写它 → 后果是:**INV-011 的「访问留痕」命题在测试期根本无法断言**,
只能退化成常量断言(这正是 Task 2.2 之前的状态)。已按三份迁移补齐列定义(不建 FK,
因测试库无 `operators` 表;与 `review_tasks` / `local_eligibility_evidences` 同风格)。
与 schema-h2.sql 中已记录的 Phase 12/15/19 系列「表/约束漂移盲区」同族。
9. **本机跑 Java 测试的通道**(工具性发现,可复用)
本机**无 JDK / 无 Maven / 无 `~/.m2`**(`mvn` 报 `Could not find Maven installation`),
但存在镜像 `danyang-match-backend-test`(940MB,内含 Temurin JDK 21 + Maven 3.9.16 +
`/root/.m2` 132MB 依赖缓存 + 完整源码)。挂载源码即可直接跑 surefire:
```bash
docker run --rm -v "E:/develop/公益婚恋服务平台/backend":/app -w /app \
danyang-match-backend-test:latest mvn test -Dtest=<测试类> -DfailIfNoTests=false
```
- 首次运行需**联网**下载 `surefire-junit-platform`(该 jar 不在缓存里);`-o` 离线模式会失败。
- 单次编译 + 运行约 3.5 分钟;`backend/target/` 会被容器写回宿主机(该目录已忽略,无碍)。
- **重要**:这使 Task 3.x 一类「改 Java 代码」的验证不再需要重建后端镜像 ——
原 Task 2.2 Step 3 标注的「改 Java 需重建镜像、成本极高」不再成立,负向注入可直接做。
- ⚠️ **本机跑「全量」后端测试会卡住(实测)**:2026-09-19 尝试 `mvn test` 跑全部 102 个测试类,
运行 **1 小时仍未产出任何 surefire 报告**(`docker ps` 显示容器在跑,`surefire-reports/` 无新文件),
疑似某个 `@SpringBootTest` 阻塞在无超时的外部连接上。已强制终止。
**结论:本机只适合跑「单个测试类」回归**(`-Dtest=<类名>`,约 3.5 分钟);
全量回归应交给 CI(Task 2.3 已把 backend test 串进流水线)。
本机验证策略因此为:改动哪个测试类就单跑哪个 + 依赖 CI 做全量兜底。
10. **5 个 Mapper 方法「声明了却无实现」**(High,**未实测触发,但判定依据可复核**)
`Backend` 的 mapper 统一用**注解式 SQL**(如 `ActivityCapacityGroupMapper` 的 `@Select`/`@Update`)。
以下方法**既无 SQL 注解、也无 XML**:
| Mapper 方法 | 调用点 | 后果 |
|---|---|---|
| `ReviewReasonMapper.findAllEnabled` | `ReviewService:92,143` | 审核原因选项接口**必崩** |
| `UserPreferenceMapper.findByUserId` | `MatchEligibilityService:59,107`;`RecommendationEngineService:140,141,216,219` | 推荐打分 / 匹配资格判定**必崩** |
| `UserPrivacySettingsMapper.findByUserId` | `RecommendationEngineService:334`;`PrivacyService` | 推荐 + 隐私设置读写**必崩** |
| `ReviewItemMapper.findByReviewTaskId` | 无 | 死方法 |
| `ReviewReasonMapper.findByCategory` | 无 | 死方法 |
**判定依据**(三条均已复核):① 全仓无任何 mapper XML —— `Glob backend/src/main/resources/**/*.xml` 返回空;
② `pom.xml` 无自定义 `ISqlInjector` / `MapperAnnotationBuilder` —— MyBatis-Plus 只会为 `BaseMapper`
的 CRUD 注入语句;③ 对照类 `ActivityCapacityGroupMapper` 的同位置方法均带注解。
→ 上述方法在 MyBatis 解析期抛 `BindingException: Invalid bound statement (not found)`。
**为什么此前没人发现**:本机无候选用户、无审核数据,这些路径的前置条件为空
(例:`getDailyRecommendations` 先 `isParticipantEligible` 再查候选池,候选池为空就不会走到
打分环节)→ **测试环境用「数据为空」掩盖了「代码必崩」**。生产有数据即触发。
**未实测的原因**:需要构造「有候选用户 / 有审核任务」的数据集才能从 HTTP 层触发。
建议的**机械化验证**(比人工审查强):新增一个守卫测试,用
`sqlSessionFactory.getConfiguration().hasStatement(<MapperFqn>.<methodName>)` 遍历全部
Mapper 接口的声明方法 —— 无绑定即失败。这样一类缺陷可被一次性、持续地挡住。
11. **隐私设置的「三方契约冲突」+ 表/实体主键错配**(High —— 直接影响 Task 3.1 第 1 项的工作量评估)
原文把 Task 3.1 第 1 项描述为「接真实 `user_privacy_settings`」的**接线**工作。
实测发现它**不是接线**,而是需要**契约裁定**:
| 来源 | 字段集 |
|---|---|
| 生产表(V002) | `visible_in_recommendations` / `visible_in_search` / `show_occupation` / `show_lifestyle_photos` / `receive_activity_recommendations` / `accept_matchmaker_recommendations` |
| 小程序页 `pages/privacy-settings` | `visibleInRecommendations` / `allowActivityInvitation` / `showLastOnline` |
| `AccountLifecycleService`(桩) | `visibleInRecommendations` / `allowActivityInvitation` / `showLastOnline` —— **与前端一致** |
| `PrivacyService`(看似「真实实现」) | 与生产表一致的六个 —— **与前端仅 1 个交集** |
- **小程序的 `allowActivityInvitation` / `showLastOnline` 在表里没有对应列**;
表里的 5 列在小程序里没有 UI。三方只有 `visibleInRecommendations` 同时存在。
- 也就是说:**桩是「照前端契约写的假数据」,而「真实实现」是「照表结构写的」** ——
两者根本没在同一个契约上。直接「接线」会立刻打断小程序页面。
- 另有**表/实体错配**:`user_privacy_settings` 主键是 `user_id`、且**无 `id` / `deleted_at` 列**,
而实体 `UserPrivacySettings extends BaseEntity`(带 `@TableId` 的 `id` 与 `deletedAt`)→
`PrivacyService.updatePrivacySettings` 里的 `privacySettingsMapper.insert(...)` 会尝试写 `id` 列 →
**必然失败**(且它对该插入路径用 `insert` 而非 upsert,即使列对齐也存在「已存在记录再插入」的问题)。
- **需要用户/产品三选一**:以表为准改造前端 UI / 以小程序为准补迁移加列 / 加一层映射。
在此之前 Task 3.1 第 1 项**不应动手**。
- 附带:`user_privacy_settings` / `user_preferences` / `review_reasons` / `review_items`
**四张表均不在 H2 测试库**(同附 B-8 的表漂移盲区),即上表所有方法在测试期都无法被触达验证。
---
*创建: 2026-09-18 — 承接 `docs/文档治理报告-2026-09-18.md` 与 STATUS.md 的两处悬空引用(D1)*
*审阅校正: 2026-09-19 — 按实测推翻 4 处失实断言(见附 A),登记 7 项新发现(见附 B)*
*审阅校正: 2026-09-19 — 按实测推翻 7 处失实断言(见附 A,含 1 处**对本文档自身初稿的更正**),登记 11 项新发现(见附 B)*
*执行进展: 2026-09-19 — Task 2.1(E2E 16 场景)、Task 2.2(INV-011 守卫)均已完成并验证*