# Markdown PDF 导出器进度

最后更新：2026-07-25

## 1. 当前概况

项目目录：

```text
C:\Projects\md-to-pdf
```

当前分支：

```text
main
```

已有提交：

```text
fa07472 feat: 实现网页实时预览
7224dfd feat: 实现 Markdown 渲染核心
ec48bce chore: 初始化项目骨架
```

当前工作区存在未提交修改，主要是主题基础 CSS 组合、安全的 CSS `@import` 展开、三套本地 Typora 默认主题导入和主题开发文档。接手时必须保留并审查这些修改，不要重置工作区。

## 2. 已完成

### 2.1 项目骨架

- 建立 npm workspaces。
- 建立 React + Vite 前端。
- 建立 Fastify 后端。
- 建立 `packages/core` 共享包。
- 建立主题、测试和 Docker 目录。
- 初始化本地 Git 仓库。

### 2.2 导出配置模型

`packages/core/src/export-config.ts` 已包含：

- 配置版本号；
- A3、A4、A5、Letter、Legal、Tabloid 和自定义纸张；
- 横向、纵向；
- 四边页边距；
- 页眉和页脚左右中区域；
- 页码位置和格式；
- PDF 元数据；
- 打印背景、缩放和一级标题分页选项；
- Zod 数据校验；
- 默认 A4 技术文档预设。

### 2.3 主题接口

`packages/core/src/theme.ts`、`themes/typora-like` 和动态主题注册器已包含：

- 版本化主题清单；
- 主题 ID、名称、版本、作者、许可证；
- DOM 预设；
- 支持能力声明；
- 可选基础 CSS、主体 CSS 和打印 CSS；
- 自制 Typora 风格主题；
- `#write` 兼容文档结构；
- 内置主题和 `.local/themes` 本地主题动态扫描；
- 按基础 CSS、主体 CSS、打印 CSS 的固定顺序组合；
- 主题内相对 CSS `@import` 安全展开；
- 主题 CSS 相对资源重写与受限资源接口；
- 目录匹配、真实路径包含关系和外部 URL 安全检查。

内置主题为项目自有实现，没有复制 Typora 官方默认主题。用户可以通过导入工具将本机已安装的 Typora 基础 CSS以及 GitHub、Pixyll 和 Whitey 三套适合打印的白色默认主题复制到 Git 忽略的 `.local/themes`。这些副本仅供本机使用，不进入仓库、容器或发布包。

### 2.4 Markdown 渲染核心

提交 `7224dfd` 已完成：

- `packages/renderer` 独立工作区；
- Front Matter 解析；
- Markdown 到安全 HTML；
- 标题锚点；
- 表格；
- 任务列表；
- 脚注；
- highlight.js 代码高亮；
- KaTeX 数学公式；
- Mermaid 安全占位；
- sanitize-html 安全过滤；
- 元数据规范化；
- 功能检测；
- 统一 `<article id="write">` 输出；
- 5 项渲染单元测试。

### 2.5 网页实时预览

提交 `fa07472` 已完成：

- 可测试的 Fastify `buildApp()`；
- `POST /api/render` 服务端统一 Markdown 渲染；
- 动态主题清单、CSS 和资源 API；
- Markdown 编辑及本地 `.md` 文件读取；
- 250ms 防抖 A4 实时预览；
- iframe 隔离主题 CSS；
- KaTeX、highlight.js 和按需加载的 Mermaid；
- 桌面双栏与移动端上下布局；
- 5 项渲染器测试和 4 项后端测试。

## 3. 当前未提交工作

以下内容已写入工作区，但尚未提交：

### 3.1 主题清单与服务端主题注册

- 主题清单新增可选 `base` 字段。
- CSS 按基础 CSS、主体 CSS、打印 CSS 的顺序组合，预览与未来 PDF 可复用同一结果。
- 支持带引号或 `url()` 写法的相对 `@import`。
- 限制导入深度为 8 层，并检测循环引用。
- 阻止外部 URL、绝对路径和 `..` 越界导入。
- 按每个 CSS 文件所在目录重写相对字体和图片 URL。
- 增加基础 CSS 组合、相对导入、循环导入和外部导入测试，后端测试增至 6 项。

### 3.2 本地 Typora 默认主题导入

- 导入器从本机 Typora 安装目录读取 `resources/style`。
- 一次导入 GitHub、Pixyll 和 Whitey 三套适合打印的白色默认主题。
- 每套本地主题包含独立的 Typora 基础 CSS、主题 CSS 和所需资源。
- 主题版本从 Typora `resources/package.json` 读取；当前本机版本为 1.14.7。
- 默认拒绝覆盖已有主题；`--replace` 使用暂存目录并将旧副本备份到 `.local/theme-backups/<时间戳>`。
- 当前三套主题及替换操作产生的备份均位于被 Git 忽略的 `.local`，不得提交或发布。

### 3.3 文档及依赖

- README 已更新三套本地 Typora 主题的导入和替换说明。
- 新增 `docs/THEMES.md`，说明主题目录、清单字段、CSS 加载顺序、`#write` DOM、相对资源、安全限制和自定义主题流程。
- `npm run theme:import-typora` 保持为本地导入入口。

## 4. 已执行验证

2026-07-25 在当前完整工作区成功执行：

```text
npm test
npm run typecheck
npm run build
git diff --check
```

结果：

- 渲染器测试：5 项通过；
- 后端测试：6 项通过；
- 全项目类型检查通过；
- 生产构建通过；
- `git diff --check` 通过，仅出现工作区 LF 将来可能转为 CRLF 的提示；
- 导入器默认的已存在目标保护通过；
- GitHub、Pixyll 和 Whitey 三套本地主题的 CSS API 均返回成功，组合结果无残留 `@import`。

已使用浏览器插件完成视觉验证：

- 导入并打开 `tmp/数据中台项目周报_2026_W30.md`；
- 参考 `tmp/数据中台项目周报_2026_W30.pdf` 的 Typora 输出；
- GitHub、Pixyll 和 Whitey 三套保留的本地主题均可正常切换；
- 三套主题中的表格均为 `border-collapse: collapse`、单元格间距为 0，并铺满 `#write` 内容宽度；
- GitHub 表格边框颜色与主题定义的 `#dfe2e5` 一致；
- Open Sans、PT Serif 和 Merriweather 字体资源均成功加载；
- KaTeX、代码高亮和 Mermaid 正常显示；
- 浏览器控制台无警告或错误。

为方便用户继续检查，开发服务当前仍在后台运行，前端监听 5173，后端监听 3001。

## 5. 当前注意事项

- 工作区不是干净状态，禁止重置。
- `apps/web/src/App.tsx` 是当前预览实现的主要文件。
- `apps/server/src/app.ts` 是新增的可测试 Fastify 应用。
- `apps/server/src/theme-registry.ts` 负责内置和本地主题发现、CSS 处理及资源安全。
- `.local/themes/typora-*` 是用户本机副本，已被 Git 忽略，不得提交。
- `.local/theme-backups` 中保留 GitHub、Pixyll 和 Whitey 的可恢复备份；Newsprint 和 Night 的当前副本及备份已按用户要求删除。
- Typora 官方资源是 All Rights Reserved，仅限当前用户本机使用，不进入 Git、容器或发布包。
- Mermaid 已按需加载，但生产构建仍提示 `mermaid.core` 和 `cynefin` 两个分块超过 500 kB；这不影响功能，可后续优化。
- PDF 生成尚未实现。
- 资源目录上传、本地相对图片、临时目录和路径安全尚未实现。
- Dockerfile 和 Compose 尚未实现。

## 6. 推荐接手顺序

### 阶段一：提交主题兼容增强

网页实时预览已在 `fa07472` 提交。当前主题基础 CSS、三套本地 Typora 主题导入、主题开发文档、全量验证和视觉检查均已完成。用户确认后创建独立提交：

```text
feat: 扩展本地主题兼容能力
```

### 阶段二：实现真实 PDF

开始编码前必须先给出具体设计和详细任务清单，等待用户确认。设计至少覆盖：

1. 增加 Playwright 和固定版本 Chromium。
2. 抽取可复用的完整 HTML 文档组装器。
3. 预览和 PDF 共用文章 HTML、主题 CSS、打印 CSS及资源。
4. 等待字体、图片、KaTeX 和 Mermaid 完成。
5. 实现 `POST /api/pdf`，响应 `application/pdf`。
6. 前端启用“导出 PDF”按钮并下载文件。
7. 增加 PDF 接口与端到端测试。

### 阶段三：导出配置界面

- 纸张尺寸；
- 横向或纵向；
- 四边页边距；
- 页眉页脚开关；
- 左中右内容区域；
- 当前页和总页数；
- 多种页码预设；
- Front Matter 元数据覆盖；
- 浏览器本地配置预设；
- 配置 JSON 导入和导出。

### 阶段四：资源与安全

- Markdown 文件夹或 ZIP；
- 相对图片解析；
- 每请求独立临时目录；
- 路径穿越防护；
- 文件数量、大小和超时限制；
- Chromium 并发和网络访问限制；
- 请求结束可靠清理。

### 阶段五：容器化与交付

- Dockerfile；
- Docker Compose；
- Chromium 字体与中文字体；
- 非 root 用户；
- 健康检查；
- 临时目录容量限制；
- 内网部署说明；
- 完整 PDF 样例和视觉回归验证。

## 7. 首版验收目标

- 可以选择或粘贴 Markdown；
- 网页正确预览常用 Markdown、公式和 Mermaid；
- 可以下载真实 PDF；
- PDF 文本可搜索；
- 预览与 PDF 基本一致；
- 支持 A4、Letter、方向和边距；
- 支持基础页眉、页脚和页码；
- 支持主题切换扩展；
- 相对图片可用；
- 转换后不保留用户文档；
- Docker Compose 可在内网启动。