WenwuMap/4-data-model.md

中华文明全图鉴——数据模型文档

1. 数据模型目标

本数据模型服务于第一阶段 PC Web 地图站 MVP，覆盖文物、机构、位置、标签、数字资产、权限、操作日志和地图查询所需的核心数据结构。

2. 设计原则

• PostgreSQL + PostGIS：结构化业务数据与地理数据统一存储。
• 多位置记录：一件文物可有多条位置记录，前台默认展示最新有效位置。
• 敏感坐标分级：同一位置可保存精确坐标和公开展示坐标或模糊区域。
• 标签可扩展：基础标签固定，扩展标签通过标签分类和标签类型支持动态扩展。
• 操作可追溯：核心对象修改必须记录操作日志。
• 字段可演进：对角色卡、故事、AI 推荐等中后期能力保留扩展空间。

3. 枚举定义

3.1 artifact_category

值	含义
bronze	青铜
painting_calligraphy	书画
porcelain	陶瓷
jade	玉器
gold_silver	金银器
lacquer	漆器
textile	织绣
stone_carving	石刻
wood_carving	木雕
dunhuang	敦煌
ancient_book	古籍
other	其他

3.2 artifact_level

值	含义
level_1	一级
level_2	二级
level_3	三级
general	一般
unknown	未定级

3.3 artifact_status

值	含义
at_home	在家
away	离家
in_transit	在途
unknown	未知

3.4 location_type

值	含义
domestic	国内
overseas	海外
unknown	未知
in_transit	在途

3.5 location_precision

值	含义
exact_room	展厅
exact_building	建筑
city	城市
country	国家
region	区域

3.6 display_status

值	含义
on_display	在展
in_storage	库藏
loaned	外借
repairing	修复中
touring	巡展中
unknown	未知

3.7 source_type

值	含义
institution_feed	机构直供
manual_entry	后台录入
user_report	用户报告
expert_verify	专家验证
public_source	公开资料

3.8 publish_status

值	含义
draft	草稿
pending	待发布
published	已发布
archived	已归档
rejected	已驳回

3.9 tag_value_type

值	含义
single	单选
multiple	多选
boolean	布尔
text	文本
number	数字

4. 核心表设计

4.1 users

后台账号和前台用户统一存储，MVP 优先支持后台账号。

字段	类型	约束	说明
id	uuid	pk	用户 ID
username	varchar(100)	unique	登录名
phone	varchar(30)	nullable	手机号
email	varchar(255)	nullable	邮箱
password_hash	varchar(255)	nullable	密码 hash
nickname	varchar(100)	nullable	昵称
avatar_url	text	nullable	头像
user_type	varchar(30)	not null	admin、institution、public、expert、editor
institution_id	uuid	fk nullable	绑定机构
is_active	boolean	default true	是否启用
created_at	timestamptz	not null	创建时间
updated_at	timestamptz	not null	更新时间

4.2 roles

字段	类型	约束	说明
id	uuid	pk	角色 ID
code	varchar(50)	unique	角色编码
name	varchar(100)	not null	角色名称
description	text	nullable	描述
created_at	timestamptz	not null	创建时间

4.3 permissions

字段	类型	约束	说明
id	uuid	pk	权限 ID
code	varchar(100)	unique	权限编码
name	varchar(100)	not null	权限名称
module	varchar(50)	not null	模块
created_at	timestamptz	not null	创建时间

4.4 user_roles

字段	类型	约束	说明
user_id	uuid	pk fk	用户 ID
role_id	uuid	pk fk	角色 ID
created_at	timestamptz	not null	创建时间

4.5 institutions

字段	类型	约束	说明
id	uuid	pk	机构 ID
name	varchar(255)	not null	机构名称
short_name	varchar(100)	nullable	简称
code	varchar(100)	unique nullable	机构编码
institution_type	varchar(50)	not null	museum、research、private、other
country	varchar(100)	not null	国家
province	varchar(100)	nullable	省份
city	varchar(100)	nullable	城市
address	text	nullable	地址
location	geography(Point, 4326)	nullable	机构坐标
official_website	text	nullable	官网
description	text	nullable	简介
is_verified	boolean	default false	是否认证
publish_status	publish_status	not null	发布状态
created_at	timestamptz	not null	创建时间
updated_at	timestamptz	not null	更新时间

索引：

• idx_institutions_location_gist：GIST(location)
• idx_institutions_name：name
• idx_institutions_country_city：country, city

4.6 artifacts

字段	类型	约束	说明
id	uuid	pk	文物 ID
unified_map_id	varchar(50)	unique	全图唯一编码
name	varchar(255)	not null	文物名称
alternative_names	text[]	nullable	别名
category	artifact_category	not null	门类
dynasty	varchar(100)	nullable	年代
level	artifact_level	default unknown	文物级别
material	varchar(255)	nullable	材质
dimensions	varchar(255)	nullable	尺寸
current_status	artifact_status	default unknown	在家、离家、在途、未知
home_institution_id	uuid	fk nullable	原属或现属国内机构
summary	text	nullable	简介
story_hook	varchar(255)	nullable	一句话故事钩子
persona_quote	varchar(255)	nullable	趣味化角色短句
publish_status	publish_status	not null	发布状态
created_by	uuid	fk nullable	创建人
updated_by	uuid	fk nullable	更新人
created_at	timestamptz	not null	创建时间
updated_at	timestamptz	not null	更新时间

索引：

• idx_artifacts_name：name
• idx_artifacts_category：category
• idx_artifacts_dynasty：dynasty
• idx_artifacts_status：current_status
• idx_artifacts_home_institution：home_institution_id

4.7 artifact_locations

字段	类型	约束	说明
id	uuid	pk	位置记录 ID
artifact_id	uuid	fk not null	文物 ID
location_type	location_type	not null	国内、海外、未知、在途
institution_id	uuid	fk nullable	关联机构
precise_location	geography(Point, 4326)	nullable	精确坐标
public_location	geography(Point, 4326)	nullable	前台可展示坐标
fuzzy_area	geography(Polygon, 4326)	nullable	模糊区域
precision	location_precision	not null	坐标精度
floor_plan_ref	varchar(255)	nullable	展厅平面图编号
room_name	varchar(255)	nullable	展厅名称
cabinet_no	varchar(100)	nullable	展柜编号
display_status	display_status	default unknown	展出状态
source_type	source_type	not null	来源类型
source_description	text	nullable	来源说明
discoverer_user_id	uuid	fk nullable	发现者
is_current	boolean	default false	是否当前有效位置
verified_at	timestamptz	nullable	审核通过时间
valid_from	timestamptz	nullable	有效开始
valid_until	timestamptz	nullable	有效截止
created_by	uuid	fk nullable	创建人
created_at	timestamptz	not null	创建时间
updated_at	timestamptz	not null	更新时间

索引：

• idx_artifact_locations_artifact_id：artifact_id
• idx_artifact_locations_institution_id：institution_id
• idx_artifact_locations_public_location_gist：GIST(public_location)
• idx_artifact_locations_precise_location_gist：GIST(precise_location)
• idx_artifact_locations_fuzzy_area_gist：GIST(fuzzy_area)
• idx_artifact_locations_current：artifact_id, is_current

当前位置规则：

1. 优先取 is_current = true 的位置记录。
2. 若存在多条，则取 verified_at 最新的一条。
3. 若 valid_until 已过期，则不作为前台当前位置展示。
4. 无权限用户只能读取 public_location 或 fuzzy_area。

4.8 tag_categories

字段	类型	约束	说明
id	uuid	pk	标签分类 ID
code	varchar(100)	unique	分类编码
name	varchar(100)	not null	分类名称
description	text	nullable	描述
sort_order	int	default 0	排序
is_system	boolean	default false	是否系统内置
created_at	timestamptz	not null	创建时间

4.9 tags

字段	类型	约束	说明
id	uuid	pk	标签 ID
category_id	uuid	fk not null	分类 ID
code	varchar(100)	unique	标签编码
name	varchar(100)	not null	展示名
value_type	tag_value_type	not null	值类型
description	text	nullable	描述
color	varchar(20)	nullable	展示颜色
icon	varchar(100)	nullable	图标
is_system	boolean	default false	是否系统标签
is_active	boolean	default true	是否启用
sort_order	int	default 0	排序
created_at	timestamptz	not null	创建时间
updated_at	timestamptz	not null	更新时间

4.10 artifact_tags

字段	类型	约束	说明
id	uuid	pk	关系 ID
artifact_id	uuid	fk not null	文物 ID
tag_id	uuid	fk not null	标签 ID
value_text	text	nullable	文本值
value_number	numeric	nullable	数字值
confidence	numeric(5,2)	nullable	置信度
source_type	source_type	not null	来源
review_status	varchar(30)	default approved	pending、approved、rejected
created_by	uuid	fk nullable	创建人
created_at	timestamptz	not null	创建时间

唯一约束：

• artifact_id, tag_id, value_text

4.11 digital_assets

字段	类型	约束	说明
id	uuid	pk	资产 ID
artifact_id	uuid	fk nullable	文物 ID
institution_id	uuid	fk nullable	机构 ID
asset_type	varchar(50)	not null	image、audio、video、model_3d、document
title	varchar(255)	nullable	标题
url	text	not null	资源地址
thumbnail_url	text	nullable	缩略图
mime_type	varchar(100)	nullable	MIME 类型
size_bytes	bigint	nullable	文件大小
copyright_owner	varchar(255)	nullable	版权方
license_scope	text	nullable	授权范围
sort_order	int	default 0	排序
created_by	uuid	fk nullable	上传人
created_at	timestamptz	not null	创建时间

4.12 operation_logs

字段	类型	约束	说明
id	uuid	pk	日志 ID
operator_id	uuid	fk nullable	操作人
operator_role	varchar(50)	nullable	操作角色
action	varchar(100)	not null	操作类型
target_type	varchar(100)	not null	目标类型
target_id	uuid	nullable	目标 ID
before_data	jsonb	nullable	变更前
after_data	jsonb	nullable	变更后
ip_address	varchar(50)	nullable	IP
user_agent	text	nullable	UA
created_at	timestamptz	not null	创建时间

索引：

• idx_operation_logs_operator_id
• idx_operation_logs_target
• idx_operation_logs_created_at

5. 地图接口视图建议

5.1 artifact_current_locations_view

用途：地图点位与文物详情快速读取。

字段：

• artifact_id
• artifact_name
• category
• dynasty
• level
• current_status
• story_hook
• persona_quote
• institution_id
• institution_name
• public_location
• fuzzy_area
• precision
• display_status
• source_type
• verified_at

5.2 map_summary_view

用途：顶部统计栏。

字段：

• total_artifacts
• domestic_count
• overseas_count
• on_display_count
• in_storage_count
• loaned_count
• unknown_location_count

6. Seed 数据建议

6.1 系统角色

• admin
• institution_user
• editor
• expert
• public_user

6.2 标签分类

• basic_attribute
• circulation_experience
• emotional_attribute
• content_derivation

6.3 基础标签

• 门类
• 年代
• 级别
• 材质
• 功能
• 流失状态
• 回归状态
• 南迁北归
• 修复经历
• 数字化经历
• 情绪主调
• 适合年龄

7. 数据校验规则

7.1 文物校验

• name 必填。
• category 必须在枚举范围内。
• unified_map_id 必须唯一。
• current_status 必须在枚举范围内。
• 发布时至少需要一条当前有效位置或明确标记为未知位置。

7.2 位置校验

• location_type = domestic 时优先要求 institution_id。
• precision = exact_room 时需要 room_name 或 floor_plan_ref。
• 公开坐标必须符合经纬度范围。
• 存在敏感位置时，前台不得返回 precise_location。
• valid_until 小于当前时间时不作为当前有效位置。

7.3 标签校验

• 系统标签不可随意删除。
• 禁用标签不允许新增绑定。
• AI 推荐标签必须人工确认后才能公开展示。

8. 测试要点

• migration 可从空库完整执行。
• PostGIS 扩展可启用。
• 空间索引创建成功。
• 1000 件文物点位范围查询响应时间符合要求。
• 敏感坐标在游客权限下不可见。
• 机构用户无法访问其他机构文物。
• 文物标签绑定、解绑和筛选结果正确。