shouqianceshi/codebuddy-org-bridge

Public

WeChat Login

Code Issues Pull requests Events Packages Insights

master

Branch

Tag

余朋飞

Initial commit: CodeBuddy organization sync service with API integration

a31be485

1 commit

.codebuddy
src
.env.example
.gitignore
README.md
package-lock.json
package.json
tsconfig.json

CodeBuddy 第三方组织架构同步服务

基于 CodeBuddy Custom Provider 规范实现的组织架构同步服务，支持与 CodeBuddy 平台的深度集成。

功能特性

完整的组织架构管理（部门树、成员信息）
支持 CodeBuddy 标准 API 接口
Bearer Token 鉴权
支持精准/模糊搜索
分页查询支持
CodeBuddy API 集成：通过工号自动匹配 CodeBuddy 用户与本地组织架构
详细的请求日志：记录完整的请求/响应信息，便于调试
静态 JSON 数据，易于扩展

API 接口列表

接口	方法	路径	说明
健康检查	GET	`/org/health`	验证服务可用性（无需鉴权）
获取部门树	GET	`/org/nodes`	获取完整组织架构
获取单个部门	GET	`/org/nodes/:id`	获取部门详情
批量获取部门	POST	`/org/nodes/batch`	批量查询部门
子部门列表	GET	`/org/nodes/:id/children`	获取直接子部门
部门成员列表	GET	`/org/nodes/:id/members`	分页获取部门成员
路径解析节点	GET	`/org/path`	根据路径查找部门
搜索	GET	`/org/search`	支持精准/模糊搜索部门或用户
用户详情	GET	`/org/users/:id`	通过 CodeBuddy API 查询用户并匹配本地架构
刷新缓存	POST	`/org/cache/refresh`	刷新数据缓存
同步状态	GET	`/org/sync/status`	查看同步状态
解析成员	POST	`/org/members/resolve`	通过工号匹配用户

快速开始

1. 安装依赖

npm install

2. 配置环境变量

复制 .env.example 为 .env：

cp .env.example .env

编辑 .env 文件：

# 服务配置
PORT=3000
NODE_ENV=development

# 鉴权配置（CodeBuddy 配置中使用的 auth_token）
AUTH_TOKEN=your-secret-token-here

# 企业配置
ENTERPRISE_ID=ent-demo

# CodeBuddy API 配置（用于 /org/users/:id 接口）
CODEBUDDY_SERVICE_HOST=https://your-enterprise.copilot-staging.qq.com
CODEBUDDY_API_TOKEN=your-api-token-here

3. 启动服务

开发模式（热重载）：

npm run dev

生产模式：

npm run build
npm start

服务启动后，访问 http://localhost:3000 查看服务信息。

CodeBuddy 配置

在 CodeBuddy 后台 <企业id>.copilot.qq.com/admin → 开放与集成 → 组织架构同步 中配置：

{
  "name": "custom-org",
  "base_url": "http://your-server:3000",
  "enterprise_id": "ent-demo",
  "timeout_seconds": 15,
  "auth_token": "your-secret-token-here",
  "extra_headers": {
    "X-From": "org-service"
  },
  "success_code": 0
}

重要配置项：

base_url: 你的服务地址（必填）
auth_token: 鉴权令牌，必须与 .env 中的 AUTH_TOKEN 一致
success_code: 响应成功码，默认 0

数据结构

组织节点 (OrgNode)

{
  "id": "dept-rd",
  "name": "研发中心",
  "display_name": "研发中心",
  "parent_id": "root",
  "full_path": "/科技有限公司/研发中心",
  "has_child": true,
  "member_count": 80,
  "user_count": 65,
  "order": 1
}

成员 (OrgMember)

{
  "id": "u-001",
  "name": "zhangsan",
  "display_name": "张三",
  "email": "zhangsan@company.com",
  "mobile": "13800138001",
  "employee_number": "EMP001",
  "title": "技术总监",
  "department_path": ["科技有限公司", "研发中心", "后端开发部", "Java组"],
  "is_leader": true,
  "status": "active"
}

模拟数据

项目内置了完整的模拟数据：

组织架构: 15 个部门，包含研发中心、产品中心、销售中心等
成员信息: 22 名员工，包含各种职位和状态

数据文件位置：

src/data/org-nodes.json - 部门数据
src/data/members.json - 成员数据

关键员工示例

姓名	工号	职位	部门
余朋飞	EMP021	技术架构师	研发中心/后端开发部
叶泰林	e011891	后端工程师	研发中心/后端开发部
张三	EMP001	技术总监	研发中心

API 使用示例

健康检查

curl http://localhost:3000/org/health

获取部门树

curl -H "Authorization: Bearer your-token" \
  http://localhost:3000/org/nodes

搜索用户（模糊搜索）

curl -H "Authorization: Bearer your-token" \
  "http://localhost:3000/org/search?type=user&fuzzy=true&keyword=zhang"

搜索用户（精准搜索）

curl -H "Authorization: Bearer your-token" \
  "http://localhost:3000/org/search?type=user&fuzzy=false&keyword=zhangsan@company.com"

获取部门成员

curl -H "Authorization: Bearer your-token" \
  "http://localhost:3000/org/nodes/dept-rd/members?limit=10&offset=0"

解析成员（通过工号）

curl -X POST -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{"Username": "e011891"}' \
  http://localhost:3000/org/members/resolve

说明：该接口根据 Username 字段（工号）匹配本地成员的 employee_number。

获取用户详情（CodeBuddy 集成）

curl -H "Authorization: Bearer your-token" \
  "http://localhost:3000/org/users/da7dc1b0-439f-42f8-902e-acaba3c88714?enterprise_id=ent-demo"

说明：该接口会：

调用 CodeBuddy API 根据用户 ID 查询用户信息
获取 CodeBuddy 用户的 nickname（工号）
根据工号匹配本地成员的 employee_number
返回本地成员详情，但使用 CodeBuddy 的用户 ID

核心功能说明

1. 成员解析（/org/members/resolve）

该接口用于通过工号匹配用户信息。

匹配逻辑：

使用请求参数 Username 匹配本地成员的 employee_number 字段
匹配时不区分大小写
如果找不到匹配的用户，返回 404 错误

请求示例：

{
  "Username": "e011891"
}

响应示例：

{
  "code": 0,
  "message": "ok",
  "data": {
    "member": {
      "id": "u-021",
      "name": "yetailin",
      "display_name": "叶泰林",
      "employee_number": "e011891",
      "title": "后端工程师",
      ...
    }
  }
}

2. 用户详情（/org/users/:id）

该接口集成 CodeBuddy API，实现跨平台用户匹配。

工作流程：

接收 CodeBuddy 用户 ID（如 da7dc1b0-439f-42f8-902e-acaba3c88714）
调用 CodeBuddy API: GET /api/v1/enterprises/{enterprise_id}/users?keyword={id}
从 CodeBuddy 响应中获取用户的 nickname（工号）
使用工号匹配本地成员的 employee_number
返回本地成员的完整信息（包括所属部门），但 id 字段使用 CodeBuddy 的 ID

配置要求：

需要在 .env 中配置 CODEBUDDY_SERVICE_HOST 和 CODEBUDDY_API_TOKEN
如果未配置，接口会降级为直接查询本地数据

响应示例：

{
  "code": 0,
  "message": "ok",
  "data": {
    "member": {
      "id": "da7dc1b0-439f-42f8-902e-acaba3c88714",  // CodeBuddy ID
      "name": "yetailin",
      "display_name": "叶泰林",
      "employee_number": "e011891",
      ...
    },
    "nodes": [...]  // 所属部门信息
  }
}

3. 详细日志记录

服务内置了完整的请求日志中间件，记录：

请求 URL、Method、Query、Headers、Body
响应状态码、耗时、Body
每个请求分配唯一的 requestId 便于追踪

日志示例：

[2025-01-30T10:30:45.123Z] [a1b2c3d4] ==================== REQUEST ====================
[a1b2c3d4] Method: POST
[a1b2c3d4] URL: http://localhost:9000/org/members/resolve
[a1b2c3d4] Body: {"Username": "e011891"}
[a1b2c3d4] ==================== RESPONSE ===================
[a1b2c3d4] Status: 200
[a1b2c3d4] Duration: 15ms
[a1b2c3d4] Body: {"code": 0, "message": "ok", "data": {...}}

扩展开发

接入真实数据源

修改 src/data/dataStore.ts 中的数据加载逻辑
替换静态 JSON 加载为数据库/API 查询
保持接口不变，CodeBuddy 无需修改配置

添加新字段

在 src/types/index.ts 中更新类型定义
在数据文件中添加对应字段
控制器会自动透传新字段

部署配置

生产环境部署

项目已配置为可部署到远程服务器。参考配置：

服务器信息：

地址：120.79.95.108
部署目录：/data/app/codebuddy-org-sync
端口：9000

部署步骤：

将代码上传到服务器
复制并配置 .env 文件
安装依赖：npm install
构建项目：npm run build
启动服务：npm start

生产环境变量示例：

PORT=9000
NODE_ENV=production
AUTH_TOKEN=test-token-12345
ENTERPRISE_ID=your-enterprise-id
CODEBUDDY_SERVICE_HOST=https://1229miliiwang.copilot-staging.qq.com
CODEBUDDY_API_TOKEN=your-production-token

注意事项

鉴权: 除 /org/health 外，所有接口都需要 Authorization: Bearer <token> 请求头
工号匹配: /org/members/resolve 和 /org/users/:id 都依赖工号（employee_number）进行匹配
CodeBuddy 集成: /org/users/:id 需要配置 CodeBuddy API 才能正常工作，否则会降级为本地查询
搜索: 搜索接口必须同时支持精准搜索 (fuzzy=false) 和模糊搜索 (fuzzy=true)
分页: 成员列表接口支持分页，默认每页 20 条
响应格式: 统一返回 { code, message, data } 格式
日志: 所有请求都会被详细记录，便于排查问题

技术栈

运行时: Node.js 18+
语言: TypeScript 5.x
Web 框架: Express.js 4.x
数据存储: 静态 JSON 文件
外部集成: CodeBuddy API (可选)
中间件:
- helmet - 安全增强
- cors - 跨域支持
- 自定义鉴权中间件
- 自定义日志中间件

项目结构

src/
├── controllers/        # 控制器（业务逻辑）
│   └── orgController.ts
├── data/              # 静态数据文件
│   ├── dataStore.ts   # 数据管理类
│   ├── members.json   # 成员数据
│   └── org-nodes.json # 组织架构数据
├── middleware/        # 中间件
│   ├── auth.ts        # Bearer Token 鉴权
│   ├── errorHandler.ts # 错误处理
│   └── logger.ts      # 请求日志记录
├── routes/            # 路由定义
│   └── org.ts
├── types/             # TypeScript 类型定义
│   └── index.ts
└── index.ts           # 入口文件