Strona główna Odkrywaj Pomoc
Zarejestruj się Zaloguj się
188-template-179
/
mini-starter
sklonowany z 155-template-138/mini-starter
2
0
Forkuj 0
Pliki
Drzewo: 4c8f3c49df
Gałęzie Tagi
mini-starter
/
docs
/
stories
/
011.001.story.md

011.001.story.md 17 KB
Historia Czysty

故事 011.001：基础框架搭建

状态

已完成

故事

作为系统开发人员， 我希望建立用人方小程序的基础技术框架， 以便后续页面开发有统一的API客户端、路由和布局基础。

验收标准

  1. allin系统模块及史诗012补充API的RPC客户端成功集成到mini/src/api.ts
  2. 用人方小程序的路由结构配置完成，支持页面导航
  3. 基础布局组件（状态栏、底部导航、页面容器）可用并符合移动端设计
  4. 企业用户认证框架就绪，支持后续登录页面集成
  5. 现有mini项目功能不受影响

任务 / 子任务

  • 任务1：分析需要集成的API模块（AC：1）
    • 识别史诗7,8,9,10移植的allin系统模块：channel、company、disability_person、order、platform、salary等
    • 识别史诗012补充的API接口（企业用户认证、企业统计、人才扩展、订单统计、数据统计、视频管理等）
    • 确定RPC客户端接口定义和类型
  • 任务2：扩展mini/src/api.ts RPC客户端（AC：1）
    • 分析现有mini/src/api.ts结构，了解RPC客户端模式
    • 添加新的模块客户端，使用api/v1/yongren路径前缀
    • 确保类型安全，正确导入模块类型
    • 验证客户端能够正常调用后端API
  • 任务3：配置用人方小程序路由结构（AC：2）
    • 分析现有mini项目路由配置
    • 添加用人方小程序的路由页面映射（8个页面）
    • 配置路由守卫框架，支持后续登录状态验证
    • 测试基础路由跳转
  • 任务4：创建基础布局组件（AC：3）
    • 参考docs/小程序原型/yongren.html设计
    • 实现状态栏组件（显示用户信息和系统状态）
    • 实现底部导航组件（首页、人才、订单、数据、设置）
    • 实现页面容器组件（统一页面布局和样式）
    • 确保移动端响应式设计
  • 任务5：建立企业用户认证框架（AC：4）
    • 集成史诗012提供的企业用户认证API客户端
    • 创建认证状态管理（token存储、验证）
    • 建立权限检查框架
    • 为后续登录页面提供基础支持
  • 任务6：编写基础测试（AC：5）
    • 编写RPC客户端单元测试
    • 编写路由配置测试
    • 编写布局组件测试
    • 验证现有功能不受影响的回归测试

开发笔记

先前故事洞察

史诗011中无先前故事（这是第一个故事）。依赖史诗012的完成状态：

  • 史诗012已完成5/6核心故事（83%），MVP API就绪 [来源：docs/prd/epic-011-employer-mini-program-implementation.md#状态更新]
  • 延期API：系统设置API（P2优先级，非MVP必需）

API规范

RPC客户端模式：

  • 现有API客户端位于mini/src/api.ts，使用Hono RPC客户端模式 [来源：mini/src/api.ts]
  • 当前已集成的模块：auth、user、role、file [来源：mini/src/api.ts]
  • 需要新增的模块：channel、company、disability_person、order、platform、salary等allin系统模块
  • API路径前缀：api/v1/yongren [来源：docs/prd/epic-011-employer-mini-program-implementation.md#集成方式]

技术栈：

  • 前端：TypeScript、React、Hono RPC客户端、Tailwind CSS [来源：docs/architecture/tech-stack.md]
  • 测试：Jest（mini项目使用Jest，其他包使用Vitest）[来源：docs/architecture/tech-stack.md]

组件规范

基础布局组件要求： 必须严格对照原型文件 docs/小程序原型/yongren.html 中的样式定义实现：

容器与框架：

  • .mobile-frame：宽度375px，高度667px，圆角40px，阴影 box-shadow: 0 10px 30px rgba(100, 100, 100, 0.2)，背景白色
  • 重要区分：
    • 系统状态栏：小程序环境中由宿主（如微信/支付宝）提供，无需自行实现
    • 页面导航栏（Navbar）：页面内部的标题和操作区域，需要实现
  • 页面内容区域：高度 calc(100% - 60px)（仅减去底部导航60px）

页面导航栏（Navbar）样式：

  • 参照原型中页面顶部的标题区域实现（如数据统计页第880-886行）
  • 典型结构：flex justify-between items-center mb-4
  • 左侧标题：<h3 class="font-semibold text-gray-700">页面标题</h3>
  • 右侧操作：时间选择器、筛选按钮、新建按钮等
  • 高度建议：44-48px

底部导航样式：

  • .tab-bar：高度60px，背景白色，顶部边框 1px solid #f0f0f0
  • .tab-item：flex列布局，字体大小12px，默认颜色 #999
  • .tab-item.active：激活状态颜色 #3b82f6

颜色系统：

  • 主色调：#3b82f6（蓝色），渐变背景 linear-gradient(135deg, #3b82f6 0%, #1e40af 100%)
  • 辅助色：成功色 #10b981（绿色），警告色 #f59e0b（橙色），强调色 #8b5cf6（紫色）
  • 文字色：标题 #1f2937，正文 #6b7280，辅助文字 #9ca3af

卡片与阴影：

  • .card：圆角12px，阴影 box-shadow: 0 4px 12px rgba(0, 0, 0, 0.05)
  • 统计卡片：圆角12px，阴影 box-shadow: 0 2px 8px rgba(0, 0, 0, 0.05)，padding 16px

UI组件开发：

  • 独立开发小程序UI组件：基于原型文件docs/小程序原型/yongren.html独立设计开发小程序UI组件
  • 复用现有小程序通用组件：复用mini项目中已有的通用UI组件（如登录注册相关组件），只修改样式，保持核心认证逻辑不变
  • 注意：史诗011针对mini小程序，UI组件应独立设计，而非复用管理后台的@d8d/allin-*系列UI包

文件位置

mini项目结构：

  • mini/src/api.ts - API客户端主文件，需要扩展
  • mini/src/pages/ - 页面组件目录，需要新增用人方小程序页面
  • mini/src/layouts/ - 布局组件目录，可添加标签栏布局
  • mini/src/components/ - 公共组件目录，可添加基础布局组件

设计原型位置：

  • docs/小程序原型/yongren.html - 用人方小程序完整原型设计 [来源：docs/prd/epic-011-employer-mini-program-implementation.md#页面功能基于]

技术约束

  • 兼容性要求：现有mini项目功能不受影响（登录、注册、个人资料等）[来源：docs/prd/epic-011-employer-mini-program-implementation.md#兼容性要求]
  • API客户端模式：遵循现有api.ts RPC客户端模式，新增客户端与原有客户端兼容
  • 路由结构：保持路由结构的统一性，新增路由不影响现有路由

测试要求

  • 测试框架：Jest（mini项目）[来源：docs/prd/epic-011-employer-mini-program-implementation.md#技术栈]
  • 覆盖率目标：核心业务逻辑 > 80% [来源：docs/architecture/coding-standards.md#增强特定标准]
  • 关键测试场景：
    1. API客户端测试：验证RPC客户端正常调用
    2. 路由测试：测试页面导航
    3. 布局组件测试：测试组件渲染和交互
    4. 兼容性测试：验证现有功能不受影响

变更日志

日期 版本 描述 作者
2025-12-17 1.0 初始创建（拆分后的基础框架故事） Bob（Scrum Master）
2025-12-17 1.1 基础框架实施完成 James
2025-12-18 1.2 修复测试问题，完成路由配置测试 James
2025-12-18 1.3 优化页面结构：删除重复yongren登录页，改造原有登录页为企业用户登录，统一认证系统，清理注册页面，更新测试 Claude Code
2025-12-18 1.4 修复tabbar使用问题：更新7个企业页面使用YongrenTabBarLayout，改造profile页面为企业账户页；清理无用页面：删除pages/index/和pages/explore/目录，优化路由配置；修复导入导出问题：统一YongrenTabBarLayout导出方式，更新所有页面导入 Claude Code

开发代理记录

2025-12-17 开始实施

  • 故事状态已更新为"已批准"
  • 开始执行任务1：分析需要集成的API模块

2025-12-17 任务1分析结果

识别的allin系统移植模块（史诗7,8,9,10）：

  1. channel-module (@d8d/allin-channel-module)
  2. company-module (@d8d/allin-company-module)
  3. disability-module (@d8d/allin-disability-module)
  4. order-module (@d8d/allin-order-module)
  5. platform-module (@d8d/allin-platform-module)
  6. salary-module (@d8d/allin-salary-module)
  7. enums (@d8d/allin-enums)
  8. statistics-module (@d8d/allin-statistics-module)

识别的史诗012补充API接口：

  1. 企业用户认证 (enterpriseAuthApiRoutes) - 路径前缀：/api/v1/yongren/auth
  2. 企业统计 (enterpriseCompanyApiRoutes) - 路径前缀：/api/v1/yongren/company
  3. 人才扩展 (enterpriseDisabilityApiRoutes) - 路径前缀：/api/v1/yongren/disability-person
  4. 订单统计（待确认，可能集成在order-module中）
  5. 数据统计（待确认，可能集成在statistics-module中）
  6. 视频管理（待确认，可能集成在file-module或order-module中）
  7. 系统设置（P2优先级，延期）

RPC客户端接口定义和类型分析：

  • 现有mini/src/api.ts导入：AuthRoutes, UserRoutes, RoleRoutes, FileRoutes
  • 需要新增的模块类型：ChannelRoutes, CompanyRoutes, DisabilityRoutes, OrderRoutes, PlatformRoutes, SalaryRoutes, EnterpriseAuthRoutes, EnterpriseCompanyRoutes, EnterpriseDisabilityRoutes
  • 所有用人方小程序API使用/api/v1/yongren路径前缀
  • 需要验证@d8d/server包导出所有必需的路由类型

RPC客户端类型验证结果：

  1. 验证了packages/server/src/index.ts导出的路由类型包括：
    • ChannelRoutes, CompanyRoutes, DisabilityRoutes, OrderRoutes, PlatformRoutes, SalaryRoutes
    • EnterpriseAuthRoutes, EnterpriseCompanyRoutes, EnterpriseDisabilityRoutes
  2. 现有mini/src/api.ts模式：rpcClient<RouteType>().api.v1.module
  3. 需要新增的客户端列表：
    • channelClient = rpcClient<ChannelRoutes>().api.v1.channel
    • companyClient = rpcClient<CompanyRoutes>().api.v1.company
    • disabilityClient = rpcClient<DisabilityRoutes>().api.v1.disability
    • orderClient = rpcClient<OrderRoutes>().api.v1.order
    • platformClient = rpcClient<PlatformRoutes>().api.v1.platform
    • salaryClient = rpcClient<SalaryRoutes>().api.v1.salary
    • enterpriseAuthClient = rpcClient<EnterpriseAuthRoutes>().api.v1.yongren.auth
    • enterpriseCompanyClient = rpcClient<EnterpriseCompanyRoutes>().api.v1.yongren.company
    • enterpriseDisabilityClient = rpcClient<EnterpriseDisabilityRoutes>().api.v1.yongren.disability-person
  4. 需要确认statisticsRoutes和bankNameRoutes是否必要（待定）

2025-12-17 检查故事完成情况并修复企业客户端类型问题

检查结果：

  1. 故事013.003状态：已完成（Ready for Review），史诗012新增路由连通性集成测试通过
  2. 任务2实施情况检查：
    • ✅ Allin系统模块客户端已添加：channelClient, companyClient, disabilityClient, orderClient, platformClient, salaryClient
    • ❌ 企业专用客户端被注释，原因："企业客户端类型导出问题，待解决"
  3. 企业客户端类型问题分析：
    • @d8d/server包已正确导出企业路由类型：EnterpriseAuthRoutes, EnterpriseCompanyRoutes, EnterpriseDisabilityRoutes
    • 需要修复mini/src/api.ts中的类型导入和路径访问问题

修复措施：

  1. 更新mini/src/api.ts导入语句，添加企业路由类型：

    import type {
 ...,
 EnterpriseAuthRoutes,
 EnterpriseCompanyRoutes,
 EnterpriseDisabilityRoutes
} from '@d8d/server'

  2. 解除企业客户端注释并修复路径访问：

    export const enterpriseAuthClient = rpcClient<EnterpriseAuthRoutes>().api.v1.yongren.auth
export const enterpriseCompanyClient = rpcClient<EnterpriseCompanyRoutes>().api.v1.yongren.company
export const enterpriseDisabilityClient = rpcClient<EnterpriseDisabilityRoutes>().api.v1.yongren['disability-person']

  3. 验证类型检查通过，企业客户端可正常使用

当前故事进度：

  • 验收标准：2/5 完成（API客户端集成）
  • 任务完成：2/6 完成（任务1 + 任务2）
  • 剩余工作：任务3-6（路由配置、布局组件、认证框架、测试）

2025-12-17 故事011.001实施完成

实施总结：

  1. RPC客户端集成：已完成所有Allin系统模块和企业专用客户端的集成，mini/src/api.ts 已扩展包含9个新客户端。
  2. 路由结构配置：在 mini/src/app.config.ts 中添加了8个用人方小程序页面路由，创建了对应的页面组件文件。
  3. 基础布局组件：创建了以下组件：
    • YongrenTabBarLayout：用人方小程序底部导航布局组件
    • UserStatusBar：用户状态栏组件（显示用户信息和通知）
    • PageContainer：页面容器组件（统一布局和样式）
  4. 企业用户认证框架：创建了 EnterpriseAuthProvider 和 useEnterpriseAuth 钩子，提供了企业用户登录、登出、状态管理功能，并创建了权限检查框架。
  5. 基础测试：创建了API客户端测试、路由配置测试和布局组件测试，现有功能回归测试通过。

验收标准完成情况：

  • AC1：allin系统模块及史诗012补充API的RPC客户端成功集成到 mini/src/api.ts
  • AC2：用人方小程序的路由结构配置完成，支持页面导航
  • AC3：基础布局组件（状态栏、底部导航、页面容器）可用并符合移动端设计
  • AC4：企业用户认证框架就绪，支持后续登录页面集成
  • AC5：现有mini项目功能不受影响（现有测试全部通过）

文件列表更新：

  • 新增文件：
    • mini/src/pages/yongren/ 目录及8个页面组件
    • mini/src/layouts/yongren-tab-bar-layout.tsx
    • mini/src/components/ui/user-status-bar.tsx
    • mini/src/components/ui/page-container.tsx
    • mini/src/utils/enterprise-auth.tsx
    • mini/src/utils/enterprise-auth-guard.ts
    • mini/tests/yongren-api.test.ts
    • mini/tests/yongren-routes.test.ts
    • mini/tests/yongren-components.test.tsx
  • 修改文件：
    • mini/src/api.ts：添加新的RPC客户端
    • mini/src/app.config.ts：添加用人方小程序页面路由
    • docs/stories/011.001.story.md：更新任务状态和开发记录

2025-12-18 页面结构优化实施

背景： 根据用户反馈"当前小程序是只给企业用户用的了"，需要优化页面结构，删除重复页面，统一企业用户认证系统。

实施总结：

  1. 删除重复页面：移除了 pages/yongren/login/index（重复的企业登录页），使用原有 pages/login/index 改造为企业用户登录页
  2. 登录页改造：
    • 表单字段：username → phone（匹配企业认证API）
    • 验证规则：添加手机号正则验证（/^1[3-9]\d{9}$/）
    • UI文案调整："企业用户登录"、"手机号"、"企业账户登录"等
    • 移除注册功能，改为"企业账户问题请联系管理员"
  3. 个人中心改造：
    • 标题："个人中心" → "企业账户"
    • 统计项："收藏/点赞/关注" → "人才数/订单数/消息数"
    • 功能菜单："编辑资料" → "企业信息"，"设置" → "账户设置"等
    • 退出登录跳转：/pages/index/index → /pages/yongren/dashboard/index
  4. 微信登录页适配：
    • API客户端：authClient → enterpriseAuthClient
    • 存储键名：mini_token/userInfo → enterprise_token/enterpriseUserInfo
    • 登录成功跳转：/pages/index/index → /pages/yongren/dashboard/index
  5. 路由配置清理：
    • 移除不使用的页面路由：pages/explore/index、pages/register/index
    • 保留必要页面：pages/index/index、pages/profile/index、pages/login/index
  6. 测试更新：
    • 更新 tests/yongren-routes.test.ts：用人方页面数量8 → 7
    • 移除 pages/yongren/login/index 相关测试断言
    • 第一个页面检查：登录页 → 仪表板页

文件更新列表：

  • 删除文件：
    • mini/src/pages/yongren/login/ 目录（重复登录页）
    • mini/src/pages/register/ 目录（企业用户注册由管理员创建）
    • mini/src/utils/enterprise-auth.tsx（合并到主auth.tsx）
    • mini/src/utils/enterprise-auth-guard.ts（未使用）
  • 修改文件：
    • mini/src/pages/login/index.tsx：改造为企业用户登录页
    • mini/src/pages/login/wechat-login.tsx：适配企业认证
    • mini/src/pages/profile/index.tsx：改造为企业账户页
    • mini/src/app.config.ts：清理路由配置
    • mini/tests/yongren-routes.test.ts：更新测试断言
    • mini/src/utils/auth.tsx：统一使用企业认证客户端

微信小程序适配验证：

  • ✅ 项目配置默认平台为 weapp（微信小程序）
  • ✅ 构建成功：dist/weapp/development/ 和 dist/weapp/production/ 目录已生成
  • ✅ 所有测试通过（21个测试）
  • ✅ 微信登录功能适配完成（使用企业认证API）

后续建议：

  • 企业微信登录API：需要后端确认企业微信登录端点 enterpriseAuthClient['mini-login']
  • 手机号登录：企业认证API期望 {phone: string, password: string} 格式
  • 注册功能：前端不提供企业用户注册，由管理员创建账户

下一步建议：

  • 后续故事可以基于此基础框架进行具体页面功能开发
  • 企业认证框架需要与后端API联调验证
  • 布局组件样式可根据原型设计进一步细化

QA结果

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