WenwuMap/3-architecture.md

中华文明全图鉴——技术架构文档

1. 架构目标

本项目第一阶段优先建设 PC Web 地图站 MVP，目标是在 PC 大屏上提供专业、美观、有探索趣味的文物地图体验，并配套机构/专家/编辑后台、后端 API、PostGIS 地理数据底座和可扩展的 AI/内容能力。

2. 架构原则

• PC Web 优先：第一阶段不做完整微信小程序，优先保证大屏地图、筛选、详情抽屉、图层和统计体验。
• 数据可信优先：所有文物、位置、标签、故事、数字资产均记录来源、审核状态和操作日志。
• PostGIS 优先：文物位置、模糊区域、地图范围查询、附近查询、路线查询统一基于 PostgreSQL + PostGIS。
• 前后端类型一致：优先采用 TypeScript 技术栈，减少接口字段漂移。
• 模块化演进：MVP 采用单体 API + 模块化目录，后续可拆分搜索、AI、内容、审核等服务。
• AI 后置增强：MVP 先预留 AI 接口与数据结构，AI 标签推荐、RAG、AIGC 在后续阶段逐步接入。
• 测试随阶段推进：每个阶段必须保留接口测试、数据测试、前端测试和文档更新记录。

3. 推荐技术栈

模块	技术选型	说明
PC Web 地图站	Next.js + React + TypeScript	面向公众的大屏地图、详情、搜索、筛选
管理后台	React + TypeScript + Ant Design	机构、文物、标签、位置、审核、日志管理
后端 API	NestJS + TypeScript	REST API、权限、业务服务、OpenAPI 文档
主数据库	PostgreSQL + PostGIS	结构化数据与地理数据统一存储
缓存	Redis	热点地图点位、会话、限流、异步任务状态
搜索	PostgreSQL 基础搜索，后续 OpenSearch	MVP 先用数据库搜索，数据增长后升级
向量检索	pgvector，后续 Milvus	AI/RAG 阶段启用
对象存储	本地 MinIO / 云 OSS / COS / S3	图片、音频、视频、3D 模型、资料附件
地图引擎	MapLibre GL JS	PC Web 大屏地图、图层、点位聚合、路线
队列	BullMQ + Redis	后续 AI 生成、导入、图片处理等异步任务
部署	Docker Compose，后续 Kubernetes	MVP 简化部署，中后期可扩展
监控	Sentry + OpenTelemetry + Prometheus/Grafana	前后端错误、接口耗时、服务健康

4. 推荐仓库结构

wenwumap/
  apps/
    web/                    # PC Web 地图站
    admin/                  # 管理后台
    api/                    # NestJS 后端 API
  packages/
    shared/                 # 共享类型、枚举、工具函数
    db/                     # 数据库 schema、migration、seed
    ui/                     # 可复用 UI 组件，后续抽取
  docs/                     # 后续补充的设计、接口、测试文档
  infra/
    docker-compose.yml      # 本地 PostgreSQL/PostGIS、Redis、MinIO
    nginx/                  # 反向代理配置，后续使用
  scripts/                  # 数据导入、校验、测试脚本
  0-中华文明全图鉴.md
  1-prd.md
  2-task.md
  3-architecture.md
  4-data-model.md
  5-api.md

5. 系统逻辑架构

┌───────────────────────────────────────────────┐
│                  用户访问层                    │
│  PC Web 地图站 / 管理后台 / 后续小程序           │
└──────────────────────┬────────────────────────┘
                       │ HTTPS REST API
┌──────────────────────▼────────────────────────┐
│                  API 服务层                    │
│ Auth / Artifact / Institution / Location / Tag │
│ Map / Asset / AuditLog / Search / Admin        │
└───────────────┬───────────────┬───────────────┘
                │               │
┌───────────────▼───────┐ ┌─────▼────────────────┐
│ PostgreSQL + PostGIS  │ │ Redis / Queue          │
│ 文物、机构、位置、标签 │ │ 缓存、限流、异步任务     │
└───────────────┬───────┘ └─────┬────────────────┘
                │               │
┌───────────────▼───────────────▼────────────────┐
│                 扩展能力层                      │
│ 对象存储 / 搜索 / pgvector / AI/RAG / 内容生成    │
└───────────────────────────────────────────────┘

6. 前端架构

6.1 PC Web 地图站

核心页面：

• 首页
• 地图页
• 文物详情页
• 机构详情页
• 搜索结果页
• 专题页占位

核心组件：

• 地图主画布
• 左侧筛选栏
• 右侧详情抽屉
• 顶部数据统计栏
• 图层控制面板
• 地图图例
• 文物卡片
• 机构卡片
• 文物故事钩子
• 数据来源与可信度标识

PC 端设计要求：

• 专业：信息层级、可信度、来源、审核状态清晰。
• 美观：东方色彩、文博纹样、克制质感、现代卡片。
• 趣味：点位 hover、聚合展开、故事短句、探索反馈、路线叙事。
• 克制：避免过度卡通化，不削弱文物信息可信度。

6.2 管理后台

后台模块：

• 登录与权限
• 仪表盘
• 机构管理
• 文物管理
• 位置管理
• 标签管理
• 数字资产管理
• 操作日志
• 批量导入
• 审核任务占位

7. 后端模块划分

模块	职责
AuthModule	登录、鉴权、角色权限、机构数据隔离
UserModule	用户、后台账号、角色绑定
InstitutionModule	机构信息、机构点位、机构文物列表
ArtifactModule	文物主数据、详情、状态、搜索筛选
LocationModule	文物位置、当前位置、历史位置、地图范围查询
TagModule	标签分类、标签定义、文物标签绑定
AssetModule	图片、文件、3D 模型等数字资产元数据
MapModule	地图点位、聚合、统计、图层数据
AuditLogModule	操作日志、关键字段变更记录
ImportModule	批量导入、数据校验、导入报告
HealthModule	服务健康检查

8. 数据流

8.1 PC 地图浏览数据流

用户打开地图页
  → Web 请求 /map/summary 获取顶部统计
  → Web 请求 /map/points?bbox&zoom&filters 获取地图点位
  → 用户点击点位
  → Web 请求 /artifacts/{id} 或 /institutions/{id}/artifacts
  → 右侧详情抽屉展示文物或机构信息

8.2 后台录入数据流

机构用户登录后台
  → 新增或编辑文物
  → 保存草稿
  → 录入位置、标签、图片
  → 提交发布
  → 系统校验字段和坐标
  → 写入操作日志
  → 前台地图可见

8.3 位置展示数据流

artifact_locations 保存多条位置记录
  → 后端根据 valid_until、verified_at、display_status 计算最新有效位置
  → 地图接口只返回当前用户权限可见的精度
  → 私密或敏感位置返回模糊区域

9. 权限模型

角色	权限范围
游客	浏览公开地图、文物详情、机构信息
注册用户	收藏、分享、纠错、后续海外线索提交
机构用户	管理本机构文物、位置、标签、资产
编辑	管理故事、角色卡、标签、内容模板
专家	审核海外线索、校验史实
运营	用户、贡献体系、专题、活动
管理员	全局管理、权限、审计、系统配置

MVP 优先实现：

• 管理员
• 机构用户
• 游客

10. 地图与地理策略

MVP 地图策略：

• 使用 MapLibre GL JS 承载 PC Web 地图交互。
• 后端通过 PostGIS 提供 bbox 范围查询。
• 低缩放级别返回聚合点或机构点。
• 高缩放级别返回具体文物点。
• 敏感位置返回模糊区域或城市级中心点。

后续增强：

• 矢量瓦片 MVT。
• H3/Geohash 预聚合。
• 南迁路线 LineString。
• 室内展厅平面图叠加。

11. 测试策略

阶段	测试类型	内容
阶段 0	文档测试	架构、数据模型、API 与 PRD/任务清单一致性检查
阶段 1	单元测试	后端 service、权限、数据校验、地图查询
阶段 1	接口测试	Auth、机构、文物、位置、标签、地图接口
阶段 1	数据测试	migration、seed、PostGIS 索引、范围查询
阶段 1	前端测试	地图加载、点位交互、筛选、详情抽屉
阶段 1	视觉验收	PC 专业美观、趣味交互、大屏适配
阶段 1	E2E 测试	管理后台录入文物后，PC 地图可展示

12. 阶段 0 当前结论

• 第一阶段不做完整小程序，优先 PC Web 地图站。
• MVP 后端采用 NestJS + PostgreSQL/PostGIS。
• MVP 搜索先用数据库能力，保留 OpenSearch 扩展点。
• MVP AI 能力先预留，不阻塞核心地图上线。
• 所有阶段完成后必须更新 2-task.md 状态，并记录测试结果。