datai/docs/archive/REQ-012.md

# Requirements - 环境有效性字段功能

## 需求信息

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

## 输入引用

引用相关的 docs 文档链接：

- [DataiConfigEnvironment.java](../../datai-salesforce-setting/src/main/java/com/datai/setting/model/domain/DataiConfigEnvironment.java) - 配置环境实体类

## Context Maps

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

- [Authentication.canvas](../Authentication.canvas) - 项目架构视觉化展示
- **相关节点**: [配置管理](node_setting) - 提供配置管理功能
- **相关节点**: [认证管理](node_auth) - 提供登录认证功能

## 需求目标

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

## 相关文档

- [设计文档](../design/2026-01-22-012-环境有效性字段功能设计.md) - 环境有效性字段功能设计
- [SQL 脚本](../sql/2026-01-22-012-environment-validity-field.sql) - 环境有效性字段功能 SQL 脚本
- [提示词文档](../prompts/2026-01-22-012-prompt-环境有效性字段功能.md) - 环境有效性字段功能实现提示词
- [参考代码](../reference-code/2026-01-22-012-code-环境有效性字段功能.md) - 环境有效性字段功能参考代码
- [实施方案](../implementation/2026-01-22-012-implementation-环境有效性字段功能.md) - 环境有效性字段功能实施方案
- [变更日志](../changelog/0012-environment-validity-field.md) - 环境有效性字段功能变更日志
- [会话记录](../sessions/20260122-req-012-environment-validity-field.md) - 环境有效性字段功能会话记录
- [复盘文档](../retros/20260123-req-012-environment-validity-field-retro.md) - 环境有效性字段功能复盘文档

## 需求变更记录

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

## 相关人员

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

## 评审信息

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