# 中华文明全图鉴——阶段进度与测试记录

## 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 后台登录页和文物管理列表页