|
|
@@ -1,153 +1,160 @@
|
|
|
-# Story 012.001: Database Schema Expansion
|
|
|
+# 故事 012.001：数据库架构扩展
|
|
|
|
|
|
-## Status
|
|
|
-Draft
|
|
|
+## 状态
|
|
|
+草稿
|
|
|
|
|
|
-## Story
|
|
|
-**As a** system developer,
|
|
|
-**I want** to extend the database schema to support employer mini-program features,
|
|
|
-**so that** subsequent API implementations have complete data support and accurate age statistics.
|
|
|
+## 故事
|
|
|
+**作为**系统开发人员，
|
|
|
+**我希望**扩展数据库架构以支持用人方小程序功能，
|
|
|
+**以便**后续的API实现有完整的数据支持和准确的年龄统计。
|
|
|
|
|
|
-## Acceptance Criteria
|
|
|
-Copy the acceptance criteria numbered list from the epic file
|
|
|
+## 验收标准
|
|
|
+从史诗文件复制的验收标准编号列表
|
|
|
|
|
|
1. [ ] `disabled_person`表成功添加`birth_date`字段，现有记录该字段值为NULL
|
|
|
2. [ ] `order_person_asset`表的`asset_type`枚举扩展完成，新增视频类型枚举值
|
|
|
3. [ ] `users2`表成功添加`company_id`字段，现有admin用户的该字段值为NULL
|
|
|
4. [ ] 数据库迁移脚本可正确执行向前和向后迁移
|
|
|
-5. [ ] Prisma/Drizzle schema定义更新完成
|
|
|
+5. [ ] TypeORM实体定义更新完成
|
|
|
6. [ ] 现有业务功能不受影响，测试通过
|
|
|
|
|
|
-## Tasks / Subtasks
|
|
|
-Break down the story into specific tasks and subtasks needed for implementation.
|
|
|
-Reference applicable acceptance criteria numbers where relevant.
|
|
|
-
|
|
|
-- [ ] Task 1: Add nullable `birth_date` field to `disabled_person` table (AC: 1)
|
|
|
- - [ ] Modify `allin-packages/disability-module/src/entities/disabled-person.entity.ts` to add `birthDate` field
|
|
|
- - [ ] Update corresponding schema validation in disability-module
|
|
|
- - [ ] Create database migration script for adding `birth_date` column
|
|
|
-- [ ] Task 2: Extend `asset_type` enum in `order_person_asset` table (AC: 2)
|
|
|
- - [ ] Update `AssetType` enum in `allin-packages/order-module/src/schemas/order.schema.ts`
|
|
|
- - [ ] Add new video types: `salary_video`, `tax_video`, `checkin_video`, `work_video`
|
|
|
- - [ ] Ensure backward compatibility with existing enum values
|
|
|
- - [ ] Update entity validation in `order-person-asset.entity.ts`
|
|
|
-- [ ] Task 3: Add nullable `company_id` field to `users2` table (AC: 3)
|
|
|
- - [ ] Locate user entity (likely in user-module or auth-module)
|
|
|
- - [ ] Add `companyId` field with foreign key reference to `employer_company.company_id`
|
|
|
- - [ ] Create database migration script for adding `company_id` column
|
|
|
-- [ ] Task 4: Create database migration scripts (AC: 4)
|
|
|
- - [ ] Create forward migration script for all three schema changes
|
|
|
- - [ ] Create backward/rollback migration script
|
|
|
- - [ ] Test migration scripts on test database
|
|
|
-- [ ] Task 5: Update Prisma/Drizzle schema definitions (AC: 5)
|
|
|
- - [ ] Update schema definitions to reflect new fields and enum values
|
|
|
- - [ ] Verify schema consistency across all modules
|
|
|
-- [ ] Task 6: Validation and testing (AC: 6)
|
|
|
- - [ ] Run existing tests to ensure no regression
|
|
|
- - [ ] Add unit tests for new fields and enum values
|
|
|
- - [ ] Test backward compatibility with existing data
|
|
|
- - [ ] Verify all existing business functions work correctly
|
|
|
-
|
|
|
-## Dev Notes
|
|
|
-Populate relevant information, only what was pulled from actual artifacts from docs folder, relevant to this story:
|
|
|
-
|
|
|
-### Previous Story Insights
|
|
|
-No previous stories in epic 012 (this is the first story).
|
|
|
-
|
|
|
-### Data Models
|
|
|
-Based on existing entity definitions:
|
|
|
-
|
|
|
-**DisabledPerson Entity** (allin-packages/disability-module/src/entities/disabled-person.entity.ts):
|
|
|
-- Primary key: `id` (mapped to `person_id` column) [Source: architecture/backend-module-package-standards.md#实体设计规范]
|
|
|
-- Field naming convention: database underscore → TypeScript camelCase [Source: architecture/backend-module-package-standards.md#字段命名转换]
|
|
|
-- Current fields include: `name`, `gender`, `idCard`, `disabilityId`, `disabilityType`, `disabilityLevel`, `phone`, `jobStatus`, etc.
|
|
|
-- Missing `birth_date` field (DATE type) for accurate age calculation
|
|
|
-- New field should be nullable: `birthDate?: Date` [Source: docs/prd/epic-012-api-supplement-for-employer-mini-program.md#故事012-01]
|
|
|
-
|
|
|
-**OrderPersonAsset Entity** (allin-packages/order-module/src/entities/order-person-asset.entity.ts):
|
|
|
-- Primary key: `id` (mapped to `op_id` column)
|
|
|
-- `assetType` field uses `AssetType` enum (varchar(50))
|
|
|
-- Current enum values: `tax`, `salary`, `job_result`, `contract_sign`, `disability_cert`, `other` [Source: allin-packages/order-module/src/schemas/order.schema.ts]
|
|
|
-- Need to extend with video types: `salary_video`, `tax_video`, `checkin_video`, `work_video`
|
|
|
-- Enum values should be lowercase strings with underscores [Source: architecture/backend-module-package-standards.md#枚举值一致性]
|
|
|
-
|
|
|
-**User Entity** (to be located):
|
|
|
-- Based on epic description, `users2` table needs `company_id` field
|
|
|
-- Should reference `employer_company.company_id` as foreign key
|
|
|
-- Field should be nullable (existing admin users have NULL) [Source: docs/prd/epic-012-api-supplement-for-employer-mini-program.md#故事012-01]
|
|
|
-
|
|
|
-### API Specifications
|
|
|
-Not applicable for this schema-only story. Subsequent stories will implement APIs using these schema changes.
|
|
|
-
|
|
|
-### Component Specifications
|
|
|
-Not applicable (backend schema story).
|
|
|
-
|
|
|
-### File Locations
|
|
|
-Based on project structure [Source: architecture/source-tree.md]:
|
|
|
+## 任务 / 子任务
|
|
|
+将故事分解为实施所需的具体任务和子任务。
|
|
|
+在相关处引用适用的验收标准编号。
|
|
|
+
|
|
|
+- [ ] 任务1：向`disabled_person`表添加可为空的`birth_date`字段（AC：1）
|
|
|
+ - [ ] 修改`allin-packages/disability-module/src/entities/disabled-person.entity.ts`以添加`birthDate`字段
|
|
|
+ - [ ] 在disability-module中更新对应的schema验证
|
|
|
+ - [ ] 创建添加`birth_date`列的数据库迁移脚本
|
|
|
+- [ ] 任务2：扩展`order_person_asset`表中的`asset_type`枚举（AC：2）
|
|
|
+ - [ ] 更新`allin-packages/order-module/src/schemas/order.schema.ts`中的`AssetType`枚举
|
|
|
+ - [ ] 添加新的视频类型：`salary_video`、`tax_video`、`checkin_video`、`work_video`
|
|
|
+ - [ ] 确保向后兼容现有的枚举值
|
|
|
+ - [ ] 更新`order-person-asset.entity.ts`中的实体验证
|
|
|
+- [ ] 任务3：向`users2`表添加可为空的`company_id`字段（AC：3）
|
|
|
+ - [ ] 定位用户实体（可能在user-module或auth-module中）
|
|
|
+ - [ ] 添加`companyId`字段，外键引用`employer_company.company_id`
|
|
|
+ - [ ] 创建添加`company_id`列的数据库迁移脚本
|
|
|
+- [ ] 任务4：创建数据库迁移脚本（AC：4）
|
|
|
+ - [ ] 为所有三个schema变更创建向前迁移脚本
|
|
|
+ - [ ] 创建向后/回滚迁移脚本
|
|
|
+ - [ ] 在测试数据库上测试迁移脚本
|
|
|
+- [ ] 任务5：更新TypeORM实体定义（AC：5）
|
|
|
+ - [ ] 更新实体定义以反映新字段和枚举值
|
|
|
+ - [ ] 验证所有模块中的schema一致性
|
|
|
+- [ ] 任务6：验证和测试（AC：6）
|
|
|
+ - [ ] 运行现有测试以确保没有回归
|
|
|
+ - [ ] 为新字段和枚举值添加单元测试
|
|
|
+ - [ ] 测试与现有数据的向后兼容性
|
|
|
+ - [ ] 验证所有现有业务功能正常工作
|
|
|
+
|
|
|
+## 开发笔记
|
|
|
+仅填充从docs文件夹中的实际工件提取的相关信息，与此故事相关：
|
|
|
+
|
|
|
+### 先前故事洞察
|
|
|
+史诗012中无先前故事（这是第一个故事）。
|
|
|
+
|
|
|
+### 数据模型
|
|
|
+基于现有实体定义：
|
|
|
+
|
|
|
+**DisabledPerson实体**（allin-packages/disability-module/src/entities/disabled-person.entity.ts）：
|
|
|
+- 主键：`id`（映射到`person_id`列）[来源：architecture/backend-module-package-standards.md#实体设计规范]
|
|
|
+- 字段命名约定：数据库下划线 → TypeScript驼峰命名 [来源：architecture/backend-module-package-standards.md#字段命名转换]
|
|
|
+- 当前字段包括：`name`、`gender`、`idCard`、`disabilityId`、`disabilityType`、`disabilityLevel`、`phone`、`jobStatus`等
|
|
|
+- 缺少`birth_date`字段（DATE类型）用于准确年龄计算
|
|
|
+- 新字段应为可为空：`birthDate?: Date` [来源：docs/prd/epic-012-api-supplement-for-employer-mini-program.md#故事012-01]
|
|
|
+- **注意**：`birth_date`字段应为DATE类型，用于存储出生日期而非时间戳
|
|
|
+
|
|
|
+**OrderPersonAsset实体**（allin-packages/order-module/src/entities/order-person-asset.entity.ts）：
|
|
|
+- 主键：`id`（映射到`op_id`列）
|
|
|
+- `assetType`字段使用`AssetType`枚举（varchar(50)）
|
|
|
+- 当前枚举值：`tax`（税务）、`salary`（薪资）、`job_result`（工作成果）、`contract_sign`（合同签署）、`disability_cert`（残疾证明）、`other`（其他）[来源：allin-packages/order-module/src/schemas/order.schema.ts]
|
|
|
+- 需要扩展的视频类型：`salary_video`（工资视频）、`tax_video`（个税视频）、`checkin_video`（打卡视频）、`work_video`（工作视频）
|
|
|
+- 枚举值应为小写字符串加下划线 [来源：architecture/backend-module-package-standards.md#枚举值一致性]
|
|
|
+- **枚举值对比**：
|
|
|
+ - 现有：`tax`, `salary`, `job_result`, `contract_sign`, `disability_cert`, `other`
|
|
|
+ - 新增：`salary_video`, `tax_video`, `checkin_video`, `work_video`
|
|
|
+ - 全部：`tax`, `salary`, `job_result`, `contract_sign`, `disability_cert`, `other`, `salary_video`, `tax_video`, `checkin_video`, `work_video`
|
|
|
+
|
|
|
+**用户实体**（待定位）：
|
|
|
+- 基于史诗描述，`users2`表需要`company_id`字段
|
|
|
+- 应引用`employer_company.company_id`作为外键
|
|
|
+- 字段应为可为空（现有admin用户为NULL）[来源：docs/prd/epic-012-api-supplement-for-employer-mini-program.md#故事012-01]
|
|
|
+- **注意**：需要在`packages/user-module`或`packages/auth-module`中查找对应的用户实体文件。如果不存在，可能需要基于`users2`表创建新的实体
|
|
|
+
|
|
|
+### API规范
|
|
|
+不适用于此仅schema的故事。后续故事将使用这些schema变更实现API。
|
|
|
+
|
|
|
+### 组件规范
|
|
|
+不适用（后端schema故事）。
|
|
|
+
|
|
|
+### 文件位置
|
|
|
+基于项目结构 [来源：architecture/source-tree.md]：
|
|
|
- `allin-packages/disability-module/src/entities/disabled-person.entity.ts`
|
|
|
- `allin-packages/order-module/src/entities/order-person-asset.entity.ts`
|
|
|
- `allin-packages/order-module/src/schemas/order.schema.ts`
|
|
|
-- User entity location: Need to locate (check `packages/user-module` or `packages/auth-module`)
|
|
|
-- Migration scripts: Should be created in appropriate location (TBD based on existing migration pattern)
|
|
|
-
|
|
|
-### Technical Constraints
|
|
|
-- **Backward compatibility**: All new fields must be nullable, existing data unaffected [Source: docs/prd/epic-012-api-supplement-for-employer-mini-program.md#兼容性要求]
|
|
|
-- **Database**: PostgreSQL 17, TypeORM 0.3.25 [Source: architecture/tech-stack.md]
|
|
|
-- **Enum extension**: Must retain existing enum values, new values added [Source: docs/prd/epic-012-api-supplement-for-employer-mini-program.md#风险缓解]
|
|
|
-- **Migration scripts**: Must support forward and backward migration [Source: docs/prd/epic-012-api-supplement-for-employer-mini-program.md#任务列表]
|
|
|
-
|
|
|
-### Project Structure Notes
|
|
|
-- Monorepo structure with `allin-packages/` for business modules [Source: architecture/source-tree.md]
|
|
|
-- Each module follows backend module package standards [Source: architecture/backend-module-package-standards.md]
|
|
|
-- Entity naming: `disabled-person.entity.ts` (kebab-case) [Source: architecture/source-tree.md#集成指南]
|
|
|
-- Field mapping: Database `birth_date` → TypeScript `birthDate` [Source: architecture/backend-module-package-standards.md#字段命名转换]
|
|
|
-
|
|
|
-### Testing
|
|
|
-List Relevant Testing Standards from Architecture the Developer needs to conform to:
|
|
|
-
|
|
|
-#### Test File Location
|
|
|
-- Unit tests: `allin-packages/{module-name}/tests/unit/**/*.test.ts` [Source: architecture/testing-strategy.md#单元测试]
|
|
|
-- Integration tests: `allin-packages/{module-name}/tests/integration/**/*.test.ts` [Source: architecture/testing-strategy.md#集成测试]
|
|
|
-
|
|
|
-#### Test Standards
|
|
|
-- Test framework: Vitest [Source: architecture/testing-strategy.md#单元测试]
|
|
|
-- Database testing: Use test database with transaction rollback [Source: architecture/testing-strategy.md#数据库测试策略]
|
|
|
-- Coverage requirements: Unit tests ≥ 80%, Integration tests ≥ 60% [Source: architecture/testing-strategy.md#测试覆盖率标准]
|
|
|
-
|
|
|
-#### Testing Frameworks and Patterns
|
|
|
-- **Unit tests**: Test individual entities and schemas
|
|
|
-- **Integration tests**: Test database migration scripts and schema changes
|
|
|
-- **Backward compatibility tests**: Verify existing data and queries work
|
|
|
-- **Enum validation tests**: Test new enum values are accepted
|
|
|
-
|
|
|
-#### Specific Testing Requirements for This Story
|
|
|
-1. **Schema validation tests**: Verify new fields are correctly nullable
|
|
|
-2. **Enum extension tests**: Verify new enum values work with existing code
|
|
|
-3. **Migration tests**: Test forward and backward migration scripts
|
|
|
-4. **Regression tests**: Run existing module tests to ensure no breakage
|
|
|
-5. **Foreign key tests**: Verify `company_id` foreign key relationship
|
|
|
-
|
|
|
-## Change Log
|
|
|
-Track changes made to this story document
|
|
|
-
|
|
|
-| Date | Version | Description | Author |
|
|
|
-|------|---------|-------------|--------|
|
|
|
-| 2025-12-13 | 1.0 | Initial story creation | Bob (Scrum Master) |
|
|
|
-
|
|
|
-## Dev Agent Record
|
|
|
-This section is populated by the development agent during implementation
|
|
|
-
|
|
|
-### Agent Model Used
|
|
|
+- 用户实体位置：需要定位（检查`packages/user-module`或`packages/auth-module`）
|
|
|
+- 迁移脚本：应在适当位置创建（基于现有迁移模式TBD）
|
|
|
+
|
|
|
+### 技术约束
|
|
|
+- **向后兼容性**：所有新字段必须可为空，现有数据不受影响 [来源：docs/prd/epic-012-api-supplement-for-employer-mini-program.md#兼容性要求]
|
|
|
+- **数据库**：PostgreSQL 17，TypeORM 0.3.25 [来源：architecture/tech-stack.md]
|
|
|
+- **枚举扩展**：必须保留现有枚举值，添加新值 [来源：docs/prd/epic-012-api-supplement-for-employer-mini-program.md#风险缓解]
|
|
|
+- **迁移脚本**：必须支持向前和向后迁移 [来源：docs/prd/epic-012-api-supplement-for-employer-mini-program.md#任务列表]
|
|
|
+
|
|
|
+### 项目结构说明
|
|
|
+- Monorepo结构，`allin-packages/`用于业务模块 [来源：architecture/source-tree.md]
|
|
|
+- 每个模块遵循后端模块包标准 [来源：architecture/backend-module-package-standards.md]
|
|
|
+- 实体命名：`disabled-person.entity.ts`（kebab-case）[来源：architecture/source-tree.md#集成指南]
|
|
|
+- 字段映射：数据库`birth_date` → TypeScript`birthDate` [来源：architecture/backend-module-package-standards.md#字段命名转换]
|
|
|
+
|
|
|
+### 测试
|
|
|
+列出开发者需要遵循的相关测试标准：
|
|
|
+
|
|
|
+#### 测试文件位置
|
|
|
+- 单元测试：`allin-packages/{模块名称}/tests/unit/**/*.test.ts` [来源：architecture/testing-strategy.md#单元测试]
|
|
|
+- 集成测试：`allin-packages/{模块名称}/tests/integration/**/*.test.ts` [来源：architecture/testing-strategy.md#集成测试]
|
|
|
+
|
|
|
+#### 测试标准
|
|
|
+- 测试框架：Vitest [来源：architecture/testing-strategy.md#单元测试]
|
|
|
+- 数据库测试：使用测试数据库和事务回滚 [来源：architecture/testing-strategy.md#数据库测试策略]
|
|
|
+- 覆盖率要求：单元测试 ≥ 80%，集成测试 ≥ 60% [来源：architecture/testing-strategy.md#测试覆盖率标准]
|
|
|
+
|
|
|
+#### 测试框架和模式
|
|
|
+- **单元测试**：测试单个实体和schema
|
|
|
+- **集成测试**：测试数据库迁移脚本和schema变更
|
|
|
+- **向后兼容性测试**：验证现有数据和查询正常工作
|
|
|
+- **枚举验证测试**：测试新枚举值是否被接受
|
|
|
+
|
|
|
+#### 此故事的特定测试要求
|
|
|
+1. **Schema验证测试**：验证新字段是否正确可为空
|
|
|
+2. **枚举扩展测试**：验证新枚举值适用于现有代码
|
|
|
+3. **迁移测试**：测试向前和向后迁移脚本
|
|
|
+4. **回归测试**：运行现有模块测试以确保没有破坏
|
|
|
+5. **外键测试**：验证`company_id`外键关系
|
|
|
+
|
|
|
+## 变更日志
|
|
|
+跟踪对此故事文档所做的更改
|
|
|
+
|
|
|
+| 日期 | 版本 | 描述 | 作者 |
|
|
|
+|------|------|------|------|
|
|
|
+| 2025-12-13 | 1.0 | 初始故事创建 | Bob（Scrum Master） |
|
|
|
+| 2025-12-13 | 1.1 | 转换为中文，应用检查清单改进建议 | Bob（Scrum Master） |
|
|
|
+
|
|
|
+## 开发代理记录
|
|
|
+此部分由开发代理在实施过程中填充
|
|
|
+
|
|
|
+### 使用的代理模型
|
|
|
{{agent_model_name_version}}
|
|
|
|
|
|
-### Debug Log References
|
|
|
-Reference any debug logs or traces generated during development
|
|
|
+### 调试日志引用
|
|
|
+引用在开发过程中生成的任何调试日志或跟踪
|
|
|
|
|
|
-### Completion Notes List
|
|
|
-Notes about the completion of tasks and any issues encountered
|
|
|
+### 完成笔记列表
|
|
|
+关于任务完成和遇到的任何问题的笔记
|
|
|
|
|
|
-### File List
|
|
|
-List all files created, modified, or affected during story implementation
|
|
|
+### 文件列表
|
|
|
+列出在故事实施过程中创建、修改或受影响的所有文件
|
|
|
|
|
|
-## QA Results
|
|
|
-Results from QA Agent QA review of the completed story implementation
|
|
|
+## QA结果
|
|
|
+来自QA代理对已完成故事实施的QA审查结果
|
yourname