chore: 初始化仓库

中华文明全图鉴——文物全图系统（PC Web 地图 + NestJS API + 管理后台）。
含三大 IP（文物南迁北归 / 国宝海外回归 / 博物馆手艺人）、AI 文物对话、
文物地图与详情、以及 demo-video-kit 演示视频生成工具。

4-data-model.md

@@ -0,0 +1,458 @@
+# 中华文明全图鉴——数据模型文档
+
+## 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 件文物点位范围查询响应时间符合要求。
+- 敏感坐标在游客权限下不可见。
+- 机构用户无法访问其他机构文物。
+- 文物标签绑定、解绑和筛选结果正确。