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

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

接口	方法	路径	说明
健康检查	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	通过工号匹配用户

npm install

复制 .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

开发模式（热重载）：

npm run dev

生产模式：

npm run build
npm start

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

在 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

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

{
  "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	技术总监	研发中心

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。

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

说明：该接口会：

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

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

匹配逻辑：

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

请求示例：

{
  "Username": "e011891"
}

响应示例：

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

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

工作流程：

1. 接收 CodeBuddy 用户 ID（如 da7dc1b0-439f-42f8-902e-acaba3c88714）
2. 调用 CodeBuddy API: GET /api/v1/enterprises/{enterprise_id}/users?keyword={id}
3. 从 CodeBuddy 响应中获取用户的 nickname（工号）
4. 使用工号匹配本地成员的 employee_number
5. 返回本地成员的完整信息（包括所属部门），但 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": [...]  // 所属部门信息
  }
}

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

• 请求 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": {...}}

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

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

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

服务器信息：

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

部署步骤：

1. 将代码上传到服务器
2. 复制并配置 .env 文件
3. 安装依赖：npm install
4. 构建项目：npm run build
5. 启动服务：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

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

• 运行时: 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           # 入口文件

MIT