创建您的第一个项目

本综合指南将引导您在 Archyl 中创建第一个架构文档项目，从初始设置到与团队共享。

前提条件

开始之前：

一个 Archyl 帐户（在此注册）
一个要记录的软件系统
可选：对代码库仓库的访问权限

步骤 1：创建新项目

从仪表板开始

登录 Archyl
点击 "+ 新建项目" 按钮
输入项目详情：
- 名称：清晰的描述性名称（例如"电商平台"）
- 描述：系统简要概述
- 标签：用于组织的关键词（例如"后端"、"微服务"）
点击 "创建项目"

项目设置

创建后，配置您的项目：

可见性：公开或私有
团队访问：哪些团队可以查看/编辑
仓库：连接以进行 AI 发现（可选）

步骤 2：理解系统上下文

在绘制图表之前，了解系统的上下文：

识别用户

谁使用您的系统？

最终用户（客户、员工）
管理员
外部开发者
其他系统

识别外部系统

您的系统与什么交互？

支付处理器
认证提供商
邮件/通知服务
分析平台
合作伙伴 API

步骤 3：创建系统上下文图

添加主系统

在空白画布上，点击 "+" 或右键点击
选择 "添加系统"
输入：
- 名称：您的系统名称
- 描述：系统功能
- 类型：内部（您拥有的）

添加用户

点击 "+" 并选择 "添加人员"
创建每种用户类型：
- 名称："客户"、"管理员用户"等
- 描述：他们的角色和职责

添加外部系统

点击 "+" 并选择 "添加外部系统"
对于每个外部依赖：
- 名称："Stripe"、"SendGrid"等
- 描述：提供的功能

创建关系

将鼠标悬停在源元素上
从连接点拖动到目标
添加标签："通过...下单"、"通过...发送邮件"等
可选添加技术："REST/HTTPS"、"SMTP"

步骤 4：深入容器

打开容器视图

双击主系统以放大到容器层级。

识别容器

技术构建块有哪些？

应用程序：Web 应用、移动应用、桌面客户端
服务：API 服务器、后台工作进程
数据存储：数据库、缓存、文件存储
消息队列：事件总线、队列

添加容器

对于每个容器：

点击 "+" 并选择 "添加容器"
输入：
- 名称："Web 应用程序"、"API 服务器"、"PostgreSQL"
- 描述：其职责
- 技术："React"、"Node.js"、"PostgreSQL 15"

连接容器

展示容器之间的通信方式：

Web 应用 → API 服务器："发起 API 调用 [REST/HTTPS]"
API 服务器 → 数据库："读写数据 [SQL]"
API 服务器 → 缓存："缓存会话数据 [Redis 协议]"

步骤 5：添加组件（可选）

对于关键容器，深入到组件级别：

双击一个容器
添加代表主要模块的组件：
- 控制器
- 服务
- 仓储
- 工具类

步骤 6：使用 AI 发现（可选）

让 AI 帮助记录您的架构：

连接仓库

前往项目设置 → 仓库
连接您的 Git 提供商
选择您的仓库

运行发现

点击 "开始发现"
等待分析完成
审查待处理的发现

审查和批准

检查每个发现的元素
根据需要编辑名称/描述
批准准确的项目
拒绝或修改不正确的项目

步骤 7：添加文档

元素描述

点击任何元素并添加详细描述：

目的和职责
已做出的关键决策
重要说明

架构决策记录

记录重要决策：

前往 ADR 部分
点击"新建 ADR"
填写：
- 标题："使用 PostgreSQL 进行持久化"
- 上下文：为什么需要这个决策
- 决定：决定了什么
- 后果：决策的影响

链接文档

将 ADR 和文档链接到特定元素以提供上下文。

步骤 8：与团队共享

邀请团队成员

前往项目设置 → 团队
点击"邀请"
输入邮箱地址
分配角色（查看者、编辑者、管理员）

创建共享链接

对于没有帐户的利益相关者：

在工具栏中点击"分享"
配置访问选项
复制并分享链接

导出图表

用于演示或文档：

点击"导出"
选择格式（PNG、SVG、PDF）
下载您的图表

最佳实践

简单开始

从系统上下文开始
逐步添加细节
不要试图一次记录所有内容

保持最新

架构变更时更新
重大变更后运行 AI 发现
定期与团队审查

注重沟通

使用清晰的描述性名称
在描述中添加上下文
展示最重要的关系

后续步骤

恭喜！您已创建了第一个架构文档。继续学习：

创建您的第一个项目 - Archyl Docs