kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/docs/archive/REQ-012.md

9.0 KiB
Raw Permalink Blame History

Requirements - 环境有效性字段功能

需求信息

  • 需求名称: 环境有效性字段功能
  • 需求类型: 功能需求
  • 需求编号: REQ-012
  • 父需求: 无
  • 创建日期: 2026-01-22
  • 需求版本: v1.0.0
  • 需求提出人: 系统管理员
  • 需求状态: 已完成

输入引用

引用相关的 docs 文档链接：

Context Maps

强制列出本次需求依赖的 Canvas 文件：

需求目标

在 DataiConfigEnvironment 实体类中增加一个"是否有效"字段（isValid），用于标记环境是否有效。当环境登录成功后，自动将该环境设置为有效状态，以便系统能够识别哪些环境配置是可用的。

需求描述

概述

本需求旨在在 datai-salesforce-setting 模块的 DataiConfigEnvironment 实体类中新增一个 isValid 字段，用于标记环境配置的有效性。当用户使用某个环境配置成功登录 Salesforce 后，系统自动将该环境设置为有效状态，从而帮助用户识别哪些环境配置是可用的、哪些是无效的。

详细需求

1. 数据库表结构变更

  • 需求描述: 在 datai_config_environment 表中新增 is_valid 字段
  • 优先级: 高
  • 验收标准:
    • 数据库表 datai_config_environment 新增 is_valid 字段
    • 字段类型为 TINYINT(1) 或 BOOLEAN
    • 字段默认值为 false
    • 字段允许为 NULL（兼容历史数据）
    • 字段添加注释"是否有效（登录成功后自动设置为true）"
  • 依赖关系: 无
  • 实现建议:
    • 使用 ALTER TABLE 语句添加字段
    • 提供数据库升级脚本

2. 实体类字段添加

  • 需求描述: 在 DataiConfigEnvironment 实体类中新增 isValid 字段及其 getter/setter 方法
  • 优先级: 高
  • 验收标准:
    • DataiConfigEnvironment 类新增 isValid 字段
    • 字段类型为 Boolean
    • 添加 @Schema 注解，描述为"是否有效"
    • 添加 @Excel 注解，支持导出
    • 添加 setIsValid(Boolean isValid) 方法
    • 添加 Boolean getIsValid() 方法
    • 在 toString() 方法中添加 isValid 字段
  • 依赖关系: 依赖于数据库表结构变更
  • 实现建议:
    • 遵循现有实体类的代码风格
    • 使用 Swagger 注解进行 API 文档描述

3. DTO 和 VO 类字段添加

  • 需求描述: 在 DataiConfigEnvironmentDto 和 DataiConfigEnvironmentVo 类中新增 isValid 字段
  • 优先级: 高
  • 验收标准:
    • DataiConfigEnvironmentDto 类新增 isValid 字段
    • DataiConfigEnvironmentVo 类新增 isValid 字段
    • 字段类型为 Boolean
    • 添加相应的 getter/setter 方法
  • 依赖关系: 依赖于实体类字段添加
  • 实现建议:
    • 遵循现有 DTO 和 VO 的代码风格
    • 确保字段映射正确

4. Mapper XML 文件更新

  • 需求描述: 更新 DataiConfigEnvironmentMapper.xml 文件，在 SQL 语句中包含 is_valid 字段
  • 优先级: 高
  • 验收标准:
    • resultMap 中包含 is_valid 字段映射
    • insert 语句包含 is_valid 字段
    • update 语句包含 is_valid 字段
    • select 语句包含 is_valid 字段
  • 依赖关系: 依赖于数据库表结构变更
  • 实现建议:
    • 使用 MyBatis 的 resultMap 进行字段映射
    • 确保所有 SQL 语句都包含新字段

5. 登录成功后自动设置环境有效

  • 需求描述: 在登录成功后，自动将对应的环境设置为有效状态
  • 优先级: 高
  • 验收标准:
    • 登录成功后，自动更新 datai_config_environment 表的 is_valid 字段为 true
    • 更新操作在登录成功后立即执行
    • 更新操作不影响登录流程的性能
    • 更新失败不影响登录结果
    • 记录更新日志
  • 依赖关系: 依赖于实体类和 Mapper 更新
  • 实现建议:
    • 在 SalesforceLoginServiceImpl 的 login 方法中，登录成功后调用环境更新服务
    • 使用 DataiConfigEnvironmentService 更新环境有效性
    • 使用事务确保数据一致性
    • 添加异常处理，确保更新失败不影响登录结果

6. 环境管理接口支持有效性字段

  • 需求描述: 在环境管理的增删改查接口中支持 isValid 字段
  • 优先级: 中
  • 验收标准:
    • 环境列表接口返回 isValid 字段
    • 环境详情接口返回 isValid 字段
    • 环境添加接口支持设置 isValid 字段
    • 环境编辑接口支持修改 isValid 字段
    • 环境导出接口包含 isValid 字段
  • 依赖关系: 依赖于 DTO 和 VO 类字段添加
  • 实现建议:
    • 更新 DataiConfigEnvironmentController 的相关方法
    • 确保 API 接口符合 RESTful 规范

约束

  • 技术栈限制: 必须基于现有的 Spring Boot 3 技术栈
  • 架构约束: 必须遵循 Authentication.canvas 中定义的架构和调用关系
  • 模块约束: 必须在 datai-salesforce-setting 模块下实现
  • 数据库约束: 必须提供数据库升级脚本，确保向后兼容
  • 性能约束: 登录成功后更新环境有效性不能影响登录性能
  • 事务约束: 更新环境有效性必须在事务中执行
  • 文档约束: 必须遵循 SSOT 方法论
  • 代码规范约束: 必须遵循项目现有的代码规范

Rule Set

"请严格参考 @Authentication.canvas 中的状态机转移逻辑，不要自行发挥。"

具体规则：

  • 必须使用 Canvas 中定义的类名和方法名
  • 必须遵循 Canvas 中定义的调用关系
  • 必须参考 Canvas 中的流程图逻辑
  • 必须使用现有的认证模块进行登录
  • 必须遵循现有的异常处理机制
  • 必须遵循现有的日志记录规范

验收标准

  • 功能完整性:
    • 数据库表成功添加 is_valid 字段
    • 实体类、DTO、VO 类成功添加 isValid 字段
    • Mapper XML 文件成功更新
    • 登录成功后自动设置环境为有效状态
    • 环境管理接口支持 isValid 字段
  • 数据一致性:
    • 数据库字段与实体类字段一致
    • DTO、VO 字段与实体类字段一致
    • Mapper XML 字段映射正确
  • 性能指标:
    • 登录成功后更新环境有效性不影响登录性能
    • 环境列表查询性能不受影响
  • 代码规范性:
    • 代码符合项目编码规范，有清晰的注释
    • 遵循单一职责原则和开闭原则
  • 可维护性:
    • 代码结构清晰，易于扩展和维护
    • 数据库升级脚本清晰，易于执行

风险

  • 数据迁移风险:
    • 历史数据中 is_valid 字段为 NULL，需要正确处理
    • 需要提供数据迁移脚本，将历史数据设置为合理的默认值
  • 性能风险:
    • 登录成功后更新环境有效性可能影响登录性能
    • 需要使用异步更新或批量更新优化性能
  • 事务风险:
    • 更新环境有效性失败可能导致数据不一致
    • 需要使用事务确保数据一致性
  • 兼容性风险:
    • 新增字段可能与现有代码不兼容
    • 需要确保所有相关代码都正确处理新字段

相关文档

需求变更记录

日期 变更内容 变更原因 变更人 审核人 状态
2026-01-22 创建需求文档 初始需求 系统管理员 - 待审核

相关人员

  • 需求提出人: 系统管理员 - 联系方式
  • 需求负责人: 系统管理员 - 联系方式
  • 技术负责人: 开发工程师 - 联系方式
  • 测试负责人: 测试工程师 - 联系方式
  • 其他相关人员: - 联系方式

评审信息

  • 评审日期: -
  • 评审人员: -
  • 评审结果: -
  • 评审意见: -
  • 修改建议: -