一、背景#

当前管理后台（/admin-one 和 /admin 路由）的全部接口都在 one_enterprise_api（Java Spring Boot）中，但前端侧需要对这些接口进行更频繁的迭代和扩展。为避免前后端协作瓶颈，计划将管理后台的核心 API 抽离为独立的 Node.js（NestJS）项目，逐步替代 Java 后端中的对应接口。

二、迁移范围#

先抽取 5 个路由组，共约 93 个 endpoint，涉及 16 个 Java Controller：

未包含的模块：考勤、文档、知识库、会议、日程、电子签、统计日志等非核心管理接口，仍由 Java 端提供。

三、技术选型#

四、鉴权方案（关键决策）#

1
请求 → RemoveVersionFilter (剥离 /v1/admin-one/ 前缀)
2
     → AuthorizationInterceptor
3
        → SSO gRPC 调用 (127.0.0.1:9207, SsoService.Verify)
4
           → 返回 user_uuid + team_uuid
5
        → 查本地 ddm_team_member 表获取 roleType
6
        → 注入 CurrentUser

1
请求 → NestJS Middleware (剥离版本号前缀，同 Java)
2
     → AuthGuard
3
        → gRPC 调用 SsoService.Verify(token)
4
           → 地址: 127.0.0.1:9207
5
           → Proto: proto/sso.proto
6
           → 入参: VerifyParam { token }
7
           → 出参: VerifyResponse { status, data: Token { user_uuid, team_uuid } }
8
        → status === 0 时，查本地 ddm_team_member 表获取 roleType
9
        → 注入 Request (userUuid, teamUuid, roleType)

1
service SsoService {
2
  rpc Verify(VerifyParam) returns (VerifyResponse);
3
}
4

5
message VerifyParam {
6
  string token = 1;
7
}
8

9
message VerifyResponse {
10
  int64 status = 1;     // 0 成功，非 0 失败
11
  string message = 2;
12
  Token data = 3;
13
}
14

15
message Token {
16
  string user_uuid = 1;
17
  string team_uuid = 6;
18
}

五、涉及的数据表#

六、现有 Java 服务中的外部依赖#

NestJS 项目需要处理以下依赖：

待确认项：

1. IUserInfoService 数据来源：Java 代码中大量调用此服务获取用户姓名、手机、头像等信息。需要确认数据来自哪里（gRPC 服务 / 另一张数据库表 / 外部 API）。如果也在 MySQL 中，需要补充对应的 Prisma model。

2. gRPC 调用范围：部分 endpoint 可能涉及其他 gRPC 服务（IM、日程、文档空间等）。需要确认本次 5 个路由组中哪些 endpoint 实际依赖了这些外部服务。

七、API 响应格式#

保持与 Java 端一致的 ResponseDTO 格式：

1
{
2
  "status": 0,
3
  "message": "ok",
4
  "data": { ... }
5
}

列表接口统一包装：

1
{
2
  "status": 0,
3
  "message": "ok",
4
  "data": { "list": [...] }
5
}

失败响应：

1
{
2
  "status": 1,
3
  "message": "错误信息",
4
  "data": {},
5
  "errDetail": { "uri": "...", "ip": "...", "qmpLogId": "..." }
6
}

八、URL 路由兼容#

前端现有请求格式：POST /v1/admin-one/Team/showTeamMember

NestJS 中间件处理（复刻 Java RemoveVersionFilter 逻辑）：

1
/v1/admin-one/Team/showTeamMember  →  /Team/showTeamMember
2
/v1/admin-one/team/getTeamInfoBasic →  /team/getTeamInfoBasic
3
/enterprise/admin-one/contact/xxx   →  /contact/xxx (带 enterprise 标记)

配置规则（同 Java application.base.yml）：

1
^(/v\d+)?/(admin-one|app)/  →  /
2
/enterprise/admin-one/      →  /  (并标记 enterprise=true)

前端无需改动 URL，只需将 API 网关/反向代理指向新的 NestJS 服务即可。

九、项目结构#

1
nestjs-admin/
2
├── prisma/
3
│   └── schema.prisma          # 数据库 schema
4
├── proto/
5
│   └── sso.proto              # SSO gRPC proto（从 Java 端拷贝）
6
├── src/
7
│   ├── main.ts                # 入口，端口 12000
8
│   ├── app.module.ts
9
│   ├── common/
10
│   │   ├── guards/auth.guard.ts           # SSO gRPC 鉴权
11
│   │   ├── filters/exception.filter.ts    # 全局异常处理
12
│   │   ├── interceptors/response.interceptor.ts
13
│   │   ├── decorators/public-access.decorator.ts
14
│   │   └── middlewares/url-prefix.middleware.ts  # URL 前缀剥离
15
│   ├── team/                  # /Team + /team 路由组
16
│   ├── contact/               # /contact 路由组
17
│   ├── user/                  # /User 路由组
18
│   └── sub-manager/           # /subManager 路由组
19
├── package.json
20
└── tsconfig.json

十、实施计划#

十一、风险与缓解#

十二、需要的后端配合#

1. 确认 IUserInfoService 的数据来源和查询方式（最关键）
2. 确认本次 5 个路由组中是否有 endpoint 依赖了其他 gRPC 服务（IM、日程、文档等）
3. 确认 SSO gRPC 服务地址（当前是 127.0.0.1:9207，生产环境可能不同）
4. 协助 review 关键 SQL 查询（特别是部门树、权限相关的复杂查询）