# 开发入门

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

---

## 目录

1. [项目概览](#1-项目概览)
2. [快速开始](#2-快速开始)
3. [项目结构](#3-项目结构)
4. [开发工作流](#4-开发工作流)
5. [常用命令](#5-常用命令)
6. [代码质量](#6-代码质量)
7. [测试](#7-测试)
8. [文档体系](#8-文档体系)

---

## 1. 项目概览

<!-- 项目简介 -->

### 技术栈

| 组件 | 技术 |
|------|------|
| 语言 | <!-- 语言 --> |
| 框架 | <!-- 框架 --> |
| 数据库 | <!-- 数据库 --> |
| 版本控制 | Jujutsu (jj) |
| 包管理 | uv（Python）/ nvm + npm（前端） |

### 核心架构约束

- **模块独立性**：各模块完全独立，禁止跨模块代码引用
- **通信方式**：仅通过 REST API
- <!-- 其他约束 -->

---

## 2. 快速开始

### 2.1 环境搭建

完整的环境搭建指南见 [`管理-开发环境搭建.md`](./管理-开发环境搭建.md)。核心步骤：

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

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

### 2.2 验证安装

```bash
# <!-- 模块 -->
cd apps/<!-- 模块 -->
uv run python -c "from <!-- 模块名 -->.main import app; print('OK')"
```

---

## 3. 项目结构

```
<!-- 项目名 -->/
├── apps/
│   ├── <!-- 模块1 -->/          # <!-- 说明 -->
│   │   ├── src/<!-- 模块名 -->/
│   │   │   ├── main.py
│   │   │   ├── api/
│   │   │   ├── services/
│   │   │   ├── models/
│   │   │   └── db/
│   │   ├── tests/
│   │   └── pyproject.toml
│   │
│   └── <!-- 模块2 -->/          # <!-- 说明 -->
│       └── ...
│
├── docs/                           # 项目文档
├── specs/                          # 功能规格
├── team/                          # 团队公共知识
└── .claude/                        # Claude Code 配置
```

### 模块边界

| 规则 | 说明 |
|------|------|
| 禁止跨模块引用 | 各模块之间不能 import |
| 仅通过 REST API 通信 | <!-- 说明 --> |
| 独立数据库 | 各模块有独立数据库，Schema 版本独立递增 |
| 独立依赖 | 各模块有独立 `pyproject.toml` |

---

## 4. 开发工作流

### 4.1 speckit 功能开发流程

```
/speckit.specify → spec.md → /speckit.plan → plan.md → /speckit.tasks → tasks.md → /speckit.implement
```

### 4.2 版本控制

项目使用 Jujutsu (jj)，并存模式：

```bash
# 日常开发
jj new trunk                    # 在 trunk 上新建工作副本
# ... 编写代码 ...
jj diff                         # 查看变更
jj describe -m "功能: 添加xxx"  # 设置提交消息
jj new                          # 固化当前提交

# 推送到远程
jj b c feature-xxx              # 创建书签
jj git push -b feature-xxx      # 推送
```

> 完整 jj 命令对照表见 [`team/jj.md`](../team/jj.md)，Git 提交规范见 [`team/git.md`](../team/git.md)。

**提交类型（中文）**：功能、修复、维护、文档、重构、测试、格式、性能、构建、安全、依赖、清理、配置、规格、合并、回滚

### 4.3 PR 规范

- 每个 PR 只能改动一个模块
- 标题格式：`[模块] 描述`
- 主分支：`trunk`（Trunk-Based Development）

---

## 5. 常用命令

```bash
# 类型检查
uv run mypy src --strict

# 运行测试
uv run pytest

# 代码质量
ruff format --check . && ruff check .

# 格式化
ruff format .

# Lint 自动修复
ruff check . --fix
```

---

## 6. 代码质量

### 编码规范

| 规范项 | 规则 |
|--------|------|
| 缩进 | 4 空格 |
| 行长度 | 100 字符 |
| 命名 | PascalCase 类/类型，snake_case 函数/变量，UPPER_SNAKE_CASE 常量 |
| 类型注解 | mypy strict，禁止 `Any` |
| Docstring | Google 风格，公共 API 必须有 |
| 字符串 | 用户可见用双引号，代码内部用单引号 |

### 质量门禁

```bash
ruff format --check .    # 格式检查
ruff check .             # Lint 检查
uv run mypy --strict      # 类型检查
uv run pytest             # 测试通过
```

---

## 7. 测试

### 测试策略

详见 [`10-测试-方案.md`](./10-测试-方案.md) 和 [`测试-计划.md`](./测试-计划.md)。

### 测试文件组织

```
apps/<!-- 模块 -->/tests/
├── unit/              # 单元测试
├── integration/       # 集成测试
└── conftest.py        # 测试夹具
```

### 运行测试

```bash
# 全部测试
uv run pytest

# 仅单元测试
uv run pytest tests/unit/

# 带覆盖率
uv run pytest --cov=src --cov-report=term-missing
```

---

## 8. 文档体系

项目文档按类型分类，全部使用中文命名：

| 类别 | 前缀 | 示例 |
|------|------|------|
| 核心文档 | `01-` ~ `12-` | `01-用户需求.md` |
| 设计文档 | `设计-` | `设计-Apple风格.md` |
| 管理文档 | `管理-` | `管理-开发入门.md` |
| 运维文档 | `运维-` | `运维-部署实施.md` |
| 测试文档 | `测试-` | `测试-方案.md` |

完整索引见 [`README.md`](./README.md) 和 [`CLAUDE.md`](./CLAUDE.md)。

---

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