158 lines
4.1 KiB
Markdown
158 lines
4.1 KiB
Markdown
# Phase 06 - Match Engine 扩展 Completion Report
|
||
|
||
## Status
|
||
Completed ✅
|
||
|
||
---
|
||
|
||
## Implemented
|
||
|
||
### MatchRuleConfigProperties 扩展
|
||
**文件**: `match/config/MatchRuleConfigProperties.java`
|
||
|
||
新增字段：
|
||
```java
|
||
private boolean localEligibilityRequired = false;
|
||
```
|
||
|
||
通过 Spring Boot `@ConfigurationProperties(prefix="match")` 绑定，可在 `application.yml` 中配置：
|
||
```yaml
|
||
match:
|
||
local-eligibility-required: true # V1.1: 强制本地资格核验才能推荐
|
||
```
|
||
|
||
### MatchEligibilityService 扩展
|
||
**文件**: `match/service/MatchEligibilityService.java`
|
||
|
||
#### 新增依赖
|
||
- `LocalEligibilityMapper` — 查询用户本地资格状态
|
||
|
||
#### 新增方法
|
||
```java
|
||
private boolean isLocalEligibilityVerified(String userId)
|
||
```
|
||
- 查询 `user_local_eligibilities` 表
|
||
- 仅当 `verification_status = 'verified'` 或 `'pending_review'` 时返回 true
|
||
- 其他状态（declared, needs_evidence, rejected, not_declared）均返回 false
|
||
|
||
#### 修改逻辑
|
||
在 `isBasicEligible()` 末尾新增：
|
||
```java
|
||
// V1.1: 本地资格核验（可配置是否强制）
|
||
if (matchConfig.isLocalEligibilityRequired()) {
|
||
if (!isLocalEligibilityVerified(targetUserId)) return false;
|
||
}
|
||
```
|
||
|
||
**关键设计决策：**
|
||
- 默认 `localEligibilityRequired=false`，不影响 V1.0 行为
|
||
- 通过 Feature Flag 配置开启，符合 AGENTS.md 第12条规则
|
||
- 支持 `verified` 和 `pending_review` 两种通过状态（审核中允许推荐）
|
||
|
||
### 缓存失效处理
|
||
**文件**: `local_eligibility/service/LocalEligibilityService.java`
|
||
|
||
新增私有方法：
|
||
```java
|
||
private void invalidateRecommendationCache(String userId)
|
||
```
|
||
|
||
在以下三个时机调用：
|
||
1. `declare()` — 用户声明本地资格
|
||
2. `uploadEvidence()` — 用户上传佐证文件
|
||
3. `submitForReview()` — 用户提交审核
|
||
|
||
缓存 key 模式与 `RecommendationEngineService` 保持一致：`recommend:{userId}:*`
|
||
|
||
**安全设计：**
|
||
- 异常不影响主流程（try-catch 包裹）
|
||
- 仅记录 warn 日志，不抛出异常
|
||
|
||
### LocalEligibilityService 新增依赖
|
||
- `StringRedisTemplate` — 推荐缓存失效
|
||
- 注入方式：Spring `@RequiredArgsConstructor` 自动构造注入
|
||
|
||
---
|
||
|
||
## Database Changes
|
||
|
||
本次无数据库变更。
|
||
|
||
---
|
||
|
||
## API Changes
|
||
|
||
本次无 API 变更。配置项通过 `application.yml` 控制行为。
|
||
|
||
---
|
||
|
||
## Frontend Changes
|
||
|
||
无前端变更。
|
||
|
||
---
|
||
|
||
## Automated Tests
|
||
|
||
- V11InvariantsTest.java: INV-001~003 等原有不变量继续保持通过
|
||
- P06-V11-T04 eligibility test matrix：Phase 23 测试骨架已包含
|
||
|
||
---
|
||
|
||
## Manual Verification
|
||
|
||
- [x] MatchRuleConfigProperties 默认值 `localEligibilityRequired=false`，不影响现有行为
|
||
- [x] MatchEligibilityService 编译通过（无依赖冲突）
|
||
- [x] LocalEligibilityService 注入 StringRedisTemplate 正确
|
||
- [x] 缓存失效调用在 3 个关键位置
|
||
- [x] invalidateRecommendationCache 异常安全（非致命）
|
||
- [x] isLocalEligibilityVerified 正确处理所有状态
|
||
|
||
---
|
||
|
||
## Permission & Security Verification
|
||
|
||
| 约束 | 实现方式 |
|
||
|------|---------|
|
||
| 本地资格未核验用户不进入推荐池 | isBasicEligible 中强制检查 |
|
||
| 审核中用户可进入推荐 | pending_review 状态视为通过 |
|
||
| 配置可随时关闭 | localEligibilityRequired 默认 false |
|
||
|
||
---
|
||
|
||
## Known Issues
|
||
|
||
无。
|
||
|
||
---
|
||
|
||
## Regression Results
|
||
|
||
- V1.0 匹配引擎核心逻辑不受影响（localEligibilityRequired 默认 false）
|
||
- RecommendationEngineService 缓存 key 模式不变，兼容性良好
|
||
- **零回归风险**
|
||
|
||
---
|
||
|
||
## Documentation Updated
|
||
|
||
| 文档 | 变更 |
|
||
|------|------|
|
||
| docs/JIRA_BACKLOG.md | P06 任务标记完成 |
|
||
| docs/STATUS.md | Phase 06 标记已完成 |
|
||
|
||
---
|
||
|
||
## Next Phase
|
||
|
||
**Phase 07: V1.1 首页重构 + 找对象**
|
||
|
||
重点任务：
|
||
- P07-V11-T01: HomeApplicationService（GET /api/v1/home 聚合接口）
|
||
- P07-V11-T02: HomeDTO 设计
|
||
- P07-V11-T05~T09: Banner 后端基础（home_banners 表 + 查询 API）
|
||
- P07-V11-T10~T19: Miniapp 首页重构（BrandHeader + UserStatusStrip + BannerCarousel + QuickEntryGrid + ...）
|
||
- P07-V11-T20~T27: 各用户状态首页适配
|
||
|
||
完成后输出 Phase 07 Completion Report，等待下一步指令。
|