# “善缘丹阳”公益婚恋服务平台 # 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。 --- # 第一百五十七章 WorkBuddy 开发计划影响 原 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 新增公益服务而引入不必要的微服务、工作流引擎、社区系统或大数据架构。 这使“善缘丹阳”既能完整承接最新项目计划书要求的线上线下一体化公益服务，又能保持开发、部署和后期维护成本可控。