Главная Обзор Помощь
Регистрация Вход
188-template-179
/
mini-starter
ответвлено от 155-template-138/mini-starter
2
0
Ответвить 0
Файлы
Дерево: c22e83452d
Ветки Метки
mini-starter
/
docs
/
prd
/
epic-011-employer-mini-program-implementation.md

epic-011-employer-mini-program-implementation.md 15 KB
История Исходник

史诗011 - 用人方小程序功能实现

史诗目标

在mini项目中完整实现用人方小程序的所有页面功能，基于史诗7,8,9,10已移植的API模块基础，为企业用户提供残疾人就业管理的完整解决方案。

史诗描述

现有系统上下文

当前相关功能：

  • mini项目：基础小程序前端，现有登录、注册、个人资料等基础页面
  • API客户端：已集成auth、user、role、file模块的RPC客户端（api.ts）
  • 史诗7,8,9,10成果：已移植allin系统的7个后端模块和对应UI模块（channel、company、disability_person、order、platform、salary等）
  • 原型设计：docs/小程序原型/yongren.html 提供了完整的8个页面原型设计

技术栈：

  • 前端：TypeScript、React、Hono RPC客户端、Tailwind CSS
  • 测试：Jest（mini项目使用Jest，其他包使用Vitest）
  • API通信：基于Hono RPC的API客户端模式
  • 包管理：pnpm workspace

集成点：

  • 需要将史诗7,8,9,10移植的allin系统模块API客户端集成到mini项目
  • 基于已有RPC客户端模式扩展新的API客户端
  • 复用史诗008移植的@d8d/allin-*系列UI组件包
  • 遵循mini项目现有的页面结构和路由配置

增强详情

新增/变更内容： 在mini项目中实现用人方小程序的8个核心页面，包括：

  1. 登录页 - 企业用户手机号密码登录
  2. 首页/看板 - 企业概览、人才分配、数据卡片
  3. 人才列表页 - 人才搜索、筛选、分页展示
  4. 人才详情页 - 个人信息、工作历史、薪资、视频管理
  5. 数据统计页 - 可视化图表、残疾类型分布、性别年龄分布等
  6. 订单管理页 - 订单列表、状态管理、打卡数据统计
  7. 企业设置页 - 企业信息、账号管理、安全设置
  8. 视频查看下载页 - 企业/个人维度的视频管理

页面功能基于：

  • docs/小程序原型/yongren.html 完整原型设计
  • 史诗7,8,9,10移植的API模块提供数据支持
  • 缺失的API接口进行增补实现

集成方式：

  1. API客户端集成：基于现有api.ts模式，新增allin系统模块的RPC客户端
  2. UI组件复用：复用史诗008移植的@d8d/allin-*系列UI包（channel、company、disability_person、order、platform、salary等）
  3. 页面结构：遵循mini项目现有的页面目录结构（src/pages/）
  4. 路由配置：使用现有的路由配置模式

成功标准：

  1. 8个页面功能完整实现，符合原型设计要求
  2. 与史诗7,8,9,10移植的API模块无缝集成
  3. 保持mini项目现有功能的完整性（登录、注册、个人资料等）
  4. 通过Jest测试验证，包括组件测试和集成测试
  5. 遵循项目编码规范和UI组件使用规范

故事列表

故事011-00：补充缺失的API接口

背景： 经过数据库结构分析和API验证，现有allin系统移植模块的API不足以完全支持用人方小程序的所有功能需求，需要基于实际数据库表结构补充关键API接口。

数据库分析发现：

  • 企业用户认证缺失：users2表只有admin用户，缺乏企业用户与employer_company表的关联
  • 视频管理基础存在：order_person_asset表已支持文件关联，但asset_type枚举需要扩展以支持工资视频、个税视频、打卡视频、工作视频等类型
  • 数据统计需要实时计算：无专门统计表，需要基于disabled_person、employment_order、order_person等表实时计算
  • 年龄统计字段缺失：disabled_person表只有age字段，缺乏birth_date字段用于准确年龄统计
  • 个人征信信息存储：通过disabled_bank_card.file_id关联files表存储个人征信截图
  • 企业统计可基于现有表：employer_company、employment_order、order_person表已包含必要关联关系

任务列表：

  1. 数据库schema扩展：

    • 在disabled_person表添加birth_date字段（DATE类型），用于准确年龄统计
    • 扩展order_person_asset表的asset_type枚举，新增视频类型：salary_video（工资视频）、tax_video（个税视频）、checkin_video（打卡视频）、work_video（工作视频）
    • 在users2表添加company_id字段（外键引用employer_company.company_id），建立企业用户关联

  2. 企业用户认证API：扩展auth-module，支持企业用户手机号密码登录（基于users2表+company_id关联）、退出登录、获取企业用户信息（包含关联的企业信息）

  3. 企业统计API：扩展company-module，基于employer_company、employment_order、order_person表实时计算：

    • 企业概览统计：在职人员数、进行中订单数、已完成订单数、累计订单数
    • 企业维度人才统计：分配人才列表、人才状态分布

  4. 人才扩展API：扩展disability-module，提供聚合查询接口：

    • 工作历史查询：基于order_person表查询个人的历史工作记录（关联employment_order表）
    • 薪资历史查询：基于order_person.salary_detail字段和order表查询历史薪资记录
    • 个人征信信息查询：基于disabled_bank_card.file_id关联files表获取征信截图信息
    • 视频关联查询：基于order_person_asset表查询关联的视频文件（按扩展的asset_type分类）

  5. 订单统计API：扩展order-module，提供企业维度统计：

    • 打卡数据统计：基于order_person_asset表（asset_type为checkin_video）统计打卡视频数量
    • 视频统计：按视频类型（工资、个税、打卡、工作）分类统计
    • 企业维度订单查询：支持按企业ID过滤订单列表，包含订单状态、人员关联等详细信息

  6. 数据统计API：创建统计模块或扩展现有模块，基于实时计算提供：

    • 残疾类型分布：基于disabled_person.disability_type统计
    • 性别分布：基于disabled_person.gender统计
    • 年龄分布：基于新增的birth_date字段计算年龄分组（18-25、26-35、36-45、46+）
    • 户籍分布：基于disabled_person.household_province和household_city统计
    • 在职状态统计：基于disabled_person.job_status统计
    • 薪资分布：基于order_person.salary_detail统计薪资范围分布

  7. 视频管理API：扩展file-module或创建视频管理模块：

    • 视频分类管理：支持按扩展的asset_type枚举分类查询
    • 企业维度视频查询：基于企业ID查询关联的所有视频（通过employment_order→order_person→order_person_asset关联链）
    • 个人维度视频查询：基于人员ID查询关联的视频
    • 批量下载功能：支持按企业或个人维度批量下载视频文件

  8. 系统设置API：添加企业用户专属的设置接口：

    • 账号信息管理：修改手机号、密码等
    • 安全设置：登录设备管理、登录日志
    • 消息通知设置：订单状态通知、人才分配通知等

  9. API文档与测试：为所有新增API编写OpenAPI文档、TypeScript类型定义和单元测试

验收标准：

  • 数据库schema扩展完成：disabled_person表添加birth_date字段，order_person_asset表扩展asset_type枚举，users2表添加company_id字段
  • 企业用户可成功登录和获取企业信息（包含关联的企业详情）
  • 企业概览统计接口返回正确的在职人员数、进行中订单数、已完成订单数、累计订单数
  • 人才详情页可查询到工作历史、薪资历史、个人征信信息、关联视频列表
  • 订单管理页可获取打卡数据统计和按类型分类的视频统计
  • 数据统计页所有图表数据可通过API正确获取（残疾类型、性别、年龄、户籍、在职状态、薪资分布）
  • 视频管理页支持按企业/个人维度查询，支持按视频类型筛选和批量下载
  • 系统设置功能完整，账号信息、安全设置、消息通知均可管理
  • 所有新增API通过单元测试，OpenAPI文档和TypeScript类型定义完整

故事011-01：API客户端集成与基础框架搭建

任务列表：

  1. 分析史诗7,8,9,10移植的API模块及故事011-00补充的API，确定需要集成的RPC客户端
  2. 扩展src/api.ts，新增allin系统模块的RPC客户端，包括补充的API接口
  3. 创建用人方小程序的基础布局组件（底部导航、状态栏等）
  4. 实现登录页面功能，与企业用户认证系统集成
  5. 配置用人方小程序的路由结构
  6. 编写API集成的基础测试

验收标准：

  • allin系统模块及补充API的RPC客户端成功集成到api.ts
  • 登录页面功能完整，支持企业用户手机号密码登录
  • 基础布局组件可用，符合移动端设计
  • 路由配置正确，页面导航正常
  • 现有mini项目功能不受影响

故事011-02：核心管理页面实现（人才与订单）

任务列表：

  1. 实现首页/看板页面，展示企业概览数据、在职人员统计、分配人才列表
  2. 实现人才列表页，支持按姓名、残疾证号搜索，按状态、残疾类型筛选
  3. 实现人才详情页，展示基本信息、工作信息、薪资信息、历史工作内容、个人征信、视频管理
  4. 集成人才相关的API接口（disability_person、order等模块及补充API）
  5. 实现薪资信息展示和历史薪资记录查看功能
  6. 添加个人征信信息展示和文件下载功能

验收标准：

  • 首页数据展示正确，统计卡片实时更新
  • 人才列表搜索筛选功能正常，分页可用
  • 人才详情页信息完整，包含基本信息、工作历史、薪资数据、个人征信、视频列表
  • 薪资历史记录可查看，数据准确
  • 个人征信截图可预览和下载
  • API调用错误处理完善

故事011-03：数据统计与系统管理功能

任务列表：

  1. 实现数据统计页，包含残疾类型分布、性别分布、年龄分布、户籍省份分布等图表
  2. 实现订单管理页，展示订单列表、状态管理、打卡数据统计、视频统计
  3. 实现企业设置页，包含企业信息展示、账号管理、安全设置等功能
  4. 实现视频查看下载页，支持企业维度和个人维度的视频管理
  5. 集成订单相关的API接口，支持订单状态管理和数据统计
  6. 添加数据导出和批量下载功能
  7. 完成全面测试和性能优化

验收标准：

  • 数据统计图表正确显示，数据准确
  • 订单管理功能完整，支持查看、编辑、打卡数据统计、视频统计
  • 企业设置页面功能可用，账号信息可管理
  • 视频管理页面支持播放、下载、分享、批量下载功能
  • 批量下载功能正常，支持企业维度批量操作
  • 所有页面响应式设计良好，移动端体验优秀
  • 性能测试通过，页面加载速度符合要求

兼容性要求

  • 现有mini项目功能不受影响（登录、注册、个人资料等）
  • 遵循现有api.ts RPC客户端模式，新增客户端与原有客户端兼容
  • 使用一致的UI组件库，保持界面风格统一
  • 保持路由结构的统一性，新增路由不影响现有路由
  • 数据库schema变化保持向后兼容
  • 性能影响最小化，不影响现有功能响应速度

风险缓解

主要风险：

  1. 数据库schema变更风险：新增字段和枚举扩展可能影响现有数据操作和查询
  2. API集成可能影响现有功能稳定性
  3. UI组件复用可能存在兼容性问题
  4. 数据统计图表性能可能影响页面加载速度

缓解措施：

  1. 数据库变更分步实施：
    • 先添加可为空的birth_date字段，不影响现有记录
    • 扩展asset_type枚举时保留原有枚举值，确保向后兼容
    • users2表添加可为空的company_id字段，现有admin用户不受影响
  2. 逐步集成：每个API模块独立集成，分阶段测试验证
  3. 组件测试：对复用的UI组件进行充分测试，确保兼容性
  4. 性能优化：数据统计图表采用懒加载和分页，优化大数据量展示；实时统计查询添加适当的数据库索引
  5. 回滚计划：保持原有api.ts不变，新增独立客户端文件，便于回滚

回滚计划：

  1. 如果新增功能导致严重问题，可临时移除新增路由，恢复原有功能
  2. API客户端变更可通过版本控制回退到上一个稳定版本
  3. 数据库schema变更支持可逆回滚：
    • birth_date字段：如需要可删除该字段，不影响核心业务数据
    • asset_type枚举扩展：新增的枚举值不影响原有数据，可安全保留
    • company_id字段：如需要可删除该字段，企业用户可暂时通过其他方式关联
  4. 保留完整的数据迁移脚本，支持向前和向后迁移

完成定义

  • 所有4个故事完成，验收标准全部满足
  • 8个页面功能完整，符合原型设计要求
  • API集成测试通过，包括正常流程和异常情况测试
  • 现有功能回归测试通过，确保无功能退化
  • 代码符合项目编码规范，通过代码审查
  • 文档更新完成，包括API接口文档和用户操作手册
  • 性能测试通过，页面加载时间在可接受范围内
  • 移动端适配良好，主流设备测试通过

依赖关系

  • 依赖史诗7,8,9,10移植的API模块和UI组件包
  • 依赖现有mini项目的基础框架和构建配置
  • 依赖数据库schema与移植模块保持一致
  • 需要测试环境支持，包括API服务和数据库

测试策略

  1. 单元测试：对新增组件和工具函数进行Jest单元测试
  2. 集成测试：测试API客户端与后端服务的集成
  3. UI测试：对页面交互和用户体验进行测试
  4. 性能测试：验证数据统计页面的加载和渲染性能
  5. 兼容性测试：测试不同设备和浏览器的兼容性
  6. 回归测试：确保现有功能不受影响

故事经理交接说明：

请为这个已有项目开发详细用户故事。关键考虑：

  • 这是对现有mini项目的增强，技术栈：TypeScript、React、Hono RPC、Tailwind CSS，测试使用Jest
  • 集成点：史诗7,8,9,10移植的allin系统API模块（channel、company、disability_person、order、platform、salary等）
  • 现有模式：遵循mini项目现有的api.ts RPC客户端模式、页面结构和路由配置
  • 关键兼容要求：不影响现有登录、注册、个人资料等功能，保持系统完整性
  • 每个故事必须验证现有功能保持完整

史诗应在保持系统完整性的同时，为企业用户提供完整的残疾人就业管理功能，实现docs/小程序原型/yongren.html中的完整页面功能。