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. 推荐仓库结构

```txt
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. 系统逻辑架构

```txt
┌───────────────────────────────────────────────┐
│                  用户访问层                    │
│  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 地图浏览数据流

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

## 8.2 后台录入数据流

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

## 8.3 位置展示数据流

```txt
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` 状态，并记录测试结果。