# 开发环境搭建

**文档版本**: 1.0.0
**最后更新**: 2026-04-19

---

## 目录

1. [环境要求](#1-环境要求)
2. [<!-- 模块1 -->环境](#2-模块1环境)
3. [<!-- 模块2 -->环境](#3-模块2环境)
4. [IDE 配置](#4-ide-配置)
5. [常见问题](#5-常见问题)

---

## 1. 环境要求

### 1.1 操作系统

- <!-- 操作系统要求 -->

### 1.2 基础依赖

| 工具 | 版本 | 用途 |
|------|------|------|
| <!-- 工具 --> | <!-- 版本 --> | <!-- 用途 --> |

### 1.3 镜像源配置

国内开发环境建议配置镜像源（详见 [`team/mirrors.md`](../team/mirrors.md)）。

---

## 2. <!-- 模块1 -->环境

### 2.1 克隆与安装

```bash
# 克隆仓库
jj git clone <!-- 仓库地址 -->
cd <!-- 项目目录 -->

# 安装依赖
cd apps/<!-- 模块 -->
uv sync
```

### 2.2 开发服务器启动

```bash
cd apps/<!-- 模块 -->
uv run <!-- 启动命令 -->
```

### 2.3 数据库初始化

> 待编写

---

## 3. <!-- 模块2 -->环境

### 3.1 <!-- 环境说明 -->

```bash
# 安装依赖
cd apps/<!-- 模块 -->
uv sync

# 启动
uv run <!-- 启动命令 -->
```

---

## 4. IDE 配置

### 4.1 VS Code 推荐扩展

```json
{
  "recommendations": [
    "charliermarsh.ruff",
    "ms-python.mypy-type-checker",
    "ms-python.python"
  ]
}
```

| 扩展 | 用途 |
|------|------|
| **Ruff** | Python 格式化 + Lint |
| **mypy Type Checker** | Python 类型检查 |
| **Python** | Python 语言支持、调试 |

### 4.2 代码格式化与 Lint

- 格式化：`ruff format`
- Lint：`ruff check`
- 类型检查：`mypy --strict`

### 4.3 调试配置

> 待编写

---

## 5. 常见问题

### 5.1 Python 环境问题

**Q: `uv sync` 安装依赖失败**
A: 检查 Python 版本是否符合要求，并确认镜像源配置正确。

**Q: `mypy --strict` 报大量错误**
A: 项目强制 mypy strict 模式，禁止 `Any` 类型。确保所有函数和变量都有完整类型注解。

### 5.2 前端环境问题

> 待编写

### 5.3 数据库问题

**Q: Schema 迁移失败**
A: 迁移前会自动备份。恢复方法：
```bash
cp backups/backup_v{N}.db data/<!-- 数据库文件 -->
```

### 5.4 版本控制问题

**Q: jj 和 git 命令如何选择**
A: 项目默认使用 jj。常用命令对照见 [`team/jj.md`](../team/jj.md)。

> 更多运行时故障排除见 [`运维-故障排除.md`](./运维-故障排除.md)。

---

**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板