配置: 初始化 ISOS Agent Teams 软件研发模板

docs/管理-开发环境搭建.md

@@ -0,0 +1,142 @@
+# 开发环境搭建
+
+**文档版本**: 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): 初始化模板