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

“善缘丹阳”公益婚恋服务平台

V1.1 数据库与 API 增量设计

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

---

第一章 本次增量设计目标

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

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

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

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

---

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

以下核心表继续保留：

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 新业务而重做这些表。

---

第三章 本次新增核心实体

建议新增：

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 运营。

表：

home_banners

建议字段：

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

建议：

activity
matchmaker
counseling
premarital
service_location
article
internal_page
none

---

第六章 Banner AudienceScope

支持：

all
onboarding
searching
getting_to_know
successful

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

使用等义业务状态。

---

第七章 Banner 状态

技术候选：

draft
scheduled
active
inactive
expired

也可以简化为：

status
+
start_at
+
end_at

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

---

第八章 Banner 业务规则

必须满足：

未到start_at
→ 不展示

超过end_at
→ 不展示

status不可用
→ 不展示

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

---

第九章 Banner 图片

使用原统一文件系统。

不要单独建：

banner_images

只保存：

image_file_id

---

第十章 Banner 跳转安全

不允许：

target_type = arbitrary_url

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

避免：

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

---

第十一章 Banner API

用户端：

GET /api/v1/home/banners

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

---

第十二章 Banner Admin API

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 权限

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

---

第十四章 service_locations

用于固定公益服务阵地。

当前首个正式服务点：

万善公园婚姻登记处。

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

---

第十五章 service_locations 字段

建议：

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

---

第十六章 地图位置

服务站可保存：

latitude
longitude

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

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

---

第十七章 opening_hours

V1.1 推荐先使用：

opening_hours_text

例如：

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

暂不建设复杂排班引擎。

---

第十八章 service_location_services

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

service_location_services

字段：

service_location_id
service_type
enabled
display_order

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

---

第十九章 ServiceType

建议：

matchmaker
counseling
premarital
activity_support
anti_fraud
marriage_culture
general_inquiry

---

第二十章 服务站用户 API

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

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

仍使用列表+详情结构。

方便未来扩展。

---

第二十一章 服务站 Admin API

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 字段

建议：

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

推荐：

submitted
pending_confirmation
confirmed
completed
cancelled

技术上可以进一步精简。

---

第二十五章 用户预约原则

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

不能：

UNIQUE(user_id)

只能在必要时限制：

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

---

第二十六章 服务预约 API

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

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

---

第二十七章 后台预约 API

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

---

第二十八章 预约权限

service_appointment.view
service_appointment.assign
service_appointment.confirm
service_appointment.complete
service_appointment.cancel

---

第二十九章 counseling_services

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

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

但系统定位：

公益婚恋指导服务。

不是：

医疗诊疗系统。

---

第三十章 counseling_services 字段

建议：

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

建议：

relationship_guidance
emotional_support
premarital_guidance
anti_fraud_guidance

---

第三十二章 是否单独建 premarital_services

V1.1 不建议。

婚前辅导继续复用：

counseling_services

通过：

service_type = premarital_guidance

区分。

减少表数量。

---

第三十三章 ServiceMode

建议：

offline
phone
online_other

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

---

第三十四章 CounselingStatus

建议：

requested
assigned
scheduled
in_service
completed
closed
cancelled

如果希望减少状态：

可采用：

status
+
next_action_type

---

第三十五章 counseling_followups

用于服务必要记录。

字段：

id
counseling_service_id
operator_id

followup_type

summary
result_code
next_action

next_followup_at

created_at

---

第三十六章 咨询记录边界

禁止存：

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

仅保存：

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

---

第三十七章 用户咨询 API

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

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

---

第三十九章 咨询权限

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

---

第四十章 Counselor 数据范围

默认：

assigned

咨询人员只能访问：

明确分配给自己的服务。

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

---

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

如果咨询过程中发现：

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

通过：

RiskEvent

转交。

source：

counseling

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

---

第四十二章 content_categories

用于轻量公益内容。

分类建议：

relationship
premarital
marriage_culture
anti_fraud

---

第四十三章 content_categories 字段

id
code
name
sort_order
status
created_at
updated_at

---

第四十四章 content_articles

字段：

id

category_id
title
summary

cover_file_id
content

status

publish_at
unpublish_at

created_by
updated_by

created_at
updated_at

---

第四十五章 ArticleStatus

建议：

draft
published
offline

配合时间字段。

---

第四十六章 内容格式

V1.1 推荐：

Markdown

或：

受控富文本

必须做：

XSS 安全处理。

---

第四十七章 内容用户 API

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

支持：

category
page
pageSize

---

第四十八章 首页内容 API

可以复用：

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

或者：

GET /api/v1/home/content

推荐后者聚合首页。

---

第四十九章 内容后台 API

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

---

第五十章 内容权限

content.view
content.create
content.edit
content.publish
content.offline

---

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

V1.1 明确不新增：

article_comments
article_likes
article_favorites
followers

内容中心不是社区。

---

第五十二章 user_local_eligibilities

用于丹阳本地服务资格。

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

---

第五十三章 user_local_eligibilities 字段

建议：

id
user_id

eligibility_type
declared_region_code

verification_status

review_task_id

verified_at
verified_by

created_at
updated_at

---

第五十四章 EligibilityType

household_registration
residence
employment
other

---

第五十五章 LocalVerificationStatus

建议：

declared
needs_evidence
pending_review
verified
rejected

---

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

业务流程：

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

这能降低注册门槛。

---

第五十七章 local_eligibility_evidences

字段：

id
local_eligibility_id
file_id
evidence_type
status
created_at

---

第五十八章 EvidenceType

可以：

employment_proof
residence_proof
household_proof
other

最终根据运营实际确认。

---

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

默认：

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

审核员只在：

本地资格审核任务

中访问。

---

第六十章 本地资格用户 API

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

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

---

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

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。

新增：

review_type

例如：

profile
local_eligibility
photo
other

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

---

第六十三章 人脸核验设计

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

如果后续启用合规 Provider：

建议只增加到：

user_identities

字段：

liveness_verification_status
liveness_verified_at
verification_provider

不保存：

face_embedding
face_template

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

---

第六十四章 service_programs

用于专项公益服务项目。

例如：

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

---

第六十五章 service_programs 字段

id
code
name
description

organization_id

start_at
end_at

status

eligibility_description

created_at
updated_at

---

第六十六章 service_program_members

字段：

id
service_program_id
user_id

join_source
status

joined_at
exited_at

created_at
updated_at

---

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

不要存：

low_value
difficult_match
disabled_user
poor_family

专项服务资格：

使用具体 Program Membership 表达。

---

第六十八章 service_programs API

用户端：

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

后台：

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

此前已经有：

organizations

因此是否需要 partner_organizations 应谨慎。

推荐：

不新增独立表。

直接扩展：

organizations

增加：

organization_role

或建立关联表：

organization_relationships

---

第七十章 organization_relationships

建议：

id

organization_id
related_organization_id

relationship_type

start_at
end_at
status

---

第七十一章 RelationshipType

sponsor
co_sponsor
operator
partner
venue_partner

---

第七十二章 Activity 与组织关系

原来如果只有：

organizer_org_id

建议升级为：

activity_organizations

字段：

activity_id
organization_id
role

role：

host
organizer
co_organizer
partner
venue_partner

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

---

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

这是硬规则。

例如：

organization_relationship = sponsor

不代表：

operator can view all users

数据权限仍由：

Role + Permission + DataScope

决定。

---

第七十四章 source_campaigns

用于公益来源追踪。

字段：

id
code
name

source_type

organization_id
activity_id

start_at
end_at

status

created_at

---

第七十五章 SourceType

建议：

service_station
organization
activity
qr_code
official_account
community
enterprise
school
hospital
other

---

第七十六章 user_acquisition_sources

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

可以直接：

users.source_campaign_id

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

user_acquisition_sources

字段：

id
user_id
source_campaign_id
source_scene
first_touch
created_at

---

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

为了避免过度设计：

首次上线只实现：

users.registration_source
users.source_campaign_id

足够。

未来再独立拆表。

---

第七十八章 二维码参数

推荐统一 Scene：

sourceCampaignId
activityId
serviceLocationId

不要把：

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

直接放二维码。

---

第七十九章 首页聚合 API

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

GET /api/v1/home

返回：

userStatus
banners
quickEntries
recommendations
recommendedServices
upcomingActivities
serviceLocation
featuredContent
safetyNotice

---

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

否则首页可能请求：

banner
user status
recommendation
activity
service station
content

六七次接口。

V1.1 推荐由：

HomeApplicationService

聚合。

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

---

第八十一章 Home API DTO

建议：

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

---

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

Home Service 只负责：

聚合。

不能复制：

• Match Eligibility
• Activity Eligibility
• Privacy Rules

必须调用正式业务模块。

---

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

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

因此：

不建议存 quick_entries 表。

前端/配置常量即可。

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

---

第八十四章 FeatureFlag

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

counselingEnabled
premaritalEnabled
serviceLocationEnabled
contentEnabled

入口结构固定。

是否启用：

Config控制。

---

第八十五章 Activity 增量字段

现有 activities 建议增加：

activity_type
registration_policy
target_group
industry_scope
post_event_interest_enabled

---

第八十六章 ActivityType

matchmaking
interest_social
relationship_education
premarital_guidance
marriage_custom_culture
anti_fraud

---

第八十七章 RegistrationPolicy

不建议只存一个巨大 JSON。

如果规则简单：

requires_identity_verified
requires_local_eligibility
requires_profile_approved
requires_searching_status
requires_manual_review

字段或配置快照均可。

---

第八十八章 Activity Capacity 修正

不能默认写死：

male_limit
female_limit

推荐：

total_capacity

配：

activity_capacity_groups

字段：

activity_id
group_code
rule_definition
capacity
approved_count

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

---

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

已有：

activity_user_interests

继续使用。

新增：

mutual_result_at

以及建议新增：

activity_mutual_connection_consents

---

第九十章 activity_mutual_connection_consents

字段：

id
activity_id
user_a_id
user_b_id

user_a_confirmed_at
user_b_confirmed_at

status

match_id

created_at
updated_at

---

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

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

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

---

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

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

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

“活动互选”

本身定义为：

同意建立线上沟通。

目前采用更安全的：

二阶段同意。

---

第九十三章 Matchmaker 增量

红娘模块基本不改。

只增加服务转介：

matchmaker → counseling
matchmaker → activity
matchmaker → service_location

---

第九十四章 Service Referral

可以增加：

service_referrals

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

直接利用：

source
source_business_id

创建相应服务申请即可。

---

第九十五章 Counseling来源

例如：

user_self
matchmaker_referral
activity_followup
service_station
operator_assisted

---

第九十六章 operator_assisted 使用边界

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

必须记录：

request_source = operator_assisted
created_by_operator_id
user_confirmed_at

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

---

第九十七章 新增 Operator Roles

建议：

service_station_operator
counselor
counseling_manager
content_editor

---

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

如果初期人员少：

一个 Operator 可以同时拥有：

matchmaker
service_station_operator

或者：

counselor
content_editor

不需要创建多个账号。

---

第九十九章 Service Station Operator 权限

建议：

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

不拥有：

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

---

第一百章 Counselor 权限

counseling.service.view
counseling.service.process
counseling.note.create

DataScope：

assigned

---

第一百零一章 Content Editor 权限

content.view
content.create
content.edit
content.publish

默认：

无用户数据权限。

---

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

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

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

需要加入：

Data Classification。

---

第一百零三章 建议分类

L2
服务预约信息

L3
本地资格佐证

L3
婚恋咨询服务信息

L3
婚前辅导记录

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

---

第一百零四章 咨询隐私

普通 Platform Admin：

不默认看咨询正文。

管理统计只看：

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

---

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

Signed URL 前必须：

权限校验。

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

---

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

必须 Audit：

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

---

第一百零七章 SensitiveAccessLog 增量

至少：

local_eligibility_evidence.view
counseling_sensitive_note.view

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

---

第一百零八章 Notification 增量类型

增加：

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

---

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

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

使用中性文案。

例如：

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

避免：

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

减少锁屏隐私暴露。

---

第一百一十章 Analytics 增量

新增指标：

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

---

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

必须区分。

例如：

UNIQUE_SERVICE_USERS

与：

SERVICE_OCCURRENCES

一个用户接受4次服务：

用户数 = 1
服务人次 = 4

---

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

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

建议系统定义：

EFFECTIVE_CONNECTION

一种推荐口径：

Mutual Match
+
Two-Way Chat Started

但这是建议指标口径。

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

---

第一百一十三章 首页 Analytics

建议事件：

home_banner_impression
home_banner_click

home_quick_entry_click

home_recommendation_impression
home_activity_click
home_service_location_click
home_content_click

---

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

例如：

counseling completed

以：

counseling_services.completed_at

为准。

不能只靠：

前端埋点。

---

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

原：

/me/status

增加：

localEligibilityStatus

例如：

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

---

第一百一十六章 App Routing 修订

启动路由建议：

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

---

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

例如：

婚恋反诈课堂

可以开放。

真正婚恋匹配：

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

---

第一百一十八章 Home API Capability

推荐后端返回：

capabilities

例如：

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

前端不要自行推测。

---

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

V1.1 新模块加入后：

更应该由：

CapabilityService

统一判断。

避免每个页面自己写：

if verified && approved...

---

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

Backend 增加：

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

---

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

虽然用户前台叫：

公益服务中心。

后端仍保持独立领域：

Appointment
Counseling
Content
ServiceLocation

不要全部塞进：

service/

一个巨型模块。

---

第一百二十二章 Miniapp Service API

增加：

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

---

第一百二十三章 Admin Modules

新增：

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

---

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

以下 POST 建议支持：

Idempotency-Key

包括：

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

---

第一百二十五章 Service Appointment 并发

同一预约被：

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

同时发生。

最终必须：

单一合法状态。

---

第一百二十六章 Counseling Assign 并发

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

必须：

原子更新。

---

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

API 内部可以叫：

counseling

前台主要使用：

婚恋咨询
公益婚恋指导

不要将服务包装成：

心理诊断。

---

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

建议：

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

GET /home

---

服务站 U50

GET /service-locations/{id}

---

服务预约 U51

POST /service-appointments

---

我的预约 U52

GET /service-appointments

---

婚恋课堂 U53

GET /content/articles

---

内容详情 U54

GET /content/articles/{id}

---

婚恋咨询 U55/U56/U57

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

---

婚前辅导 U58/U59

复用：

/counseling/services

参数：

serviceType = premarital_guidance

---

婚恋反诈 U60

复用：

/content/articles?category=anti_fraud

---

本地资格 U62/U63

/local-eligibility

---

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

Home Aggregate API：

建议：

P95 < 1.5s

作为技术目标。

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

---

第一百三十一章 Home Cache

可缓存：

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

不能盲目缓存：

用户Capability
用户推荐

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

---

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

Home API 不能自己写：

SELECT users ORDER BY created_at

必须调用：

RecommendationService。

---

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

可：

查询时按时间过滤。

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

保持简单。

---

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

仍然支持：

status

未来暂停服务：

可立即下线预约入口。

---

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

建议直接增加：

notice_text

或使用 Notification/Content。

V1.1 不需要独立：

service_location_notices

除非后续公告很多。

---

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

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

可以增加：

counseling_service_participants

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

简单方案：

primary_user_id
companion_user_id nullable
companion_confirmed_at

---

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

如果 companion_user_id 是平台用户：

必须：

对方确认。

---

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

Program管理员只能看到：

服务项目必要信息。

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

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

---

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

文章可以增加：

publisher_organization_id

例如：

乐活公益发布。

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

---

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

U64 公益服务记录建议由：

ServiceHistoryQueryService

聚合：

MatchmakerService
CounselingService
ActivityRegistration
ServiceAppointment

不新建：

user_service_history

重复保存所有业务。

---

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

GET /api/v1/me/service-history

返回统一结构：

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

---

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

V1.1 建议：

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

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

---

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

建议：

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)

---

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

user_local_eligibilities.user_id

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

Program：

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：

按数据保留政策处理。

---

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

需要写入：

PENDING_DECISIONS.md

包括：

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

不得代码硬编码。

---

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

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

---

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

必须增加：

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

红娘访问咨询记录 → 403

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

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

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

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

---

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

必须测试：

Banner按时间显示

Banner按用户状态显示

已过期Banner不显示

核心8入口顺序固定

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

Paused不返回新推荐

Successful不返回找对象推荐

Service Location停用时入口正确降级

---

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

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

同时验证：

无权限Operator不能访问

---

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

必须：

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

以及：

无需补充的规则场景

如果运营以后允许。

---

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

必须修订旧测试：

错误旧逻辑：

Activity mutual → Match

新逻辑：

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 增加

Local Eligibility基础字段与页面

但人脸核验具体 Provider：

保持 Pending。

---

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

预约
咨询
本地资格

通知。

---

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

公益咨询与婚前辅导

---

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

新增：

activity_type
registration_policy
行业专场
多组织关联

---

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

改成：

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

---

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

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

---

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

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

---

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

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

Phase 19A 公益内容与服务站

但不是必须。

仍可放 Phase 19。

---

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

建议：

banner.maxActiveCount

localEligibility.enabled
localEligibility.evidencePolicy

counseling.enabled
premarital.enabled

serviceLocation.enabled

content.enabled

activity.mutualConnectionConfirmationEnabled

---

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

以下功能：

已确认进入 V1.1。

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

所以不是：

PENDING_PRODUCT_SCOPE

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

---

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

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

---

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

新增后：

/home

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

/counseling/services

/content/categories
/content/articles

/local-eligibility

/service-programs

/operator/...

---

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

仍然：

单一 Modular Monolith Backend。

所有：

/api/v1

统一服务。

---

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

Content Module：

直接在主后台。

---

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

咨询人员：

登录同一 Web 后台。

根据权限看到：

公益咨询工作台。

---

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

服务站人员：

响应式 Web 后台。

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

---

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

最终建议确认如下：

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 最合理的增量范围。

---

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

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 将从原来的：

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

正式升级为：

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

同时仍然保持：

一个 PostgreSQL。

一个模块化单体后端。

一个微信小程序。

一个统一 Web 后台。

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

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