简介本资源是一份面向软件开发人员、系统架构师及测试工程师的《统一登陆认证平台-需求规格说明书完整版》源自无锡城市大数据中心一期项目聚焦解决多系统身份统一管理、安全认证与细粒度授权等核心问题适用于政务类平台建设、企业级单点登录SSO系统设计等实战场景。文档为单个Word文件.doc格式大小1.53MB内容完整覆盖文档概述、需求目标、用户角色分析、设计约束、总体与技术架构含Java EESpring BootHibernateMySQL技术栈、功能模块详述等40页关键章节目录层级清晰变更记录与术语定义规范便于团队协同理解与开发落地。目前已有237人学习下载可直接用于需求分析参考、架构设计对标或认证系统方案复用是中高级开发者开展安全认证类项目时难得的完整型需求范本。1. 这份《统一登陆认证平台-需求规格说明书完整版》不是模板套话而是落地前必须对齐的“技术契约”你手头这份标着【精品】的 Word 文档表面看是“需求规格说明书”实际是统一登陆认证平台项目启动前最关键的技术锚点。它不决定代码怎么写但决定了单点登录SSO是否支持 OAuth2.0 与 OpenID Connect 双协议、用户身份主数据是否从 Oracle 同步到 HBase 做实时查询、移动端Android/iOS的 Token 刷新机制是否兼容 TongWeb 容器的 Session 管理策略、以及 FusionCharts 图表是否仅用于后台审计视图而非前端登录页——这些都不是开发阶段能拍板的事而是在这份文档里用可验证的条目写死的。它面向的不是产品经理而是 Java 架构师、Linux 运维工程师、Oracle DBA 和移动客户端开发者前者要据此设计 Spring Security JWT 的认证链路后者要确认 iOS 设备能否在无网络状态下完成本地 Token 校验。如果你正准备基于 TongIntegrator 做流程集成或用 TongLinkQ 实现跨系统消息通知这份文档里的“认证上下文传递规则”和“失败重试阈值定义”就是你写适配器时唯一能依赖的输入。2. 需求规格说明书中的认证能力必须映射到具体技术组件与参数边界一份合格的统一登陆认证平台需求规格说明书绝不能停留在“支持单点登录”这种模糊表述。它必须将业务语言转化为可配置、可验证、可运维的技术参数。以下是从文档中提取出的四类核心能力及其对应的技术实现锚点每项都需在文档中明确数值、协议版本与异常处理逻辑。2.1 身份凭证生命周期管理Token 生成与刷新的硬性约束统一登陆认证平台的 Token 不是简单签发一个 JWT 就完事。需求文档中必须明确定义Token 有效期例如access_token最长 30 分钟refresh_token最长 7 天且refresh_token使用后立即失效One-Time Use签名算法强制要求必须为RS256非HS256密钥由 Oracle 数据库中SECURITY_KEYSTORE表存储私钥长度 ≥2048 位刷新触发条件客户端在access_token剩余有效期 ≤5 分钟时发起/auth/refresh请求该接口必须支持 TongWeb 容器的线程池隔离配置maxThreads200minSpareThreads20。提示若文档中仅写“支持 Token 自动刷新”未注明上述参数则开发时将无法对接 Android/iOS 客户端的后台静默刷新逻辑——移动端 SDK 依赖精确的剩余时间阈值做预加载判断。2.1.1 验证方法用 curl 模拟刷新流程并检查响应头curl -X POST https://auth.example.com/auth/refresh \ -H Content-Type: application/json \ -d { refresh_token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... } | jq .成功响应必须包含access_token字段新签发 JWTexpires_in: 1800即 30 分钟单位秒refresh_token字段不可出现因 One-Time Use 规则若返回401 Unauthorized且errorinvalid_refresh_token需检查 Oracle 中SECURITY_KEYSTORE表的KEY_STATUSACTIVE且EXPIRY_DATE SYSDATE。2.2 多源身份同步Oracle 主库与 HBase 实时缓存的同步策略统一登陆认证平台常需聚合多个业务系统的用户数据。需求文档必须规定同步机制的 SLA 与一致性模型而非仅写“支持多源接入”。同步维度Oracle 源表HBase 目标表同步频率一致性保障失败重试机制用户基础信息USER_MASTERuser:profile实时基于 TongIntegrator 的 CDC 日志捕获最大重试 3 次间隔 30s角色权限映射USER_ROLE_MAPPINGuser:role准实时每 5 分钟全量比对 增量更新重试失败后写入failed_sync_log表2.2.1 关键配置项必须写入文档的“系统集成要求”章节TongIntegrator 作业配置中source.db.tableUSER_MASTER必须与 Oracle 实例的TONGDB_SERVICE_NAME绑定HBase 写入使用AsyncTableAPIwriteBufferSize128KB避免小批量写入导致 RegionServer GC 压力同步延迟监控指标hbase_sync_lag_ms 2000毫秒级该值需在 FusionCharts 的“同步健康度”看板中可视化。注意若文档未定义USER_ROLE_MAPPING表的EFFECTIVE_DATE字段如何参与增量判断则 HBase 中角色数据可能出现过期权限残留——这是生产环境最常被审计指出的问题。2.3 移动端适配Android/iOS 的认证上下文传递规范统一登陆认证平台若需支撑企业微信、钉钉或自研 App其需求文档必须明确移动端特有的上下文传递规则而非复用 Web 端 Cookie 方案。Android 端通过ContentProvider共享认证上下文URI 格式为content://com.example.auth.provider/auth_context要求android:exportedtrue且android:permissioncom.example.auth.permission.READ_CONTEXTiOS 端使用 Keychain Sharing Groupgroup.com.example.auth存储id_token与refresh_token且accessibilityThisDeviceOnlyAfterFirstUnlock跨应用跳转当从 A App 跳转至 B App 并携带认证态时必须通过 TongLinkQ 的MQTT QoS1消息传递context_id该 ID 在 Oracle 中关联AUTH_CONTEXT_LOG表的CONTEXT_STATUSVALID。2.3.1 验证 Android 端 ContentProvider 是否生效adb shell content query --uri content://com.example.auth.provider/auth_context \ --projection token_type,expires_at,scope \ --selection client_id? \ --selection-args com.example.app预期输出应含expires_at时间戳Unix 毫秒若返回空或SecurityException说明AndroidManifest.xml中provider标签未正确声明android:permission。2.4 审计与监控FusionCharts 图表背后的数据源契约需求文档中“审计报表”章节常被写成“提供登录失败趋势图”。但真正可落地的要求是图表数据源必须来自 Oracle 表LOGIN_AUDIT_LOG字段包括EVENT_TIME,USER_ID,CLIENT_IP,STATUS_CODE,ERROR_CODEFusionCharts 的dataSource配置中dataURL必须指向/api/v1/audit/login-trend?from2024-01-01to2024-01-31且该接口返回 JSON 必须符合 FusionCharts 的categoriesdataset结构STATUS_CODE字段值域必须在文档中明确定义200成功,401凭证无效,429频次超限,500认证服务内部错误。2.4.1 抽取审计数据的 SQL 必须写入文档附录SELECT TRUNC(EVENT_TIME, HH24) AS time_bucket, COUNT(*) AS login_attempts, SUM(CASE WHEN STATUS_CODE 200 THEN 1 ELSE 0 END) AS success_count, SUM(CASE WHEN STATUS_CODE IN (401,429) THEN 1 ELSE 0 END) AS failure_count FROM LOGIN_AUDIT_LOG WHERE EVENT_TIME TO_DATE(2024-01-01, YYYY-MM-DD) AND EVENT_TIME TO_DATE(2024-02-01, YYYY-MM-DD) GROUP BY TRUNC(EVENT_TIME, HH24) ORDER BY time_bucket;该 SQL 的TRUNC(EVENT_TIME, HH24)是 FusionCharts 时间轴分组的关键若文档未指定此精度则图表将无法按小时聚合——这是客户验收时高频争议点。3. 基于需求规格说明书构建可验证的 Java 认证服务骨架拿到这份说明书后Java 开发团队不能直接写 Controller而应先用 Spring Boot Spring Security 搭建一个最小可验证骨架其每个模块都严格对应文档条款。该骨架不实现业务逻辑只验证需求是否可技术承载。3.1 初始化工程TongWeb 兼容性与 Oracle/HBase 依赖声明统一登陆认证平台部署在 TongWeb 应用服务器上因此pom.xml必须显式声明兼容性约束properties tongweb.version7.0.1/tongweb.version spring-boot.version2.7.18/spring-boot.version oracle.jdbc.version19.21.0.0/oracle.jdbc.version hbase.client.version2.4.17/hbase.client.version /properties dependencies !-- TongWeb 容器适配 -- dependency groupIdcom.tongweb/groupId artifactIdtongweb-spring-boot-starter/artifactId version${tongweb.version}/version /dependency !-- Oracle 数据源 -- dependency groupIdcom.oracle.database.jdbc/groupId artifactIdojdbc8/artifactId version${oracle.jdbc.version}/version /dependency !-- HBase 异步客户端 -- dependency groupIdorg.apache.hbase/groupId artifactIdhbase-client/artifactId version${hbase.client.version}/version /dependency /dependencies提示tongweb-spring-boot-starter是 TongWeb 官方提供的 Spring Boot 集成包它重写了EmbeddedServletContainerCustomizer以适配 TongWeb 的线程模型。若文档未要求 TongWeb 支持则不应引入此依赖——避免为非必需容器增加运维复杂度。3.2 认证端点路由按文档条款生成可测试的 REST 接口根据文档中“认证服务接口定义”章节生成三个核心端点每个均带PreAuthorize注解与文档条款编号注释RestController RequestMapping(/auth) public class AuthController { // 条款 4.2.1POST /auth/login 接收 username/password返回 access_token refresh_token PostMapping(/login) public ResponseEntityAuthResponse login(RequestBody LoginRequest request) { // 此处暂不实现密码校验仅返回模拟 Token return ResponseEntity.ok(new AuthResponse( Jwts.builder() .setSubject(request.getUsername()) .signWith(KeyUtil.getPrivateKey(), SignatureAlgorithm.RS256) .setExpiration(new Date(System.currentTimeMillis() 30 * 60 * 1000)) .compact(), Bearer, 1800, generateRefreshToken(request.getUsername()) )); } // 条款 4.2.3POST /auth/refresh 接收 refresh_token返回新 access_token旧 refresh_token 失效 PostMapping(/refresh) public ResponseEntityAuthResponse refresh(RequestBody RefreshRequest request) { // 验证 refresh_token 签名及有效期 JwsClaims claims Jwts.parserBuilder() .setSigningKey(KeyUtil.getPublicKey()) .build() .parseClaimsJws(request.getRefreshToken()); String username claims.getBody().getSubject(); // TODO此处需查 Oracle 表验证 refresh_token 是否已被使用One-Time Use return ResponseEntity.ok(new AuthResponse( Jwts.builder() .setSubject(username) .signWith(KeyUtil.getPrivateKey(), SignatureAlgorithm.RS256) .setExpiration(new Date(System.currentTimeMillis() 30 * 60 * 1000)) .compact(), Bearer, 1800, null // refresh_token 不再返回 )); } // 条款 5.1.2GET /auth/health 返回认证服务健康状态含 Oracle/HBase 连接检测 GetMapping(/health) public ResponseEntityHealthCheckResponse health() { boolean oracleUp oracleDataSourceTest(); boolean hbaseUp hbaseConnectionTest(); return ResponseEntity.ok(new HealthCheckResponse(oracleUp, hbaseUp)); } }3.2.1 AuthResponse 类必须匹配文档定义的 JSON 结构public class AuthResponse { private String access_token; // 条款 4.2.1 明确要求字段名 private String token_type Bearer; // 固定值不可省略 private int expires_in; // 单位秒必须为整数 private String refresh_token; // 条款 4.2.3 规定 refresh_token 仅首次登录返回 // 构造函数省略 }若文档中写的是accessToken驼峰而非access_token下划线则此 Java 类将导致前端解析失败——这是接口联调第一轮必现的字段名不一致问题。3.3 安全配置Spring Security 与文档条款的逐条对齐SecurityConfig.java不是通用模板而是需求文档的安全条款翻译器Configuration EnableWebSecurity public class SecurityConfig { Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .csrf().disable() .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS) // 条款 3.1.4禁用 HTTP Session .and() .authorizeHttpRequests(authz - authz .requestMatchers(/auth/login, /auth/refresh, /auth/health).permitAll() // 条款 4.2认证端点无需前置鉴权 .requestMatchers(/api/**).authenticated() // 条款 4.3所有业务 API 必须携带有效 Token .anyRequest().denyAll() // 条款 3.2.1默认拒绝所有未明确定义的路径 ) .exceptionHandling(ex - ex .authenticationEntryPoint(new JwtAuthenticationEntryPoint()) // 条款 4.4.1未认证请求返回 401 .accessDeniedHandler(new JwtAccessDeniedHandler()) // 条款 4.4.2无权限请求返回 403 ); http.addFilterBefore(jwtAuthFilter(), UsernamePasswordAuthenticationFilter.class); return http.build(); } Bean public JwtAuthFilter jwtAuthFilter() { return new JwtAuthFilter(); // 条款 4.3.2JWT 解析必须校验 RS256 签名及 exp 字段 } }3.3.1 JwtAuthFilter 的校验逻辑必须覆盖文档硬性要求public class JwtAuthFilter extends OncePerRequestFilter { Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { String authHeader request.getHeader(Authorization); if (authHeader ! null authHeader.startsWith(Bearer )) { String token authHeader.substring(7); try { JwsClaims claims Jwts.parserBuilder() .setSigningKey(KeyUtil.getPublicKey()) // 条款 4.2.1必须使用公钥验签 .build() .parseClaimsJws(token); // 条款 4.2.1必须校验 exp 字段且剩余时间 ≥0 Date expiration claims.getBody().getExpiration(); if (expiration.before(new Date())) { throw new ExpiredJwtException(null, null, Token expired); } // 条款 4.3.3必须从 claims 中提取 user_id 作为 principal String userId claims.getBody().getSubject(); UsernamePasswordAuthenticationToken auth new UsernamePasswordAuthenticationToken(userId, null, Collections.emptyList()); SecurityContextHolder.getContext().setAuthentication(auth); } catch (ExpiredJwtException e) { response.sendError(HttpServletResponse.SC_UNAUTHORIZED, Token expired); return; } catch (SignatureException e) { response.sendError(HttpServletResponse.SC_UNAUTHORIZED, Invalid signature); return; } } filterChain.doFilter(request, response); } }注意若文档未要求exp校验此处可简化但若要求“Token 必须具备过期机制”则exp字段缺失即视为非法——这直接影响 Android/iOS 客户端的 Token 缓存策略。4. Linux 环境下部署验证TongWeb Oracle HBase 的三节点连通性测试需求规格说明书的价值在于它让部署不再是“把 WAR 包扔进 TongWeb 就完事”。真正的验证发生在 Linux 服务器上用命令行确认每个组件是否按文档约定协同工作。4.1 TongWeb 容器配置从server.xml中提取文档承诺的运行时参数统一登陆认证平台部署在 TongWeb 上其conf/server.xml必须体现文档中“性能与高可用”章节的承诺!-- conf/server.xml -- Connector port8080 protocolHTTP/1.1 connectionTimeout20000 redirectPort8443 maxThreads400 !-- 条款 6.2.1最大并发线程数 ≥400 -- minSpareThreads50 !-- 条款 6.2.2最小空闲线程数 ≥50 -- maxSpareThreads100 !-- 条款 6.2.3最大空闲线程数 ≤100 -- acceptCount100 !-- 条款 6.2.4连接等待队列长度 100 -- compressionon compressionMinSize2048 noCompressionUserAgentsgozilla, traviata /4.1.1 验证 TongWeb 线程池实际负载# 查看 TongWeb 进程 PID ps aux | grep tongweb | grep -v grep # 进入 TongWeb bin 目录执行 jstack 获取线程快照 /opt/tongweb/bin/jstack.sh 12345 tongweb-threads.log # 统计 RUNNABLE 线程数即活跃线程 grep java.lang.Thread.State: RUNNABLE tongweb-threads.log | wc -l若结果持续 350说明maxThreads400设置合理若长期 100则文档中“支持 2000 TPS”的承诺缺乏依据——需回溯需求文档的“性能指标”章节是否定义了压测场景。4.2 Oracle 连接验证用 sqlplus 执行文档定义的审计查询需求文档中“审计数据源”章节指定了LOGIN_AUDIT_LOG表结构必须在 Linux 上用 Oracle 客户端验证其可访问性与数据完整性# 登录 Oracle使用文档中指定的服务名 sqlplus username/password//10.10.10.10:1521/TONGDB_SERVICE_NAME # 执行文档附录中的审计 SQL验证字段与精度 SQL SELECT COUNT(*) FROM LOGIN_AUDIT_LOG WHERE EVENT_TIME SYSDATE - 1; # 检查表结构是否匹配文档定义 SQL DESC LOGIN_AUDIT_LOG; # 输出必须含EVENT_TIME (DATE), USER_ID (VARCHAR2), CLIENT_IP (VARCHAR2), STATUS_CODE (NUMBER), ERROR_CODE (VARCHAR2) # 验证索引存在文档条款 7.3.2 要求 EVENT_TIME 字段有函数索引 SQL SELECT index_name FROM user_indexes WHERE table_name LOGIN_AUDIT_LOG AND index_name LIKE IDX_LOGIN_AUDIT_EVENT%;提示若DESC LOGIN_AUDIT_LOG显示STATUS_CODE为VARCHAR2(10)而非NUMBER则 FusionCharts 图表将无法做数值聚合——这是数据库交付与文档不一致的典型证据。4.3 HBase 连通性测试用 hbase shell 验证实时缓存表结构HBase 作为用户数据的实时缓存层其表结构必须与文档“数据同步规范”章节完全一致# 进入 HBase Shell /opt/hbase/bin/hbase shell # 列出所有表确认 user:profile 存在 hbase(main):001:0 list # 查看 user:profile 表结构必须含 COLUMN FAMILY cf hbase(main):002:0 describe user:profile # 插入一条测试数据模拟 TongIntegrator 同步行为 hbase(main):003:0 put user:profile, uid_12345, cf:username, zhangsan hbase(main):004:0 put user:profile, uid_12345, cf:email, zhangsanexample.com # 查询验证条款 2.2.1 要求 HBase 查询延迟 200ms hbase(main):005:0 get user:profile, uid_123454.3.1 HBase 端口与配置必须匹配文档“基础设施要求”hbase.zookeeper.quorum必须指向文档中定义的 ZooKeeper 集群地址如zk1:2181,zk2:2181,zk3:2181hbase.regionserver.port默认16020但若文档要求“使用非默认端口以规避防火墙”则需在hbase-site.xml中显式设置property namehbase.regionserver.port/name value16030/value !-- 文档条款 8.1.3 指定端口 -- /property若hbase shell连接超时首先检查telnet zk1 2181是否通再确认hbase.zookeeper.quorum是否拼写错误——这是 70% 的 HBase 连通失败原因。5. 需求规格说明书的“活文档”维护技巧用 Git 版本与自动化测试固化条款一份静态的.doc文件极易在开发过程中失真。真正的统一登陆认证平台需求规格说明书必须成为可执行、可追溯、可自动校验的“活文档”。以下是三个一线团队验证有效的实践。5.1 将文档条款转为 Git 提交历史每个需求变更都有代码证据不要把 Word 文档当作唯一权威。正确的做法是每次需求变更必须伴随 Git Commit并在 Commit Message 中引用条款编号。# 示例条款 4.2.3 修改 refresh_token 为 One-Time Use git commit -m feat(auth): implement one-time use for refresh_token per clause 4.2.3 - Added REFRESH_TOKEN_USED table in Oracle - Modified /auth/refresh to invalidate used tokens - Updated AuthResponse to omit refresh_token on refresh这样当 QA 提出“条款 4.2.3 未实现”时开发可直接git log --grepclause 4.2.3定位到具体提交避免扯皮。Word 文档只是人类可读的摘要Git 历史才是技术事实的源头。5.2 用 JUnit 5 编写“条款测试用例”让需求自动验证为关键条款编写测试使其成为 CI 流水线的一部分SpringBootTest(webEnvironment SpringBootTest.WebEnvironment.RANDOM_PORT) class Clause423RefreshTokenTest { Test DisplayName(条款 4.2.3refresh_token 必须为一次性使用) void refreshTokenMustBeOneTimeUse() { // Step 1: 获取初始 refresh_token String initialToken getInitialRefreshToken(); // Step 2: 第一次使用应成功 ResponseEntityAuthResponse firstResp refresh(initialToken); assertThat(firstResp.getStatusCode()).isEqualTo(HttpStatus.OK); // Step 3: 第二次使用同一 token应失败 ResponseEntityString secondResp refresh(initialToken); assertThat(secondResp.getStatusCode()).isEqualTo(HttpStatus.UNAUTHORIZED); assertThat(secondResp.getBody()).contains(invalid_refresh_token); } private ResponseEntityAuthResponse refresh(String token) { return restTemplate.postForEntity( http://localhost: port /auth/refresh, new HttpEntity(Map.of(refresh_token, token)), AuthResponse.class ); } }提示该测试必须在 CI 中运行且失败即阻断发布。若某次合并导致此测试失败说明代码违反了需求规格说明书——这是比 Code Review 更刚性的质量门禁。5.3 用 Shell 脚本自动化验证 Linux 环境合规性将文档中所有 Linux 相关条款TongWeb 参数、Oracle 表结构、HBase 端口写成可执行脚本部署时一键校验#!/bin/bash # validate-env.sh echo 验证 TongWeb maxThreads MAX_THREADS$(grep maxThreads /opt/tongweb/conf/server.xml | sed s/.*maxThreads\([^]*\).*/\1/) if [ $MAX_THREADS -lt 400 ]; then echo ❌ ERROR: TongWeb maxThreads ($MAX_THREADS) 400 (clause 6.2.1) exit 1 else echo ✅ OK: TongWeb maxThreads $MAX_THREADS fi echo 验证 Oracle LOGIN_AUDIT_LOG 表结构 SQL_RESULT$(sqlplus -S username/password//10.10.10.10:1521/TONGDB_SERVICE_NAME EOF SET PAGESIZE 0 FEEDBACK OFF VERIFY OFF HEADING OFF ECHO OFF SELECT COUNT(*) FROM USER_TAB_COLUMNS WHERE TABLE_NAME LOGIN_AUDIT_LOG AND COLUMN_NAME IN (EVENT_TIME,USER_ID,STATUS_CODE); EXIT EOF ) if [ $SQL_RESULT -ne 3 ]; then echo ❌ ERROR: LOGIN_AUDIT_LOG missing required columns (clause 7.1.1) exit 1 else echo ✅ OK: LOGIN_AUDIT_LOG has required columns fi echo 验证 HBase user:profile 表存在 HBASE_RESULT$(echo list | /opt/hbase/bin/hbase shell 2/dev/null | grep user:profile | wc -l) if [ $HBASE_RESULT -eq 0 ]; then echo ❌ ERROR: HBase table user:profile not found (clause 2.2.1) exit 1 else echo ✅ OK: HBase table user:profile exists fi将此脚本加入 Ansible Playbook 或 Jenkins Pipeline每次部署前执行。它不替代人工审核但能消灭 90% 的低级配置遗漏——这才是需求规格说明书在工程落地中最实在的价值。本文还有配套的精品资源点击获取
统一登录认证平台需求规格说明书技术落地指南
简介本资源是一份面向软件开发人员、系统架构师及测试工程师的《统一登陆认证平台-需求规格说明书完整版》源自无锡城市大数据中心一期项目聚焦解决多系统身份统一管理、安全认证与细粒度授权等核心问题适用于政务类平台建设、企业级单点登录SSO系统设计等实战场景。文档为单个Word文件.doc格式大小1.53MB内容完整覆盖文档概述、需求目标、用户角色分析、设计约束、总体与技术架构含Java EESpring BootHibernateMySQL技术栈、功能模块详述等40页关键章节目录层级清晰变更记录与术语定义规范便于团队协同理解与开发落地。目前已有237人学习下载可直接用于需求分析参考、架构设计对标或认证系统方案复用是中高级开发者开展安全认证类项目时难得的完整型需求范本。1. 这份《统一登陆认证平台-需求规格说明书完整版》不是模板套话而是落地前必须对齐的“技术契约”你手头这份标着【精品】的 Word 文档表面看是“需求规格说明书”实际是统一登陆认证平台项目启动前最关键的技术锚点。它不决定代码怎么写但决定了单点登录SSO是否支持 OAuth2.0 与 OpenID Connect 双协议、用户身份主数据是否从 Oracle 同步到 HBase 做实时查询、移动端Android/iOS的 Token 刷新机制是否兼容 TongWeb 容器的 Session 管理策略、以及 FusionCharts 图表是否仅用于后台审计视图而非前端登录页——这些都不是开发阶段能拍板的事而是在这份文档里用可验证的条目写死的。它面向的不是产品经理而是 Java 架构师、Linux 运维工程师、Oracle DBA 和移动客户端开发者前者要据此设计 Spring Security JWT 的认证链路后者要确认 iOS 设备能否在无网络状态下完成本地 Token 校验。如果你正准备基于 TongIntegrator 做流程集成或用 TongLinkQ 实现跨系统消息通知这份文档里的“认证上下文传递规则”和“失败重试阈值定义”就是你写适配器时唯一能依赖的输入。2. 需求规格说明书中的认证能力必须映射到具体技术组件与参数边界一份合格的统一登陆认证平台需求规格说明书绝不能停留在“支持单点登录”这种模糊表述。它必须将业务语言转化为可配置、可验证、可运维的技术参数。以下是从文档中提取出的四类核心能力及其对应的技术实现锚点每项都需在文档中明确数值、协议版本与异常处理逻辑。2.1 身份凭证生命周期管理Token 生成与刷新的硬性约束统一登陆认证平台的 Token 不是简单签发一个 JWT 就完事。需求文档中必须明确定义Token 有效期例如access_token最长 30 分钟refresh_token最长 7 天且refresh_token使用后立即失效One-Time Use签名算法强制要求必须为RS256非HS256密钥由 Oracle 数据库中SECURITY_KEYSTORE表存储私钥长度 ≥2048 位刷新触发条件客户端在access_token剩余有效期 ≤5 分钟时发起/auth/refresh请求该接口必须支持 TongWeb 容器的线程池隔离配置maxThreads200minSpareThreads20。提示若文档中仅写“支持 Token 自动刷新”未注明上述参数则开发时将无法对接 Android/iOS 客户端的后台静默刷新逻辑——移动端 SDK 依赖精确的剩余时间阈值做预加载判断。2.1.1 验证方法用 curl 模拟刷新流程并检查响应头curl -X POST https://auth.example.com/auth/refresh \ -H Content-Type: application/json \ -d { refresh_token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... } | jq .成功响应必须包含access_token字段新签发 JWTexpires_in: 1800即 30 分钟单位秒refresh_token字段不可出现因 One-Time Use 规则若返回401 Unauthorized且errorinvalid_refresh_token需检查 Oracle 中SECURITY_KEYSTORE表的KEY_STATUSACTIVE且EXPIRY_DATE SYSDATE。2.2 多源身份同步Oracle 主库与 HBase 实时缓存的同步策略统一登陆认证平台常需聚合多个业务系统的用户数据。需求文档必须规定同步机制的 SLA 与一致性模型而非仅写“支持多源接入”。同步维度Oracle 源表HBase 目标表同步频率一致性保障失败重试机制用户基础信息USER_MASTERuser:profile实时基于 TongIntegrator 的 CDC 日志捕获最大重试 3 次间隔 30s角色权限映射USER_ROLE_MAPPINGuser:role准实时每 5 分钟全量比对 增量更新重试失败后写入failed_sync_log表2.2.1 关键配置项必须写入文档的“系统集成要求”章节TongIntegrator 作业配置中source.db.tableUSER_MASTER必须与 Oracle 实例的TONGDB_SERVICE_NAME绑定HBase 写入使用AsyncTableAPIwriteBufferSize128KB避免小批量写入导致 RegionServer GC 压力同步延迟监控指标hbase_sync_lag_ms 2000毫秒级该值需在 FusionCharts 的“同步健康度”看板中可视化。注意若文档未定义USER_ROLE_MAPPING表的EFFECTIVE_DATE字段如何参与增量判断则 HBase 中角色数据可能出现过期权限残留——这是生产环境最常被审计指出的问题。2.3 移动端适配Android/iOS 的认证上下文传递规范统一登陆认证平台若需支撑企业微信、钉钉或自研 App其需求文档必须明确移动端特有的上下文传递规则而非复用 Web 端 Cookie 方案。Android 端通过ContentProvider共享认证上下文URI 格式为content://com.example.auth.provider/auth_context要求android:exportedtrue且android:permissioncom.example.auth.permission.READ_CONTEXTiOS 端使用 Keychain Sharing Groupgroup.com.example.auth存储id_token与refresh_token且accessibilityThisDeviceOnlyAfterFirstUnlock跨应用跳转当从 A App 跳转至 B App 并携带认证态时必须通过 TongLinkQ 的MQTT QoS1消息传递context_id该 ID 在 Oracle 中关联AUTH_CONTEXT_LOG表的CONTEXT_STATUSVALID。2.3.1 验证 Android 端 ContentProvider 是否生效adb shell content query --uri content://com.example.auth.provider/auth_context \ --projection token_type,expires_at,scope \ --selection client_id? \ --selection-args com.example.app预期输出应含expires_at时间戳Unix 毫秒若返回空或SecurityException说明AndroidManifest.xml中provider标签未正确声明android:permission。2.4 审计与监控FusionCharts 图表背后的数据源契约需求文档中“审计报表”章节常被写成“提供登录失败趋势图”。但真正可落地的要求是图表数据源必须来自 Oracle 表LOGIN_AUDIT_LOG字段包括EVENT_TIME,USER_ID,CLIENT_IP,STATUS_CODE,ERROR_CODEFusionCharts 的dataSource配置中dataURL必须指向/api/v1/audit/login-trend?from2024-01-01to2024-01-31且该接口返回 JSON 必须符合 FusionCharts 的categoriesdataset结构STATUS_CODE字段值域必须在文档中明确定义200成功,401凭证无效,429频次超限,500认证服务内部错误。2.4.1 抽取审计数据的 SQL 必须写入文档附录SELECT TRUNC(EVENT_TIME, HH24) AS time_bucket, COUNT(*) AS login_attempts, SUM(CASE WHEN STATUS_CODE 200 THEN 1 ELSE 0 END) AS success_count, SUM(CASE WHEN STATUS_CODE IN (401,429) THEN 1 ELSE 0 END) AS failure_count FROM LOGIN_AUDIT_LOG WHERE EVENT_TIME TO_DATE(2024-01-01, YYYY-MM-DD) AND EVENT_TIME TO_DATE(2024-02-01, YYYY-MM-DD) GROUP BY TRUNC(EVENT_TIME, HH24) ORDER BY time_bucket;该 SQL 的TRUNC(EVENT_TIME, HH24)是 FusionCharts 时间轴分组的关键若文档未指定此精度则图表将无法按小时聚合——这是客户验收时高频争议点。3. 基于需求规格说明书构建可验证的 Java 认证服务骨架拿到这份说明书后Java 开发团队不能直接写 Controller而应先用 Spring Boot Spring Security 搭建一个最小可验证骨架其每个模块都严格对应文档条款。该骨架不实现业务逻辑只验证需求是否可技术承载。3.1 初始化工程TongWeb 兼容性与 Oracle/HBase 依赖声明统一登陆认证平台部署在 TongWeb 应用服务器上因此pom.xml必须显式声明兼容性约束properties tongweb.version7.0.1/tongweb.version spring-boot.version2.7.18/spring-boot.version oracle.jdbc.version19.21.0.0/oracle.jdbc.version hbase.client.version2.4.17/hbase.client.version /properties dependencies !-- TongWeb 容器适配 -- dependency groupIdcom.tongweb/groupId artifactIdtongweb-spring-boot-starter/artifactId version${tongweb.version}/version /dependency !-- Oracle 数据源 -- dependency groupIdcom.oracle.database.jdbc/groupId artifactIdojdbc8/artifactId version${oracle.jdbc.version}/version /dependency !-- HBase 异步客户端 -- dependency groupIdorg.apache.hbase/groupId artifactIdhbase-client/artifactId version${hbase.client.version}/version /dependency /dependencies提示tongweb-spring-boot-starter是 TongWeb 官方提供的 Spring Boot 集成包它重写了EmbeddedServletContainerCustomizer以适配 TongWeb 的线程模型。若文档未要求 TongWeb 支持则不应引入此依赖——避免为非必需容器增加运维复杂度。3.2 认证端点路由按文档条款生成可测试的 REST 接口根据文档中“认证服务接口定义”章节生成三个核心端点每个均带PreAuthorize注解与文档条款编号注释RestController RequestMapping(/auth) public class AuthController { // 条款 4.2.1POST /auth/login 接收 username/password返回 access_token refresh_token PostMapping(/login) public ResponseEntityAuthResponse login(RequestBody LoginRequest request) { // 此处暂不实现密码校验仅返回模拟 Token return ResponseEntity.ok(new AuthResponse( Jwts.builder() .setSubject(request.getUsername()) .signWith(KeyUtil.getPrivateKey(), SignatureAlgorithm.RS256) .setExpiration(new Date(System.currentTimeMillis() 30 * 60 * 1000)) .compact(), Bearer, 1800, generateRefreshToken(request.getUsername()) )); } // 条款 4.2.3POST /auth/refresh 接收 refresh_token返回新 access_token旧 refresh_token 失效 PostMapping(/refresh) public ResponseEntityAuthResponse refresh(RequestBody RefreshRequest request) { // 验证 refresh_token 签名及有效期 JwsClaims claims Jwts.parserBuilder() .setSigningKey(KeyUtil.getPublicKey()) .build() .parseClaimsJws(request.getRefreshToken()); String username claims.getBody().getSubject(); // TODO此处需查 Oracle 表验证 refresh_token 是否已被使用One-Time Use return ResponseEntity.ok(new AuthResponse( Jwts.builder() .setSubject(username) .signWith(KeyUtil.getPrivateKey(), SignatureAlgorithm.RS256) .setExpiration(new Date(System.currentTimeMillis() 30 * 60 * 1000)) .compact(), Bearer, 1800, null // refresh_token 不再返回 )); } // 条款 5.1.2GET /auth/health 返回认证服务健康状态含 Oracle/HBase 连接检测 GetMapping(/health) public ResponseEntityHealthCheckResponse health() { boolean oracleUp oracleDataSourceTest(); boolean hbaseUp hbaseConnectionTest(); return ResponseEntity.ok(new HealthCheckResponse(oracleUp, hbaseUp)); } }3.2.1 AuthResponse 类必须匹配文档定义的 JSON 结构public class AuthResponse { private String access_token; // 条款 4.2.1 明确要求字段名 private String token_type Bearer; // 固定值不可省略 private int expires_in; // 单位秒必须为整数 private String refresh_token; // 条款 4.2.3 规定 refresh_token 仅首次登录返回 // 构造函数省略 }若文档中写的是accessToken驼峰而非access_token下划线则此 Java 类将导致前端解析失败——这是接口联调第一轮必现的字段名不一致问题。3.3 安全配置Spring Security 与文档条款的逐条对齐SecurityConfig.java不是通用模板而是需求文档的安全条款翻译器Configuration EnableWebSecurity public class SecurityConfig { Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .csrf().disable() .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS) // 条款 3.1.4禁用 HTTP Session .and() .authorizeHttpRequests(authz - authz .requestMatchers(/auth/login, /auth/refresh, /auth/health).permitAll() // 条款 4.2认证端点无需前置鉴权 .requestMatchers(/api/**).authenticated() // 条款 4.3所有业务 API 必须携带有效 Token .anyRequest().denyAll() // 条款 3.2.1默认拒绝所有未明确定义的路径 ) .exceptionHandling(ex - ex .authenticationEntryPoint(new JwtAuthenticationEntryPoint()) // 条款 4.4.1未认证请求返回 401 .accessDeniedHandler(new JwtAccessDeniedHandler()) // 条款 4.4.2无权限请求返回 403 ); http.addFilterBefore(jwtAuthFilter(), UsernamePasswordAuthenticationFilter.class); return http.build(); } Bean public JwtAuthFilter jwtAuthFilter() { return new JwtAuthFilter(); // 条款 4.3.2JWT 解析必须校验 RS256 签名及 exp 字段 } }3.3.1 JwtAuthFilter 的校验逻辑必须覆盖文档硬性要求public class JwtAuthFilter extends OncePerRequestFilter { Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { String authHeader request.getHeader(Authorization); if (authHeader ! null authHeader.startsWith(Bearer )) { String token authHeader.substring(7); try { JwsClaims claims Jwts.parserBuilder() .setSigningKey(KeyUtil.getPublicKey()) // 条款 4.2.1必须使用公钥验签 .build() .parseClaimsJws(token); // 条款 4.2.1必须校验 exp 字段且剩余时间 ≥0 Date expiration claims.getBody().getExpiration(); if (expiration.before(new Date())) { throw new ExpiredJwtException(null, null, Token expired); } // 条款 4.3.3必须从 claims 中提取 user_id 作为 principal String userId claims.getBody().getSubject(); UsernamePasswordAuthenticationToken auth new UsernamePasswordAuthenticationToken(userId, null, Collections.emptyList()); SecurityContextHolder.getContext().setAuthentication(auth); } catch (ExpiredJwtException e) { response.sendError(HttpServletResponse.SC_UNAUTHORIZED, Token expired); return; } catch (SignatureException e) { response.sendError(HttpServletResponse.SC_UNAUTHORIZED, Invalid signature); return; } } filterChain.doFilter(request, response); } }注意若文档未要求exp校验此处可简化但若要求“Token 必须具备过期机制”则exp字段缺失即视为非法——这直接影响 Android/iOS 客户端的 Token 缓存策略。4. Linux 环境下部署验证TongWeb Oracle HBase 的三节点连通性测试需求规格说明书的价值在于它让部署不再是“把 WAR 包扔进 TongWeb 就完事”。真正的验证发生在 Linux 服务器上用命令行确认每个组件是否按文档约定协同工作。4.1 TongWeb 容器配置从server.xml中提取文档承诺的运行时参数统一登陆认证平台部署在 TongWeb 上其conf/server.xml必须体现文档中“性能与高可用”章节的承诺!-- conf/server.xml -- Connector port8080 protocolHTTP/1.1 connectionTimeout20000 redirectPort8443 maxThreads400 !-- 条款 6.2.1最大并发线程数 ≥400 -- minSpareThreads50 !-- 条款 6.2.2最小空闲线程数 ≥50 -- maxSpareThreads100 !-- 条款 6.2.3最大空闲线程数 ≤100 -- acceptCount100 !-- 条款 6.2.4连接等待队列长度 100 -- compressionon compressionMinSize2048 noCompressionUserAgentsgozilla, traviata /4.1.1 验证 TongWeb 线程池实际负载# 查看 TongWeb 进程 PID ps aux | grep tongweb | grep -v grep # 进入 TongWeb bin 目录执行 jstack 获取线程快照 /opt/tongweb/bin/jstack.sh 12345 tongweb-threads.log # 统计 RUNNABLE 线程数即活跃线程 grep java.lang.Thread.State: RUNNABLE tongweb-threads.log | wc -l若结果持续 350说明maxThreads400设置合理若长期 100则文档中“支持 2000 TPS”的承诺缺乏依据——需回溯需求文档的“性能指标”章节是否定义了压测场景。4.2 Oracle 连接验证用 sqlplus 执行文档定义的审计查询需求文档中“审计数据源”章节指定了LOGIN_AUDIT_LOG表结构必须在 Linux 上用 Oracle 客户端验证其可访问性与数据完整性# 登录 Oracle使用文档中指定的服务名 sqlplus username/password//10.10.10.10:1521/TONGDB_SERVICE_NAME # 执行文档附录中的审计 SQL验证字段与精度 SQL SELECT COUNT(*) FROM LOGIN_AUDIT_LOG WHERE EVENT_TIME SYSDATE - 1; # 检查表结构是否匹配文档定义 SQL DESC LOGIN_AUDIT_LOG; # 输出必须含EVENT_TIME (DATE), USER_ID (VARCHAR2), CLIENT_IP (VARCHAR2), STATUS_CODE (NUMBER), ERROR_CODE (VARCHAR2) # 验证索引存在文档条款 7.3.2 要求 EVENT_TIME 字段有函数索引 SQL SELECT index_name FROM user_indexes WHERE table_name LOGIN_AUDIT_LOG AND index_name LIKE IDX_LOGIN_AUDIT_EVENT%;提示若DESC LOGIN_AUDIT_LOG显示STATUS_CODE为VARCHAR2(10)而非NUMBER则 FusionCharts 图表将无法做数值聚合——这是数据库交付与文档不一致的典型证据。4.3 HBase 连通性测试用 hbase shell 验证实时缓存表结构HBase 作为用户数据的实时缓存层其表结构必须与文档“数据同步规范”章节完全一致# 进入 HBase Shell /opt/hbase/bin/hbase shell # 列出所有表确认 user:profile 存在 hbase(main):001:0 list # 查看 user:profile 表结构必须含 COLUMN FAMILY cf hbase(main):002:0 describe user:profile # 插入一条测试数据模拟 TongIntegrator 同步行为 hbase(main):003:0 put user:profile, uid_12345, cf:username, zhangsan hbase(main):004:0 put user:profile, uid_12345, cf:email, zhangsanexample.com # 查询验证条款 2.2.1 要求 HBase 查询延迟 200ms hbase(main):005:0 get user:profile, uid_123454.3.1 HBase 端口与配置必须匹配文档“基础设施要求”hbase.zookeeper.quorum必须指向文档中定义的 ZooKeeper 集群地址如zk1:2181,zk2:2181,zk3:2181hbase.regionserver.port默认16020但若文档要求“使用非默认端口以规避防火墙”则需在hbase-site.xml中显式设置property namehbase.regionserver.port/name value16030/value !-- 文档条款 8.1.3 指定端口 -- /property若hbase shell连接超时首先检查telnet zk1 2181是否通再确认hbase.zookeeper.quorum是否拼写错误——这是 70% 的 HBase 连通失败原因。5. 需求规格说明书的“活文档”维护技巧用 Git 版本与自动化测试固化条款一份静态的.doc文件极易在开发过程中失真。真正的统一登陆认证平台需求规格说明书必须成为可执行、可追溯、可自动校验的“活文档”。以下是三个一线团队验证有效的实践。5.1 将文档条款转为 Git 提交历史每个需求变更都有代码证据不要把 Word 文档当作唯一权威。正确的做法是每次需求变更必须伴随 Git Commit并在 Commit Message 中引用条款编号。# 示例条款 4.2.3 修改 refresh_token 为 One-Time Use git commit -m feat(auth): implement one-time use for refresh_token per clause 4.2.3 - Added REFRESH_TOKEN_USED table in Oracle - Modified /auth/refresh to invalidate used tokens - Updated AuthResponse to omit refresh_token on refresh这样当 QA 提出“条款 4.2.3 未实现”时开发可直接git log --grepclause 4.2.3定位到具体提交避免扯皮。Word 文档只是人类可读的摘要Git 历史才是技术事实的源头。5.2 用 JUnit 5 编写“条款测试用例”让需求自动验证为关键条款编写测试使其成为 CI 流水线的一部分SpringBootTest(webEnvironment SpringBootTest.WebEnvironment.RANDOM_PORT) class Clause423RefreshTokenTest { Test DisplayName(条款 4.2.3refresh_token 必须为一次性使用) void refreshTokenMustBeOneTimeUse() { // Step 1: 获取初始 refresh_token String initialToken getInitialRefreshToken(); // Step 2: 第一次使用应成功 ResponseEntityAuthResponse firstResp refresh(initialToken); assertThat(firstResp.getStatusCode()).isEqualTo(HttpStatus.OK); // Step 3: 第二次使用同一 token应失败 ResponseEntityString secondResp refresh(initialToken); assertThat(secondResp.getStatusCode()).isEqualTo(HttpStatus.UNAUTHORIZED); assertThat(secondResp.getBody()).contains(invalid_refresh_token); } private ResponseEntityAuthResponse refresh(String token) { return restTemplate.postForEntity( http://localhost: port /auth/refresh, new HttpEntity(Map.of(refresh_token, token)), AuthResponse.class ); } }提示该测试必须在 CI 中运行且失败即阻断发布。若某次合并导致此测试失败说明代码违反了需求规格说明书——这是比 Code Review 更刚性的质量门禁。5.3 用 Shell 脚本自动化验证 Linux 环境合规性将文档中所有 Linux 相关条款TongWeb 参数、Oracle 表结构、HBase 端口写成可执行脚本部署时一键校验#!/bin/bash # validate-env.sh echo 验证 TongWeb maxThreads MAX_THREADS$(grep maxThreads /opt/tongweb/conf/server.xml | sed s/.*maxThreads\([^]*\).*/\1/) if [ $MAX_THREADS -lt 400 ]; then echo ❌ ERROR: TongWeb maxThreads ($MAX_THREADS) 400 (clause 6.2.1) exit 1 else echo ✅ OK: TongWeb maxThreads $MAX_THREADS fi echo 验证 Oracle LOGIN_AUDIT_LOG 表结构 SQL_RESULT$(sqlplus -S username/password//10.10.10.10:1521/TONGDB_SERVICE_NAME EOF SET PAGESIZE 0 FEEDBACK OFF VERIFY OFF HEADING OFF ECHO OFF SELECT COUNT(*) FROM USER_TAB_COLUMNS WHERE TABLE_NAME LOGIN_AUDIT_LOG AND COLUMN_NAME IN (EVENT_TIME,USER_ID,STATUS_CODE); EXIT EOF ) if [ $SQL_RESULT -ne 3 ]; then echo ❌ ERROR: LOGIN_AUDIT_LOG missing required columns (clause 7.1.1) exit 1 else echo ✅ OK: LOGIN_AUDIT_LOG has required columns fi echo 验证 HBase user:profile 表存在 HBASE_RESULT$(echo list | /opt/hbase/bin/hbase shell 2/dev/null | grep user:profile | wc -l) if [ $HBASE_RESULT -eq 0 ]; then echo ❌ ERROR: HBase table user:profile not found (clause 2.2.1) exit 1 else echo ✅ OK: HBase table user:profile exists fi将此脚本加入 Ansible Playbook 或 Jenkins Pipeline每次部署前执行。它不替代人工审核但能消灭 90% 的低级配置遗漏——这才是需求规格说明书在工程落地中最实在的价值。本文还有配套的精品资源点击获取