Epic-005: Mini-Auth 通用模块 Package 化集成 - Brownfield Enhancement

Epic Goal

将 mini-auth-demo 项目中开发的高度通用模块（地区、地点、小程序认证、支付、乘客管理）从 /mini-auth-demo/packages/server/src 拆分反哺到主项目的 /packages 目录下，以独立 package 方式组织，为未来继承该 starter 的项目提供按需使用的可复用基础模块，同时保持模块的独立性和向后兼容性。

Epic Description

Existing System Context

Current relevant functionality:

主项目目前包含基础的认证、用户管理、文件管理模块
使用 TypeORM + PostgreSQL 作为数据访问层
采用 Hono 框架构建 RESTful API
前端使用 React/Taro 框架
已有基础的 JWT 认证和用户角色管理

Technology stack:

Backend: Node.js, TypeScript, Hono, TypeORM, PostgreSQL
Frontend: React, Taro, TanStack Query
Authentication: JWT, Redis session management
Payment: WeChat Pay v3 SDK
Database: PostgreSQL with tree structure support

Integration points:

现有认证系统需要扩展支持小程序登录
数据库需要新增地区、地点、乘客等实体表
现有用户实体需要扩展小程序相关字段
支付模块需要与现有订单系统集成

Enhancement Details

What's being added/changed:

地区模块：完整的省市区三级联动数据管理和API
地点模块：基于地理位置的POI管理和搜索功能
小程序认证：微信小程序登录和手机号解密功能
支付模块：微信小程序支付集成和回调处理
乘客模块：多乘客管理和默认乘客设置

Package 架构设计:

packages/
├── server/                    # 核心服务器 (现有，重构后)
├── shared-types/              # 共享类型定义 (新增)
├── shared-utils/              # 工具核心 (新增)
├── shared-crud/               # CRUD核心基础设施 (新增)
├── shared-test-util/          # 测试基础设施 (新增)
├── user-module/               # 用户管理模块 (新增)
├── auth-module/               # 认证管理模块 (已包含小程序认证功能)
├── file-module/               # 文件管理模块 (新增)
├── mini-payment/              # 小程序支付 (待实现)
├── geo-areas/                 # 地区模块 (待实现)
├── geo-locations/             # 地点模块 (待实现)
└── passenger-management/      # 乘客管理 (待实现)

How it integrates:

每个模块作为独立 package，支持按需安装
遵循现有项目架构模式，使用相同的 TypeORM 实体和服务结构
复用现有的认证中间件和权限控制
保持 API 设计风格一致，使用 Hono 路由
集成到现有的数据库连接和事务管理
通过 pnpm workspace 管理依赖关系

Success criteria:

所有通用模块作为独立 package 可用
现有功能不受影响，保持向后兼容
支持按需安装，项目可选择性引入所需模块
提供完整的 API 文档和类型定义
所有模块通过单元测试和集成测试
package 间依赖关系清晰，版本管理独立

Stories

阶段 1: 基础设施重构 (已完成 ✅)

Story 1: 基础设施和业务模块包拆分 - 从 packages/server/src 拆分迁移 shared-types、shared-utils、shared-crud、shared-test-util、user-module、auth-module、file-module package，重构server依赖关系

阶段 2: 业务模块 Package 化

Story 2: 地区模块 package - 从 mini-auth-demo/packages/server/src 拆分反哺省市区三级联动数据管理和API
Story 3: 小程序认证模块增强 - 在现有 auth-module 中补充微信小程序手机号解密认证功能
Story 4: 小程序支付模块 package - 从 mini-auth-demo/packages/server/src 拆分反哺小程序支付模块
Story 5: 地理位置和乘客模块 package - 从 mini-auth-demo/packages/server/src 拆分反哺地点模块和乘客管理模块

Compatibility Requirements

现有 APIs 保持不变，新增模块使用独立命名空间
数据库 schema 变更向后兼容，新增表不影响现有功能
UI 组件遵循现有设计模式，提供可复用的 React/Taro 组件
性能影响最小化，关键操作使用缓存和索引优化
Package 依赖关系清晰，避免循环依赖
支持按需安装，项目可选择性引入所需模块

Risk Mitigation

Primary Risk: 数据库 schema 变更可能影响现有数据 Mitigation: 使用 TypeORM migrations 管理数据库变更，确保数据迁移安全 Rollback Plan: 保留数据库备份，提供回滚脚本，模块化设计便于独立禁用

Primary Risk: 小程序认证与现有认证系统冲突 Mitigation: 扩展现有认证服务，提供多种认证方式共存 Rollback Plan: 保持原有认证方式不变，小程序认证作为可选功能

Primary Risk: Package 依赖关系复杂化 Mitigation: 设计清晰的依赖层次，基础设施package作为基础依赖 Rollback Plan: 保持核心 server package 独立，其他 package 可选择性移除

Primary Risk: 基础设施重构影响现有功能 Mitigation: 分阶段重构，每个阶段完成后进行回归测试 Rollback Plan: 保留重构前的代码备份，提供快速回滚方案

Definition of Done

阶段 1 stories 完成且验收标准满足
现有功能通过回归测试验证
集成点正常工作，API 调用无冲突
模块文档和类型定义完整
现有功能无回归问题
所有 package 独立构建和测试通过
Package 依赖关系清晰，无循环依赖
阶段 2 stories 完成且验收标准满足

架构设计详情

Package 结构设计

packages/
├── server/                    # 核心服务器 (现有，重构后)
│   ├── src/
│   ├── package.json
│   └── tsconfig.json
├── shared-types/              # 共享类型定义 (新增)
│   ├── src/
│   ├── package.json
│   └── tsconfig.json
├── shared-utils/              # 工具核心 (新增)
│   ├── src/
│   ├── package.json
│   └── tsconfig.json
├── shared-crud/               # CRUD核心基础设施 (新增)
│   ├── src/
│   ├── package.json
│   └── tsconfig.json
├── shared-test-util/          # 测试基础设施 (新增)
│   ├── src/
│   ├── package.json
│   └── tsconfig.json
├── user-module/               # 用户管理模块 (新增)
│   ├── src/
│   ├── package.json
│   └── tsconfig.json
├── auth-module/               # 认证管理模块 (新增)
│   ├── src/
│   ├── package.json
│   └── tsconfig.json
├── file-module/               # 文件管理模块 (新增)
│   ├── src/
│   ├── package.json
│   └── tsconfig.json
├── mini-auth/                 # 小程序认证增强 (待实现)
│   ├── src/
│   ├── package.json
│   └── tsconfig.json
├── mini-payment/              # 小程序支付 (待实现)
│   ├── src/
│   ├── package.json
│   └── tsconfig.json
├── geo-areas/                 # 地区模块 (待实现)
│   ├── src/
│   ├── package.json
│   └── tsconfig.json
├── geo-locations/             # 地点模块 (待实现)
│   ├── src/
│   ├── package.json
│   └── tsconfig.json
└── passenger-management/      # 乘客管理 (待实现)
    ├── src/
    ├── package.json
    └── tsconfig.json

依赖关系设计

依赖层次

shared-types (基础类型)
    ↑
shared-utils (工具基础设施)
    ↑
shared-crud (CRUD基础设施) + shared-test-util (测试基础设施)
    ↑
业务模块 (user-module, auth-module, file-module)
    ↑
server (应用入口)

基础设施 Package 依赖关系

shared-crud package

{
  "name": "@d8d/shared-crud",
  "dependencies": {
    "@d8d/shared-types": "workspace:*",
    "@d8d/shared-utils": "workspace:*",
    "typeorm": "^0.3.20",
    "@hono/zod-openapi": "1.0.2",
    "zod": "^4.1.12"
  }
}

shared-utils package

{
  "name": "@d8d/shared-utils",
  "dependencies": {
    "@d8d/shared-types": "workspace:*",
    "jsonwebtoken": "^9.0.2",
    "bcrypt": "^6.0.0",
    "typeorm": "^0.3.20",
    "pg": "^8.16.3"
  }
}

shared-test-util package

{
  "name": "@d8d/shared-test-util",
  "dependencies": {
    "@d8d/shared-utils": "workspace:*",
    "typeorm": "^0.3.20",
    "vitest": "^3.2.4"
  },
  "peerDependencies": {
    "hono": "^4.8.5"
  }
}

shared-types package

{
  "name": "@d8d/shared-types",
  "dependencies": {
    // 纯类型定义，不需要外部依赖
  }
}

业务模块 Package 依赖关系

user-module package

{
  "name": "@d8d/user-module",
  "dependencies": {
    "@d8d/shared-types": "workspace:*",
    "@d8d/shared-utils": "workspace:*",
    "@d8d/shared-crud": "workspace:*",
    "typeorm": "^0.3.20"
  },
  "devDependencies": {
    "@d8d/shared-test-util": "workspace:*"
  }
}

auth-module package

{
  "name": "@d8d/auth-module",
  "dependencies": {
    "@d8d/shared-types": "workspace:*",
    "@d8d/shared-utils": "workspace:*",
    "@d8d/user-module": "workspace:*",
    "typeorm": "^0.3.20"
  },
  "devDependencies": {
    "@d8d/shared-test-util": "workspace:*"
  }
}

file-module package

{
  "name": "@d8d/file-module",
  "dependencies": {
    "@d8d/shared-types": "workspace:*",
    "@d8d/shared-utils": "workspace:*",
    "@d8d/shared-crud": "workspace:*",
    "typeorm": "^0.3.20"
  },
  "devDependencies": {
    "@d8d/shared-test-util": "workspace:*"
  }
}

重构后的 server package

{
  "name": "@d8d/server",
  "dependencies": {
    "@d8d/shared-types": "workspace:*",
    "@d8d/shared-utils": "workspace:*",
    "@d8d/shared-crud": "workspace:*",
    "@d8d/user-module": "workspace:*",
    "@d8d/auth-module": "workspace:*",
    "@d8d/file-module": "workspace:*",
    // 其他现有依赖保持不变
  }
}

Package 导出设计

shared-types 导出

// 基础工具类型
export type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
};

// 通用响应类型
export interface ApiResponse<T> {
  data: T;
  message?: string;
  code?: number;
}

// 分页类型
export interface Pagination {
  total: number;
  current: number;
  pageSize: number;
}

// 通用查询参数
export interface QueryParams {
  page?: number;
  pageSize?: number;
  keyword?: string;
  sortBy?: string;
  sortOrder?: 'ASC' | 'DESC';
}

// 通用错误类型
export interface ApiError {
  code: number;
  message: string;
  details?: any;
}

模块 package 导出模式

每个模块 package 遵循统一的导出模式，业务相关类型放在各自package中：

// 实体
export { AreaEntity } from './entities/area.entity';

// 服务
export { AreaService } from './services/area.service';

// DTOs
export { CreateAreaDto, UpdateAreaDto } from './dto/area.dto';

// 控制器
export { AreaController } from './controllers/area.controller';

// 路由
export { areaRoutes } from './routes/area.routes';

// 业务相关类型 (放在各自package中)
export type { Area, AreaLevel } from './types/area.types';

业务模块类型示例

geo-areas package 中的类型

// 地区相关类型
export interface Area {
  id: string;
  name: string;
  code: string;
  level: number;
  parentId?: string;
}

export type AreaLevel = 1 | 2 | 3; // 省市区

geo-locations package 中的类型

// 地点相关类型
export interface Location {
  id: string;
  name: string;
  latitude: number;
  longitude: number;
  areaId: string;
}

mini-auth package 中的类型

// 小程序认证相关类型
export interface MiniAuthUser {
  openid: string;
  unionid?: string;
  sessionKey: string;
}

使用示例

项目按需使用

// package.json - 只需要地区功能
{
  "dependencies": {
    "@d8d/server": "^1.0.0",
    "@d8d/geo-areas": "^1.0.0"
  }
}

// package.json - 需要完整地理位置功能
{
  "dependencies": {
    "@d8d/server": "^1.0.0",
    "@d8d/geo-areas": "^1.0.0",
    "@d8d/geo-locations": "^1.0.0"
  }
}

// package.json - 需要小程序生态功能
{
  "dependencies": {
    "@d8d/server": "^1.0.0",
    "@d8d/mini-auth": "^1.0.0",
    "@d8d/mini-payment": "^1.0.0"
  }
}

代码中使用

// 只导入需要的模块和类型
import { AreaService, type Area } from '@d8d/geo-areas';
import { LocationService, type Location } from '@d8d/geo-locations';
import { MiniAuthService, type MiniAuthUser } from '@d8d/mini-auth';

// 使用通用类型
import type { ApiResponse, Pagination } from '@d8d/shared-types';

// 或者从 server 统一导入
import {
  AreaService,
  LocationService,
  MiniAuthService
} from '@d8d/server';

模块详细说明

地区模块 (Areas Module)

功能: 完整的中国行政区划管理
核心实体: AreaEntity (省市区三级树形结构)
主要服务: AreaService (树形查询、路径查询、层级查询)
API: /api/areas, /api/admin/areas
前端组件: AreaPicker (三级联动选择器)

地点模块 (Locations Module)

功能: 地理位置POI管理和搜索
核心实体: LocationEntity (名称、坐标、类型)
主要服务: LocationService (搜索、筛选、距离计算)
API: /api/locations, /api/admin/locations

小程序认证模块 (Mini Auth Module)

功能: 微信小程序手机号解密
核心服务: MiniAuthService (手机号解密)
集成点: 扩展现有 UserEntity (手机号字段)
API: /api/auth/decrypt-phone

支付模块 (Payment Module)

功能: 微信小程序支付集成
核心服务: PaymentService (创建支付、处理回调、查询状态)
依赖: wechatpay-node-v3 SDK
API: /api/payment/create, /api/payment/callback

乘客模块 (Passengers Module)

功能: 多乘客管理和默认乘客设置
核心实体: PassengerEntity (姓名、证件、联系方式)
主要服务: PassengerService (CRUD、默认乘客管理)
API: /api/passengers, /api/admin/passengers

技术实现要点

基础设施重构

Package 架构: 基础设施和业务模块分离，支持按需安装
依赖管理: 清晰的依赖层次，避免循环依赖
类型共享: shared-types 作为所有package的基础依赖

业务模块实现

数据库设计: 使用 TypeORM 实体和 migrations
服务层: 基于 crud-core 的服务模式，依赖注入
API 层: Hono 路由，统一错误处理
前端集成: 提供 React/Taro 组件和类型定义
配置管理: 环境变量控制模块启用状态
测试覆盖: 每个 package 独立测试 + 集成测试

向后兼容性保证

基础设施重构

现有API接口保持不变
数据库schema保持不变
认证流程保持不变
重构分阶段进行，每个阶段验证兼容性

业务模块集成

现有用户表新增字段均为可选
所有新增 API 使用独立命名空间
数据库 migrations 确保数据安全
提供模块禁用配置选项
核心 server package 保持独立，其他 package 可选
Package 版本独立管理，避免强制升级

当前进展总结

已完成 ✅

阶段 1: 基础设施重构 - 全部完成
- Story 1: 基础设施和业务模块包拆分 - 已完成
- 创建了 4 个基础设施包：shared-types、shared-utils、shared-crud、shared-test-util
- 创建了 3 个业务模块包：user-module、auth-module、file-module
- 成功重构 server package 依赖关系
- 所有包通过单元测试和集成测试验证
- 保持向后兼容性，现有功能无回归

待完成 🔄

阶段 2: 业务模块 Package 化 - 待实现
- Story 2: 地区模块 package (geo-areas)
- Story 3: 小程序认证模块 package (mini-auth) - 微信小程序手机号解密
- Story 4: 小程序支付模块 package (mini-payment)
- Story 5: 地理位置和乘客模块 package (geo-locations, passenger-management)
  
  Story Manager Handoff

"请为这个brownfield epic开发详细的用户故事。关键考虑因素：

这是一个对现有系统的增强，运行在 Node.js + TypeScript + Hono + TypeORM + PostgreSQL 技术栈上
集成点：现有认证系统、用户实体、数据库连接、API路由结构
需要遵循的现有模式：TypeORM实体结构、Hono路由设计、服务层依赖注入、统一错误处理
关键兼容性要求：现有API保持不变、数据库变更向后兼容、认证流程不中断
每个故事必须包含验证现有功能保持完整的测试

该epic应该保持系统完整性，同时实现将mini-auth-demo项目中的通用模块（地区、地点、小程序认证、支付、乘客管理）标准化并集成到主项目的目标。"

epic-005-mini-auth-modules-integration.md 17 KB Vēsture Neapstrādāts

Epic-005: Mini-Auth 通用模块 Package 化集成 - Brownfield Enhancement

Epic Goal

Epic Description

Existing System Context

Enhancement Details

Stories

阶段 1: 基础设施重构 (已完成 ✅)

阶段 2: 业务模块 Package 化

Compatibility Requirements

Risk Mitigation

Definition of Done

架构设计详情

Package 结构设计

依赖关系设计

依赖层次

基础设施 Package 依赖关系

业务模块 Package 依赖关系

Package 导出设计

shared-types 导出

模块 package 导出模式

业务模块类型示例

使用示例

项目按需使用

代码中使用

模块详细说明

地区模块 (Areas Module)

地点模块 (Locations Module)

小程序认证模块 (Mini Auth Module)

支付模块 (Payment Module)

乘客模块 (Passengers Module)

技术实现要点

基础设施重构

业务模块实现

向后兼容性保证

基础设施重构

业务模块集成

当前进展总结

已完成 ✅

待完成 🔄

Story Manager Handoff

epic-005-mini-auth-modules-integration.md 17 KB

Vēsture Neapstrādāts