|
|
@@ -0,0 +1,372 @@
|
|
|
+# 故事 012.011：企业专用人才管理API
|
|
|
+
|
|
|
+## 状态
|
|
|
+Ready for Implementation ✅
|
|
|
+
|
|
|
+## 故事
|
|
|
+**作为**企业用户，
|
|
|
+**我希望**使用企业专用的人才列表和详情API（按企业过滤），
|
|
|
+**以便**只能访问自己企业的人才数据，确保数据安全和隐私。
|
|
|
+
|
|
|
+## 验收标准
|
|
|
+从史诗文件复制的验收标准编号列表
|
|
|
+
|
|
|
+1. [ ] 企业专用人才列表接口返回正确的企业人才列表，支持搜索、筛选、分页
|
|
|
+2. [ ] 企业专用人才详情接口返回人员完整信息
|
|
|
+3. [ ] 企业用户只能访问自己关联企业的人员数据
|
|
|
+4. [ ] 查询性能优化，添加必要的数据库索引
|
|
|
+5. [ ] 接口通过单元测试和集成测试
|
|
|
+6. [ ] API文档完善，包含OpenAPI文档注释
|
|
|
+7. [ ] 前端mini项目可无缝切换到企业专用API接口
|
|
|
+
|
|
|
+## 任务 / 子任务
|
|
|
+将故事分解为实施所需的具体任务和子任务。
|
|
|
+在相关处引用适用的验收标准编号。
|
|
|
+
|
|
|
+- [ ] 任务1：企业专用人才列表API开发（disability-module扩展）（AC: 1, 3, 4）
|
|
|
+ - [ ] 在`person-extension.route.ts`中添加企业专用人才列表路由：`GET /`，路径为`/api/v1/yongren/disability-person`
|
|
|
+ - [ ] 在`disabled-person.service.ts`中添加`findAllForCompany`方法，基于`order_person`表关联`employment_order`和`disabled_person`表查询企业人才
|
|
|
+ - [ ] 查询逻辑：筛选`order_person`表中关联到该企业（`employment_order.company_id`匹配用户`company_id`）的残疾人员工
|
|
|
+ - [ ] 支持搜索（姓名、残疾证号）、筛选（残疾类型、状态）、分页等参数
|
|
|
+ - [ ] 验证企业用户权限：用户只能查询自己企业（`employment_order.company_id`匹配用户`company_id`）的数据
|
|
|
+ - [ ] 添加数据库索引优化查询性能（`order_person.person_id`、`employment_order.company_id`等字段索引）
|
|
|
+ - [ ] 创建相应的Zod Schema验证：`CompanyPersonListSchema`
|
|
|
+
|
|
|
+- [ ] 任务2：企业专用人才详情API开发（disability-module扩展）（AC: 2, 3, 4）
|
|
|
+ - [ ] 在`person-extension.route.ts`中添加企业专用人才详情路由：`GET /{id}`，路径为`/api/v1/yongren/disability-person/{id}`
|
|
|
+ - [ ] 在`disabled-person.service.ts`中添加`findOneForCompany`方法，基于`order_person`表关联验证人员是否属于该企业
|
|
|
+ - [ ] 查询逻辑：验证人员ID是否通过`order_person`表关联到该企业（使用现有的`validatePersonBelongsToCompany`方法）
|
|
|
+ - [ ] 返回人员完整信息（包含关联的银行卡片、照片、备注、访问记录等）
|
|
|
+ - [ ] 验证企业用户权限：用户只能访问自己企业的人员数据
|
|
|
+
|
|
|
+- [ ] 任务3：API路由集成和认证中间件配置（AC: 3, 5, 6）
|
|
|
+ - [ ] 在`person-extension.route.ts`中集成企业专用人才列表和详情路由
|
|
|
+ - [ ] 配置企业用户认证中间件（使用故事012.002实现的`enterpriseAuthMiddleware`）
|
|
|
+ - [ ] 验证接口需要企业用户权限（通过`company_id`验证）
|
|
|
+ - [ ] 确保API路径前缀符合约定：`/api/v1/yongren/disability-person`
|
|
|
+ - [ ] 统一错误处理，使用标准错误响应格式
|
|
|
+ - [ ] 更新server包中的路由注册（`enterpriseDisabilityApiRoutes`已存在，无需修改）
|
|
|
+
|
|
|
+- [ ] 任务4：数据库性能优化（AC: 4）
|
|
|
+ - [ ] 分析查询性能，识别需要添加索引的字段
|
|
|
+ - [ ] 在相关表上添加索引：`order_person.person_id`、`order_person.order_id`、`employment_order.company_id`
|
|
|
+ - [ ] 考虑添加复合索引优化多表关联查询（`employment_order.company_id` + `order_person.person_id`）
|
|
|
+ - [ ] 验证索引效果，确保查询响应时间符合要求（< 200ms）
|
|
|
+
|
|
|
+- [ ] 任务5：集成测试开发（AC: 5）
|
|
|
+ - [ ] 在残疾人模块集成测试中新增测试用例：`person-extension.integration.test.ts`（扩展现有测试）
|
|
|
+ - [ ] 测试企业专用人才列表接口的各种场景：有数据、无数据、搜索、筛选、分页
|
|
|
+ - [ ] 测试企业专用人才详情接口：正常访问、人员不存在、人员不属于该企业
|
|
|
+ - [ ] 测试企业用户权限验证：非企业用户无法访问接口
|
|
|
+ - [ ] 测试不同企业用户只能访问自己企业的数据
|
|
|
+ - [ ] 测试错误场景：无效的参数等
|
|
|
+ - [ ] 确保测试覆盖率≥60%（集成测试要求）
|
|
|
+
|
|
|
+- [ ] 任务6：API文档完善（AC: 6）
|
|
|
+ - [ ] 为新增接口添加OpenAPI文档注释
|
|
|
+ - [ ] 生成TypeScript类型定义文件，供前端使用
|
|
|
+ - [ ] 更新模块的README文档，说明新增的企业专用人才管理功能
|
|
|
+ - [ ] 验证所有接口的OpenAPI文档生成正确
|
|
|
+
|
|
|
+## 开发笔记
|
|
|
+仅填充从docs文件夹中的实际工件提取的相关信息，与此故事相关：
|
|
|
+
|
|
|
+### 先前故事洞察
|
|
|
+故事012.001（数据库schema扩展）、012.002（企业用户认证API扩展）和012.003（企业统计与人才扩展API）已完成的变更：
|
|
|
+
|
|
|
+1. **数据库schema扩展（故事012.001）**：
|
|
|
+ - `users2`表已包含`company_id`字段（外键引用`employer_company.company_id`）[来源：docs/stories/012.001.story.md]
|
|
|
+ - `order_person`表已包含`join_date`字段和`work_status`字段[来源：docs/stories/012.001.story.md]
|
|
|
+
|
|
|
+2. **企业用户认证（故事012.002）**：
|
|
|
+ - 企业用户手机号密码登录接口已实现：`POST /api/v1/yongren/auth/login` [来源：docs/stories/012.002.story.md]
|
|
|
+ - 企业用户认证中间件已实现：`enterpriseAuthMiddleware` [来源：docs/stories/012.002.story.md]
|
|
|
+ - 企业用户权限验证逻辑：基于`users2`表的`company_id`字段验证 [来源：docs/stories/012.002.story.md]
|
|
|
+
|
|
|
+3. **企业统计与人才扩展API（故事012.003）**：
|
|
|
+ - 个人工作历史查询：`GET /api/v1/yongren/disability-person/{id}/work-history` [来源：docs/stories/012.003.story.md]
|
|
|
+ - 个人薪资历史查询：`GET /api/v1/yongren/disability-person/{id}/salary-history` [来源：docs/stories/012.003.story.md]
|
|
|
+ - 个人征信信息查询：`GET /api/v1/yongren/disability-person/{id}/credit-info` [来源：docs/stories/012.003.story.md]
|
|
|
+ - 个人视频关联查询：`GET /api/v1/yongren/disability-person/{id}/videos` [来源：docs/stories/012.003.story.md]
|
|
|
+ - `person-extension.route.ts`文件已存在，包含上述扩展路由 [来源：docs/stories/012.003.story.md]
|
|
|
+
|
|
|
+### 数据模型
|
|
|
+基于现有实体定义和架构文档：
|
|
|
+
|
|
|
+**残疾人实体**（`allin-packages/disability-module/src/entities/disabled-person.entity.ts`）：
|
|
|
+- 表名：`disabled_person`（@Entity('disabled_person')）
|
|
|
+- 主键：`id`（映射到`person_id`列）
|
|
|
+- 字段：`name`、`gender`、`idCard`、`disabilityId`、`disabilityType`、`disabilityLevel`、`birthDate`、`phone`、`jobStatus`等
|
|
|
+
|
|
|
+**订单人员实体**（`allin-packages/order-module/src/entities/order-person.entity.ts`）：
|
|
|
+- 表名：`order_person`（@Entity('order_person')）
|
|
|
+- 主键：`id`（映射到`op_id`列）
|
|
|
+- 字段：`orderId`、`personId`、`joinDate`、`salaryDetail`、`workStatus`等
|
|
|
+- 关联：`personId`关联DisabledPerson，`orderId`关联EmploymentOrder
|
|
|
+
|
|
|
+**就业订单实体**（`allin-packages/order-module/src/entities/employment-order.entity.ts`）：
|
|
|
+- 表名：`employment_order`（@Entity('employment_order')）
|
|
|
+- 主键：`id`（映射到`order_id`列）
|
|
|
+- 字段：`orderName`、`platformId`、`companyId`、`channelId`、`orderStatus`、`workStatus`等
|
|
|
+- 公司关联：`companyId`字段关联Company实体
|
|
|
+
|
|
|
+### API规范
|
|
|
+**API路径约定**（来自史诗012）：
|
|
|
+- 所有用人方小程序的API路径统一使用 `api/v1/yongren` 前缀 [来源：docs/prd/epic-012-api-supplement-for-employer-mini-program.md#api路径约定]
|
|
|
+- 现有管理后台API保持不变，新增的用人方小程序API使用独立的路由前缀
|
|
|
+- 示例：企业专用人才API：`GET /api/v1/yongren/disability-person` [来源：docs/prd/epic-012-api-supplement-for-employer-mini-program.md#api路径约定]
|
|
|
+
|
|
|
+**新增接口规范**：
|
|
|
+1. **企业专用人才列表查询**：
|
|
|
+ - 路径：`GET /api/v1/yongren/disability-person`
|
|
|
+ - 查询参数：
|
|
|
+ - `search`（可选，string）：搜索关键词（姓名、残疾证号）
|
|
|
+ - `disabilityType`（可选，enum）：残疾类型筛选
|
|
|
+ - `jobStatus`（可选，enum）：工作状态筛选
|
|
|
+ - `page`（可选，number，默认1）：页码
|
|
|
+ - `limit`（可选，number，默认10）：每页记录数
|
|
|
+ - 请求头：`Authorization: Bearer <企业用户token>`
|
|
|
+ - 响应示例：
|
|
|
+ ```json
|
|
|
+ {
|
|
|
+ "data": [
|
|
|
+ {
|
|
|
+ "personId": 123,
|
|
|
+ "name": "张三",
|
|
|
+ "gender": "male",
|
|
|
+ "idCard": "330102199001011234",
|
|
|
+ "disabilityType": "肢体残疾",
|
|
|
+ "disabilityLevel": "二级",
|
|
|
+ "phone": "13800138000",
|
|
|
+ "jobStatus": "在职",
|
|
|
+ "latestJoinDate": "2024-12-15T00:00:00.000Z",
|
|
|
+ "orderName": "2024年第四季度用工订单"
|
|
|
+ }
|
|
|
+ ],
|
|
|
+ "pagination": {
|
|
|
+ "page": 1,
|
|
|
+ "limit": 10,
|
|
|
+ "total": 45,
|
|
|
+ "totalPages": 5
|
|
|
+ }
|
|
|
+ }
|
|
|
+ ```
|
|
|
+ - 状态码：200成功，400参数错误，401未授权，403权限不足，500服务器错误
|
|
|
+
|
|
|
+2. **企业专用人才详情查询**：
|
|
|
+ - 路径：`GET /api/v1/yongren/disability-person/{id}`
|
|
|
+ - 路径参数：`id`（required，number）：人员ID
|
|
|
+ - 请求头：`Authorization: Bearer <企业用户token>`
|
|
|
+ - 响应示例：
|
|
|
+ ```json
|
|
|
+ {
|
|
|
+ "personId": 123,
|
|
|
+ "name": "张三",
|
|
|
+ "gender": "male",
|
|
|
+ "idCard": "330102199001011234",
|
|
|
+ "disabilityType": "肢体残疾",
|
|
|
+ "disabilityLevel": "二级",
|
|
|
+ "birthDate": "1990-01-01T00:00:00.000Z",
|
|
|
+ "phone": "13800138000",
|
|
|
+ "jobStatus": "在职",
|
|
|
+ "bankCards": [
|
|
|
+ {
|
|
|
+ "cardId": 1,
|
|
|
+ "bankName": "中国工商银行",
|
|
|
+ "cardNumber": "6222021234567890123",
|
|
|
+ "isDefault": true
|
|
|
+ }
|
|
|
+ ],
|
|
|
+ "photos": [
|
|
|
+ {
|
|
|
+ "fileId": 1,
|
|
|
+ "fileName": "身份证正面照.jpg",
|
|
|
+ "fileUrl": "https://minio.example.com/files/身份证正面照.jpg"
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+ ```
|
|
|
+ - 状态码：200成功，401未授权，403权限不足，404人员不存在或不属于该企业，500服务器错误
|
|
|
+
|
|
|
+**查询逻辑**：
|
|
|
+- 企业人才列表查询：
|
|
|
+ - 关联链：`disabled_person` ← `order_person`（`person_id`）→ `employment_order`（`order_id`）→ 验证`company_id`匹配
|
|
|
+ - 筛选条件：`employment_order.company_id` = 用户`company_id`
|
|
|
+ - 去重：同一人员可能关联多个订单，需要按人员ID去重或显示最新订单信息
|
|
|
+ - 排序：默认按人员ID或姓名排序，支持按入职日期、残疾类型等排序
|
|
|
+
|
|
|
+- 企业人才详情查询：
|
|
|
+ - 验证人员是否属于企业：`disabled_person.id` → `order_person.person_id` → `employment_order.order_id` → 验证`company_id`匹配
|
|
|
+ - 使用现有的`validatePersonBelongsToCompany`方法进行权限验证
|
|
|
+
|
|
|
+**认证要求**：
|
|
|
+- 需要企业用户权限验证
|
|
|
+- 使用故事012.002实现的`enterpriseAuthMiddleware`中间件
|
|
|
+- 验证用户`company_id`字段不为空
|
|
|
+- 企业用户只能访问自己关联的企业数据
|
|
|
+
|
|
|
+### 组件规范
|
|
|
+不适用（后端API故事）。
|
|
|
+
|
|
|
+### 文件位置
|
|
|
+基于项目结构和后端模块包规范：
|
|
|
+
|
|
|
+**残疾人模块位置**：
|
|
|
+- `allin-packages/disability-module/src/routes/` - 现有路由文件位置
|
|
|
+- `allin-packages/disability-module/src/services/` - 服务层文件位置
|
|
|
+- `allin-packages/disability-module/src/schemas/` - Schema验证文件位置
|
|
|
+- `allin-packages/disability-module/tests/integration/` - 集成测试位置
|
|
|
+
|
|
|
+**文件修改位置**：
|
|
|
+1. **现有文件需要修改**：
|
|
|
+ - `allin-packages/disability-module/src/routes/person-extension.route.ts` - 扩展现有文件，添加企业专用人才列表和详情路由
|
|
|
+ - `allin-packages/disability-module/src/services/disabled-person.service.ts` - 添加`findAllForCompany`和`findOneForCompany`方法
|
|
|
+ - `allin-packages/disability-module/src/schemas/person-extension.schema.ts` - 添加`CompanyPersonListSchema`等Schema
|
|
|
+
|
|
|
+2. **现有文件可能修改**：
|
|
|
+ - `packages/server/src/index.ts` - 验证企业人才路由已正确注册（`enterpriseDisabilityApiRoutes`）
|
|
|
+
|
|
|
+**新文件建议位置**：
|
|
|
+- `allin-packages/disability-module/tests/integration/person-extension.integration.test.ts` - 扩展现有集成测试
|
|
|
+
|
|
|
+### 技术约束
|
|
|
+基于技术栈和架构文档：
|
|
|
+
|
|
|
+1. **技术栈约束**：
|
|
|
+ - 后端框架：Hono 4.8.5
|
|
|
+ - 数据库ORM：TypeORM 0.3.25
|
|
|
+ - 数据库：PostgreSQL 17
|
|
|
+ - 认证：JWT 9.0.2
|
|
|
+ - 测试框架：Vitest
|
|
|
+
|
|
|
+2. **API设计约束**：
|
|
|
+ - 使用Zod OpenAPI进行Schema验证和文档生成
|
|
|
+ - 遵循现有的路由聚合模式
|
|
|
+ - 错误响应格式统一：`{ "success": false, "message": "...", "code": "..." }`
|
|
|
+
|
|
|
+3. **性能约束**：
|
|
|
+ - 查询响应时间 < 200ms（现有测试基准）
|
|
|
+ - 需要添加适当的数据库索引优化查询性能
|
|
|
+ - 人才列表查询需要支持分页，避免返回大量数据
|
|
|
+
|
|
|
+4. **安全约束**：
|
|
|
+ - 企业用户只能访问自己关联的企业数据
|
|
|
+ - 需要验证`company_id`匹配性
|
|
|
+ - 使用企业用户专属的认证中间件
|
|
|
+
|
|
|
+5. **向后兼容性**：
|
|
|
+ - 现有通用人才API（`/api/v1/disability`）保持不变
|
|
|
+ - 新增企业专用人才API使用独立的路由前缀`/api/v1/yongren/disability-person`
|
|
|
+ - 前端mini项目可逐步迁移到企业专用API
|
|
|
+
|
|
|
+### 项目结构说明
|
|
|
+基于monorepo结构和模块化包架构：
|
|
|
+
|
|
|
+1. **模块化架构**：
|
|
|
+ - `allin-packages/disability-module` - 残疾人管理业务模块
|
|
|
+ - 企业专用人才管理API在`disability-module`中实现，与其他企业扩展API保持一致
|
|
|
+
|
|
|
+2. **依赖关系**：
|
|
|
+ - `disability-module`依赖`order-module`查询订单和人员关联数据
|
|
|
+ - `disability-module`依赖`company-module`获取企业关联信息
|
|
|
+ - 所有模块依赖核心的`auth-module`进行认证
|
|
|
+
|
|
|
+3. **路由结构**：
|
|
|
+ - 现有企业人才扩展路由：`/api/v1/yongren/disability-person/{id}/work-history`等
|
|
|
+ - 新增企业专用人才基础路由：`/api/v1/yongren/disability-person`（列表）、`/api/v1/yongren/disability-person/{id}`（详情）
|
|
|
+ - 所有企业用户API使用统一的前缀和认证中间件
|
|
|
+
|
|
|
+4. **代码组织**：
|
|
|
+ - 遵循后端模块包规范
|
|
|
+ - 实体、服务、路由、Schema分层清晰
|
|
|
+ - 测试文件与源码对应，位于`tests/integration/`目录
|
|
|
+
|
|
|
+### 测试
|
|
|
+列出开发者需要遵循的相关测试标准：
|
|
|
+
|
|
|
+#### 测试文件位置
|
|
|
+基于测试策略文档：
|
|
|
+- 集成测试：`allin-packages/disability-module/tests/integration/person-extension.integration.test.ts`（扩展现有测试）
|
|
|
+- 测试基础设施：使用`@d8d/shared-test-util`提供的工具
|
|
|
+
|
|
|
+#### 测试标准
|
|
|
+基于测试策略文档：
|
|
|
+- 测试框架：Vitest
|
|
|
+- API测试：使用`hono/testing`进行API端点测试
|
|
|
+- 数据库测试：使用测试数据库和事务回滚
|
|
|
+- 覆盖率要求：集成测试 ≥ 60%
|
|
|
+- 测试数据管理：使用`TestDataFactory`创建测试数据
|
|
|
+
|
|
|
+#### 测试框架和模式
|
|
|
+基于现有集成测试模式：
|
|
|
+1. **集成测试模式**：
|
|
|
+ - 使用`setupIntegrationDatabaseHooksWithEntities`设置测试数据库
|
|
|
+ - 使用`testClient`创建Hono测试客户端
|
|
|
+ - 每个测试前清理测试数据，避免唯一性约束冲突
|
|
|
+ - 使用`TestDataFactory`创建一致的测试数据
|
|
|
+
|
|
|
+2. **测试场景覆盖**：
|
|
|
+ - 成功场景：企业用户访问接口，返回企业人才列表和详情
|
|
|
+ - 参数场景：测试搜索、筛选、分页参数的各种组合
|
|
|
+ - 数据场景：测试有数据、无数据、多页数据情况
|
|
|
+ - 权限场景：非企业用户访问被拒绝，不同企业用户只能访问自己数据
|
|
|
+ - 详情验证：验证人员不属于企业时返回403
|
|
|
+
|
|
|
+3. **断言模式**：
|
|
|
+ - 验证HTTP状态码：`expect(response.status).toBe(200)`
|
|
|
+ - 验证响应数据结构：`expect(responseData).toHaveProperty('data')`
|
|
|
+ - 验证分页信息：`expect(responseData.pagination.total).toBeGreaterThan(0)`
|
|
|
+ - 验证权限：`expect(response.status).toBe(403)`（跨企业访问）
|
|
|
+ - 验证数据正确性：`expect(responseData.data[0].name).toBe('张三')`
|
|
|
+
|
|
|
+#### 此故事的特定测试要求
|
|
|
+1. **企业专用人才列表API测试**：
|
|
|
+ - 测试接口返回正确的企业人才列表
|
|
|
+ - 测试搜索功能（姓名、残疾证号）
|
|
|
+ - 测试筛选功能（残疾类型、工作状态）
|
|
|
+ - 测试分页功能（页码、每页记录数）
|
|
|
+ - 测试排序功能（默认排序和可选排序）
|
|
|
+
|
|
|
+2. **企业专用人才详情API测试**：
|
|
|
+ - 测试接口返回人员完整信息
|
|
|
+ - 测试人员不属于企业时返回403
|
|
|
+ - 测试人员不存在时返回404
|
|
|
+ - 测试关联数据正确返回（银行卡片、照片等）
|
|
|
+
|
|
|
+3. **权限测试**：
|
|
|
+ - 测试企业用户权限验证正确
|
|
|
+ - 测试跨企业访问数据被拒绝
|
|
|
+ - 测试认证中间件正确拦截非企业用户
|
|
|
+
|
|
|
+4. **性能测试**：
|
|
|
+ - 测试查询响应时间 < 200ms
|
|
|
+ - 测试数据库索引效果
|
|
|
+ - 测试大量数据时的分页性能
|
|
|
+
|
|
|
+## 变更日志
|
|
|
+跟踪对此故事文档所做的更改
|
|
|
+
|
|
|
+| 日期 | 版本 | 描述 | 作者 |
|
|
|
+|------|------|------|------|
|
|
|
+| 2025-12-18 | 1.0 | 初始故事创建，实现企业专用人才管理API | Claude Code |
|
|
|
+
|
|
|
+## 开发代理记录
|
|
|
+此部分由开发代理在实施过程中填充
|
|
|
+
|
|
|
+### 使用的代理模型
|
|
|
+待填充
|
|
|
+
|
|
|
+### 调试日志引用
|
|
|
+待填充
|
|
|
+
|
|
|
+### 完成笔记列表
|
|
|
+待填充
|
|
|
+
|
|
|
+### 待解决问题
|
|
|
+待填充
|
|
|
+
|
|
|
+### 文件列表
|
|
|
+待填充
|
|
|
+
|
|
|
+## QA结果
|
|
|
+来自QA代理对已完成故事实施的QA审查结果
|
yourname