admin/lehuo

Template

Fork 0

Files

T

admin f3737c80be feat(old-items): complete reuse workflow and refine miniapp home

2026-08-15 16:38:30 +08:00

14 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 直接上线。
删除列采用“停用 → 迁移 → 验证 → 后续版本删除”。

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：只追加积分流水，记录获得/人工校正、变更值、变更后余额、来源捐赠/规则版本、幂等指纹、加密原因和操作人；来源捐赠唯一，防止重复计分。

捐赠完成、证书签发、积分账户更新、积分流水和审计在同一事务提交。积分没有货币价值，不建立兑换订单、商品、转让、提现、到期或排行榜数据结构。

14 KiB Raw Blame History Unescape Escape