System项目AI文档

Appearance

系统集成场景分析 ​

文档编号：SYS-DES-BA-006
文档版本：1.0
创建日期：2026-03-08
文档作者：架构师
文档状态：✅ Reviewed and Approved（2026-03-08）

1. 概述 ​

1.1 文档目的 ​

本文档分析System基础平台与外部系统的集成场景，明确集成需求、数据流转和异常处理策略，为系统集成设计提供场景化指导。

1.2 输入文档 ​

  • 核心业务流程分析（SYS-DES-BA-003）
  • 业务规则梳理（SYS-DES-BA-004）
  • System系统业务需求文档（BRD）V1.1
  • 现有系统架构资料

1.3 集成系统清单 ​

系统名称系统类型集成方式集成优先级
HR系统内部系统API + 消息队列P0
ERP系统内部系统APIP1
OA系统内部系统API + SSOP1
CRM系统内部系统APIP2
财务系统内部系统APIP2
邮件服务外部服务SMTP/IMAPP0
短信服务外部服务HTTP APIP1
文件存储外部服务S3/OSS APIP1

2. HR系统集成场景 ​

2.1 员工入职同步 ​

场景2.1.1：新员工入职自动开户 ​

场景描述：HR系统中员工入职审批通过后，自动在System平台创建用户账号

集成方式：消息队列（异步）

触发条件：

  • HR系统中员工入职审批通过
  • 员工信息完整且有效

数据流向：

HR系统 → 消息队列 → System平台 → 用户创建 → 通知发送

场景步骤：

步骤操作方操作内容数据内容
1HR系统入职审批通过员工信息
2HR系统发送入职事件EmployeeEntryEvent
3消息队列事件入队消息持久化
4System平台消费入职事件解析员工数据
5System平台检查用户是否存在员工编号查询
6System平台创建用户账号用户信息
7System平台分配默认角色普通用户角色
8System平台分配主部门部门映射
9System平台生成初始密码随机密码
10System平台发送通知邮件账号信息
11System平台确认消息消费ACK确认

数据映射：

HR字段System字段转换规则
employee_noemployee_no直接映射
namereal_name直接映射
emailemail直接映射
mobilemobile直接映射
department_codedept_id部门编码映射
positionposition直接映射
entry_dateentry_date日期格式转换

业务规则：

  • BR-INT-001: 员工入职后24小时内必须完成账号创建
  • BR-INT-002: 如用户已存在则更新员工状态为在职
  • BR-INT-003: 初始密码必须满足复杂度要求
  • BR-INT-004: 账号创建成功后必须发送通知邮件

异常处理：

异常场景处理策略补偿机制
消息消费失败重试3次，间隔5分钟死信队列，人工处理
部门映射失败记录错误，分配默认部门管理员手动调整
邮件发送失败记录日志，不重试管理员手动补发
用户创建失败记录错误，不消费消息人工排查后重试

幂等性保证：

  • 使用员工编号作为幂等键
  • 重复消息不重复创建用户
  • 更新操作覆盖原有数据

场景2.1.2：员工信息变更同步 ​

场景描述：HR系统中员工信息变更后，同步更新System平台用户信息

集成方式：消息队列（异步）

触发条件：

  • HR系统中员工关键信息变更
  • 变更字段涉及：姓名、部门、职位、邮箱、手机号

场景步骤：

步骤操作方操作内容数据内容
1HR系统员工信息变更变更字段
2HR系统发送变更事件EmployeeChangedEvent
3System平台消费变更事件解析变更数据
4System平台查询现有用户员工编号查询
5System平台比对变更字段差异分析
6System平台更新用户信息增量更新
7System平台记录变更日志审计日志
8System平台通知用户（如必要）变更通知

可变更字段：

  • 姓名（real_name）
  • 部门（dept_id）
  • 职位（position）
  • 邮箱（email）- 需校验唯一性
  • 手机号（mobile）- 需校验唯一性

不可变更字段：

  • 员工编号（employee_no）
  • 用户名（username）
  • 用户ID（user_id）

2.2 员工离职同步 ​

场景2.2.1：员工离职自动禁用账号 ​

场景描述：HR系统中员工离职审批通过后，自动禁用System平台账号

集成方式：消息队列（异步）

触发条件：

  • HR系统中员工离职审批通过
  • 离职日期到达

数据流向：

HR系统 → 消息队列 → System平台 → 账号禁用 → 会话清理

场景步骤：

步骤操作方操作内容数据内容
1HR系统离职审批通过离职信息
2HR系统发送离职事件EmployeeResignEvent
3System平台消费离职事件解析离职数据
4System平台查询用户账号员工编号查询
5System平台禁用用户账号状态更新为DISABLED
6System平台撤销所有TokenToken失效
7System平台清理用户会话会话销毁
8System平台更新员工状态状态更新为RESIGNED
9System平台记录审计日志操作日志
10System平台通知管理员离职处理通知

业务规则：

  • BR-INT-005: 离职员工账号必须立即禁用
  • BR-INT-006: 禁用账号时所有Token立即失效
  • BR-INT-007: 离职员工历史数据保留
  • BR-INT-008: 离职处理必须记录审计日志

延迟离职处理：

场景处理策略
提前审批记录离职日期，到达日期自动处理
即时离职立即处理
离职取消撤销离职状态，恢复账号

2.3 组织架构同步 ​

场景2.3.1：部门变更同步 ​

场景描述：HR系统中组织架构变更后，同步更新System平台部门结构

集成方式：消息队列（异步）

触发条件：

  • HR系统中部门新增、修改、删除
  • HR系统中部门层级调整

场景步骤：

步骤操作方操作内容数据内容
1HR系统部门变更部门数据
2HR系统发送部门变更事件DepartmentChangedEvent
3System平台消费变更事件解析部门数据
4System平台部门映射转换编码映射
5System平台执行变更操作增删改
6System平台级联更新子部门树路径更新
7System平台更新部门用户部门关联更新
8System平台记录变更日志审计日志

变更类型处理：

变更类型处理逻辑注意事项
新增部门创建部门节点检查父部门存在性
修改部门更新部门信息编码不可修改
删除部门检查无用户后删除有用户则标记禁用
部门移动更新父部门和树路径级联更新子部门

3. ERP系统集成场景 ​

3.1 基础数据同步 ​

场景3.1.1：供应商/客户主数据同步 ​

场景描述：ERP系统中供应商或客户信息变更后，同步到System平台用于权限控制

集成方式：API（定时同步）

触发条件：

  • 定时任务触发（每日凌晨2点）
  • 手动触发同步

数据流向：

System平台 → API调用 → ERP系统 → 返回数据 → System平台处理

场景步骤：

步骤操作方操作内容数据内容
1System平台触发同步任务同步请求
2System平台调用ERP接口GET /api/partners
3ERP系统返回数据列表供应商/客户数据
4System平台解析响应数据数据转换
5System平台比对本地数据差异分析
6System平台增量更新数据增删改操作
7System平台记录同步日志同步结果
8System平台发送同步报告管理员通知

同步策略：

策略项配置
同步频率每日凌晨2:00
同步方式全量比对，增量更新
超时时间30秒
重试次数3次
失败处理记录日志，发送告警

4. OA系统集成场景 ​

4.1 单点登录（SSO） ​

场景4.1.1：OA系统免密登录System平台 ​

场景描述：用户已登录OA系统，点击链接免密跳转到System平台

集成方式：SSO Token（同步）

触发条件：

  • 用户已登录OA系统
  • 用户点击System平台链接

数据流向：

用户 → OA系统 → 生成SSO Token → 跳转System → 验证Token → 自动登录

场景步骤：

步骤操作方操作内容数据内容
1用户点击System链接访问请求
2OA系统生成SSO Token加密Token
3OA系统跳转System平台携带Token
4System平台接收SSO请求解析Token
5System平台验证Token有效性签名验证
6System平台验证Token时效时间戳检查
7System平台查询或创建用户用户映射
8System平台创建本地会话Token生成
9System平台跳转工作台登录成功

Token规范：

属性说明示例
用户标识OA系统用户唯一标识user_12345
时间戳Token生成时间1646723400
有效期Token有效时长5分钟
签名HMAC-SHA256签名abc123...

安全控制：

  • BR-INT-009: SSO Token有效期不超过5分钟
  • BR-INT-010: SSO Token只能使用一次
  • BR-INT-011: Token必须包含防篡改签名
  • BR-INT-012: 用户映射失败时拒绝登录

4.2 待办集成 ​

场景4.2.1：System待办同步到OA ​

场景描述：System平台产生的待办任务同步到OA系统统一展示

集成方式：API（实时推送）

触发条件：

  • System平台产生新的待办任务
  • 待办任务状态变更

场景步骤：

步骤操作方操作内容数据内容
1System平台待办任务创建待办数据
2System平台调用OA接口POST /api/todos
3OA系统接收待办数据数据解析
4OA系统创建待办记录数据存储
5OA系统返回处理结果成功/失败
6System平台记录同步状态同步日志

待办数据格式：

json
{
  "sourceSystem": "SYSTEM",
  "todoId": "todo_12345",
  "userId": "user_67890",
  "title": "审批申请",
  "content": "您有一条待审批的申请",
  "url": "https://system.example.com/approval/12345",
  "priority": "HIGH",
  "createTime": "2026-03-08T10:30:00Z",
  "expireTime": "2026-03-09T10:30:00Z"
}

5. 外部服务集成场景 ​

5.1 邮件服务集成 ​

场景5.1.1：系统通知邮件发送 ​

场景描述：系统需要向用户发送通知邮件（账号开通、密码重置等）

集成方式：SMTP（异步）

触发条件：

  • 用户账号创建成功
  • 用户申请密码重置
  • 系统告警通知

场景步骤：

步骤操作方操作内容数据内容
1System平台触发邮件发送邮件任务
2System平台邮件内容渲染HTML内容
3System平台发送SMTP请求SMTP协议
4邮件服务器接收邮件请求邮件队列
5邮件服务器发送邮件投递到收件箱
6邮件服务器返回发送结果成功/失败
7System平台记录发送日志发送记录

邮件模板：

模板名称使用场景关键变量
welcome账号开通username, password, loginUrl
reset_password密码重置resetUrl, expireTime
password_changed密码修改成功changeTime, ipAddress
login_alert异常登录提醒loginTime, ipAddress, location

失败处理：

失败类型重试策略告警方式
网络超时重试3次，间隔1分钟无
邮箱不存在不重试记录日志
邮箱已满重试1次，间隔1小时无
SMTP服务不可用重试5次，间隔5分钟发送告警

5.2 短信服务集成 ​

场景5.2.1：验证码短信发送 ​

场景描述：用户登录或敏感操作时需要短信验证码

集成方式：HTTP API（同步）

触发条件：

  • 用户开启短信二次验证
  • 敏感操作确认

场景步骤：

步骤操作方操作内容数据内容
1用户请求发送验证码手机号
2System平台生成验证码6位随机数字
3System平台保存验证码Redis缓存（5分钟）
4System平台调用短信APIPOST /api/sms/send
5短信服务商发送短信短信投递
6短信服务商返回发送结果发送状态
7System平台返回发送结果成功/失败

频率限制：

限制类型限制值说明
单手机号日限制10条防止短信轰炸
单IP日限制50条防止恶意调用
发送间隔60秒同一手机号间隔
验证码有效期5分钟过期需重新获取

5.3 文件存储集成 ​

场景5.3.1：用户头像上传 ​

场景描述：用户上传头像，存储到对象存储服务

集成方式：S3/OSS API（同步）

触发条件：

  • 用户上传头像文件

场景步骤：

步骤操作方操作内容数据内容
1用户选择头像文件图片文件
2System平台校验文件格式格式检查
3System平台校验文件大小大小检查（最大2MB）
4System平台生成文件路径用户ID/avatar/timestamp.jpg
5System平台上传文件到OSSPUT Object
6OSS服务存储文件文件持久化
7OSS服务返回文件URL访问地址
8System平台更新用户头像URL数据库更新
9System平台返回上传结果成功/失败

文件规范：

属性限制说明
格式JPG, PNG, GIF图片格式
大小最大2MB文件大小限制
尺寸建议200x200推荐尺寸
存储路径user/{userId}/avatar/按用户隔离
访问权限公开读允许公开访问

6. 集成异常处理 ​

6.1 异常分类 ​

异常类型说明示例
网络异常网络连接问题超时、断开
服务异常外部服务故障500错误、服务不可用
数据异常数据格式或内容问题格式错误、数据缺失
业务异常业务规则冲突重复数据、状态冲突
安全异常安全验证失败签名错误、Token过期

6.2 异常处理策略 ​

6.2.1 重试策略 ​

场景重试次数重试间隔退避策略
网络超时3次1秒固定间隔
服务不可用5次5秒指数退避
限流错误3次10秒固定间隔

6.2.2 降级策略 ​

场景降级方案用户体验
邮件服务不可用延迟发送，记录队列无感知
短信服务不可用切换备用通道可能有延迟
HR同步失败标记失败，人工处理数据可能延迟
SSO失败跳转登录页需手动登录

6.2.3 熔断策略 ​

指标阈值动作
错误率> 50%开启熔断
响应时间> 5秒开启熔断
熔断时长60秒自动恢复
半开请求数5个测试恢复

6.3 监控告警 ​

监控项阈值告警级别通知方式
集成失败率> 5%警告邮件
集成失败率> 20%严重邮件+短信
响应时间> 3秒警告邮件
响应时间> 10秒严重邮件+短信
消息堆积> 1000条警告邮件
消息堆积> 5000条严重邮件+短信

7. 集成安全要求 ​

7.1 传输安全 ​

要求项具体要求实现方式
传输加密所有接口使用HTTPSTLS 1.2+
证书验证验证服务端证书证书 pinning
敏感数据加密敏感字段额外加密AES-256

7.2 认证授权 ​

要求项具体要求实现方式
API认证所有API调用需认证API Key + Secret
请求签名请求参数签名防篡改HMAC-SHA256
Token时效Token有效期控制JWT过期时间
权限控制最小权限原则接口权限配置

7.3 数据安全 ​

要求项具体要求实现方式
数据脱敏日志中敏感数据脱敏正则替换
数据加密敏感数据存储加密AES加密
数据隔离不同系统数据隔离独立数据库/Schema
审计日志所有集成操作记录日志统一日志平台

8. 集成测试场景 ​

8.1 正常流程测试 ​

测试场景测试内容预期结果
员工入职同步模拟HR入职事件用户自动创建
员工离职同步模拟HR离职事件用户自动禁用
SSO登录模拟OA跳转免密登录成功
邮件发送触发邮件通知邮件成功发送
短信发送请求验证码短信成功发送

8.2 异常流程测试 ​

测试场景测试内容预期结果
HR系统不可用模拟HR服务宕机消息堆积，恢复后处理
重复入职事件发送重复入职消息幂等处理，不重复创建
Token过期使用过期SSO Token拒绝登录，跳转登录页
邮件发送失败模拟SMTP错误重试后记录失败
网络超时模拟网络超时重试机制生效

8.3 性能测试 ​

测试场景测试指标目标值
HR事件处理处理延迟< 5秒
SSO登录响应时间< 1秒
邮件发送发送延迟< 10秒
并发处理同时处理事件数> 100/秒

9. 附录 ​

9.1 集成接口清单 ​

系统接口名称接口类型调用方式文档链接
HR系统入职事件消息队列消费内部文档
HR系统离职事件消息队列消费内部文档
HR系统变更事件消息队列消费内部文档
ERP系统主数据查询APIHTTP GETAPI文档
OA系统SSO认证APIHTTP POST对接文档
OA系统待办推送APIHTTP POST对接文档
邮件服务SMTP发送SMTPTCP标准协议
短信服务短信发送APIHTTP POST服务商文档
文件存储文件上传APIHTTP PUTS3协议

9.2 消息队列Topic清单 ​

Topic名称用途生产者消费者
hr.employee.entry员工入职HR系统System平台
hr.employee.resign员工离职HR系统System平台
hr.employee.change员工变更HR系统System平台
hr.department.change部门变更HR系统System平台
system.user.change用户变更System平台其他系统

9.3 修订记录 ​

版本日期修订人修订内容
1.02026-03-08架构师初始版本

文档编制：架构师
文档审核：技术负责人
编制日期：2026-03-08

Released under the MIT License.

Copyright © 2026 linsir | 鄂ICP备99999999号