# build-flow.admin 对接 build-flow.api 指南

本文档记录新前端 `build-flow.admin`（Ant Design Pro v6 + React 19 + antd v6）与 .NET 10 后端 `build-flow.api` 的对接细节。

## 1. 后端关键信息

| 项 | 值 | 出处 |
|---|---|---|
| 全局 API 前缀 | `/api` | `BuildFlowHostModule.cs` 中 `config.Endpoints.RoutePrefix = "api"` |
| 本地监听端口 | `5200`（命令行 `--urls` 优先） | `run-dev.sh` |
| 登录接口 | `POST /api/auth/login` | `Endpoints/Platform/Auth/LoginEndpoint.cs` |
| 当前用户 | `GET /api/user/info` | `Endpoints/Platform/Auth/GetCurrentUserEndpoint.cs` |
| 用户菜单 | `GET /api/menu/all` | `Endpoints/Platform/Menus/GetAllMenusEndpoint.cs` |
| 菜单管理树 | `GET /api/menu/tree` | `Endpoints/Platform/Menus/GetMenuTreeEndpoint.cs` |
| Token 类型 | JWT (AccessToken) + HttpOnly Cookie (RefreshToken) | `LoginEndpoint.cs` |
| 响应信封 | `{ code: 200, message, data }` | `ApiResponseMiddleware` |
| 时间格式 | UTC 毫秒时间戳（FastEndpoints 序列化器配置） | `BuildFlowHostModule.cs` |
| 默认拒绝策略 | 任何未显式 `AllowAnonymous` 的端点都需登录 | `BuildFlowHostModule.cs` `FallbackPolicy` |

## 2. 前端启动

```bash
cd build-flow.admin
pnpm install
pnpm start                  # 默认 dev 模式，监听 http://localhost:8000
# 或：MOCK=none pnpm start  关闭 mock（推荐，避免 demo mock 拦截 /api）
```

代理：`config/proxy.ts` 默认把 `/api/**` 代理到 `http://localhost:5200`。
- 远程后端：`BUILDFLOW_API_TARGET=http://114.132.44.45:5200 pnpm start`

## 3. 后端启动（需 PG/Redis/MongoDB/RabbitMQ 等中间件已起）

```bash
cd build-flow.api
./run-dev.sh                 # 加载根 .env 后 dotnet run --urls http://localhost:5200
```

## 4. 联调登录清单

按以下顺序验证：

1. **后端 health**：`curl http://localhost:5200/api/auth/login -X POST -H "Content-Type: application/json" -d '{"username":"x","password":"y"}'` 应返回 200 或 400（业务校验错误），而非连接拒绝。
2. **前端代理**：`curl http://localhost:8000/api/auth/login -X POST -H "Content-Type: application/json" -d '{"username":"x","password":"y"}'` 应与上面响应一致。
3. **登录**：浏览器打开 `http://localhost:8000/user/login`，输入后端真实账号密码。
   - 成功：`services/ant-design-pro/api.ts` 的 `login()` 把 `accessToken` 写入 `localStorage`，触发 `window.location.href = redirectUrl` 整页刷新。
   - 失败：底部 toast 提示。
4. **getInitialState**：刷新后 `src/app.tsx` 检测 token，并行拉 `/user/info` + `/menu/all`，填充 `initialState.currentUser` 和 `initialState.menuRoutes`。
5. **菜单渲染**：`layout.menu.request` 把后端 `MenuRouteDto[]` 转成 `ProLayout MenuDataItem[]`（见 `src/utils/menuTransform.ts`）。
   - icon 字符串 `"home"` 会解析为 `<HomeOutlined />`。
   - `path` 与静态路由匹配时点击可跳；不匹配时点击进入 404（渐进迁移提示）。

## 5. 字段映射对照表

### 5.1 用户信息（GET /api/user/info → API.CurrentUser）

| 后端 CurrentUserInfo | 前端 API.CurrentUser | 说明 |
|---|---|---|
| UserId | userid | 字符串化 long |
| Username | username | 登录账号 |
| RealName | name, realName | 显示名 |
| Avatar | avatar | 预签名 URL（后端已签） |
| Desc | signature, desc | |
| Email | email | |
| Roles | roles, access | access 由 roles 推断（含 admin → 'admin'） |
| HomePath | homePath | 登录后落地页 |

### 5.2 菜单（GET /api/menu/all → API.MenuRoute → ProLayout MenuDataItem）

| 后端 MenuRouteDto | ProLayout 字段 | 说明 |
|---|---|---|
| name | name（作 i18n key，但本工程 locale:false 当文案兜底） | |
| path | path | |
| component | （忽略，由静态 routes.ts 决定） | |
| redirect | redirect | |
| children | routes | 递归转换 |
| meta.title | name（覆盖 i18n） | |
| meta.icon | icon（解析为 antd 图标） | |
| meta.hideInMenu | hideInMenu | |
| meta.link | target（外链） | |
| meta.authority | （前端暂不做按钮级权限，仅用 access.ts 做路由级） | |
| meta.order | （ProLayout 按数组顺序，需后端已 ORDER BY） | GetAllMenusQueryHandler 已 ORDER BY m.Order |
| meta.noBasicLayout | （ProLayout 用 layout: false，待补） | |
| meta.renderType | （BuildFlowForm 模式待补） | Phase 2 |

## 6. 已知限制（Phase 1）

- 静态 routes.ts 仅保留 `/welcome` + `/user/*` + `*`。后端菜单返回的 path 不在静态路由里时点击会 404。
  **后续每做一个业务模块，需要：**
  1. 在 `src/pages/` 下新建组件
  2. 在 `config/routes.ts` 加上 `{ path, component }`（不写 name/icon，让后端菜单控制）
- 后端菜单返回的 `path` 必须与静态路由的 `path` 完全一致（包括前导斜杠、大小写）。
- BuildFlowForm 类型菜单（renderType='BuildFlowForm'）的运行时表单渲染尚未实现。
- AccessToken 过期后用 RefreshToken（HttpOnly Cookie）调 `/auth/refresh` 自动续期的逻辑尚未实现（Vben 老前端有，可参考 `build-flow.web/apps/web-antdv-next/src/api/request.ts`）。

## 7. 改造文件清单

| 文件 | 改动 |
|---|---|
| `config/proxy.ts` | 加 dev/test/pre 代理到 5200 |
| `config/defaultSettings.ts` | title=BuildFlow, logo=/logo.svg |
| `config/config.ts` | title=BuildFlow |
| `config/routes.ts` | 简化为 login/welcome/404（业务路由后续补） |
| `src/services/ant-design-pro/typings.d.ts` | 重写 CurrentUser/LoginParams/LoginResult，加 MenuRoute/MenuMeta/ProMenuItem |
| `src/services/ant-design-pro/api.ts` | login→/auth/login, currentUser→/user/info, outLogin→清 token |
| `src/services/ant-design-pro/menu.ts` | 新建：getCurrentUserMenus, getMenuTree |
| `src/utils/menuTransform.ts` | 新建：MenuRouteDto → ProLayout MenuDataItem |
| `src/requestErrorConfig.ts` | JWT 注入、{ code, message, data } 解包、401 跳登录 |
| `src/access.ts` | 基于 roles 判断 canAdmin |
| `src/app.tsx` | 并行拉 user/info + menu/all，layout.menu.request 接入动态菜单 |