# Developer Manual

开发笔记本快照扩展的工程手册。面向**接手开发**的人：架构、构建、调试、打包全流程。

> 用户视角（安装 / 配置 / 排错）见 [README.md](README.md)。设计目标见 [design.md](design.md)。AI 编码规范见 [AGENTS.md](AGENTS.md)。

## 1. 架构概览

四层结构，数据自下而上：

```
┌──────────────────────────────────────────────────────────────┐
│  JupyterLab 前端  (src/)                                    │
│  ├─ commands / api / model / diff / widgets                 │
│  └─ 与后端走 HTTP  (POST commit / GET list / GET content)   │
└──────────────────┬───────────────────────────────────────────┘
                   │ JSON over HTTP
┌──────────────────┴───────────────────────────────────────────┐
│  Server Extension  (snapshot/)                              │
│  ├─ routes.py     REST handlers                              │
│  ├─ store.py      SnapshotStore（清洗 + hash + envelope +  │
│  │                manifest 原子写 + 重建）                   │
│  ├─ config.py     traitlets 配置                             │
│  └─ __init__.py   _load_jupyter_server_extension 入口        │
└──────────────────┬───────────────────────────────────────────┘
                   │
┌──────────────────┴───────────────────────────────────────────┐
│  Storage Adapter  (snapshot/storage/)                       │
│  ├─ base.py       StorageAdapter ABC（put/get/list/delete） │
│  ├─ local.py      LocalFileStorage（原子写 tmp+rename）     │
│  └─ s3.py         S3Storage（boto3，懒加载）                 │
└──────────────────────────────────────────────────────────────┘
```

**关键设计决策**（实现时不得违背，见 [AGENTS.md](AGENTS.md)）：

1. 存储适配器是**哑字节桶**——不知道 notebook / 版本 / manifest 这些概念
2. MD5 在清洗后 JSON 上计算；hash 与最近版本相同则跳过保存
3. 快照文件是 **envelope**（`{id, timestamp, name, description, hash, size, notebook}`），name/description 内嵌以便 manifest 损坏时从版本文件重建
4. manifest 是可重建的索引，原真相在 envelope 里
5. 手动提交，不绑定 Ctrl+S，**不**自动 commit
6. Cell diff 按 id 优先匹配，LCS 兜底

## 2. 仓库布局

```
.
├── src/                    前端 TypeScript / React
│   ├── index.ts            插件入口（注册命令、挂面板、装工具栏）
│   ├── commands.ts         命令实现（snapshot:commit / restore）
│   ├── api.ts              类型化 HTTP 包装
│   ├── model.ts            SnapshotModel（path + versions + 信号）
│   ├── diff.ts             Cell 级 diff（id 优先 + LCS 兜底）
│   ├── request.ts          requestAPI（带 /snapshot 前缀）
│   └── widgets/            ReactWidget 组件
│       ├── CommitDialog.ts       名称/描述输入
│       ├── SnapshotPanel.tsx     左侧栏时间轴
│       └── DiffWidget.tsx        主区 diff 视图
├── snapshot/               后端 Python
│   ├── __init__.py         _load_jupyter_server_extension
│   ├── routes.py           三个 REST 处理器
│   ├── store.py            SnapshotStore（核心业务）
│   ├── config.py           traitlets 配置
│   ├── storage/            存储适配器
│   │   ├── base.py         ABC
│   │   ├── local.py
│   │   └── s3.py
│   └── tests/              pytest
├── style/                  CSS（base.css 命名空间 jp-snapshot-*）
├── schema/plugin.json      前端 settings schema（目前空）
├── ui-tests/               Playwright + Galata 集成测试
├── design.md               架构设计文档（单一事实源）
├── AGENTS.md / CLAUDE.md   AI 编码规范（CLAUDE.md 是符号链接）
├── README.md               用户文档
└── DEVELOPER.md            本文件
```

## 3. 开发环境搭建

一次性：

```bash
# 后端
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,test,s3]"

# 前端
.venv/bin/jlpm install

# 注册扩展到 JupyterLab
jupyter server extension enable snapshot
jupyter labextension develop . --overwrite
```

每日：

```bash
source .venv/bin/activate
.venv/bin/jlpm watch      # 终端 1：自动重编
jupyter lab              # 终端 2：启动 JupyterLab
```

**改了 Python**：重启 `jupyter lab`（不需要 rebuild 前端）
**改了 TypeScript**：`jlpm watch` 自动重编 → 浏览器**硬刷新**（Cmd+Shift+R）拿新 bundle
**改了 CSS**：`jlpm watch` 不会自动 rebuild——手动 `jlpm build` 后刷新

## 4. 常用命令

| 操作 | 命令 |
|------|------|
| 后端测试 | `.venv/bin/pytest snapshot/tests/ -vv` |
| 后端单测 | `.venv/bin/pytest snapshot/tests/test_store.py::test_xxx -vv` |
| 前端构建 | `.venv/bin/jlpm build` |
| 前端打包 | `.venv/bin/jlpm build:prod` |
| Lint | `.venv/bin/jlpm lint:check` |
| 看日志 | 启动 jupyter lab 的那个终端 |
| 跑 ui-tests | `cd ui-tests && yarn install && yarn test` |
| 清理 | `.venv/bin/jlpm clean:all` |

## 5. 调试

### 5.1 后端（Python）

`jupyter lab` 的终端会打印所有 server extension 的日志，包括本扩展。

**结构化日志**（在 `_load_jupyter_server_extension` 里）：
```python
server_app.log.info(f"Activated snapshot storage backend: {config.storage_type}")
# S3 模式还会打：
# server_app.log.info(f"Snapshot S3 storage ready: endpoint=..., bucket=...")
```

**S3 连接失败**：会抛 `S3ConnectionError`（带 endpoint / bucket / 修复建议），JupyterLab 启动失败。看 traceback。

**手动看 API**（不通过前端）：
```bash
# 启动后
.venv/bin/jupyter server --port 8888 &
# 拿到 token from jupyter_server 的输出
TOK=...

# 提交
curl -X POST -H "Authorization: token $TOK" -H "Content-Type: application/json" \
  -d '{"path":"test.ipynb","content":{"cells":[],"metadata":{},"nbformat":4,"nbformat_minor":5},"name":"v1","description":""}' \
  http://localhost:8888/snapshot/notebook-version/commit

# 列表
curl -H "Authorization: token $TOK" \
  "http://localhost:8888/snapshot/notebook-version/list?path=test.ipynb"
```

### 5.2 前端（TypeScript / React）

**1. 浏览器 DevTools Console**

打开 DevTools (F12 或 Cmd+Option+I) → Console。

代码里有 `console.log` 诊断日志：
- `'JupyterLab extension snapshot is activated!'` — 插件加载
- `'snapshot settings loaded:'` — settings 加载
- `'[snapshot] commit response:'` — commit 响应（最近调试加的）
- `'Failed to list snapshots'` — list 失败
- `'Diff failed'` — diff 失败

**2. 看 React 组件树**：装 React DevTools 扩展

**3. 看 Lumino Widget 树**：在 Console 跑 `JupyterLab.shell.widgets()` 看主区 widget，左区 widget 列表

**4. 改前端后必须硬刷新**：JupyterLab 缓存 labextension，**软刷新可能拿到旧 bundle**。Cmd+Shift+R 清缓存。

### 5.3 端到端问题排查

| 症状 | 排查 |
|------|------|
| 工具栏没「保存快照」按钮 | (1) 硬刷新浏览器；(2) `jupyter labextension list` 看 snapshot 状态 |
| 提交没反应 | 看 Console 有无 `[snapshot] commit response:` 日志，看 jupyter 终端有无 traceback |
| 「内容未变更」warning 不弹 | Console 里看 commit response 实际是什么 |
| 保存后历史列表没新条目 | 点侧边栏「刷新」按钮（手动 list）；检查 S3 manifest 写入（用 `aws s3 ls` 或 MinIO 控制台） |
| Diff 视图空白 | 检查 `model.versions` 是否有目标 id；后端 `/content?path=&id=` 单独 curl 一次 |
| Restore 失败 | Console 报具体错；检查 `notebook.model.fromJSON` 的入参结构 |

### 5.4 测试覆盖现状

```
backend pytest:  33 passed   (13 storage + 9 store + 6 routes_api + 5 misc)
frontend jest:   ❌ pnpm 链接器下跑不起来（见下方"已知坑"）
ui-tests:        跑通需先 `cd ui-tests && yarn install`，未在 CI 中
```

**新增后端测试**：`snapshot/tests/test_*.py`，命名 `test_<模块>_<场景>`.py

**新增前端测试**：jest 暂时不可用。如需单测 `src/diff.ts` 的纯逻辑，可：
- 临时方案：把 diff 函数复制到 `__tests__/diff.spec.ts` 跑（在已知坑解决前）
- 正确方案：改 `.yarnrc.yml` 的 `nodeLinker` 为 `node-modules`，再重装

## 6. 打包与发布

### 6.1 版本管理

- **单一事实源**：`package.json` 的 `version` 字段
- `pyproject.toml` 通过 `hatch-nodejs-version` 自动从 `package.json` 同步
- 手动修改 `pyproject.toml` 的版本会被覆盖

### 6.2 后端 wheel

```bash
.venv/bin/pip install build hatch hatch-jupyter-builder hatch-nodejs-version
.venv/bin/python -m build
# 产物：dist/snapshot-0.1.0-py3-none-any.whl + dist/snapshot-0.1.0.tar.gz
```

`pyproject.toml` 的 `[tool.hatch.build.hooks.jupyter-builder]` 会自动 build 前端并打进 wheel 的 `snapshot/labextension/`。

发布到 PyPI：
```bash
.venv/bin/python -m twine upload dist/*
```

### 6.3 前端 labextension

前端**不单独发布**。build 产物（`snapshot/labextension/`）通过 hatch hook 嵌进 wheel。

本地 dev 模式：`jupyter labextension develop . --overwrite` 建立符号链接，改前端代码即时生效。

### 6.4 发布 checklist

1. 改 `package.json` 的 version（不要改 `pyproject.toml`）
2. 更新 `CHANGELOG.md`
3. `git tag v0.1.0`
4. 跑全套验证：`pytest` + `jlpm build:prod` + `jlpm lint:check`
5. `python -m build` 出 wheel
6. (可选) `twine upload dist/*` 发 PyPI
7. `git push --tags`

CI 流程见 `.github/workflows/build.yml` 和 `publish-release.yml`。

## 7. 已知坑

### 7.1 Jest 在 pnpm 链接器下跑不起来

`jlpm test` 报 `Cannot find module 'jest-util'`，stack 指向 `ts-jest/dist/legacy/config/config-set.js`。

**根因**：`yarnLinker: pnpm`（`.yarnrc.yml`）的虚拟存储把 `ts-jest` 和 `jest-util` 隔开，pnpm 严格隔离破坏了 require 路径。

**绕过**：
- 暂时不修——前端用 `jlpm build`（tsc 严格模式 + rspack bundle）验证类型和模块等价
- 真要跑单测，改 `.yarnrc.yml` 切 `nodeLinker: node-modules`（影响整个 monorepo 解析）
- 或完全重写 `jest.config.js` 不依赖 `@jupyterlab/testing` 的 baseConfig

### 7.2 S3 强一致性

AWS S3 自 2020 年起强一致（读写单对象强一致）。**但 MinIO / Ceph RGW / 阿里云 OSS 等 S3 兼容服务实现各异**。

表现：commit 写入 manifest 成功，但紧随其后的 list 偶尔返回旧 manifest。

**临时缓解**：侧边栏有「刷新」按钮，用户手动拉一次。

**彻底修复**（未做）：commit 响应里直接返回最新 list，省掉独立 list 调用。

### 7.3 `.yarnrc.yml` / `.venv` / lockfile

- 仓库用 **uv/venv**（不是 conda）：`source .venv/bin/activate`
- 前端用 **Yarn Berry**（不是 npm / yarn classic）：`jlpm`，不要 `npm install`
- 不要混 `package-lock.json` 和 `yarn.lock`

## 8. 给新 contributor 的 5 分钟清单

1. `source .venv/bin/activate && pip install -e ".[dev,test,s3]"`
2. `.venv/bin/jlpm install && .venv/bin/jlpm build`
3. `jupyter server extension enable snapshot && jupyter labextension develop . --overwrite`
4. `jupyter lab` → 打开任意 `.ipynb` → 看工具栏「保存快照」按钮
5. 点按钮 → 填 name → 看左侧栏时间轴；改 cell 再保存 → 时间轴更新

如果第 4 步没看到按钮：**硬刷新**浏览器（Cmd+Shift+R）。