233 lines
5.1 KiB
Markdown
233 lines
5.1 KiB
Markdown
# 开发入门
|
||
|
||
**文档版本**: 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): 初始化模板
|