admin/lehuo

Template

Fork 0

Files

T

admin c3dd9be674 feat: complete V1 phases 0-7

2026-08-12 14:35:12 +08:00

11 KiB

Raw Blame History

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. 数据库规则

必须使用 FK 或由 ORM/服务保证等价完整性；禁止无约束“凭感觉关联”。
唯一业务编号必须 unique。
常查字段建组合索引。
禁止对大文本字段滥建索引。
金额如未来出现用 decimal，禁止 float。
所有枚举在 contracts 中有单一事实来源。
migration 不允许 destructive change 直接上线。
删除列采用“停用 → 迁移 → 验证 → 后续版本删除”。

11 KiB Raw Blame History Unescape Escape