跳到主要内容

产品需求文档 (PRD): 平台配置迁移与租户接口统一

1. 概述​

本功能旨在将当前独立存在的平台配置（platform_config）中除邀请码和平台名称之外的配置项迁移到 tenant 表中，并统一 tenant 和平台配置相关的接口。此举旨在简化平台配置的管理，并通过统一接口提供租户及其相关配置。系统将把 tenant_id = 1 的租户作为平台租户，其 name 字段将作为平台名称。管理平台配置时，管理员将通过其 owned_tenant_id = 1 访问该租户的配置，无需在 tenant 服务的核心逻辑中为 tenant_id = 1 做特殊处理。

2. 目标​

  • 简化平台配置管理，消除独立的 platform_config 表
  • 统一租户和平台配置的访问接口
  • 确保管理员能够通过统一的接口管理平台配置
  • 保持系统的向后兼容性和数据一致性
  • 优化代码结构，减少重复的配置访问逻辑

3. 用户故事​

作为系统管理员​

  • 我希望能够通过统一的租户配置接口管理平台级配置
  • 我希望在访问平台配置时，系统能够自动识别我的管理员权限（owned_tenant_id = 1）
  • 我希望平台配置的修改能够立即生效，无需特殊的处理逻辑

作为开发者​

  • 我希望能够通过单一的租户服务接口获取所有配置信息
  • 我希望平台配置和租户配置使用相同的数据结构和访问模式
  • 我希望减少代码中的条件判断，提高代码的可维护性

作为系统​

  • 我需要在启动时检查平台租户（tenant_id = 1）是否存在
  • 我需要确保只有具有管理员权限的用户才能修改平台配置
  • 我需要为非管理员用户访问平台配置时返回权限错误

4. 功能需求​

4.1 数据模型统一​

  1. 系统必须删除现有的 platform_config 表或实体
  2. 系统必须在 tenant 表中包含原平台配置的所有相关字段（除邀请码和平台名称外）
  3. 系统必须将 tenant_id = 1 的租户标识为平台租户
  4. 系统必须使用租户的 name 字段作为平台名称
  5. 系统必须使用租户的 platform_name 字段存储平台显示名称

4.2 访问控制​

  1. 系统必须验证用户的 owned_tenant_id 是否为 1 来确定管理员权限
  2. 系统必须只允许 owned_tenant_id = 1 的管理员访问和修改平台配置
  3. 系统必须阻止非管理员用户访问其他租户的配置
  4. 系统必须在用户尝试访问未授权配置时返回权限错误

4.3 API 接口统一​

  1. 系统必须扩展现有的租户端点，当访问 tenant_id = 1 时包含平台配置字段
  2. 系统必须支持管理员通过 GetTenantConfig 和 UpdateTenantConfig 接口管理平台配置
  3. 系统必须确保用户角色为 admin 时，API 响应结构保持不变
  4. 系统必须提供统一的认证和授权规则

4.4 系统启动检查​

  1. 系统必须在启动时检查 tenant_id = 1 的租户是否存在
  2. 系统必须在平台租户不存在时创建默认的平台租户
  3. 系统必须记录启动检查的结果到日志中

4.5 错误处理​

  1. 系统必须在非管理员用户尝试访问平台配置时返回"没有权限"错误
  2. 系统必须在平台租户不存在时返回适当的错误信息
  3. 系统必须在配置验证失败时返回详细的错误描述

5. 非目标（范围之外）​

  • tenant_invite_code 的单独表维护和管理
  • 更改 tenant 服务的核心业务逻辑
  • 引入全新的平台配置项或功能
  • 为 tenant_id = 1 以外的其他租户提供特殊处理逻辑
  • 保留旧的 API 端点用于向后兼容
  • 提供数据迁移工具或脚本
  • 为旧端点设置弃用时间表

6. 设计考虑​

6.1 数据结构​

平台配置字段已集成到 tenant 表中，包括：

  • 站点信息：platform_name, platform_domain, logo_url, favicon_url, contact_email, customer_service_phone, beian_number, default_language
  • 支付配置：payment_config（微信支付、支付宝配置）
  • 存储配置：storage_config（本地存储、OSS、COS、S3配置）
  • 邮件配置：smtp_config
  • 短信配置：sms_config
  • 文章内容：articles（隐私政策、服务条款等）

6.2 API 设计​

  • 使用现有的 GetTenantConfig 和 UpdateTenantConfig 接口
  • 通过中间件检查用户的 owned_tenant_id 来确定权限
  • 当用户为管理员且访问平台配置时，内部使用 tenant_id = 1

6.3 安全考虑​

  • 所有平台配置修改操作都需要管理员权限验证
  • 敏感配置字段（如 API 密钥、私钥等）需要标记为敏感数据
  • 配置修改操作需要记录审计日志

7. 技术考虑​

7.1 依赖服务​

  • tenant 服务：核心服务，负责配置管理
  • user 服务：提供用户认证和权限验证
  • auth 服务：提供 Token 验证和用户角色信息

7.2 数据库​

  • 使用 PostgreSQL 作为主数据库
  • 使用 Ent ORM 进行数据访问
  • 删除 platform_config 表的定义和代码

7.3 性能考虑​

  • 平台配置访问频率较高，考虑添加缓存层
  • 配置变更时需要及时更新缓存
  • 使用数据库索引优化查询性能

8. 成功指标​

  • 独立的 platform_config 表已从数据库模式中完全移除
  • 所有平台配置相关的 API 调用都能通过租户服务正常工作
  • 管理员能够成功通过统一接口管理平台配置
  • 非管理员用户无法访问未授权的配置
  • 系统启动检查成功率为 100%
  • 配置访问的响应时间不超过 100ms
  • 代码中关于配置访问的条件判断减少至少 50%

9. 待解决问题​

  1. 配置验证规则：平台配置的验证规则是否与普通租户配置有所不同？
  2. 默认配置初始化：平台租户创建时的默认配置值如何确定？
  3. 配置变更通知：平台配置变更时是否需要通知其他服务？
  4. 配置历史记录：是否需要保留平台配置的变更历史？
  5. 多环境支持：不同环境（开发、测试、生产）的平台配置如何管理？

10. 验收标准​

  • 独立 platform_config 表或实体已从数据库模式中移除
  • tenant 数据模型已更新，包含除邀请码和平台名称外的平台配置字段
  • 应用程序能够通过查询 tenant 服务获取 tenant_id = 1 的租户及其所有平台配置
  • 对 tenant 和平台配置的认证和授权规则已统一
  • 管理员（owned_tenant_id = 1）能够成功访问和修改平台配置
  • 非管理员用户访问平台配置时返回权限错误
  • 系统启动时能够正确检查和处理平台租户的存在性
  • 现有功能在配置迁移和接口统一后仍能正常工作，无回归
  • 所有相关的单元测试和集成测试通过