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

docs/管理-开发入门.md

@@ -0,0 +1,232 @@
+# 开发入门
+
+**文档版本**: 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): 初始化模板