build-flow/build-flow.admin
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity
build-flow.admin/docs/BACKEND_INTEGRATION.md
向宁 0a7842bd43 chore: establish react pro baseline
2026-07-23 17:16:04 +08:00

6.0 KiB
Raw Permalink Blame History

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. 前端启动

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 等中间件已起）

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 接入动态菜单