mini-starter/docs/epic-007.md

史诗007 - Allin System有实体模块移植到独立包

史诗目标

将allin_system-master/server/src目录下有对应数据库实体的模块移植到packages目录下，作为非多租户独立包，遵循项目现有的独立包结构和命名规范，实现模块的现代化重构和标准化管理。

史诗描述

现有系统上下文

• 当前相关功能：allin_system-master是一个基于NestJS的后端系统，根据allin_2025-11-25.sql分析，有以下有实体的模块：

  1. channel_info模块 - 对应channel_info表
  2. company模块 - 对应employer_company表
  3. dict_management模块 - 对应sys_dict表
  4. disability_person模块 - 对应disabled_person、disabled_bank_card、disabled_photo、disabled_remark、disabled_visit表
  5. order模块 - 对应employment_order、order_person、order_person_asset表
  6. platform模块 - 对应employer_platform表
  7. salary模块 - 对应salary_level表

• 无实体模块（本次不移植）：admin、auth、users模块

• 技术栈：TypeScript、NestJS、PostgreSQL、Redis、MinIO

• 集成点：模块间通过NestJS模块系统集成，共享数据库连接和配置

增强详情

• 新增/变更内容：将7个有实体的现有模块从allin_system-master/server/src移植到packages目录下的独立包
• 集成方式：每个模块将重构为独立的npm包，遵循@d8d命名规范，通过workspace依赖管理
• 成功标准：
  1. 7个有实体模块成功移植为独立包
  2. 保持原有功能完整性
  3. 遵循现有独立包结构模式
  4. 通过类型检查和基本测试验证

模块分析结果

1. 模块依赖关系分析

根据对每个模块module.ts文件的分析，依赖关系如下：

1. channel_info模块 (channel.module.ts)

   • 依赖：@nestjs/common, @nestjs/typeorm
   • 实体：Channel (对应channel_info表)
   • 无其他模块依赖

2. company模块 (company.module.ts)

   • 依赖：@nestjs/common, @nestjs/typeorm, PlatformModule
   • 实体：Company (对应employer_company表)
   • 依赖模块：platform

3. dict_management模块 (dict.module.ts)

   • 依赖：@nestjs/common, @nestjs/typeorm
   • 实体：Dict (对应sys_dict表)
   • 无其他模块依赖

4. disability_person模块 (disability_person.module.ts)

   • 依赖：@nestjs/common, @nestjs/typeorm
   • 实体：DisabledPerson, DisabledBankCard, DisabledPhoto, DisabledRemark, DisabledVisit
   • 引用其他模块实体：EmploymentOrder, OrderPerson (order模块), Platform (platform模块), Company (company模块), Channel (channel_info模块)
   • 复杂度：高（5个实体，多个控制器和服务）

5. order模块 (order.module.ts)

   • 依赖：@nestjs/common, @nestjs/typeorm
   • 实体：EmploymentOrder, OrderPerson, OrderPersonAsset
   • 引用其他模块实体：DisabledPerson (disability_person模块), Platform (platform模块), Company (company模块), Channel (channel_info模块)
   • 复杂度：中高（3个实体，跨模块依赖）

6. platform模块 (platform.module.ts)

   • 依赖：@nestjs/common, @nestjs/typeorm
   • 实体：Platform (对应employer_platform表)
   • 无其他模块依赖
   • 被依赖：company模块依赖此模块

7. salary模块 (salary.module.ts)

   • 依赖：@nestjs/common, @nestjs/typeorm
   • 实体：SalaryLevel (对应salary_level表)
   • 无其他模块依赖

2. 依赖关系图

platform ───┐
            ↓
company ────┐
            ↓
channel_info ─┐
            ↓ ↓
order ───────┘
            ↑
disability_person
            ↑
dict_management (独立)
salary (独立)

关键发现：

• platform模块是基础依赖，被company模块直接依赖
• company、channel_info模块被order和disability_person模块引用
• order和disability_person模块相互引用实体，形成循环依赖
• dict_management和salary模块完全独立

3. 模块到独立包的映射方案

基于现有项目命名规范，并考虑这是Allin系统专属模块，制定以下映射方案：

原模块名	独立包名	目录名	说明
channel_info	@d8d/allin-channel-module	channel-module	渠道管理模块
company	@d8d/allin-company-module	company-module	公司管理模块，依赖platform-module
dict_management	@d8d/allin-dict-module	dict-module	字典管理模块
disability_person	@d8d/allin-disability-module	disability-module	残疾人管理模块（简化名称）
order	@d8d/allin-order-module	order-module	订单管理模块
platform	@d8d/allin-platform-module	platform-module	平台管理模块
salary	@d8d/allin-salary-module	salary-module	薪资管理模块

命名原则：

1. 包名前缀：使用@d8d/allin-前缀，明确表明是Allin系统专属包
2. 目录名：使用简洁的{模块名}-module格式，便于在allin-packages目录中管理
3. 模块名：使用单数形式 + -module后缀
4. 名称简洁：反映模块核心功能
5. 非多租户：不使用-mt后缀（本次移植为非多租户版本）

4. 目录结构和包规范

目录结构决策

由于这些模块是allin_system-master项目独有的业务模块（非通用模块），将在项目根目录创建独立目录：

项目根目录/
├── allin-packages/          # Allin系统专属包目录
│   ├── channel-module/      # 渠道管理模块
│   ├── company-module/      # 公司管理模块
│   ├── dict-module/         # 字典管理模块
│   ├── disability-module/   # 残疾人管理模块
│   ├── order-module/        # 订单管理模块
│   ├── platform-module/     # 平台管理模块
│   └── salary-module/       # 薪资管理模块
├── packages/                # 现有通用包目录（保持不变）
└── allin_system-master/     # 原始代码目录（移植源）

目录命名说明：allin-packages清晰表明这是Allin系统专属的包目录，与allin_system-master源目录对应，区别于通用的packages目录。

包结构规范

参考现有auth-module结构，每个独立包应包含：

allin-packages/{module-name}/
├── package.json          # 包配置，workspace依赖管理
├── tsconfig.json        # TypeScript配置
├── vitest.config.ts     # 测试配置（如需要）
├── src/
│   ├── index.ts         # 主导出文件
│   ├── schemas/         # Zod模式定义（如需要）
│   │   └── index.ts
│   ├── entities/        # 数据库实体
│   ├── services/        # 业务服务
│   ├── controllers/     # API控制器
│   ├── dtos/           # 数据传输对象
│   └── types/          # TypeScript类型定义
└── dist/               # 构建输出

关键配置要求：

1. package.json中设置"type": "module"
2. 主入口为src/index.ts
3. 使用workspace依赖："@d8d/core-module": "workspace:*"
4. 包名使用@d8d/allin-前缀，如@d8d/allin-channel-module
5. 导出必要的服务和实体

5. 依赖关系解决方案

针对发现的循环依赖问题（order ↔ disability_person），解决方案：

1. 创建共享实体包：将相互引用的实体提取到共享包
2. 接口抽象：使用接口而非具体实体引用
3. 依赖注入调整：重构服务层减少直接实体依赖
4. 移植顺序策略：按依赖顺序移植，先移植基础模块

建议移植顺序：

1. allin-platform-module（基础）
2. allin-channel-module、allin-dict-module、allin-salary-module（独立）
3. allin-company-module（依赖platform）
4. allin-order-module和allin-disability-module（最后处理，解决循环依赖）

故事（更新后）

注：故事1的分析工作已完成，结果见上方"模块分析结果"部分。

1. 故事2：创建基础包模板和移植工具

   • 创建allin-packages目录结构
   • 创建标准的独立包模板（参考auth-module结构）
   • 开发自动化移植脚本
   • 配置workspace依赖管理（使用@d8d/allin-前缀）
   • 准备TypeScript配置和构建脚本
   • 创建package.json模板

2. 故事3：移植基础独立模块

   • 移植allin-platform-module（基础依赖）
   • 移植allin-channel-module（独立模块）
   • 移植allin-dict-module（独立模块）
   • 移植allin-salary-module（独立模块）
   • 验证基础模块功能

3. 故事4：移植依赖模块和解决循环依赖

   • 移植allin-company-module（依赖platform-module）
   • 处理allin-order-module和allin-disability-module的循环依赖
   • 创建共享实体或接口抽象
   • 移植两个复杂模块的核心功能

4. 故事5：完成移植和集成验证

   • 完成所有7个模块的移植
   • 解决剩余的依赖问题
   • 进行整体功能验证
   • 运行类型检查和基本测试
   • 更新文档和配置

兼容性要求

• 现有API接口保持不变
• 数据库schema保持向后兼容
• 遵循现有TypeScript配置和构建模式
• 性能影响最小化

风险缓解

• 主要风险：模块间依赖关系复杂，移植过程中可能破坏现有功能
• 缓解措施：逐个模块移植，每个模块完成后进行功能验证
• 回滚计划：保留原始allin_system-master目录作为备份，可随时恢复

完成定义

• 所有4个故事完成，验收标准满足
• 现有功能通过测试验证
• 集成点正常工作
• 文档更新适当
• 现有功能无回归

验证清单

范围验证

• 史诗可在4个故事内完成
• 不需要架构文档变更
• 增强遵循现有模式
• 集成复杂度可管理

风险评估

• 对现有系统风险较低
• 回滚计划可行
• 测试方法覆盖现有功能
• 团队对集成点有足够了解

完整性检查

• 史诗目标清晰可实现
• 故事范围适当
• 成功标准可衡量
• 依赖关系已识别

---

故事经理交接说明

"模块分析已完成，关键发现：

1. 依赖关系分析完成：7个模块的依赖关系已明确，发现order和disability_person模块存在循环依赖
2. 命名方案确定：使用@d8d/allin-前缀，-module后缀，非多租户版本
3. 目录结构：在根目录创建allin-packages/目录存放专属包
4. 移植顺序建议：platform → channel/dict/salary → company → order/disability

请基于以上分析开发详细的用户故事。关键考虑：

• 这是对运行TypeScript、NestJS、PostgreSQL、Redis、MinIO的现有系统的增强
• 只移植有实体的7个模块，映射关系已确定（使用@d8d/allin-前缀）
• 目录结构：模块将放置在allin-packages/目录下
• 循环依赖问题：order和disability_person模块需要特殊处理
• 集成点：模块间API调用、数据库访问、配置共享
• 要遵循的现有模式：workspace依赖、模块化结构
• 关键兼容性要求：API接口不变、数据库schema兼容、性能影响最小
• 每个故事必须包含验证现有功能保持完整的检查

史诗应在保持系统完整性的同时实现将有实体模块移植为标准化独立包的目标。"