danyang-match/releases/v1.0.0-RC.1/TECHNICAL_SPECS.md

# 丹阳公益婚恋服务平台 v1.0.0-RC.1 技术参数

## 一、数据存储

### 1.1 关系数据库 - PostgreSQL 16

| 参数 | 值 |
|------|-----|
| 版本 | PostgreSQL 16.15 |
| 端口 | 5434 (容器映射) |
| 数据库名 | danyang_match |
| 用户 | postgres |
| 数据大小 | ~10 MB |
| 表数量 | 41 张 |
| 索引数量 | 100 个 |

**JDBC URL**: `jdbc:postgresql://postgres:5432/danyang_match`

### 1.2 缓存数据库 - Redis 7

| 参数 | 值 |
|------|-----|
| 版本 | Redis 7.4.11 |
| 端口 | 6381 (容器映射) |
| 持久化 | AOF (appendonly yes) |
| 用途 | Session、推荐缓存、频率限制 |

**关键 Key 模式**:
- `recommend:{userId}:{date}` - 推荐缓存 (TTL: 1h)
- `auth:operator_refresh:{operatorId}` - 操作员刷新Token (TTL: 14d)
- `auth:user_refresh:{userId}` - 用户刷新Token (TTL: 14d)

### 1.3 对象存储 - MinIO

| 参数 | 值 |
|------|-----|
| 版本 | MinIO Latest |
| 控制台端口 | 9004 |
| API端口 | 9003 |
| Access Key | 通过本地环境变量配置 |
| Secret Key | 通过本地环境变量配置 |
| Bucket | danyang-match-private |

---

## 二、索引策略

### 2.1 唯一索引 (UNIQUE)

| 表 | 索引名 | 列 |
|----|--------|-----|
| users | uk_users_openid | wechat_openid (WHERE deleted_at IS NULL) |
| users | uk_users_phone | phone (WHERE phone IS NOT NULL) |
| users | uk_users_unionid | wechat_unionid |
| operators | uk_operator_username | username |
| matches | uk_match_pair | (user_a_id, user_b_id) |
| user_relations | uk_user_relation | (user_id, target_user_id, relation_type) |
| activity_registrations | activity_registrations_activity_id_user_id_key | (activity_id, user_id) |
| activity_interests | activity_interests_activity_id_source_user_id_target_user_i_key | (activity_id, source_user_id, target_user_id) |
| messages | uk_message_client_id | (sender_id, client_message_id) WHERE client_message_id IS NOT NULL |
| user_identities | uk_identity_user | user_id |
| user_identities | uk_identity_hash | id_number_hash (WHERE verification_status = 'verified') |

### 2.2 复合索引

| 表 | 索引名 | 列 | 用途 |
|----|--------|-----|------|
| activities | idx_activities_organizer | (organizer_org_id, status) | 按组织查询活动 |
| activities | idx_activities_status | (status, start_at) | 按状态排序 |
| matches | idx_match_status | (status, matched_at DESC) | 活跃匹配查询 |
| matchmaker_services | idx_matchmaker_status | (status, created_at) | 服务状态统计 |
| matchmaker_services | idx_matchmaker_operator | (assigned_operator_id, status) | 红娘任务 |
| messages | idx_messages_conversation_time | (conversation_id, created_at DESC) | 消息时间线 |
| notifications | idx_notifications_user | (user_id, read_status, created_at) | 未读通知 |
| review_tasks | idx_review_tasks_status_time | (status, submitted_at) | 待审核任务 |
| reports | idx_reports_status_priority | (status, reason_type, created_at) | 举报处理 |

### 2.3 部分索引

```sql
-- 仅索引未删除的用户
CREATE UNIQUE INDEX uk_users_openid ON users(wechat_openid) WHERE deleted_at IS NULL;
CREATE UNIQUE INDEX uk_users_phone ON users(phone) WHERE phone IS NOT NULL AND deleted_at IS NULL;

-- 仅索引已验证的身份证哈希（防重复）
CREATE UNIQUE INDEX uk_identity_hash ON user_identities(id_number_hash)
    WHERE verification_status = 'verified';
```

---

## 三、数据模型规范

### 3.1 主键策略
- **类型**: UUID (varchar(36))
- **生成方式**: `gen_random_uuid()`
- **示例**: `c1eebc99-9c0b-4ef8-bb6d-6bb9bd380a11`

### 3.2 软删除模式
- **字段**: `deleted_at smallint`
- **值**: `0` = 未删除, `非0` = 已删除
- **查询惯例**: `WHERE deleted_at = 0`

### 3.3 时间类型
- **时区**: TIMESTAMPTZ (带时区)
- **存储**: UTC
- **显示**: Asia/Shanghai (+8)

### 3.4 JSONB 字段
- `user_preferences.region_scope` - 地区范围
- `user_preferences.marital_statuses` - 婚姻状况偏好
- `audit_logs.before_data` / `after_data` - 变更快照

---

## 四、Flyway 迁移版本 (V001-V014)

| 版本 | 表 |
|------|-----|
| V001 | users, organizations, operators, roles, permissions, operator_roles, role_permissions, audit_logs, sensitive_access_logs, system_configs, interest_dictionary |
| V002 | user_identities, user_profiles, user_preferences, user_interests, user_photos, user_privacy_settings, consent_records |
| V003 | review_tasks, review_items, review_reasons, user_relations |
| V004 | recommendation_records, conversation_members |
| V005 | (审核相关补充) |
| V006 | matches |
| V007 | relationship_success_requests |
| V008 | conversations, messages |
| V009 | matchmaker_services, matchmaker_followups, matchmaker_recommendations |
| V010 | activities, activity_registrations |
| V011 | activity_interests |
| V012 | reports, risk_events, risk_actions, sensitive_access_logs |
| V013 | appeals |
| V014 | consent_records, system_configs |

---

## 五、安全加密

### 5.1 敏感字段加密
| 字段 | 算法 |
|------|------|
| phone | BCrypt hash + AES 加密存储 |
| id_number | AES-256-GCM |
| real_name | AES-256-GCM |
| emergency_contact_phone | AES-256-GCM |
| password_hash | BCrypt (rounds=10) |

### 5.2 JWT 配置
| 参数 | 值 |
|------|-----|
| 算法 | HS384 |
| 访问令牌过期 | 2小时 |
| 刷新令牌过期 | 14天 |
| 密钥长度 | 64+ bytes |

### 5.3 RBAC 权限模型
- **角色数**: 9 个
- **权限数**: 18 个细粒度权限码
- **角色**: super_admin, platform_admin, organization_admin, reviewer, matchmaker, activity_manager, risk_operator, volunteer, data_viewer

---

## 六、应用配置

### 6.1 Spring Boot 3.2.5
```yaml
datasource:
  maximum-pool-size: 20
  minimum-idle: 5
  connection-timeout: 30000

flyway:
  enabled: true
  baseline-on-migrate: true
  out-of-order: false
```

### 6.2 匹配规则默认值
| 参数 | 默认值 |
|------|--------|
| daily_recommendation_limit | 6 |
| match_score_threshold | 60 |
| recommendation_cooldown_days | 180 |
| max_profile_photos | 6 |
| max_interest_tags | 8 |
| self_intro_max_length | 500 |

### 6.3 特征开关
| 开关 | 默认值 |
|------|--------|
| activity_enabled | true |
| matchmaker_enabled | true |
| chat_image_enabled | false |
| appeal_enabled | false |
| checkin_enabled | true |

---

## 七、容器部署

### 7.1 Docker Compose 端口映射
| 服务 | 宿主机端口 | 容器端口 |
|------|-----------|----------|
| PostgreSQL | 5434 | 5432 |
| Redis | 6381 | 6379 |
| MinIO API | 9003 | 9000 |
| MinIO Console | 9004 | 9001 |
| Backend API | 8085 | 8080 |
| Admin Web | 3000 | 80 |

### 7.2 Nginx 反向代理
- `/api/v1/` → `http://backend:8080`
- `/` → Vue 静态资源
- `/ws/` → WebSocket 转发

---

## 八、数据量统计

| 实体 | 数量 |
|------|------|
| operators | 2 |
| organizations | 1 |
| roles | 1 (matchmaker) |
| permissions | 18 |
| matchmaker_services | 2 |

---

*技术规格文档 v1.0.0-RC.1*
*生成时间: 2026-09-01*