# 04 数据模型 ## 1. 通用字段规范 核心表统一包含： - id: bigint/uuid（二选一后固定；建议 bigint 内部主键 + public_id 随机ID） - public_id: varchar，外部暴露，禁止连续可枚举 - created_at - updated_at - created_by（后台业务表适用） - updated_by - deleted_at（需要软删除的表） 时间统一数据库 UTC 存储，展示按 Asia/Shanghai。 --- ## 2. 核心实体 ### users 微信/后台统一用户主体，避免重复身份系统。 - id - public_id - status - user_type - mobile（加密/脱敏策略） - nickname - avatar_url - last_login_at ### wechat_identities - user_id - openid_ciphertext（AES-256-GCM） - openid_hash（HMAC-SHA-256，仅用于等值查询） - unionid_ciphertext nullable - unionid_hash nullable - appid - created_at 唯一索引 `(appid, openid_hash)`；日志和 API 均不得返回 openid/unionid。 ### staff_profiles - user_id - employee_no nullable - display_name - department - status 工作人员显示名不是服务对象敏感档案字段；严禁把其扩展为手机号、证件号或详细住址。服务对象称呼仍按下文要求加密。 ### roles / permissions / user_roles / role_permissions 标准 RBAC。Phase 1 预置 `VOLUNTEER`、`STAFF`、`PROJECT_MANAGER`、`ADMIN`、 `SUPER_ADMIN`，权限码由 shared contracts 统一定义。角色替换必须在事务中写审计，并禁止移除最后一名有效超级管理员。 ### admin_credentials - user_id（唯一） - username（唯一） - password_hash（Argon2id） - failed_login_count - locked_until nullable - password_changed_at ### auth_sessions - public_id（随机 UUID） - user_id - channel（WECHAT/ADMIN） - token_hash（仅保存带 pepper 的 HMAC，不保存明文 token） - expires_at - last_used_at nullable - revoked_at nullable 同一用户、同一渠道重新登录时撤销旧会话；过期、撤销或非 ACTIVE 用户的会话均无效。 --- ## 3. beneficiary_profiles 服务对象档案： - id - public_id - display_name_encrypted / display_name_hash - gender nullable - birth_year nullable - mobile_encrypted / mobile_hash nullable - region_code - address_detail_encrypted nullable - primary_category - key_care_flag - is_minor - status - notes_encrypted nullable - created_by - timestamps 不要默认收集完整身份证。 --- ## 4. beneficiary_contacts - beneficiary_id - public_id - name_encrypted - relation - mobile_encrypted / mobile_hash - is_guardian - is_emergency_contact - consent_record_id nullable --- ## 5. beneficiary_tags / tags 标签： - 独居 - 高龄 - 行动不便 - 定期探访 - 困境儿童 等。 标签只能帮助服务，不应成为歧视性画像。 --- ## 6. service_applications - id - public_id（随机 UUID，仅此字段对外暴露） - application_no（随机业务编号） - applicant_user_id - beneficiary_id nullable - consent_id - source_follow_up_task_id nullable（继续帮扶来源，唯一） - parent_application_id nullable（原申请） - client_request_id - request_fingerprint（域隔离 HMAC-SHA-256） - apply_mode - service_category - beneficiary_name_encrypted（AES-256-GCM） - contact_mobile_encrypted（AES-256-GCM） - contact_mobile_hash（域隔离 HMAC-SHA-256，仅用于等值查询） - region_code - description_encrypted（AES-256-GCM） - preferred_contact_time nullable - needs_home_visit nullable - mobility_difficulty nullable - status - source - submitted_at - accepted_at nullable - closed_at nullable - timestamps 首次申请在 Phase 2 创建时不自动建立 beneficiary 档案；Phase 3 经人工核验后关联。Phase 4 的继续帮扶申请保留 `parent_application_id` 和 `source_follow_up_task_id`，并创建新的独立 consent，不修改或复用原申请授权。 索引： - application_no unique - `(applicant_user_id, client_request_id)` unique，保证数据库级幂等 - applicant_user_id + submitted_at - status + submitted_at - service_category + submitted_at - contact_mobile_hash --- ## 7. service_application_status_history - application_id - from_status - to_status - operator_user_id - reason_code - created_at 不可更新，只追加。 --- ## 8. service_cases - id - public_id - case_no - application_id - accept_request_id / accept_request_fingerprint（接单幂等） - beneficiary_id - owner_staff_id - category - priority - status - planned_start_at nullable - planned_end_at nullable - service_location_encrypted nullable - summary_encrypted - result_summary_encrypted nullable - follow_up_plan_encrypted nullable - completed_at nullable - complete_request_id / complete_request_fingerprint nullable（完成服务幂等） - timestamps --- ## 9. case_assignees 支持多人协作： - case_id - user_id - assignee_type STAFF/VOLUNTEER - role - assigned_at - removed_at nullable --- ## 10. service_records - id - public_id - case_id - beneficiary_id - service_start_at - service_end_at nullable - service_type - client_request_id / request_fingerprint（同一创建者范围内幂等） - content_encrypted - result_encrypted - follow_up_suggestion_encrypted nullable - beneficiary_confirm_status nullable - created_by - timestamps `service_record_revisions` 在修改前保存加密快照、原 revision 和修改人；更新使用 `expectedRevision` 乐观锁，防止覆盖并支持审计追溯。 --- ## 11. follow_up_tasks - id - public_id / follow_up_no（均不可预测） - beneficiary_id - case_id nullable - owner_staff_id - due_at - follow_up_type（SERVICE_COMPLETION / KEY_CARE / MANUAL） - status（PENDING / COMPLETED / CANCELLED） - source（AUTO_SERVICE_COMPLETION / STAFF_MANUAL / KEY_CARE_PLAN） - reason_encrypted - result_code nullable - result_note_encrypted nullable - create_request_id / create_request_fingerprint - complete_request_id / complete_request_fingerprint nullable - completed_at nullable - created_by / updated_by / timestamps 自动回访与服务完成在同一事务创建。人工回访以 `(created_by, create_request_id)` 唯一；完成请求保存指纹并安全重放。 ## 12. follow_up_status_history - follow_up_task_id - from_status nullable - to_status - operator_user_id - reason_code - created_at 只追加，不更新。继续帮扶申请通过 `service_applications.source_follow_up_task_id` 回指来源，原申请历史不覆盖。 --- ## 13. volunteers / volunteer_skills volunteers： - user_id - real_name - mobile - region_code - availability_note - status - approved_by nullable - approved_at nullable skills： - volunteer_id - skill_code --- ## 14. projects - id - public_id - project_no - client_request_id / request_fingerprint - name - category - summary - content - cover_file_id - manager_user_id - start_date - end_date - target_people nullable - status - is_public - sort_order - timestamps `(created_by_id, client_request_id)` 唯一；`project_status_history` 只追加记录创建、发布和完成。`service_cases.project_id` 可空，用于把既有工单归集到项目但不改变工单事实。 --- ## 15. activities - id - public_id - activity_no - client_request_id / request_fingerprint - project_id nullable - title - summary - content - cover_file_id - start_at - end_at - registration_deadline - location_text - capacity nullable - status - published_at nullable - timestamps `(created_by_id, client_request_id)` 唯一；`activity_status_history` 只追加记录活动状态变化。 --- ## 16. activity_registrations - activity_id - user_id - volunteer_id - public_id / client_request_id / request_fingerprint - status - check_in_status - registered_at - reviewed_by / reviewed_at / review_note_encrypted nullable - checked_in_at nullable - checked_in_by nullable - service_minutes nullable - service_minutes_recorded_at / service_minutes_recorded_by nullable 唯一 `(activity_id,user_id)` 防重复报名。 `activity_registration_history` 只追加保存报名审核、取消、签到和服务时长变更前后事实，并以全局请求 UUID 唯一约束支持安全重放。 志愿者资料的姓名、手机号、可参与时间和审核备注加密；手机号与姓名仅保存域隔离 HMAC 查询值。`volunteer_status_history` 只追加，并与志愿者角色授予/撤销事务一致。 --- ## 17. content_posts - id - public_id - type - title - summary - content - cover_file_id nullable - status DRAFT/REVIEW/PUBLISHED/ARCHIVED - author_user_id - reviewer_user_id nullable - published_at nullable - timestamps --- ## 18. files 只保存元数据： - id - public_id - storage_provider - bucket - object_key - original_filename_encrypted - mime_type - size - sha256 - business_type - uploader_user_id - status - created_at `service_record_files` 关联服务记录与已确认文件。对象 key 使用随机值，上传确认时复核大小、MIME 和可选 SHA-256；不匹配文件进入隔离状态。 Phase 5 允许 `files.case_id` 为空，并通过 `business_type=PROJECT_COVER/ACTIVITY_COVER` 关联公开封面；封面仍经同一私有对象存储 Adapter 生成短时读取地址，不保存永久公网 URL。 前端不得直接拼接永久公网 URL。 --- ## 19. consents - id - public_id - user_id nullable - beneficiary_id nullable - consent_type - version - granted_by - granted_at - revoked_at nullable - evidence_json（仅保存必要证明） - ip_hash nullable - created_at Phase 2 每次申请显式要求 `privacyConsent=true`，记录隐私同意版本、授权主体、授权时间、最小证据和 IP HMAC；不得在证据中重复保存申请敏感明文。 --- ## 20. audit_logs 只追加： - id - request_id - actor_user_id - actor_role - action - resource_type - resource_public_id - result - metadata_json（不得含敏感明文） - ip_hash - user_agent_summary - created_at --- ## 21. notifications / notification_deliveries 通知实体与发送记录分开，支持重试和追踪。 Phase 6 已落地 `content_posts`、只追加的 `content_post_status_history`、`notifications`、`notification_preferences` 和 `notification_deliveries`。消息以 `(user_id,event_key)` 唯一防重，微信投递以 `(notification_id,channel)` 唯一，失败最多重试五次后进入 `DEAD`。 Phase 7 不建立可人工修改的统计快照；九项 V1 指标直接从申请、工单、服务记录、服务对象、志愿者、活动和报名服务分钟事实计算。 --- ## 22. 数据库规则 1. 必须使用 FK 或由 ORM/服务保证等价完整性；禁止无约束“凭感觉关联”。 2. 唯一业务编号必须 unique。 3. 常查字段建组合索引。 4. 禁止对大文本字段滥建索引。 5. 金额如未来出现用 decimal，禁止 float。 6. 所有枚举在 contracts 中有单一事实来源。 7. migration 不允许 destructive change 直接上线。 8. 删除列采用“停用 → 迁移 → 验证 → 后续版本删除”。 --- ## 23. financial_disclosures - id / public_id（随机 UUID） - client_request_id / request_fingerprint（创建幂等） - title / summary nullable - rich_text（后端白名单清洗后的富文本） - status：DRAFT / PUBLISHED / ARCHIVED - is_pinned / sort_order / revision - published_at nullable - created_by / updated_by / timestamps `financial_disclosure_status_history` 只追加保存创建、发布和归档事实，请求 UUID 全局唯一。已发布文档禁止覆盖编辑，只能归档；草稿编辑使用 revision 乐观锁。 --- ## 24. 旧物善用 Phase 1 - `old_item_donations`：随机 `public_id`、非连续公益编号、捐赠人、幂等键、品类、新旧程度、数量、方式、状态、revision、定向需求、投递点、人工分配人员和真实帮扶人数。 - `old_item_donation_status_history`：只追加保存初始提交和每次状态变化，`request_id` 全局唯一。 - `old_item_donation_files`：关联最多六张已确认的 `OLD_ITEM_DONATION_IMAGE` 私有文件。 - `old_item_needs`：随机公开 ID、品类、区域、受助群体、需求量、已满足量、优先级、排序、发布状态和 revision。 - `old_item_need_status_history`：只追加保存需求发布与下架事实。 - `old_item_drop_off_points`：后台维护的公开投递名称、区域、地址、开放时间、启停和排序。 联系人、手机号、上门取件地址、物品描述、驳回原因和内部轨迹备注加密保存；手机号另存域隔离 HMAC。列表不公开敏感明文，管理端详情读取写审计。全部外键使用 `RESTRICT`，公开资源不暴露自增主键。 --- ## 25. 旧物善用 Phase 2 物资台账 - `old_item_inventory_imports`：记录随机公开 ID、创建人幂等键、请求指纹、加密原文件名和导入行数；不保存原 Excel 文件。 - `old_item_inventory_items`：随机公开 ID、非连续台账编号、可选来源捐赠/导入批次、品类、名称、数量、单位、仓位、状态、定向需求、可选受助对象、帮扶区域、加密备注、落地时间和 revision。每个来源捐赠最多绑定一个物资批次，避免重复入库。 - `old_item_inventory_events`：只追加保存入库、分拣、消毒、出库、落地节点，请求 UUID 全局唯一，记录前后状态、时间、位置、加密备注和操作人。 台账状态严格为 `IN_STOCK → SORTED → DISINFECTED → OUTBOUND → DELIVERED`，不允许跳级、回退或覆盖事件。Excel 批量入库在一个事务中创建导入批次、所有物资行、入库事件和审计，任一行无效时整批回滚。受助对象只保存既有内部外键；小程序仅返回流转状态、时间和出库/落地的粗粒度地区。 --- ## 26. 旧物善用 Phase 3 荣誉证书与积分 - `old_item_reward_configs`：不可变规则版本，保存证书标题/正文/颁发方/法律声明、四类物资每件积分、单笔积分上限和当前激活标识；新版本不覆盖历史版本。 - `old_item_certificates`：随机公开 ID、非连续证书编号、来源捐赠、规则版本、加密收件人称呼、完整模板快照、签发/撤销幂等指纹、签发与撤销操作者及时间。每笔捐赠最多一张当前有效证书，补发会撤销旧证书但不删除历史。 - `old_item_point_accounts`：每个用户一个荣誉积分账户，保存余额和 revision；余额不得小于零。 - `old_item_point_entries`：只追加积分流水，记录获得/人工校正、变更值、变更后余额、来源捐赠/规则版本、幂等指纹、加密原因和操作人；来源捐赠唯一，防止重复计分。 捐赠完成、证书签发、积分账户更新、积分流水和审计在同一事务提交。积分没有货币价值，不建立兑换订单、商品、转让、提现、到期或排行榜数据结构。