danyang-match/docs/善缘丹阳 V1.1 数据库与API增量设计.md

# “善缘丹阳”公益婚恋服务平台
# V1.1 数据库与 API 增量设计

版本：V1.1  
设计原则：增量扩展、兼容 V1.0、避免重复建模、保持模块化单体架构  
新增覆盖：Banner、善缘服务站、服务预约、婚恋咨询、婚前辅导、婚恋课堂、婚恋反诈、本地资格核验、专项公益服务项目、来源追踪

---

# 第一章 本次增量设计目标

最新项目计划书已经明确，“善缘丹阳”不仅承担公益婚恋交友，还包括婚恋指导、婚前辅导、婚俗新风、反诈科普、固定阵地服务等内容。

同时，万善公园婚姻登记处被明确为项目固定运营阵地。

因此本次 V1.1 必须在现有 V1.0 架构基础上增加：

```text
Banner运营
固定服务阵地
服务预约
婚恋咨询
婚前辅导
公益内容
婚恋反诈
本地资格核验
专项公益服务项目
公益推广来源
```

---

# 第二章 明确不修改的 V1.0 核心表

以下核心表继续保留：

```text
users
user_wechat_accounts
user_identities
user_profiles
user_preferences
preference_rules
user_interests
user_photos
user_privacy_settings

review_tasks
review_items
review_reasons

recommendation_records
user_relations
matches

conversations
conversation_members
messages

activities
activity_registrations
activity_feedback
activity_user_interests

matchmaker_services
matchmaker_recommendations
matchmaker_followups

reports
report_evidences
user_risk_profiles
risk_events
risk_actions

organizations
operators
roles
permissions
operator_roles
role_permissions

audit_logs
sensitive_access_logs

system_configs
match_rule_configs
```

本次不因 V1.1 新业务而重做这些表。

---

# 第三章 本次新增核心实体

建议新增：

```text
home_banners

service_locations
service_appointments

counseling_services
counseling_followups

content_categories
content_articles

user_local_eligibilities
local_eligibility_evidences

service_programs
service_program_members

partner_organizations

source_campaigns
user_acquisition_sources
```

其中部分可根据最终实现合并，但业务语义必须保留。

---

# 第四章 home_banners

用于首页 Banner 运营。

表：

```text
home_banners
```

建议字段：

```text
id
title
subtitle
image_file_id
button_text

target_type
target_value

audience_scope
sort_order

start_at
end_at

status

created_by
updated_by
created_at
updated_at
```

---

# 第五章 Banner TargetType

建议：

```text
activity
matchmaker
counseling
premarital
service_location
article
internal_page
none
```

---

# 第六章 Banner AudienceScope

支持：

```text
all
onboarding
searching
getting_to_know
successful
```

如果未来关系状态命名调整：

> 使用等义业务状态。

---

# 第七章 Banner 状态

技术候选：

```text
draft
scheduled
active
inactive
expired
```

也可以简化为：

```text
status
+
start_at
+
end_at
```

最终状态计算方式可由研发选择。

---

# 第八章 Banner 业务规则

必须满足：

```text
未到start_at
→ 不展示

超过end_at
→ 不展示

status不可用
→ 不展示

用户状态不匹配audience_scope
→ 不展示
```

---

# 第九章 Banner 图片

使用原统一文件系统。

不要单独建：

```text
banner_images
```

只保存：

```text
image_file_id
```

---

# 第十章 Banner 跳转安全

不允许：

```text
target_type = arbitrary_url
```

V1.1 只允许平台内部已知目标。

避免：

- 错误外链
- 恶意跳转
- 内容不可控

---

# 第十一章 Banner API

用户端：

```text
GET /api/v1/home/banners
```

根据当前用户状态自动过滤。

---

# 第十二章 Banner Admin API

```text
GET    /api/v1/operator/banners
POST   /api/v1/operator/banners
GET    /api/v1/operator/banners/{id}
PUT    /api/v1/operator/banners/{id}
POST   /api/v1/operator/banners/{id}/publish
POST   /api/v1/operator/banners/{id}/disable
POST   /api/v1/operator/banners/reorder
```

---

# 第十三章 Banner 权限

```text
banner.view
banner.create
banner.edit
banner.publish
banner.disable
banner.reorder
```

---

# 第十四章 service_locations

用于固定公益服务阵地。

当前首个正式服务点：

> 万善公园婚姻登记处。

计划书明确要求建立常态化驻点机制。

---

# 第十五章 service_locations 字段

建议：

```text
id
name
short_name

address
latitude
longitude

contact_phone_enc
contact_phone_display

opening_hours_text
service_description

cover_file_id
status

primary_organization_id

created_at
updated_at
```

---

# 第十六章 地图位置

服务站可保存：

```text
latitude
longitude
```

这是公共服务地点，不属于用户精确定位。

与此前“不采集用户GPS”没有冲突。

---

# 第十七章 opening_hours

V1.1 推荐先使用：

```text
opening_hours_text
```

例如：

```text
周一至周五 09:00—17:00
周末以活动公告为准
```

暂不建设复杂排班引擎。

---

# 第十八章 service_location_services

如果未来一个阵地提供多个服务点配置，建议增加：

```text
service_location_services
```

字段：

```text
service_location_id
service_type
enabled
display_order
```

V1.1 也可以先直接由 Config 管理。

---

# 第十九章 ServiceType

建议：

```text
matchmaker
counseling
premarital
activity_support
anti_fraud
marriage_culture
general_inquiry
```

---

# 第二十章 服务站用户 API

```text
GET /api/v1/service-locations
GET /api/v1/service-locations/{id}
```

当前虽然只有一个服务站：

> 仍使用列表+详情结构。

方便未来扩展。

---

# 第二十一章 服务站 Admin API

```text
GET  /api/v1/operator/service-locations
POST /api/v1/operator/service-locations
PUT  /api/v1/operator/service-locations/{id}
POST /api/v1/operator/service-locations/{id}/enable
POST /api/v1/operator/service-locations/{id}/disable
```

---

# 第二十二章 service_appointments

用于用户预约：

- 公益红娘
- 婚恋咨询
- 婚前辅导
- 服务站咨询

---

# 第二十三章 service_appointments 字段

建议：

```text
id
user_id

service_location_id
service_type

preferred_date
preferred_time_slot

user_note

status

assigned_operator_id

confirmed_start_at
confirmed_end_at

cancelled_by
cancel_reason

source

created_at
updated_at
```

---

# 第二十四章 AppointmentStatus

推荐：

```text
submitted
pending_confirmation
confirmed
completed
cancelled
```

技术上可以进一步精简。

---

# 第二十五章 用户预约原则

同一用户可以拥有多个历史预约。

不能：

```text
UNIQUE(user_id)
```

只能在必要时限制：

> 同类型同时存在的 Active Appointment 数量。

---

# 第二十六章 服务预约 API

```text
POST /api/v1/service-appointments
GET  /api/v1/service-appointments
GET  /api/v1/service-appointments/{id}

POST /api/v1/service-appointments/{id}/cancel
```

---

# 第二十七章 后台预约 API

```text
GET  /api/v1/operator/service-appointments
GET  /api/v1/operator/service-appointments/{id}

POST /api/v1/operator/service-appointments/{id}/confirm
POST /api/v1/operator/service-appointments/{id}/assign
POST /api/v1/operator/service-appointments/{id}/complete
POST /api/v1/operator/service-appointments/{id}/cancel
```

---

# 第二十八章 预约权限

```text
service_appointment.view
service_appointment.assign
service_appointment.confirm
service_appointment.complete
service_appointment.cancel
```

---

# 第二十九章 counseling_services

这是 V1.1 新增的重要业务对象。

计划书明确提出恋爱困惑、情感矛盾、婚恋焦虑以及婚前公益辅导。

但系统定位：

> 公益婚恋指导服务。

不是：

> 医疗诊疗系统。

---

# 第三十章 counseling_services 字段

建议：

```text
id
user_id

service_type
request_source

user_request_summary

organization_id
assigned_operator_id

status

preferred_service_mode
preferred_time

scheduled_start_at
scheduled_end_at

consent_version
consented_at

completed_at
closed_reason

created_at
updated_at
```

---

# 第三十一章 CounselingServiceType

建议：

```text
relationship_guidance
emotional_support
premarital_guidance
anti_fraud_guidance
```

---

# 第三十二章 是否单独建 premarital_services

V1.1 不建议。

婚前辅导继续复用：

```text
counseling_services
```

通过：

```text
service_type = premarital_guidance
```

区分。

减少表数量。

---

# 第三十三章 ServiceMode

建议：

```text
offline
phone
online_other
```

V1.1 不建设咨询即时 IM。

---

# 第三十四章 CounselingStatus

建议：

```text
requested
assigned
scheduled
in_service
completed
closed
cancelled
```

如果希望减少状态：

可采用：

```text
status
+
next_action_type
```

---

# 第三十五章 counseling_followups

用于服务必要记录。

字段：

```text
id
counseling_service_id
operator_id

followup_type

summary
result_code
next_action

next_followup_at

created_at
```

---

# 第三十六章 咨询记录边界

禁止存：

```text
完整逐字聊天记录
录音默认存档
大段私人关系细节
```

仅保存：

```text
服务需求摘要
本次服务结果
后续建议
必要风险转交
```

---

# 第三十七章 用户咨询 API

```text
GET  /api/v1/counseling/services
POST /api/v1/counseling/services
GET  /api/v1/counseling/services/{id}

POST /api/v1/counseling/services/{id}/cancel
POST /api/v1/counseling/services/{id}/feedback
```

---

# 第三十八章 后台咨询 API

```text
GET  /api/v1/operator/counseling/services
GET  /api/v1/operator/counseling/services/{id}

POST /api/v1/operator/counseling/services/{id}/assign
POST /api/v1/operator/counseling/services/{id}/schedule
POST /api/v1/operator/counseling/services/{id}/start
POST /api/v1/operator/counseling/services/{id}/followups
POST /api/v1/operator/counseling/services/{id}/complete
POST /api/v1/operator/counseling/services/{id}/close
```

---

# 第三十九章 咨询权限

```text
counseling.service.view
counseling.service.assign
counseling.service.process
counseling.service.complete
counseling.note.view
counseling.note.create
```

---

# 第四十章 Counselor 数据范围

默认：

```text
assigned
```

咨询人员只能访问：

> 明确分配给自己的服务。

不能全平台浏览所有咨询。

---

# 第四十一章 咨询与 Risk 的关系

如果咨询过程中发现：

```text
诈骗
骚扰
安全威胁
严重违法风险
```

通过：

```text
RiskEvent
```

转交。

source：

```text
counseling
```

咨询人员不直接执行封禁。

---

# 第四十二章 content_categories

用于轻量公益内容。

分类建议：

```text
relationship
premarital
marriage_culture
anti_fraud
```

---

# 第四十三章 content_categories 字段

```text
id
code
name
sort_order
status
created_at
updated_at
```

---

# 第四十四章 content_articles

字段：

```text
id

category_id
title
summary

cover_file_id
content

status

publish_at
unpublish_at

created_by
updated_by

created_at
updated_at
```

---

# 第四十五章 ArticleStatus

建议：

```text
draft
published
offline
```

配合时间字段。

---

# 第四十六章 内容格式

V1.1 推荐：

```text
Markdown
```

或：

```text
受控富文本
```

必须做：

> XSS 安全处理。

---

# 第四十七章 内容用户 API

```text
GET /api/v1/content/categories
GET /api/v1/content/articles
GET /api/v1/content/articles/{id}
```

支持：

```text
category
page
pageSize
```

---

# 第四十八章 首页内容 API

可以复用：

```text
GET /api/v1/content/articles?featured=true
```

或者：

```text
GET /api/v1/home/content
```

推荐后者聚合首页。

---

# 第四十九章 内容后台 API

```text
GET    /api/v1/operator/content/articles
POST   /api/v1/operator/content/articles
GET    /api/v1/operator/content/articles/{id}
PUT    /api/v1/operator/content/articles/{id}

POST   /api/v1/operator/content/articles/{id}/publish
POST   /api/v1/operator/content/articles/{id}/offline
```

---

# 第五十章 内容权限

```text
content.view
content.create
content.edit
content.publish
content.offline
```

---

# 第五十一章 不做内容互动表

V1.1 明确不新增：

```text
article_comments
article_likes
article_favorites
followers
```

内容中心不是社区。

---

# 第五十二章 user_local_eligibilities

用于丹阳本地服务资格。

计划书要求项目面向丹阳本地工作、居住、户籍的适龄单身人群。

---

# 第五十三章 user_local_eligibilities 字段

建议：

```text
id
user_id

eligibility_type
declared_region_code

verification_status

review_task_id

verified_at
verified_by

created_at
updated_at
```

---

# 第五十四章 EligibilityType

```text
household_registration
residence
employment
other
```

---

# 第五十五章 LocalVerificationStatus

建议：

```text
declared
needs_evidence
pending_review
verified
rejected
```

---

# 第五十六章 不要求所有用户默认上传佐证

业务流程：

```text
用户声明
↓
系统/人工判断是否需要补充
↓
需要时
↓
上传佐证
↓
人工审核
```

这能降低注册门槛。

---

# 第五十七章 local_eligibility_evidences

字段：

```text
id
local_eligibility_id
file_id
evidence_type
status
created_at
```

---

# 第五十八章 EvidenceType

可以：

```text
employment_proof
residence_proof
household_proof
other
```

最终根据运营实际确认。

---

# 第五十九章 本地资格佐证属于敏感资料

默认：

> 普通红娘、活动人员不可见原文件。

审核员只在：

> 本地资格审核任务

中访问。

---

# 第六十章 本地资格用户 API

```text
GET  /api/v1/local-eligibility
POST /api/v1/local-eligibility/declaration

POST /api/v1/local-eligibility/evidences
POST /api/v1/local-eligibility/submit
```

---

# 第六十一章 本地资格后台 API

```text
GET  /api/v1/operator/local-eligibility/reviews
GET  /api/v1/operator/local-eligibility/reviews/{id}

POST /api/v1/operator/local-eligibility/reviews/{id}/claim
POST /api/v1/operator/local-eligibility/reviews/{id}/approve
POST /api/v1/operator/local-eligibility/reviews/{id}/need-evidence
POST /api/v1/operator/local-eligibility/reviews/{id}/reject
```

---

# 第六十二章 是否复用 review_tasks

强烈建议：

> 复用现有 review_tasks。

新增：

```text
review_type
```

例如：

```text
profile
local_eligibility
photo
other
```

避免重新开发第二套审核工作流。

---

# 第六十三章 人脸核验设计

当前不建议新增自行存储的人脸表。

如果后续启用合规 Provider：

建议只增加到：

```text
user_identities
```

字段：

```text
liveness_verification_status
liveness_verified_at
verification_provider
```

不保存：

```text
face_embedding
face_template
```

除非未来有明确合法、必要且经过专项设计的理由。

---

# 第六十四章 service_programs

用于专项公益服务项目。

例如：

```text
基层职工婚恋关爱
异地务工青年服务
青年公益婚恋计划
```

---

# 第六十五章 service_programs 字段

```text
id
code
name
description

organization_id

start_at
end_at

status

eligibility_description

created_at
updated_at
```

---

# 第六十六章 service_program_members

字段：

```text
id
service_program_id
user_id

join_source
status

joined_at
exited_at

created_at
updated_at
```

---

# 第六十七章 ProgramMember 不做敏感价值标签

不要存：

```text
low_value
difficult_match
disabled_user
poor_family
```

专项服务资格：

> 使用具体 Program Membership 表达。

---

# 第六十八章 service_programs API

用户端：

```text
GET  /api/v1/service-programs
GET  /api/v1/service-programs/{id}
POST /api/v1/service-programs/{id}/apply
```

后台：

```text
GET  /api/v1/operator/service-programs
POST /api/v1/operator/service-programs
PUT  /api/v1/operator/service-programs/{id}

GET  /api/v1/operator/service-programs/{id}/members
POST /api/v1/operator/service-programs/{id}/members/{userId}/approve
```

---

# 第六十九章 partner_organizations

此前已经有：

```text
organizations
```

因此是否需要 partner_organizations 应谨慎。

推荐：

> 不新增独立表。

直接扩展：

```text
organizations
```

增加：

```text
organization_role
```

或建立关联表：

```text
organization_relationships
```

---

# 第七十章 organization_relationships

建议：

```text
id

organization_id
related_organization_id

relationship_type

start_at
end_at
status
```

---

# 第七十一章 RelationshipType

```text
sponsor
co_sponsor
operator
partner
venue_partner
```

---

# 第七十二章 Activity 与组织关系

原来如果只有：

```text
organizer_org_id
```

建议升级为：

```text
activity_organizations
```

字段：

```text
activity_id
organization_id
role
```

role：

```text
host
organizer
co_organizer
partner
venue_partner
```

这更符合多部门联合活动场景。

---

# 第七十三章 主办单位身份不自动带来数据权限

这是硬规则。

例如：

```text
organization_relationship = sponsor
```

不代表：

```text
operator can view all users
```

数据权限仍由：

```text
Role + Permission + DataScope
```

决定。

---

# 第七十四章 source_campaigns

用于公益来源追踪。

字段：

```text
id
code
name

source_type

organization_id
activity_id

start_at
end_at

status

created_at
```

---

# 第七十五章 SourceType

建议：

```text
service_station
organization
activity
qr_code
official_account
community
enterprise
school
hospital
other
```

---

# 第七十六章 user_acquisition_sources

如果只记录用户首次来源：

可以直接：

```text
users.source_campaign_id
```

但为了未来支持多触点，建议：

```text
user_acquisition_sources
```

字段：

```text
id
user_id
source_campaign_id
source_scene
first_touch
created_at
```

---

# 第七十七章 V1.1 简化建议

为了避免过度设计：

首次上线只实现：

```text
users.registration_source
users.source_campaign_id
```

足够。

未来再独立拆表。

---

# 第七十八章 二维码参数

推荐统一 Scene：

```text
sourceCampaignId
activityId
serviceLocationId
```

不要把：

- 手机号
- 用户ID
- 敏感参数

直接放二维码。

---

# 第七十九章 首页聚合 API

为了减少首页多次请求，建议新增：

```text
GET /api/v1/home
```

返回：

```text
userStatus
banners
quickEntries
recommendations
recommendedServices
upcomingActivities
serviceLocation
featuredContent
safetyNotice
```

---

# 第八十章 为什么需要 Home Aggregate API

否则首页可能请求：

```text
banner
user status
recommendation
activity
service station
content
```

六七次接口。

V1.1 推荐由：

```text
HomeApplicationService
```

聚合。

但各业务模块仍保持自己的 Service。

---

# 第八十一章 Home API DTO

建议：

```json
{
  "userState": {},
  "banners": [],
  "quickEntries": [],
  "recommendations": [],
  "serviceRecommendations": [],
  "activities": [],
  "serviceLocation": {},
  "articles": [],
  "safetyNotice": {}
}
```

---

# 第八十二章 Home API 不应自己实现业务逻辑

Home Service 只负责：

> 聚合。

不能复制：

- Match Eligibility
- Activity Eligibility
- Privacy Rules

必须调用正式业务模块。

---

# 第八十三章 QuickEntry 不需要数据库

8个核心入口已经正式固定。

因此：

> 不建议存 quick_entries 表。

前端/配置常量即可。

后台不允许运营随意重新排序。

---

# 第八十四章 FeatureFlag

可为尚未正式启用的入口配置：

```text
counselingEnabled
premaritalEnabled
serviceLocationEnabled
contentEnabled
```

入口结构固定。

是否启用：

> Config控制。

---

# 第八十五章 Activity 增量字段

现有 activities 建议增加：

```text
activity_type
registration_policy
target_group
industry_scope
post_event_interest_enabled
```

---

# 第八十六章 ActivityType

```text
matchmaking
interest_social
relationship_education
premarital_guidance
marriage_custom_culture
anti_fraud
```

---

# 第八十七章 RegistrationPolicy

不建议只存一个巨大 JSON。

如果规则简单：

```text
requires_identity_verified
requires_local_eligibility
requires_profile_approved
requires_searching_status
requires_manual_review
```

字段或配置快照均可。

---

# 第八十八章 Activity Capacity 修正

不能默认写死：

```text
male_limit
female_limit
```

推荐：

```text
total_capacity
```

配：

```text
activity_capacity_groups
```

字段：

```text
activity_id
group_code
rule_definition
capacity
approved_count
```

只有具体活动需要性别配额时才配置。

---

# 第八十九章 活动互选流程数据库增量

已有：

```text
activity_user_interests
```

继续使用。

新增：

```text
mutual_result_at
```

以及建议新增：

```text
activity_mutual_connection_consents
```

---

# 第九十章 activity_mutual_connection_consents

字段：

```text
id
activity_id
user_a_id
user_b_id

user_a_confirmed_at
user_b_confirmed_at

status

match_id

created_at
updated_at
```

---

# 第九十一章 活动互选正式流程

```text
A选择B
↓
B选择A
↓
形成mutual interest
↓
创建MutualConnectionConsent
↓
通知双方
↓
A确认开启沟通
↓
B确认开启沟通
↓
双方均确认
↓
创建新Match Episode
↓
创建Conversation
```

这是 V1.1 正式建议实现。

---

# 第九十二章 不能直接 mutual interest → Match

这是对早期文档的重要修正。

除非未来用户协议明确把：

> “活动互选”

本身定义为：

> 同意建立线上沟通。

目前采用更安全的：

> 二阶段同意。

---

# 第九十三章 Matchmaker 增量

红娘模块基本不改。

只增加服务转介：

```text
matchmaker → counseling
matchmaker → activity
matchmaker → service_location
```

---

# 第九十四章 Service Referral

可以增加：

```text
service_referrals
```

但 V1.1 不建议新增新表。

直接利用：

```text
source
source_business_id
```

创建相应服务申请即可。

---

# 第九十五章 Counseling来源

例如：

```text
user_self
matchmaker_referral
activity_followup
service_station
operator_assisted
```

---

# 第九十六章 operator_assisted 使用边界

如果线下工作人员协助群众创建服务：

必须记录：

```text
request_source = operator_assisted
created_by_operator_id
user_confirmed_at
```

不能工作人员自己替用户申请而不留痕。

---

# 第九十七章 新增 Operator Roles

建议：

```text
service_station_operator
counselor
counseling_manager
content_editor
```

---

# 第九十八章 角色是否必须独立

如果初期人员少：

一个 Operator 可以同时拥有：

```text
matchmaker
service_station_operator
```

或者：

```text
counselor
content_editor
```

不需要创建多个账号。

---

# 第九十九章 Service Station Operator 权限

建议：

```text
service_location.view
service_appointment.view
service_appointment.process
activity.checkin
service.assisted_registration
```

不拥有：

```text
user.full_search
message.content.review
user.sensitive.identity.full
```

---

# 第一百章 Counselor 权限

```text
counseling.service.view
counseling.service.process
counseling.note.create
```

DataScope：

```text
assigned
```

---

# 第一百零一章 Content Editor 权限

```text
content.view
content.create
content.edit
content.publish
```

默认：

> 无用户数据权限。

---

# 第一百零二章 数据隐私增量要求

以下新增数据属于高敏感/较敏感：

```text
本地资格佐证
咨询申请内容
咨询服务摘要
婚前辅导服务内容
```

需要加入：

> Data Classification。

---

# 第一百零三章 建议分类

```text
L2
服务预约信息

L3
本地资格佐证

L3
婚恋咨询服务信息

L3
婚前辅导记录
```

具体分类可统一到现有安全规范。

---

# 第一百零四章 咨询隐私

普通 Platform Admin：

> 不默认看咨询正文。

管理统计只看：

```text
数量
状态
完成情况
服务时效
```

---

# 第一百零五章 本地资格文件

Signed URL 前必须：

> 权限校验。

不能因为知道 FileId 就能下载。

---

# 第一百零六章 新增审计行为

必须 Audit：

```text
Banner发布/下架
服务站编辑
预约改期
咨询分配
咨询完成
查看本地资格证明
内容发布
专项项目成员审批
```

---

# 第一百零七章 SensitiveAccessLog 增量

至少：

```text
local_eligibility_evidence.view
counseling_sensitive_note.view
```

如果这些数据被定义为高敏感访问。

---

# 第一百零八章 Notification 增量类型

增加：

```text
service_appointment_submitted
service_appointment_confirmed
service_appointment_changed
service_appointment_cancelled

counseling_assigned
counseling_scheduled
counseling_completed

premarital_service_scheduled

local_eligibility_need_evidence
local_eligibility_verified
local_eligibility_rejected
```

---

# 第一百零九章 外部通知文案

微信订阅通知等外部消息：

> 使用中性文案。

例如：

```text
你的公益服务预约已有更新
```

避免：

```text
你的婚恋焦虑心理咨询已安排
```

减少锁屏隐私暴露。

---

# 第一百一十章 Analytics 增量

新增指标：

```text
BANNER_IMPRESSIONS
BANNER_CLICKS

SERVICE_APPOINTMENTS
SERVICE_APPOINTMENTS_COMPLETED

COUNSELING_REQUESTS
COUNSELING_COMPLETED

PREMARITAL_GUIDANCE_REQUESTS
PREMARITAL_GUIDANCE_COMPLETED

SERVICE_STATION_USERS

CONTENT_VIEWS

LOCAL_ELIGIBILITY_VERIFIED_USERS

SERVICE_PROGRAM_USERS
```

---

# 第一百一十一章 服务用户数与服务人次

必须区分。

例如：

```text
UNIQUE_SERVICE_USERS
```

与：

```text
SERVICE_OCCURRENCES
```

一个用户接受4次服务：

```text
用户数 = 1
服务人次 = 4
```

---

# 第一百一十二章 有效交友匹配指标

计划书提出年度“有效交友匹配”。

建议系统定义：

```text
EFFECTIVE_CONNECTION
```

一种推荐口径：

```text
Mutual Match
+
Two-Way Chat Started
```

但这是建议指标口径。

最终对外政府报送口径需要运营方确认后固化。

---

# 第一百一十三章 首页 Analytics

建议事件：

```text
home_banner_impression
home_banner_click

home_quick_entry_click

home_recommendation_impression
home_activity_click
home_service_location_click
home_content_click
```

---

# 第一百一十四章 业务事实仍以后端为准

例如：

```text
counseling completed
```

以：

```text
counseling_services.completed_at
```

为准。

不能只靠：

> 前端埋点。

---

# 第一百一十五章 用户准入 API 修订

原：

```text
/me/status
```

增加：

```text
localEligibilityStatus
```

例如：

```json
{
  "loggedIn": true,
  "phoneBound": true,
  "realNameVerified": true,
  "localEligibility": "verified",
  "profileCompleted": true,
  "profileReview": "approved"
}
```

---

# 第一百一十六章 App Routing 修订

启动路由建议：

```text
登录
↓
手机号
↓
实名
↓
本地资格声明
↓
资料
↓
择偶条件
↓
审核
↓
正常首页
```

---

# 第一百一十七章 本地资格补充佐证不能阻断所有公益内容

例如：

> 婚恋反诈课堂

可以开放。

真正婚恋匹配：

> 按平台 Eligibility 要求决定是否阻断。

---

# 第一百一十八章 Home API Capability

推荐后端返回：

```text
capabilities
```

例如：

```json
{
  "canReceiveRecommendations": true,
  "canSearchUsers": true,
  "canApplyMatchmakingActivity": true,
  "canApplyCounseling": true
}
```

前端不要自行推测。

---

# 第一百一十九章 Capability 是统一设计的重要延续

V1.1 新模块加入后：

更应该由：

```text
CapabilityService
```

统一判断。

避免每个页面自己写：

```text
if verified && approved...
```

---

# 第一百二十章 新模块代码目录建议

Backend 增加：

```text
banner/
service_location/
appointment/
counseling/
content/
service_program/
local_eligibility/
```

---

# 第一百二十一章 不新增过度“Service Center”超级模块

虽然用户前台叫：

> 公益服务中心。

后端仍保持独立领域：

```text
Appointment
Counseling
Content
ServiceLocation
```

不要全部塞进：

```text
service/
```

一个巨型模块。

---

# 第一百二十二章 Miniapp Service API

增加：

```text
services/banner.ts
services/serviceLocation.ts
services/appointment.ts
services/counseling.ts
services/content.ts
services/localEligibility.ts
services/serviceProgram.ts
```

---

# 第一百二十三章 Admin Modules

新增：

```text
modules/banner/
modules/counseling/
modules/content/
modules/service-location/
modules/service-program/
```

---

# 第一百二十四章 API 幂等要求

以下 POST 建议支持：

```text
Idempotency-Key
```

包括：

```text
创建服务预约
提交咨询申请
提交本地资格审核
申请专项服务
活动互选确认
```

---

# 第一百二十五章 Service Appointment 并发

同一预约被：

- 用户取消
- 工作人员确认

同时发生。

最终必须：

> 单一合法状态。

---

# 第一百二十六章 Counseling Assign 并发

两名管理员同时给同一咨询分配人员。

必须：

> 原子更新。

---

# 第一百二十七章 Counseling Service 不使用医疗术语

API 内部可以叫：

```text
counseling
```

前台主要使用：

```text
婚恋咨询
公益婚恋指导
```

不要将服务包装成：

> 心理诊断。

---

# 第一百二十八章 API 错误码新增

建议：

```text
BANNER_NOT_AVAILABLE

SERVICE_LOCATION_NOT_AVAILABLE

APPOINTMENT_CONFLICT
APPOINTMENT_ALREADY_CANCELLED

COUNSELING_SERVICE_NOT_AVAILABLE
COUNSELING_ALREADY_CLOSED

LOCAL_ELIGIBILITY_REQUIRED
LOCAL_ELIGIBILITY_EVIDENCE_REQUIRED
LOCAL_ELIGIBILITY_REVIEWING

SERVICE_PROGRAM_NOT_AVAILABLE
SERVICE_PROGRAM_ALREADY_JOINED
```

---

# 第一百二十九章 页面与 API 对照

## 首页 U18

```text
GET /home
```

---

## 服务站 U50

```text
GET /service-locations/{id}
```

---

## 服务预约 U51

```text
POST /service-appointments
```

---

## 我的预约 U52

```text
GET /service-appointments
```

---

## 婚恋课堂 U53

```text
GET /content/articles
```

---

## 内容详情 U54

```text
GET /content/articles/{id}
```

---

## 婚恋咨询 U55/U56/U57

```text
GET  /counseling/services
POST /counseling/services
GET  /counseling/services/{id}
```

---

## 婚前辅导 U58/U59

复用：

```text
/counseling/services
```

参数：

```text
serviceType = premarital_guidance
```

---

## 婚恋反诈 U60

复用：

```text
/content/articles?category=anti_fraud
```

---

## 本地资格 U62/U63

```text
/local-eligibility
```

---

# 第一百三十章 首页性能要求

Home Aggregate API：

建议：

```text
P95 < 1.5s
```

作为技术目标。

具体上线 SLA 结合实际环境压测确认。

---

# 第一百三十一章 Home Cache

可缓存：

```text
Banner
公开服务站
公开内容
活动摘要
```

不能盲目缓存：

```text
用户Capability
用户推荐
```

涉及用户状态必须正确失效。

---

# 第一百三十二章 首页推荐仍调用 Match Engine

Home API 不能自己写：

```text
SELECT users ORDER BY created_at
```

必须调用：

> RecommendationService。

---

# 第一百三十三章 Banner 定时任务

可：

> 查询时按时间过滤。

不一定需要定时 Job 改状态。

保持简单。

---

# 第一百三十四章 Service Location 当前只有一个阵地

仍然支持：

```text
status
```

未来暂停服务：

> 可立即下线预约入口。

---

# 第一百三十五章 服务站临时公告

建议直接增加：

```text
notice_text
```

或使用 Notification/Content。

V1.1 不需要独立：

```text
service_location_notices
```

除非后续公告很多。

---

# 第一百三十六章 婚前辅导双人参加

如果平台内双方希望共同参加：

可以增加：

```text
counseling_service_participants
```

但 V1.1 第一阶段不强制。

简单方案：

```text
primary_user_id
companion_user_id nullable
companion_confirmed_at
```

---

# 第一百三十七章 不允许一方擅自把对方加入辅导

如果 companion_user_id 是平台用户：

必须：

> 对方确认。

---

# 第一百三十八章 Service Program 与隐私

Program管理员只能看到：

> 服务项目必要信息。

不能因为用户加入某专项项目：

> 自动放开其全部婚恋档案。

---

# 第一百三十九章 内容与主办单位

文章可以增加：

```text
publisher_organization_id
```

例如：

> 乐活公益发布。

但内容展示不必每篇都堆多个组织Logo。

---

# 第一百四十章 用户服务历史统一视图

U64 公益服务记录建议由：

```text
ServiceHistoryQueryService
```

聚合：

```text
MatchmakerService
CounselingService
ActivityRegistration
ServiceAppointment
```

不新建：

```text
user_service_history
```

重复保存所有业务。

---

# 第一百四十一章 服务历史 API

```text
GET /api/v1/me/service-history
```

返回统一结构：

```json
{
  "type": "counseling",
  "title": "公益婚恋咨询",
  "occurredAt": "...",
  "status": "completed",
  "businessId": "..."
}
```

---

# 第一百四十二章 数据库 Migration 建议顺序

V1.1 建议：

```text
V1xx__add_home_banners

V1xx__add_service_locations
V1xx__add_service_appointments

V1xx__add_counseling_services
V1xx__add_counseling_followups

V1xx__add_content_categories
V1xx__add_content_articles

V1xx__add_local_eligibility

V1xx__add_service_programs

V1xx__extend_activities_v11

V1xx__add_activity_mutual_connection_consent

V1xx__extend_organization_relationships
```

具体编号由当前数据库版本决定。

---

# 第一百四十三章 数据库索引增量

建议：

```text
home_banners(status,start_at,end_at,sort_order)

service_appointments(user_id,status)
service_appointments(service_location_id,preferred_date,status)

counseling_services(user_id,status)
counseling_services(assigned_operator_id,status)
counseling_services(scheduled_start_at)

content_articles(category_id,status,publish_at)

user_local_eligibilities(user_id)
user_local_eligibilities(verification_status)

service_program_members(service_program_id,status)
service_program_members(user_id,status)
```

---

# 第一百四十四章 唯一约束建议

```text
user_local_eligibilities.user_id
```

原则上一个用户一个当前本地资格主体。

Program：

```text
UNIQUE(service_program_id,user_id)
```

预约：

> 不建议做 lifetime unique。

---

# 第一百四十五章 状态历史

重要状态变更可以通过：

> Audit / domain event

保留。

V1.1 不需要给每个小业务都建 status_history 表。

---

# 第一百四十六章 删除规则

Banner：

> soft disable。

ServiceLocation：

> disable。

Counseling：

> close，不物理删除。

Article：

> offline。

ServiceProgram：

> closed/disabled。

Local Evidence：

> 按数据保留政策处理。

---

# 第一百四十七章 数据保留待确认

需要写入：

```text
PENDING_DECISIONS.md
```

包括：

```text
本地资格佐证保留多久
婚恋咨询记录保留多久
婚前辅导记录保留多久
服务预约历史保留多久
```

不得代码硬编码。

---

# 第一百四十八章 V1.1 权限矩阵增量

| 功能 | 平台管理员 | 红娘 | 咨询人员 | 服务站人员 | 内容编辑 | 志愿者 |
|---|---:|---:|---:|---:|---:|---:|
| Banner | 管理 | 否 | 否 | 否 | 按授权 | 否 |
| 服务站 | 管理 | 查看 | 查看 | 是 | 否 | 当前服务必要 |
| 预约 | 管理 | 相关 | 相关 | 是 | 否 | 否 |
| 婚恋咨询 | 管理摘要 | 转介 | 分配服务 | 申请登记 | 否 | 否 |
| 咨询记录 | 默认否 | 否 | Assigned | 否 | 否 | 否 |
| 内容 | 管理 | 查看 | 查看 | 查看 | 是 | 查看 |
| 本地资格证明 | 特殊权限 | 否 | 否 | 否 | 否 | 否 |
| 专项项目 | 管理 | 按服务 | 按服务 | 按服务 | 否 | 否 |

---

# 第一百四十九章 关键隐私测试新增

必须增加：

```text
咨询人员访问未分配服务 → 403

红娘访问咨询记录 → 403

服务站人员访问身份证 → 403

内容编辑访问用户详情 → 403

机构A查看机构B专项项目成员 → 403

普通管理员直接访问本地资格佐证文件 → 403
```

---

# 第一百五十章 首页测试新增

必须测试：

```text
Banner按时间显示

Banner按用户状态显示

已过期Banner不显示

核心8入口顺序固定

未实名用户不返回真实推荐

Paused不返回新推荐

Successful不返回找对象推荐

Service Location停用时入口正确降级
```

---

# 第一百五十一章 咨询流程测试

```text
用户申请
↓
管理员分配
↓
咨询人员查看
↓
排期
↓
完成
```

同时验证：

```text
无权限Operator不能访问
```

---

# 第一百五十二章 本地资格测试

必须：

```text
声明丹阳工作
↓
要求补充佐证
↓
上传
↓
审核
↓
verified
```

以及：

```text
无需补充的规则场景
```

如果运营以后允许。

---

# 第一百五十三章 Activity V1.1 测试重点

必须修订旧测试：

错误旧逻辑：

```text
Activity mutual → Match
```

新逻辑：

```text
Activity mutual
↓
Mutual Result
↓
A confirm communication
↓
B confirm communication
↓
Match
```

---

# 第一百五十四章 如果一方不确认沟通

结果：

> 不创建Conversation。

单向拒绝原因：

> 不向对方详细披露。

---

# 第一百五十五章 Existing Active Match

如果活动双方已经有 Active Match：

> 不创建新 Match。

可以直接：

> 引导已有聊天。

---

# 第一百五十六章 Prior Unmatch

如果双方以前曾 Unmatch：

本次重新形成沟通：

> 创建新的 Match Episode。

不要恢复旧 Episode。

---

# 第一百五十七章 Codex 开发计划影响

原 Phase 01～26 不推翻。

建议调整如下。

---

# 第一百五十八章 在 Phase 04 增加

```text
Local Eligibility基础字段与页面
```

但人脸核验具体 Provider：

> 保持 Pending。

---

# 第一百五十九章 Phase 11 Notification 增加

```text
预约
咨询
本地资格
```

通知。

---

# 第一百六十章 Phase 13 后新增 Phase 13A

```text
公益咨询与婚前辅导
```

---

# 第一百六十一章 Phase 14 Activity 升级

新增：

```text
activity_type
registration_policy
行业专场
多组织关联
```

---

# 第一百六十二章 Phase 16 Activity Mutual 修正

改成：

```text
Mutual Interest
+
双向开启沟通确认
+
Match Episode
```

---

# 第一百六十三章 Phase 19 Admin 增加

```text
Banner
公益咨询
内容
服务站
专项服务项目
```

---

# 第一百六十四章 Phase 20 Analytics 增加

```text
服务站
咨询
婚前辅导
内容
专项项目
来源渠道
```

---

# 第一百六十五章 推荐新增 Phase 19A

如果希望开发计划更清晰，可以在 Phase 19 前增加：

```text
Phase 19A 公益内容与服务站
```

但不是必须。

仍可放 Phase 19。

---

# 第一百六十六章 V1.1 新增配置

建议：

```text
banner.maxActiveCount

localEligibility.enabled
localEligibility.evidencePolicy

counseling.enabled
premarital.enabled

serviceLocation.enabled

content.enabled

activity.mutualConnectionConfirmationEnabled
```

---

# 第一百六十七章 已确认配置

以下功能：

> 已确认进入 V1.1。

```text
Banner
8个核心入口
服务站
婚恋咨询
婚前辅导
婚恋课堂
婚恋反诈
```

所以不是：

```text
PENDING_PRODUCT_SCOPE
```

Feature Flag 只是为了灰度和故障关闭。

---

# 第一百六十八章 仍然待确认

```text
人脸核验是否首发强制
人脸Provider
所有用户是否强制上传工作/居住佐证
佐证触发规则
咨询人员实际组织和资质
服务站开放时间
Banner最大数量
服务预约具体时段规则
```

---

# 第一百六十九章 V1.1 API 模块总览

新增后：

```text
/home

/banners（后台）
/service-locations
/service-appointments

/counseling/services

/content/categories
/content/articles

/local-eligibility

/service-programs

/operator/...
```

---

# 第一百七十章 不需要增加 API Gateway

仍然：

> 单一 Modular Monolith Backend。

所有：

```text
/api/v1
```

统一服务。

---

# 第一百七十一章 不需要为内容单独做CMS服务

Content Module：

> 直接在主后台。

---

# 第一百七十二章 不需要为咨询单独开发App

咨询人员：

> 登录同一 Web 后台。

根据权限看到：

> 公益咨询工作台。

---

# 第一百七十三章 不需要服务站专用App

服务站人员：

> 响应式 Web 后台。

现场手机/平板也能使用。

---

# 第一百七十四章 V1.1数据库最终新增结构

最终建议确认如下：

```text
home_banners

service_locations
service_appointments

counseling_services
counseling_followups

content_categories
content_articles

user_local_eligibilities
local_eligibility_evidences

service_programs
service_program_members

organization_relationships
activity_organizations

activity_mutual_connection_consents
```

这是 V1.1 最合理的增量范围。

---

# 第一百七十五章 明确不新增

```text
community_posts
comments
group_chat
feed
points
user_rankings
financial_budget
donations
face_embeddings
psychological_medical_records
complex_workflow_engine
```

---

# 第一百七十六章 V1.1数据模型核心原则

> **已有业务不重复建表。**

> **新的公益服务尽量复用现有用户、组织、通知、审计、风险和文件模块。**

> **婚前辅导复用 CounselingService，而不是另造一套系统。**

> **婚恋反诈复用 Content + Risk，而不是另造反诈平台。**

> **服务站预约和专业咨询分开：预约是“什么时候来”，咨询是“具体提供什么服务”。**

> **本地资格独立于实名认证，避免把两个不同概念混为一谈。**

> **活动继续共用 Activity，但通过 ActivityType 和 RegistrationPolicy 支持多类型公益活动。**

---

# 第一百七十七章 V1.1 API核心原则

> **所有核心行为继续服务端判断。**

> **Home API只聚合，不复制业务规则。**

> **新增服务必须复用统一Authentication、Permission、DataScope和Audit。**

> **所有敏感文件访问先授权再签名。**

> **所有关键POST考虑幂等。**

> **所有待确认参数配置化。**

---

# 第一百七十八章 最终结论

V1.1 增量后，系统数据库和 API 将从原来的：

```text
用户
+
匹配
+
聊天
+
活动
+
红娘
+
风控
```

正式升级为：

```text
可信用户体系
+
本地资格
+
线上婚恋匹配
+
安全聊天
+
公益红娘
+
多类型公益活动
+
固定线下服务站
+
服务预约
+
婚恋咨询
+
婚前辅导
+
婚恋课堂
+
婚恋反诈
+
专项公益项目
+
多组织协同
+
项目服务统计
```

同时仍然保持：

> 一个 PostgreSQL。

> 一个模块化单体后端。

> 一个微信小程序。

> 一个统一 Web 后台。

没有因为 V1.1 新增公益服务而引入不必要的微服务、工作流引擎、社区系统或大数据架构。

这使“善缘丹阳”既能完整承接最新项目计划书要求的线上线下一体化公益服务，又能保持开发、部署和后期维护成本可控。