Accueil Explorer Aide
S'inscrire Connexion
186-template-175
/
mini-starter
forké depuis 155-template-138/mini-starter
2
0
Fork 0
Fichiers
Aborescence: 02aa8e1b96
Branches Tags
mini-starter
/
docs
/
stories
/
010.004.system-config-ui-package.story.md

010.004.system-config-ui-package.story.md 15 KB
Historique Raw

Story 010.004: system-config-ui-package

Status

Draft

Story

As a 系统管理员， I want 在管理后台中查看和管理租户的系统配置， so that 可以为不同租户配置小程序登录和支付参数

Acceptance Criteria

  1. 创建系统配置UI包，提供系统配置管理界面
  2. 在管理后台中集成系统配置管理页面
  3. 支持按租户筛选和查看系统配置
  4. 提供配置项的增删改查功能
  5. 验证现有功能保持完整，无回归

任务 / 子任务

  • [ ] 任务 1 (AC: 1): 创建多租户系统配置界面包结构

    • 创建包目录：packages/system-config-management-ui-mt/
    • 复制广告管理包结构作为参考：cp -r packages/advertisement-management-ui-mt/* packages/system-config-management-ui-mt/
    • 重要：复制后立即重命名文件为系统配置包名
    • 更新包名为 @d8d/system-config-management-ui-mt

  • [ ] 任务 2 (AC: 1, 3): 配置包依赖和构建

    • 复制并修改 packages/system-config-management-ui-mt/package.json：
    • 更新包名："name": "@d8d/system-config-management-ui-mt"
    • 更新依赖："@d8d/core-module-mt/system-config-module-mt": "workspace:*"
    • 删除广告管理相关依赖：@d8d/advertisements-module-mt、@d8d/advertisement-type-management-ui-mt
    • 复制并修改 packages/system-config-management-ui-mt/tsconfig.json：
    • 更新路径映射："@d8d/core-module-mt/system-config-module-mt/*"
    • 复制并修改 packages/system-config-management-ui-mt/vitest.config.ts：
    • 更新测试环境配置
    • 复制并修改 packages/system-config-management-ui-mt/tests/setup.ts：
    • 更新测试设置的系统配置相关配置
    • 复制并修改 packages/system-config-management-ui-mt/eslint.config.js：
    • 更新ESLint配置
    • 安装依赖：cd packages/system-config-management-ui-mt && pnpm install

  • [ ] 任务 3 (AC: 4, 5): 实现RPC客户端架构和类型定义

    • 复制并修改 packages/system-config-management-ui-mt/src/api/systemConfigClient.ts：
    • 更新导入路径：import { systemConfigRoutesMt } from '@d8d/core-module-mt/system-config-module-mt'
    • 更新客户端实例：systemConfigClient = systemConfigRoutesMt
    • 保持单例模式和延迟初始化逻辑 [参照: packages/advertisement-management-ui-mt/src/api/advertisementClient.ts]
    • 复制并修改 packages/system-config-management-ui-mt/src/types/systemConfig.ts：
    • 从多租户系统配置模块包导入类型定义
    • 确保类型定义与系统配置架构对齐
    • 验证RPC客户端在主应用中的正确集成 [参考: web/src/client/api_init.ts]
    • 实现类型安全的API调用模式 [参考: packages/advertisement-management-ui-mt/src/components/AdvertisementManagement.tsx:100-112]

  • [ ] 任务 4 (AC: 1, 5): 复制并调整系统配置管理界面组件

    • 复制并修改 packages/system-config-management-ui-mt/src/components/SystemConfigManagement.tsx：
    • 更新导入路径：
      • import { systemConfigClientManager } from '../api/systemConfigClient'
      • import { CreateSystemConfigDto, UpdateSystemConfigDto } from '@d8d/core-module-mt/system-config-module-mt/schemas'
    • 规范：共享UI包组件导入必须使用具体组件路径，如 @d8d/shared-ui-components/components/ui/button，避免从根导入
    • 使用系统配置客户端管理实例.get()来获取系统配置RPC客户端
    • 骨架屏优化：确保骨架屏只在表格数据区域显示，不影响搜索框、筛选器等其他UI元素
    • 调整表单字段为系统配置相关字段：configKey, configValue, description等
    • 复制并修改组件导出文件：
    • packages/system-config-management-ui-mt/src/components/index.ts

  • [ ] 任务 5 (AC: 3, 4): 实现完整的系统配置管理功能

    • 复制并修改 packages/system-config-management-ui-mt/src/hooks/useSystemConfigs.ts：
    • 更新导入路径，使用多租户系统配置客户端
    • 确保查询和突变操作使用正确的多租户API
    • 复制并修改hooks导出文件：
    • packages/system-config-management-ui-mt/src/hooks/index.ts
    • 实现搜索和过滤功能，支持按configKey和description搜索
    • 实现配置值的表单验证和错误处理
    • 确保所有组件支持多租户上下文

  • [ ] 任务 6 (AC: 2): 集成系统配置UI包到管理后台

    • 在管理后台路由中添加系统配置页面路由 [参照: web/src/client/admin/routes.tsx]
    • 在管理后台菜单中添加系统配置菜单项 [参照: web/src/client/admin/menu.tsx]
    • 配置系统配置页面的权限控制 [参照: web/src/client/admin/routes.tsx]
    • 验证系统配置页面在管理后台中正确显示和功能正常

  • [ ] 任务 7 (AC: 5, 6): 创建测试套件

    • 复制并修改 packages/system-config-management-ui-mt/tests/integration/system-config-management.integration.test.tsx：
    • 更新导入路径，使用系统配置包
    • 添加系统配置管理功能测试
    • 复制并修改 packages/system-config-management-ui-mt/tests/setup.ts：
    • 配置系统配置测试环境
    • 系统配置测试重点：
    • 测试系统配置列表页面渲染
    • 验证配置项的增删改查功能
    • 测试租户筛选功能
    • 确保API调用包含正确的租户标识

  • [ ] 任务 8 (AC: 1, 7): 配置包导出接口

    • 复制并修改 packages/system-config-management-ui-mt/src/index.ts：
    • 更新导出组件和hook的路径
    • 确保所有导出组件、hook和类型定义正确
    • 验证导出脚本正常工作

  • [ ] 任务 9 (AC: 6, 8): 验证功能无回归

    • 运行包构建：cd packages/system-config-management-ui-mt && pnpm build
    • 运行所有测试：cd packages/system-config-management-ui-mt && pnpm test
    • 验证系统配置管理功能正常
    • 验证与多租户系统兼容性
    • 验证现有管理后台功能无回归

Dev Notes

技术栈信息 [Source: architecture/tech-stack.md]

  • 前端框架: React 19.1.0 + TypeScript
  • 路由: React Router v7
  • 状态管理: @tanstack/react-query (服务端状态) + Context (本地状态)
  • UI组件库: shadcn/ui (基于Radix UI)
  • 构建工具: Vite 7.0.0
  • 样式: Tailwind CSS 4.1.11
  • HTTP客户端: 基于Hono Client的封装 + axios适配器

项目结构信息 [Source: architecture/source-tree.md]

  • 管理后台位置: web/src/client/admin/
  • 页面组件位置: web/src/client/admin/pages/
  • 共享组件位置: web/src/client/components/ui/
  • 系统配置模块位置: packages/core-module-mt/system-config-module-mt/
  • API客户端位置: web/src/client/api.ts

现有管理后台结构 [Source: web/src/client/admin/pages/Users.tsx]

  • 页面组件模式: 使用React函数组件 + TypeScript
  • 状态管理: 使用React Query管理服务端状态，useState管理本地状态
  • 表单处理: 使用react-hook-form + zod验证
  • UI组件: 使用shadcn/ui组件库
  • API调用: 使用Hono RPC客户端，类型安全
  • 分页模式: 使用DataTablePagination组件
  • 搜索过滤: 支持关键词搜索和高级筛选

系统配置模块现有结构 [Source: packages/core-module-mt/system-config-module-mt/src/services/system-config.service.mt.ts]

  • SystemConfigServiceMt: 继承GenericCrudService，支持多租户和Redis缓存
  • 实体字段: id, tenantId, configKey, configValue, description, createdBy, updatedBy, createdAt, updatedAt
  • API端点: 完整的CRUD API，支持租户隔离
  • 缓存策略: Redis缓存，正常值1小时TTL，空值5分钟TTL

API规范

  • 使用RPC客户端架构进行API调用 [Source: architecture/tech-stack.md#前端技术栈]
  • 租户上下文由后端认证包处理，前端使用标准RPC客户端 [Source: architecture/component-architecture.md#认证授权]
  • 系统配置API端点：/api/system-configs [Source: packages/core-module-mt/system-config-module-mt/src/routes/system-config.routes.mt.ts]
  • 系统配置路由导出：systemConfigRoutesMt [Source: packages/core-module-mt/system-config-module-mt/src/index.mt.ts]
  • 使用单例模式和延迟初始化确保类型安全和性能 [参照: packages/advertisement-management-ui-mt/src/api/advertisementClient.ts]

配置键定义 [Source: packages/core-module-mt/system-config-module-mt/src/constants/config-keys.constants.mt.ts]

  • 认证配置键:
    • wx.mini.app.id - 微信小程序AppID
    • wx.mini.app.secret - 微信小程序AppSecret
  • 支付配置键:
    • wx.payment.merchant.id - 微信支付商户ID
    • wx.payment.v3.key - 微信支付V3密钥
    • wx.payment.cert.serial.no - 商户证书序列号
    • wx.payment.public.key - 商户公钥
    • wx.payment.private.key - 商户私钥
    • wx.payment.notify.url - 支付回调URL

组件规范

  • React 19.1.0 + TypeScript [Source: architecture/tech-stack.md#前端技术栈]
  • TanStack Query v5用于状态管理 [Source: architecture/tech-stack.md#前端技术栈]
  • React Hook Form v7用于表单处理 [Source: architecture/tech-stack.md#前端技术栈]
  • 组件采用函数式组件和Hooks模式 [Source: architecture/component-architecture.md#组件设计原则]
  • 使用shadcn/ui组件库构建界面 [Source: architecture/tech-stack.md#前端技术栈]

文件位置

  • 新包位置：packages/system-config-management-ui-mt/ [Source: architecture/source-tree.md#包结构]
  • 组件文件：packages/system-config-management-ui-mt/src/components/ [Source: architecture/source-tree.md#前端包结构]
  • API客户端：packages/system-config-management-ui-mt/src/api/ [Source: architecture/source-tree.md#前端包结构]
  • 测试文件：packages/system-config-management-ui-mt/tests/ [Source: 广告管理包实际结构]

UI包创建策略

  • 包命名: system-config-management-ui-mt
  • 包位置: 在packages目录下创建
  • 组件结构: 遵循现有管理后台组件模式 [参照: packages/advertisement-management-ui-mt/src/components/AdvertisementManagement.tsx]
  • API集成: 使用Hono RPC客户端，类型安全 [参照: packages/advertisement-management-ui-mt/src/api/advertisementClient.ts]
  • 租户支持: 支持多租户筛选和管理 [参照: packages/advertisement-management-ui-mt/src/components/AdvertisementManagement.tsx]

测试要求

  • 使用Vitest进行集成测试 [Source: architecture/testing-strategy.md#测试框架]
  • 使用Testing Library进行组件集成测试 [Source: architecture/testing-strategy.md#测试框架]
  • 测试文件组织：集成测试在 tests/integration/，单元测试在 tests/unit/ [Source: 广告管理包实际结构]
  • 重点验证系统配置管理和功能完整性
  • 系统配置测试重点：
    • 测试系统配置列表页面渲染
    • 验证配置项的增删改查功能
    • 测试租户筛选功能
    • 确保API调用包含正确的租户标识
    • 验证认证和授权的多租户感知

技术约束

  • Node.js 20.19.2 [Source: architecture/tech-stack.md#开发环境]
  • TypeScript严格模式启用 [Source: architecture/component-architecture.md#typescript配置]
  • 租户上下文由后端处理，前端使用标准RPC客户端 [Source: architecture/component-architecture.md#多租户支持]

实施注意事项

  • 依赖管理: 所有包配置更新完成后，必须执行 pnpm install 命令以确保依赖正确安装
  • 包命名规范: 多租户包使用 -mt 后缀标识（Multi-Tenant）
  • API客户端集成: 必须使用系统配置模块包导出的路由 systemConfigRoutesMt
  • 类型安全: 确保从系统配置模块包正确导入类型定义

关键参考文件路径

  • 广告管理主组件: packages/advertisement-management-ui-mt/src/components/AdvertisementManagement.tsx - 完整的CRUD管理组件参考
  • 广告管理API客户端: packages/advertisement-management-ui-mt/src/api/advertisementClient.ts - Hono RPC客户端实现参考
  • 广告管理类型定义: packages/advertisement-management-ui-mt/src/types/advertisement.ts - TypeScript类型定义参考
  • 广告管理包配置: packages/advertisement-management-ui-mt/package.json - 包依赖和配置参考
  • 广告管理集成测试: packages/advertisement-management-ui-mt/tests/integration/advertisement-management.integration.test.tsx - 完整集成测试参考
  • 广告管理包导出: packages/advertisement-management-ui-mt/src/index.ts - 包导出结构参考
  • 系统配置路由: packages/core-module-mt/system-config-module-mt/src/routes/system-config.routes.mt.ts - API路由定义参考
  • 系统配置包导出: packages/core-module-mt/system-config-module-mt/src/index.mt.ts - 模块导出结构参考

系统配置相关参考文件路径

  • 用户管理页面参考: web/src/client/admin/pages/Users.tsx
  • 系统配置服务: packages/core-module-mt/system-config-module-mt/src/services/system-config.service.mt.ts
  • 系统配置路由: packages/core-module-mt/system-config-module-mt/src/routes/system-config.routes.mt.ts
  • 系统配置实体: packages/core-module-mt/system-config-module-mt/src/entities/system-config.entity.mt.ts
  • 系统配置Schema: packages/core-module-mt/system-config-module-mt/src/schemas/system-config.schema.mt.ts

Testing

测试标准 [Source: architecture/testing-strategy.md]

  • 测试框架: Vitest + hono/testing
  • 测试位置: 各模块的tests/integration/目录
  • 测试类型: 集成测试
  • 覆盖率目标: 集成测试 ≥ 60%

测试文件结构

  • packages/system-config-management-ui-mt/tests/unit/ - UI组件单元测试 [参照: packages/advertisement-management-ui-mt/tests/integration/advertisement-management.integration.test.tsx]
  • web/tests/integration/system-config.integration.test.ts - 系统配置页面集成测试 [参照: packages/advertisement-management-ui-mt/tests/integration/advertisement-management.integration.test.tsx]

测试场景

  • 系统配置列表页面渲染测试 [参照: packages/advertisement-management-ui-mt/tests/integration/advertisement-management.integration.test.tsx]
  • 系统配置创建功能测试 [参照: packages/advertisement-management-ui-mt/tests/integration/advertisement-management.integration.test.tsx]
  • 系统配置编辑功能测试 [参照: packages/advertisement-management-ui-mt/tests/integration/advertisement-management.integration.test.tsx]
  • 系统配置删除功能测试 [参照: packages/advertisement-management-ui-mt/tests/integration/advertisement-management.integration.test.tsx]
  • 租户筛选功能测试 [参照: packages/advertisement-management-ui-mt/tests/integration/advertisement-management.integration.test.tsx]
  • 现有管理后台功能回归测试 [参照: packages/advertisement-management-ui-mt/tests/integration/advertisement-management.integration.test.tsx]

Change Log

Date Version Description Author
2025-11-20 1.0 初始故事创建 Bob (Scrum Master)

Dev Agent Record

Agent Model Used

  • Agent: James (Dev Agent)
  • Environment: Multi-tenant development environment
  • Session Date: 2025-11-20

Debug Log References

Completion Notes List

File List

QA Results