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，等待下一步指令。
|