Inicio Explorar Ayuda
Registro Iniciar sesión
188-template-179
/
mini-starter
forked de 155-template-138/mini-starter
2
0
Fork 0
Archivos
Árbol: 38eeb08b79
Ramas Etiquetas
mini-starter
/
docs
/
stories
/
008.008.integrate-allin-ui-packages-to-web-client-admin.story.md

008.008.integrate-allin-ui-packages-to-web-client-admin.story.md 11 KB
Histórico Raw

Story 008.008: 将Allin系统UI包集成到Web client admin

Status

Draft

Story

As a 系统管理员， I want 将史诗008中创建的7个Allin系统UI包集成到Web client admin中， so that 管理员可以通过Web界面管理Allin系统的所有功能，包括渠道、公司、残疾人、订单、平台、薪资等模块，实现前后端完整集成。

Acceptance Criteria

  1. 依赖配置：在web/package.json中添加所有7个Allin系统UI包的workspace依赖

    • @d8d/allin-channel-management-ui
    • @d8d/allin-company-management-ui
    • @d8d/allin-disability-management-ui
    • @d8d/allin-disability-person-management-ui
    • @d8d/allin-order-management-ui
    • @d8d/allin-platform-management-ui
    • @d8d/allin-salary-management-ui

  2. API客户端初始化：在web/src/client/admin/api_init.ts中添加所有7个Allin系统UI包的API客户端初始化，路径必须与server包中的路由配置完全一致（参考packages/server/src/index.ts:139-144）

    • channelClientManager.init('/api/v1/channel') - 对应server中的/api/v1/channel
    • companyClientManager.init('/api/v1/company') - 对应server中的/api/v1/company
    • disabilityClientManager.init('/api/v1/disability') - 对应server中的/api/v1/disability（注意：disability_person模块在server中注册为/api/v1/disability）
    • orderClientManager.init('/api/v1/order') - 对应server中的/api/v1/order
    • platformClientManager.init('/api/v1/platform') - 对应server中的/api/v1/platform
    • salaryClientManager.init('/api/v1/salary') - 对应server中的/api/v1/salary
    • 注意：所有路径使用单数形式，没有s后缀，与server包配置保持一致

  3. 路由集成：在web/src/client/admin/routes.tsx中添加所有7个UI包的路由配置

    • /admin/channels → @d8d/allin-channel-management-ui
    • /admin/companies → @d8d/allin-company-management-ui
    • /admin/disabilities → @d8d/allin-disability-management-ui
    • /admin/disability-persons → @d8d/allin-disability-person-management-ui
    • /admin/orders → @d8d/allin-order-management-ui
    • /admin/platforms → @d8d/allin-platform-management-ui
    • /admin/salaries → @d8d/allin-salary-management-ui

  4. 菜单集成：在web/src/client/admin/menu.tsx中添加对应的菜单项

    • 渠道管理
    • 公司管理
    • 残疾人管理
    • 残疾人个人管理
    • 订单管理
    • 平台管理
    • 薪资管理

  5. 权限配置：为每个菜单项配置相应的权限（参考现有权限模式）

  6. 图标配置：为每个菜单项配置合适的图标（使用lucide-react图标库）

  7. API路径配置：确保API路径与后端路由对应（参考史诗007的server集成）

  8. 集成验证：验证所有路由正常工作，UI包正确加载，API客户端初始化成功

  9. 测试验证：通过E2E测试验证集成功能

Tasks / Subtasks

  • [ ] 任务1：添加依赖配置 (AC: 1)

    • 在web/package.json的dependencies中添加7个Allin UI包的workspace依赖
    • 验证依赖名称与UI包实际package.json中的name字段一致
    • 运行pnpm install确保依赖正确安装

  • [ ] 任务2：API客户端初始化 (AC: 2, 7)

    • 在web/src/client/admin/api_init.ts中添加7个Allin UI包的导入语句
    • 按照server包路由配置初始化每个客户端管理器
    • 关键验证：确保API路径与server包中的路由完全一致（单数形式，无s后缀）
    • 验证disability_person模块使用/api/v1/disability路径（与server配置一致）

  • [ ] 任务3：路由配置集成 (AC: 3)

    • 在web/src/client/admin/routes.tsx中导入7个Allin UI包的主要组件
    • 添加对应的路由配置到router数组中
    • 确保路由路径与菜单路径一致
    • 为每个路由添加errorElement处理

  • [ ] 任务4：菜单配置集成 (AC: 4, 5, 6)

    • 在web/src/client/admin/menu.tsx的menuItems数组中添加7个菜单项
    • 为每个菜单项配置合适的lucide-react图标
    • 为每个菜单项配置相应的权限（参考现有权限模式如'user:manage'）
    • 确保菜单路径与路由路径一致

  • [ ] 任务5：集成验证 (AC: 8)

    • 启动web开发服务器验证所有路由正常工作
    • 验证每个UI包正确加载，无导入错误
    • 验证API客户端初始化成功，无网络错误
    • 验证菜单项正确显示，点击导航正常

  • [ ] 任务6：E2E测试验证 (AC: 9)

    • 编写E2E测试验证7个Allin系统页面的基本访问
    • 测试每个页面的加载和基本交互
    • 验证API调用正常工作
    • 运行pnpm test:e2e:chromium确保测试通过

  • [ ] 任务7：类型检查和构建验证

    • 运行pnpm typecheck确保无类型错误
    • 运行pnpm build确保构建成功
    • 验证生产环境构建无错误

Dev Notes

项目结构信息

  • Web项目位置: web/目录
  • API客户端初始化文件: web/src/client/admin/api_init.ts [Source: architecture/source-tree.md#实际项目结构]
  • 路由配置文件: web/src/client/admin/routes.tsx [Source: architecture/source-tree.md#实际项目结构]
  • 菜单配置文件: web/src/client/admin/menu.tsx [Source: architecture/source-tree.md#实际项目结构]
  • 现有UI包集成模式: 参考@d8d/user-management-ui、@d8d/auth-management-ui等现有集成 [Source: architecture/source-tree.md#实际项目结构]

后端路由配置（关键参考）

Server包路由配置 (packages/server/src/index.ts:139-144):

export const channelApiRoutes = api.route('/api/v1/channel', channelRoutes)
export const companyApiRoutes = api.route('/api/v1/company', companyRoutes)
export const disabilityApiRoutes = api.route('/api/v1/disability', disabledPersonRoutes)
export const orderApiRoutes = api.route('/api/v1/order', orderRoutes)
export const platformApiRoutes = api.route('/api/v1/platform', platformRoutes)
export const salaryApiRoutes = api.route('/api/v1/salary', salaryRoutes)

重要: 所有路径使用单数形式，没有s后缀。disability_person模块在server中注册为/api/v1/disability路径。

Allin UI包信息

所有7个UI包已创建在allin-packages/目录下，包名如下：

  1. @d8d/allin-channel-management-ui - 渠道管理UI
  2. @d8d/allin-company-management-ui - 公司管理UI
  3. @d8d/allin-disability-management-ui - 残疾人管理UI
  4. @d8d/allin-disability-person-management-ui - 残疾人个人管理UI
  5. @d8d/allin-order-management-ui - 订单管理UI
  6. @d8d/allin-platform-management-ui - 平台管理UI
  7. @d8d/allin-salary-management-ui - 薪资管理UI

现有集成模式参考

API客户端初始化模式 (web/src/client/admin/api_init.ts):

import { userClientManager } from '@d8d/user-management-ui/api';
userClientManager.init('/api/v1/users');

路由集成模式 (web/src/client/admin/routes.tsx):

import { UserManagement } from '@d8d/user-management-ui';
{
  path: 'users',
  element: <UserManagement />,
  errorElement: <ErrorPage />
}

菜单集成模式 (web/src/client/admin/menu.tsx):

{
  key: 'users',
  label: '用户管理',
  icon: <Users className="h-4 w-4" />,
  path: '/admin/users',
  permission: 'user:manage'
}

权限配置参考

现有权限模式使用{resource}:{action}格式，例如：

  • 'user:manage' - 用户管理权限
  • 'file:manage' - 文件管理权限
  • 'area:manage' - 区域管理权限

建议为Allin系统模块配置相应的权限，如：

  • 'channel:manage' - 渠道管理权限
  • 'company:manage' - 公司管理权限
  • 'disability:manage' - 残疾人管理权限
  • 'order:manage' - 订单管理权限
  • 'platform:manage' - 平台管理权限
  • 'salary:manage' - 薪资管理权限

图标配置参考

使用lucide-react图标库，现有图标示例：

  • <Users className="h-4 w-4" /> - 用户管理
  • <File className="h-4 w-4" /> - 文件管理
  • <MapPin className="h-4 w-4" /> - 区域管理

建议图标：

  • 渠道管理: <MessageSquare className="h-4 w-4" /> 或 <Share2 className="h-4 w-4" />
  • 公司管理: <Building className="h-4 w-4" /> 或 <Briefcase className="h-4 w-4" />
  • 残疾人管理: <User className="h-4 w-4" /> 或 <Users className="h-4 w-4" />
  • 订单管理: <ClipboardList className="h-4 w-4" /> 或 <FileText className="h-4 w-4" />
  • 平台管理: <Monitor className="h-4 w-4" /> 或 <Globe className="h-4 w-4" />
  • 薪资管理: <DollarSign className="h-4 w-4" /> 或 <CreditCard className="h-4 w-4" />

技术栈信息

  • 前端框架: React 19 [Source: architecture/tech-stack.md#现有技术栈维护]
  • 状态管理: React Query [Source: architecture/tech-stack.md#现有技术栈维护]
  • 路由: React Router [Source: architecture/source-tree.md#实际项目结构]
  • UI组件: @d8d/shared-ui-components (基于shadcn/ui) [Source: architecture/tech-stack.md#现有技术栈维护]
  • API客户端: Hono RPC (rpcClient + ClientManager模式) [Source: architecture/ui-package-standards.md#rpc客户端实现规范]

与史诗007的对应关系

  • 本故事对应史诗007的故事8：将Allin系统模块集成到packages/server
  • 确保前端UI包与后端模块的集成时间点对齐
  • 验证前后端集成功能完整性

项目结构注意事项

  • 所有Allin UI包已创建在allin-packages/目录下
  • Web项目使用workspace依赖管理，依赖格式为"workspace:*"
  • API路径必须与server包路由配置完全一致，特别注意单数形式和路径大小写

开发服务器说明

  • 开发服务器: 开发服务器在8080端口默认开机自动启动，无需手动启动 [Source: CLAUDE.md#开发环境说明]
  • 访问地址: 集成验证时可通过 http://localhost:8080 访问Web界面
  • API服务: 后端API服务与Web服务器一同运行，API路径基于同一端口

Testing

测试标准

  • E2E测试位置: web/tests/e2e/ [Source: architecture/testing-strategy.md#e2e测试-end-to-end-tests]
  • 测试框架: Playwright [Source: architecture/testing-strategy.md#e2e测试-end-to-end-tests]
  • 执行命令: pnpm test:e2e:chromium [Source: CLAUDE.md#测试调试]
  • 测试覆盖要求: 关键用户流程100% [Source: architecture/testing-strategy.md#e2e测试-end-to-end-tests]

本故事测试要求

  • 编写E2E测试验证7个Allin系统页面的基本访问
  • 测试每个页面的加载和基本交互
  • 验证API调用正常工作
  • 确保测试通过率100%

测试执行流程

  1. 本地开发测试: cd web && pnpm test:e2e:chromium
  2. 验证所有测试通过
  3. 如有测试失败，查看test-results/**/error-context.md分析问题 [Source: CLAUDE.md#测试调试]

Change Log

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

Dev Agent Record

此部分由开发代理在实施期间填写

QA Results

来自QA代理对已完成故事实施的QA审查结果