# 上手：从 Demo 接到 Admin.NET

## 1. 打开解决方案

**Ai-DOP 主库**（Gitee `ai-dop`）克隆内，`server/` 与 `ai-dop-platform/` 同级。

- 工作区为 **`ai-dop-platform/`** 时：`../server/Admin.NET.sln`
- 工作区为 **主库根目录**（含 `server/`、`Web/`、`ai-dop-platform/`）时：`server/Admin.NET.sln`

其中 **启动项目** 为 `Admin.NET.Web.Entry`。

## 2. 数据库

在 Admin.NET 中配置 MySQL（与官方模板相同，例如 `Admin.NET.Application/Configuration/Database.json`）。插件实体映射表：

- `ado_orders`
- `ado_plans`
- `ado_work_orders`

在 **Development** 环境下，插件启动时会调用 SqlSugar `CodeFirst.InitTables` 创建上述表（若已存在则按 SqlSugar 行为处理）。生产环境请改用显式迁移或 DBA 脚本。

## 3. 与旧 Demo 对齐的 HTTP 契约

以下路由与 `legacy-demo/backend` 中控制器一致（JSON 不经 Furion 统一包装，便于旧前端对接）：

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/Order` | 分页列表，Query：`page`、`pageSize`、`orderNo`、`customerName`、`status` |
| GET | `/api/Order/{id}` | 详情 |
| POST | `/api/Order` | 创建 |
| PUT | `/api/Order/{id}` | 更新 |
| DELETE | `/api/Order/{id}` | 删除 |

`Plan`、`WorkOrder` 同理；工单完工：`POST /api/WorkOrder/{id}/complete`。

列表响应形状：`{ total, page, pageSize, list }`。

## 4. 前端（legacy-demo）

```bash
cd legacy-demo/frontend
npm install
npm run dev
```

默认开发服务器端口 **5174**，`/api` 代理到 **http://localhost:5005**（与 Admin.NET 默认端口一致，见 `vite.config.js`）。

若你本机 Admin.NET 使用其他端口，请同步修改 `vite.config.js` 中的 `proxy['/api'].target`。

**说明**：`legacy-demo/frontend`（5174）是旧业务 Demo 的 Vue 项目，**不是** Admin.NET 自带的权限/菜单/租户/审批管理端。需要配菜单、角色、工作流等底座能力时，请使用下一节的官方 `Web` 前端。

## 5. Admin.NET 官方管理 UI（双进程，日常推荐）

业务开发以 **`Admin.NET.Web.Entry`** 与插件为主；需要操作框架自带的系统管理界面时，再单独启动官方 Vue 管理端（与后端是两个进程）。

路径（相对 `ai-dop-platform/` 根目录，与 `server/` 同级）：

`../Web`

```bash
cd ../Web
pnpm install
pnpm dev
```

Vite 会拉起开发服务器；端口在 `Web/.env` 的 `VITE_PORT`（默认 **8888**），以终端输出为准。接口地址在 **`Web/.env.development`** 的 `VITE_API_URL`，默认 **`http://localhost:5005`**，须与正在运行的 `Admin.NET.Web.Entry` 一致。

登录页一般为 **hash 路由**下的 `#/login`。仓库内默认演示账号见 `Web/.env.development` 中的 `VITE_DEFAULT_USER` / `VITE_DEFAULT_USER_PASSWORD`（若与你们库中种子数据不一致，以数据库 `sys_user` 为准）。

若希望浏览器**只打开一个地址**（例如根路径即管理端），需要把 `Web` 构建产物托管进后端的 `wwwroot` 并调整静态文件/首页路由；本仓库当前文档**不**展开该部署方式，团队可按需自行补充 CI 与 `Startup` 配置。

**底座冒烟（团队自检）**：先启动 `Admin.NET.Web.Entry`，再在本节命令启动官方 `Web`；确认能登录、左侧菜单加载、点开系统相关菜单（如审批流程）无整页白屏。若菜单有入口但页面空白，优先核对库表 `sys_menu.component` 与 `Web/src/views` 下路径是否一致（含是否多写了前导 `/`）。

## 6. 构建验证

在已安装 **.NET 8+** SDK 的机器上（默认当前目录为 **`ai-dop-platform/`**；若在主库根目录，将 `../server` 改为 `server`）：

```bash
dotnet restore ../server/Admin.NET.sln
dotnet build ../server/Admin.NET.sln -c Release
```

若首次编译出现 `NETSDK1004`（找不到 `project.assets.json`），请先执行上一行的 `dotnet restore` 再构建。

（当前 CI/本机若仅有 .NET 6 SDK 会报错，需升级 SDK。）

## 7. 团队 Cursor 规则

仓库根目录 `.cursor/rules/` 下：

- `project.mdc`：全局边界与协作。
- `csharp.mdc`：插件与 C# 约定。
- `vue.mdc`：Demo 前端约定。

请将 Cursor 工作区根目录设为 **主库内的 `ai-dop-platform/`**（本机若使用 `SourceCode/ai-dop-platform`，可为指向该目录的 **junction**，与主库内文件夹为同一内容），或直接打开 **主库根目录**，以便规则与路径一致。

## 8. 自动验证与提交门禁（推荐启用）

本仓库已增加以下能力：

- Cursor 默认按“改完即验证、失败即修复再验证”的闭环执行（见 `.cursor/rules/auto-verify-fix-loop.mdc`）。
- 主库根下 `Web/` 已配置 `prepare`，安装依赖时自动写入 `pre-push` hook。

团队成员首次拉代码后，建议执行：

```bash
cd ../Web
npm install
```

若此前已安装过依赖，可手动执行：

```bash
npm run prepare
```

详细说明见：`docs/CURSOR_AUTOVERIFY_AND_HOOKS.md`。  
新同事从零接入请看：`docs/NEW_MEMBER_ONBOARDING_ZERO_TO_ONE.md`。