chore: 初始化仓库

中华文明全图鉴——文物全图系统（PC Web 地图 + NestJS API + 管理后台）。含三大 IP（文物南迁北归 / 国宝海外回归 / 博物馆手艺人）、AI 文物对话、文物地图与详情、以及 demo-video-kit 演示视频生成工具。
2026-06-13 20:55:44 +08:00
commit 2d847e154f
161 changed files with 22629 additions and 0 deletions
@@ -0,0 +1,196 @@
+# 中华文明全图鉴——阶段进度与测试记录
+
+## 1. 记录说明
+
+本文档用于记录每个阶段的实际完成内容、测试结果、文档更新和后续问题。后续每完成一个阶段或关键模块，都需要同步更新本文档与 `2-task.md`。
+
+## 2. 状态说明
+
+| 状态 | 含义 |
+|---|---|
+| 未开始 | 尚未执行 |
+| 进行中 | 已开始但未完成 |
+| 已完成 | 已完成并通过当前阶段测试 |
+| 阻塞 | 依赖外部信息或资源，暂不能继续 |
+
+---
+
+# 阶段 0：项目启动与基础准备
+
+## 0.1 当前进度
+
+| 模块 | 状态 | 说明 |
+|---|---|---|
+| 详细方案 | 已完成 | 已有 `0-中华文明全图鉴.md` |
+| PRD | 已完成 | 已有 `1-prd.md`，并调整为 PC Web 优先 |
+| 任务拆解 | 已完成 | 已有 `2-task.md`，并补充 PC 端专业美观与趣味性任务 |
+| 技术架构文档 | 已完成 | 已创建 `3-architecture.md` |
+| 数据模型文档 | 已完成 | 已创建 `4-data-model.md` |
+| API 设计文档 | 已完成 | 已创建 `5-api.md` |
+| 协作工具准备 | 未开始 | 需要确认代码仓库、Issue、任务看板等 |
+| 合规与授权准备 | 未开始 | 需要确认机构授权、地图合规、图片授权等 |
+
+## 0.2 本阶段已完成文档
+
+- `0-中华文明全图鉴.md`
+- `1-prd.md`
+- `2-task.md`
+- `3-architecture.md`
+- `4-data-model.md`
+- `5-api.md`
+- `11-progress-log.md`
+
+## 0.3 本阶段测试记录
+
+| 测试项 | 测试方式 | 结果 | 说明 |
+|---|---|---|---|
+| 文档存在性检查 | 检查阶段 0 P0 文档是否存在 | 通过 | 已检查 7 个核心文档 |
+| 文档关键词检查 | 检查 PC Web、PostGIS、API、数据模型等关键词 | 通过 | 已覆盖 PC Web、PostGIS、API、数据模型、测试记录等关键词 |
+| 任务状态一致性检查 | 检查 `2-task.md` 与已创建文档是否一致 | 通过 | `3-architecture.md`、`4-data-model.md`、`5-api.md`、`11-progress-log.md` 已在任务清单中标记完成 |
+
+测试命令：
+
+```bash
+python3 - <<'PY'
+from pathlib import Path
+root = Path('/Users/freedak/Documents/AIDashboard/wenwumap')
+required = {
+    '0-中华文明全图鉴.md': ['中华文明'],
+    '1-prd.md': ['PC Web', '专业美观', '趣味'],
+    '2-task.md': ['3-architecture.md', '11-progress-log.md', 'PC Web'],
+    '3-architecture.md': ['Next.js', 'NestJS', 'PostGIS', '测试策略'],
+    '4-data-model.md': ['artifacts', 'artifact_locations', 'PostGIS', 'operation_logs'],
+    '5-api.md': ['/api/v1', 'Map API', 'Artifact API', '权限矩阵'],
+    '11-progress-log.md': ['阶段 0', '测试记录', '下一步'],
+}
+failed = []
+for name, keywords in required.items():
+    path = root / name
+    if not path.exists():
+        failed.append(f'缺失文件: {name}')
+        continue
+    text = path.read_text(encoding='utf-8')
+    for keyword in keywords:
+        if keyword not in text:
+            failed.append(f'{name} 缺少关键词: {keyword}')
+if failed:
+    print('FAILED')
+    for item in failed:
+        print('-', item)
+    raise SystemExit(1)
+print('PASSED')
+print(f'checked_files={len(required)}')
+PY
+```
+
+测试输出：
+
+```txt
+PASSED
+checked_files=7
+```
+
+## 0.4 阻塞项
+
+- 项目负责人、产品负责人、技术负责人、设计负责人、内容负责人、数据负责人尚未由用户确认。
+- 代码仓库地址尚未确认。
+- 第一批合作机构与种子文物范围尚未确认。
+- 地图服务合规方案尚未最终确认。
+
+## 0.5 下一步
+
+- 更新 `2-task.md` 阶段 0 文档任务状态。
+- 执行阶段 0 文档一致性测试。
+- 开始阶段 1 工程初始化前的技术选型确认。
+- 根据确认结果初始化代码仓库结构和基础工程。
+
+---
+
+# 阶段 1：MVP 国内文物地图
+
+## 1.1 当前进度
+
+| 模块 | 状态 | 说明 |
+|---|---|---|
+| 技术选型 | 进行中 | 已在 `3-architecture.md` 中给出建议，地图服务商、对象存储待确认 |
+| 数据模型 | 已完成 | `4-data-model.md` 设计完成，`001_init.sql` migration 已编写 |
+| API 设计 | 已完成 | `5-api.md` 第一版完成，待转为 OpenAPI/Swagger |
+| Monorepo 工程骨架 | 已完成 | pnpm workspace + `apps/web`、`apps/admin`、`apps/api`、`packages/shared`、`packages/db` 均已创建 |
+| 共享类型包 | 已完成 | `packages/shared` 包含所有枚举和 TS 类型定义 |
+| 数据库 migration | 已完成 | `001_init.sql` 包含 PostGIS、全表结构、枚举、索引 |
+| 数据库 seed | 已完成 | 角色、标签类别、测试机构、测试文物、测试位置 seed 已编写 |
+| 本地基础设施 | 已准备 | `infra/docker-compose.yml` 包含 PostgreSQL+PostGIS、Redis、MinIO |
+| PC Web 地图站 | 骨架已就位 | `apps/web` 占位页已建立，地图引擎集成待地图 Key 确认后开展 |
+| 管理后台 | 骨架已就位 | `apps/admin` 占位页已建立 |
+| 后端 API | 骨架已就位 | `apps/api` NestJS 入口 + 健康检查接口已就位 |
+
+## 1.2 本次进度测试记录
+
+| 测试项 | 测试方式 | 结果 | 说明 |
+|---|---|---|---|
+| 工程结构校验 | `scripts/check-structure.py` | 通过 | 49 个文件全部存在 |
+| 文档关键词校验 | `scripts/check-structure.py` | 通过 | 19 项关键词均满足 |
+| SQL 结构检查 | 肥眼核查 migration | 通过 | PostGIS/枚举/全表/索引均存在 |
+| 共享类型包检查 | 肥眼核查 enums/types | 通过 | 全枚举、全类型均已定义 |
+| TS 类型误误 | IDE 反馈 | 预安装错误 | 全部为未执行 `pnpm install` 导致，安装依赖后自动消除 |
+
+测试命令：
+
+```bash
+python3 scripts/check-structure.py
+```
+
+测试输出：
+
+```txt
+PASSED — 共检查 49 个文件，所有关键词验证通过
+```
+
+## 1.2 阶段 1 测试要求
+
+- 工程初始化后必须能执行 lint。
+- 数据库 migration 必须能从空库完整执行。
+- seed 必须能生成基础角色、标签、机构、文物和位置测试数据。
+- 后端必须提供健康检查接口。
+- PC Web 必须能打开地图页并展示测试点位。
+- 管理后台必须能登录并查看基础列表页。
+
+## 1.3 后端 API 开发记录
+
+### 本次完成内容
+
+| 模块 | 文件 | 状态 |
+|---|---|---|
+| DatabaseModule | `apps/api/src/database/` | ✅ |
+| AuthModule | `apps/api/src/auth/` | ✅ |
+| MapModule | `apps/api/src/map/` | ✅ |
+| ArtifactsModule | `apps/api/src/artifacts/` | ✅ |
+| InstitutionsModule | `apps/api/src/institutions/` | ✅ |
+| 工程规范 | `.prettierrc`、`commitlint.config.js` | ✅ |
+
+### 接口验证（本地数据库 PostgreSQL 16 + PostGIS 3.4.4）
+
+```txt
+GET /api/v1/health          → {"status":"ok","service":"wenwumap-api"}
+GET /api/v1/map/stats       → {"total_artifacts":3,"total_institutions":3,"total_locations":3}
+GET /api/v1/map/points      → 3 个文物点位（含经纬度、机构名、故事钩子）
+GET /api/v1/artifacts       → {"total":3, data:[千里江山图,清明上河图,司母戊鼎]}
+GET /api/v1/institutions    → {"total":3, data:[故宫,国博,上博]}
+POST /api/v1/auth/login     → 待写入测试用户 hash 后验证
+GET  /api/v1/api/docs       → Swagger UI 可用
+```
+
+### 已知待完善
+
+- 尚未写入测试用户（users 表为空），auth/login 需要先插入管理员账号
+- 退出登录（JWT 黑名单）待实现
+- 文物/机构 CRUD 写接口待实现
+- 标签接口待实现
+
+## 1.4 下一步
+
+- 插入管理员测试用户，验证 JWT 登录完整流程
+- 实现文物/机构写接口（新增、编辑、发布）
+- 实现标签接口
+- 开发 PC Web 地图站 MapLibre 集成（待确认地图 Key）
+- 开发 Admin 后台登录页和文物管理列表页