# Ai-DOP 新成员 0->1 保姆级指南

适用对象：第一次加入 Ai-DOP 项目的开发同学（Windows + Cursor）。

目标：从零环境到“可开发、可启动、可联调、可提交”。

---

## 0. 你会得到什么

完成本指南后，你可以：

- 在 Cursor 中直接用一句话初始化项目
- 本地启动前后端（`5005` + `8888`）
- 登录系统进行功能开发与调试
- 推送代码时自动触发基础质量门禁（pre-push hook）

---

## 1. 必备软件安装

## 1.1 安装 Git

- 安装后验证：
  - `git --version`

## 1.2 安装 Node.js（建议 LTS，>=18）

- 安装后验证：
  - `node -v`
  - `npm -v`

## 1.3 安装 .NET SDK（必须 8.x）

- 安装后验证：
  - `dotnet --list-sdks`
- 至少应看到一条 `8.0.x`。

## 1.4 安装 Cursor

- 从 Cursor 官网下载安装并登录团队账号。
- 打开设置确认：
  - 终端为 PowerShell
  - 工作区信任已开启

---

## 2. 拉代码并打开工作区

推荐目录（与团队约定一致）：

- `D:/Projects/Ai-DOP/SourceCode`

仓库根为：

- `D:/Projects/Ai-DOP/SourceCode/ai-dop-platform`

打开 Cursor 工作区建议：

- 优先打开 `SourceCode/ai-dop-platform`
- 或打开上层 `SourceCode`（也支持）

---

## 3. 一句话自动初始化（推荐）

在 Cursor 对话里直接输入：

- `AIDOP项目初始化`

如果你希望初始化后直接启动前后端，输入：

- `AIDOP项目初始化并启动`

这会自动做以下事情：

- 检查 `dotnet`/`node`
- 安装 `references/Admin.NET/Web` 依赖
- 自动安装 `pre-push` hook
- 构建 `Admin.NET.Core`
- 可选直接启动前后端服务

对应脚本：

- `tools/aidop_init.ps1`

---

## 4. 手动初始化（自动化失败时兜底）

## 4.1 安装 Web 依赖并安装 hooks

```powershell
Set-Location "d:/Projects/Ai-DOP/SourceCode/references/Admin.NET/Web"
npm install --legacy-peer-deps
npm run prepare
```

## 4.2 构建后端核心

```powershell
Set-Location "d:/Projects/Ai-DOP/SourceCode/references/Admin.NET/server/Admin.NET.Core"
dotnet build --framework net8.0
```

---

## 5. 启动项目

## 5.1 启动后端

```powershell
Set-Location "d:/Projects/Ai-DOP/SourceCode/references/Admin.NET/server/Admin.NET.Web.Entry"
dotnet run --framework net8.0
```

默认地址：

- `http://localhost:5005`

## 5.2 启动前端

```powershell
Set-Location "d:/Projects/Ai-DOP/SourceCode/references/Admin.NET/Web"
npm run dev
```

默认地址：

- `http://localhost:8888`

---

## 6. 首次联调检查清单（3 分钟）

- 能打开前端登录页
- 登录后菜单可见
- 打开“租户管理/权限管理”无白屏
- 打开 Ai-DOP 看板无明显报错

接口快速检查（可选）：

```powershell
Invoke-WebRequest -UseBasicParsing "http://127.0.0.1:5005/api/sysTenant/page" -Method POST -Body '{"page":1,"pageSize":1}' -ContentType 'application/json'
```

预期：状态码 `200`。

---

## 7. 日常开发规范（你不需要记太多）

- 直接在 Cursor 下达需求即可，项目已配置“改完自动验证/失败自动修复”规则
- 提交前不用手动记构建，`pre-push` 会自动做关键检查
- 业务代码放插件：`Plugins/Admin.NET.Plugin.AiDOP`
- 不在 `Admin.NET.Core` 堆业务逻辑（除非是底座修复并经确认）

---

## 8. 常见问题

- `pnpm` 不存在：本项目支持自动回落到 `npm`
- `npm install` 依赖冲突：使用 `npm install --legacy-peer-deps`
- 后端连不上数据库：先确认 `Database.json` 里的远端库账号配置是否最新
- 前端 404：确认后端是否运行在 `5005`，再看 `Web` 的 API 配置

---

## 9. 关键文档入口

- 项目总览：`docs/PROJECT_HANDOFF.md`
- 启动与联调：`docs/GETTING_STARTED.md`
- 自动验证与 hooks：`docs/CURSOR_AUTOVERIFY_AND_HOOKS.md`
- 当前任务清单：`docs/CURRENT_TASKS.md`