# 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. 拉代码并打开工作区

1. 克隆 **Ai-DOP 主库**（示例：`git clone https://gitee.com/sky-guo/ai-dop.git`，检出团队分支如 `v2`）。
2. 进入克隆目录后，应能看到同级目录：**`server/`**、**`Web/`**、**`ai-dop-platform/`**（这就是**主库根**，下文记为 `$REPO`）。

打开 Cursor 工作区建议：

- 打开 **主库根** `$REPO`（可同时改前后端），或
- 仅打开 **`$REPO/ai-dop-platform`**（以文档与规则为主；跑初始化脚本时请在终端先 `cd` 到 **主库根** 再执行下节命令）。

---

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

在 Cursor 对话里直接输入：

- `AIDOP项目初始化`

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

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

这会自动做以下事情：

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

对应脚本（**请在主库根 `$REPO` 下执行**，脚本会自动找到 `Web/`、`server/`）：

- `ai-dop-platform/tools/aidop_init.ps1`

手动执行示例：

```powershell
Set-Location $REPO   # 你的克隆根目录
powershell -ExecutionPolicy Bypass -File ".\ai-dop-platform\tools\aidop_init.ps1"
```

---

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

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

```powershell
Set-Location $REPO\Web
npm install --legacy-peer-deps   # 或 pnpm install
npm run prepare
```

## 4.2 构建后端核心

```powershell
Set-Location $REPO\server\Admin.NET.Core
dotnet build --framework net8.0
```

若 `dotnet restore` / `build` 报 **NETSDK1045**（缺少 net10.0），请再安装 **.NET 10 SDK**（见 [CURRENT_TASKS.md](CURRENT_TASKS.md)）。

---

## 5. 启动项目

## 5.1 启动后端

```powershell
Set-Location $REPO\server\Admin.NET.Web.Entry
dotnet run --framework net8.0
```

默认地址：

- `http://localhost:5005`

## 5.2 启动前端

```powershell
Set-Location $REPO\Web
pnpm dev    # 或 npm run dev
```

默认地址：

- `http://localhost:8888`

## 5.3 数据库（必看）

- 连接串在 **`server/Admin.NET.Application/Configuration/Database.json`**（已随仓库提交）。
- 若你本机**无法访问**当前配置中的数据库（网络、账号、防火墙），请改为本机 **MySQL** 或团队提供的可达实例，否则 **`dotnet run` 会在启动时失败**。
- 本地可改用注释中的 **SQLite** 示例快速起服务（需按文件内说明改 `DbType` 与连接串）；生产环境勿用默认演示库。

---

## 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`** 是否指向你本机可达的库；团队共用库需 VPN/白名单；仅本地试跑可改用 SQLite 示例
- 前端 404：确认后端是否运行在 `5005`，再看 `Web` 的 API 配置

---

## 9. 关键文档入口

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