故事 011.001：基础框架搭建

状态

已批准

故事

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

验收标准

allin系统模块及史诗012补充API的RPC客户端成功集成到mini/src/api.ts
用人方小程序的路由结构配置完成，支持页面导航
基础布局组件（状态栏、底部导航、页面容器）可用并符合移动端设计
企业用户认证框架就绪，支持后续登录页面集成
现有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：分析需要集成的API模块

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

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

channel-module (@d8d/allin-channel-module)
company-module (@d8d/allin-company-module)
disability-module (@d8d/allin-disability-module)
order-module (@d8d/allin-order-module)
platform-module (@d8d/allin-platform-module)
salary-module (@d8d/allin-salary-module)
enums (@d8d/allin-enums)
statistics-module (@d8d/allin-statistics-module)

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

企业用户认证 (enterpriseAuthApiRoutes) - 路径前缀：/api/v1/yongren/auth
企业统计 (enterpriseCompanyApiRoutes) - 路径前缀：/api/v1/yongren/company
人才扩展 (enterpriseDisabilityApiRoutes) - 路径前缀：/api/v1/yongren/disability-person
订单统计（待确认，可能集成在order-module中）
数据统计（待确认，可能集成在statistics-module中）
视频管理（待确认，可能集成在file-module或order-module中）
系统设置（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客户端类型验证结果：

验证了packages/server/src/index.ts导出的路由类型包括：
- ChannelRoutes, CompanyRoutes, DisabilityRoutes, OrderRoutes, PlatformRoutes, SalaryRoutes
- EnterpriseAuthRoutes, EnterpriseCompanyRoutes, EnterpriseDisabilityRoutes
现有mini/src/api.ts模式：rpcClient<RouteType>().api.v1.module
需要新增的客户端列表：
- 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
需要确认statisticsRoutes和bankNameRoutes是否必要（待定）

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

检查结果：

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

修复措施：

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

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

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

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']

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

当前故事进度：

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

QA结果

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

011.001.story.md 12 KB 히스토리 Raw