📝 docs(architecture): update source tree and testing strategy documentation

- add version 3.2 to source-tree.md with infrastructure and business module packages
- restructure source tree documentation to reflect new modular architecture
- update integration guide with new package architecture hierarchy
- update testing-strategy.md to version 2.8 with modular package testing approach
- add package test architecture section detailing layered testing strategy
- update test location paths for all package types
- modify CI/CD configuration examples for modular package testing
- update local development test commands for new package structure
- add shared-test-util to testing dependencies

📝 docs(testing): enhance testing strategy with package-specific details

- define clear testing scope for infrastructure vs business module packages
- update test pyramid strategy with package-specific locations
- add detailed GitHub Actions workflow examples for modular testing
- enhance test examples with package-specific import paths
- update test commands for individual package testing
- add package-specific coverage reporting instructions
- update version history with latest changes to testing documentation

docs/architecture/source-tree.md

@@ -3,6 +3,7 @@
 ## 版本信息
 | 版本 | 日期 | 描述 | 作者 |
 |------|------|------|------|
+| 3.2 | 2025-11-11 | 更新包结构，添加基础设施和业务模块包 | Winston |
 | 3.1 | 2025-11-09 | 更新测试结构，清理重复测试文件 | James |
 | 3.0 | 2025-10-22 | 更新为 monorepo 结构，添加 packages/server | Winston |
 
@@ -52,79 +53,111 @@ d8d-mini-starter/
 │   │   └── prod.ts             # 生产环境配置
 │   └── package.json
 ├── packages/                   # 共享包
-│   └── server/                 # API服务器包 (@d8d/server)
+│   ├── server/                 # API服务器包 (@d8d/server) - 重构后
+│   │   ├── src/
+│   │   │   ├── api.ts                          # API路由导出
+│   │   │   └── index.ts                        # 服务器入口
+│   │   ├── tests/
+│   │   └── package.json
+│   ├── shared-types/           # 共享类型定义 (@d8d/shared-types)
+│   │   ├── src/
+│   │   │   └── index.ts                        # 类型定义导出
+│   │   └── package.json
+│   ├── shared-utils/           # 共享工具函数 (@d8d/shared-utils)
+│   │   ├── src/
+│   │   │   ├── utils/
+│   │   │   │   ├── jwt.util.ts                 # JWT工具
+│   │   │   │   ├── errorHandler.ts             # 错误处理
+│   │   │   │   ├── parseWithAwait.ts           # 异步解析
+│   │   │   │   ├── logger.ts                   # 日志工具
+│   │   │   │   └── redis.util.ts               # Redis会话管理
+│   │   │   └── data-source.ts                  # 数据库连接
+│   │   ├── tests/
+│   │   └── package.json
+│   ├── shared-crud/            # 通用CRUD基础设施 (@d8d/shared-crud)
+│   │   ├── src/
+│   │   │   ├── services/
+│   │   │   │   ├── generic-crud.service.ts     # 通用CRUD服务
+│   │   │   │   └── concrete-crud.service.ts    # 具体CRUD服务
+│   │   │   └── routes/
+│   │   │       └── generic-crud.routes.ts      # 通用CRUD路由
+│   │   ├── tests/
+│   │   └── package.json
+│   ├── shared-test-util/       # 测试基础设施 (@d8d/shared-test-util)
+│   │   ├── src/
+│   │   │   ├── integration-test-db.ts          # 集成测试数据库工具
+│   │   │   ├── integration-test-utils.ts       # 集成测试断言工具
+│   │   ├── tests/
+│   │   └── package.json
+│   ├── user-module/            # 用户管理模块 (@d8d/user-module)
+│   │   ├── src/
+│   │   │   ├── entities/
+│   │   │   │   ├── user.entity.ts              # 用户实体
+│   │   │   │   └── role.entity.ts              # 角色实体
+│   │   │   ├── services/
+│   │   │   │   ├── user.service.ts             # 用户服务
+│   │   │   │   └── role.service.ts             # 角色服务
+│   │   │   ├── schemas/
+│   │   │   │   ├── user.schema.ts              # 用户Schema
+│   │   │   │   └── role.schema.ts              # 角色Schema
+│   │   │   └── routes/
+│   │   │       ├── user.routes.ts              # 用户路由
+│   │   │       ├── role.routes.ts              # 角色路由
+│   │   │       └── custom.routes.ts            # 自定义路由
+│   │   ├── tests/
+│   │   └── package.json
+│   ├── auth-module/            # 认证管理模块 (@d8d/auth-module)
+│   │   ├── src/
+│   │   │   ├── services/
+│   │   │   │   ├── auth.service.ts             # 认证服务
+│   │   │   │   └── mini-auth.service.ts        # 小程序认证服务
+│   │   │   ├── schemas/
+│   │   │   │   └── auth.schema.ts              # 认证Schema
+│   │   │   ├── routes/
+│   │   │   │   ├── login.route.ts              # 登录路由
+│   │   │   │   ├── register.route.ts           # 注册路由
+│   │   │   │   ├── mini-login.route.ts         # 小程序登录路由
+│   │   │   │   ├── phone-decrypt.route.ts      # 手机号解密路由
+│   │   │   │   ├── me.route.ts                 # 获取用户信息路由
+│   │   │   │   ├── update-me.route.ts          # 更新用户信息路由
+│   │   │   │   ├── logout.route.ts             # 登出路由
+│   │   │   │   └── sso-verify.route.ts         # SSO验证路由
+│   │   │   └── middleware/
+│   │   │       ├── auth.middleware.ts          # 认证中间件
+│   │   │       └── index.ts                    # 中间件导出
+│   │   ├── tests/
+│   │   └── package.json
+│   ├── file-module/            # 文件管理模块 (@d8d/file-module)
+│   │   ├── src/
+│   │   │   ├── entities/
+│   │   │   │   └── file.entity.ts              # 文件实体
+│   │   │   ├── services/
+│   │   │   │   ├── file.service.ts             # 文件服务
+│   │   │   │   └── minio.service.ts            # MinIO服务
+│   │   │   ├── schemas/
+│   │   │   │   └── file.schema.ts              # 文件Schema
+│   │   │   └── routes/
+│   │   │       ├── upload-policy/post.ts       # 上传策略路由
+│   │   │       ├── multipart-policy/post.ts    # 多部分上传策略路由
+│   │   │       ├── multipart-complete/post.ts  # 完成多部分上传路由
+│   │   │       └── [id]/
+│   │   │           ├── get.ts                  # 获取文件详情路由
+│   │   │           ├── get-url.ts              # 获取文件URL路由
+│   │   │           ├── download.ts             # 文件下载路由
+│   │   │           └── delete.ts               # 删除文件路由
+│   │   ├── tests/
+│   │   └── package.json
+│   └── geo-areas/              # 地区模块 (@d8d/geo-areas)
 │       ├── src/
-│       │   ├── api/            # API路由
-│       │   │   ├── auth/       # 认证相关
-│       │   │   │   ├── index.ts                 # 认证路由入口
-│       │   │   │   ├── login/post.ts            # 登录接口
-│       │   │   │   ├── logout.ts                # 登出接口
-│       │   │   │   ├── me/get.ts                # 获取用户信息
-│       │   │   │   ├── me/put.ts                # 更新用户信息
-│       │   │   │   ├── mini-login/post.ts       # 小程序登录
-│       │   │   │   ├── register/create.ts       # 注册接口
-│       │   │   │   └── sso-verify.ts            # SSO验证
-│       │   │   ├── files/      # 文件管理
-│       │   │   │   ├── [id]/delete.ts           # 删除文件
-│       │   │   │   ├── [id]/download.ts         # 下载文件
-│       │   │   │   ├── [id]/get-url.ts          # 获取文件URL
-│       │   │   │   ├── index.ts                 # 文件列表
-│       │   │   │   ├── multipart-complete/post.ts # 完成分片上传
-│       │   │   │   ├── multipart-policy/post.ts # 分片上传策略
-│       │   │   │   └── upload-policy/post.ts    # 上传策略
-│       │   │   ├── roles/index.ts               # 角色管理
-│       │   │   ├── users/index.ts               # 用户管理
-│       │   │   └── users/custom.ts              # 自定义用户接口
-│       │   ├── modules/        # 业务模块
-│       │   │   ├── auth/       # 认证模块
-│       │   │   │   ├── auth.service.ts          # 认证服务
-│       │   │   │   └── mini-auth.service.ts     # 小程序认证服务
-│       │   │   ├── files/      # 文件模块
-│       │   │   │   ├── file.entity.ts           # 文件实体
-│       │   │   │   ├── file.schema.ts           # 文件模式
-│       │   │   │   ├── file.service.ts          # 文件服务
-│       │   │   │   └── minio.service.ts         # MinIO服务
-│       │   │   └── users/      # 用户模块
-│       │   │       ├── role.entity.ts           # 角色实体
-│       │   │       ├── role.schema.ts           # 角色模式
-│       │   │       ├── role.service.ts          # 角色服务
-│       │   │       ├── user.entity.ts           # 用户实体
-│       │   │       ├── user.schema.ts           # 用户模式
-│       │   │       └── user.service.ts          # 用户服务
-│       │   ├── middleware/     # 中间件
-│       │   │   ├── auth.middleware.ts           # 认证中间件
-│       │   │   └── permission.middleware.ts     # 权限中间件
-│       │   ├── share/          # 共享类型
-│       │   │   └── types.ts                     # 共享类型定义
-│       │   ├── types/          # 类型定义
-│       │   │   └── context.ts                   # 上下文类型
-│       │   ├── utils/          # 工具函数
-│       │   │   ├── backup.ts                    # 数据库备份
-│       │   │   ├── concrete-crud.service.ts     # 具体CRUD服务
-│       │   │   ├── errorHandler.ts              # 错误处理
-│       │   │   ├── generic-crud.routes.ts       # 通用CRUD路由
-│       │   │   ├── generic-crud.service.ts      # 通用CRUD服务
-│       │   │   ├── jwt.util.ts                  # JWT工具
-│       │   │   ├── logger.ts                    # 日志工具
-│       │   │   ├── parseWithAwait.ts            # 异步解析
-│       │   │   └── restore.ts                   # 数据库恢复
-│       │   ├── data-source.ts                   # 数据库连接
-│       │   └── index.ts                         # 服务器入口
-│       ├── tests/              # 服务器测试
-│       │   ├── integration/    # 集成测试
-│       │   │   ├── auth.integration.test.ts      # 认证集成测试
-│       │   │   ├── backup.integration.test.ts    # 备份集成测试
-│       │   │   ├── files.integration.test.ts     # 文件集成测试
-│       │   │   ├── minio.integration.test.ts     # MinIO集成测试
-│       │   │   └── users.integration.test.ts     # 用户集成测试
-│       │   └── unit/           # 单元测试
-│       │       ├── modules/    # 业务模块测试
-│       │       │   ├── file.service.test.ts      # 文件服务测试
-│       │       │   ├── minio.service.test.ts     # MinIO服务测试
-│       │       │   └── user.service.test.ts      # 用户服务测试
-│       │       └── utils/      # 工具函数测试
-│       │           ├── backup.test.ts            # 备份工具测试
-│       │           └── restore.test.ts           # 恢复工具测试
+│       │   ├── modules/areas/
+│       │   │   ├── area.entity.ts              # 地区实体
+│       │   │   ├── area.service.ts             # 地区服务
+│       │   │   └── area.schema.ts              # 地区Schema
+│       │   ├── api/
+│       │   │   ├── areas/index.ts              # 公共地区API
+│       │   │   └── admin/areas/index.ts        # 管理地区API
+│       │   └── index.ts                        # 包入口
+│       ├── tests/
 │       └── package.json
 ├── web/                        # Web应用 (Hono + React SSR)
 │   ├── src/
@@ -185,26 +218,31 @@ d8d-mini-starter/
 
 ## 集成指南
 - **文件命名**: 保持现有kebab-case命名约定
-- **项目结构**: 采用monorepo模式，包含小程序(mini)、Web应用(web)和共享服务器包(packages/server)
+- **项目结构**: 采用monorepo模式，包含小程序(mini)、Web应用(web)和模块化包架构
 - **包管理**: 使用pnpm workspace管理多包依赖关系
 - **小程序架构**: 基于Taro框架，支持多平台（微信小程序、H5等）
 - **Web应用架构**: 基于Hono + React SSR，使用shadcn/ui组件库
-- **API服务器**: 独立的`@d8d/server`包，基于Hono框架，提供RESTful API
+- **模块化架构**: 采用分层包结构，支持按需安装和独立开发
+- **API服务器**: 重构后的`@d8d/server`包，基于模块化架构，提供RESTful API
 - **API设计**: 使用Hono框架，RESTful API设计，支持文件分片上传
 - **数据库**: 使用PostgreSQL + TypeORM
 - **存储**: 使用MinIO进行文件存储
+- **包架构层次**:
+  - **基础设施层**: shared-types → shared-utils → shared-crud
+  - **测试基础设施**: shared-test-util
+  - **业务模块层**: user-module → auth-module → file-module → geo-areas
+  - **应用层**: server (重构后)
 - **测试结构**:
-  - **packages/server**: 独立的服务器测试
-    - 单元测试位于`packages/server/tests/unit/`
-    - 集成测试位于`packages/server/tests/integration/`
-  - **web**: Web应用测试
-    - 单元测试位于`web/tests/unit/`
-    - 集成测试位于`web/tests/integration/`
-    - E2E测试位于`web/tests/e2e/` (Playwright)
+  - **基础设施包**: 每个包独立的单元测试和集成测试
+  - **业务模块包**: 每个模块包含完整的测试套件
+  - **server包**: 集成测试验证模块间协作
+  - **web应用**: 组件测试、集成测试和E2E测试
 - **开发环境**: 多八多云端开发容器，包含Node.js 20.19.2、PostgreSQL 17、Redis 7、MinIO
 - **构建工具**: 使用Vite + pnpm，支持SSR构建
 - **架构优势**:
-  - 服务器代码可独立部署和测试
-  - 前端和后端可独立开发
-  - 共享类型定义减少重复代码
-  - 统一的错误处理和中间件
+  - 清晰的模块边界和职责分离
+  - 支持按需安装，减少包体积
+  - 基础设施和业务逻辑分离
+  - 统一的测试模式和工具
+  - 更好的代码复用和维护性
+  - 独立的包版本管理

docs/architecture/testing-strategy.md

@@ -3,6 +3,7 @@
 ## 版本信息
 | 版本 | 日期 | 描述 | 作者 |
 |------|------|------|------|
+| 2.8 | 2025-11-11 | 更新包测试结构，添加模块化包测试策略 | Winston |
 | 2.7 | 2025-11-09 | 更新为monorepo测试架构，清理重复测试文件 | James |
 | 2.6 | 2025-10-15 | 完成遗留测试文件迁移到统一的tests目录结构 | Winston |
 | 2.5 | 2025-10-14 | 更新测试文件位置到统一的tests目录结构 | Claude |
@@ -12,12 +13,22 @@
 
 本文档定义了D8D Starter项目的完整测试策略，基于monorepo架构和现有的测试基础设施。测试策略遵循测试金字塔模型，确保代码质量、功能稳定性和系统可靠性。
 
-### 测试架构更新 (v2.7)
+### 测试架构更新 (v2.8)
 
-项目已重构为monorepo结构，测试架构相应调整为：
-- **packages/server**: 独立的API服务器包，包含单元测试和集成测试
+项目已重构为模块化包架构，测试架构相应调整为：
+- **基础设施包**: shared-types、shared-utils、shared-crud、shared-test-util
+- **业务模块包**: user-module、auth-module、file-module、geo-areas
+- **应用层**: server (重构后)，包含模块集成测试
 - **web**: Web应用，包含组件测试、集成测试和E2E测试
-- **CI/CD**: 独立的工作流分别处理server和web的测试
+- **CI/CD**: 独立的工作流分别处理各包的测试
+
+### 包测试架构 (v2.8)
+
+项目采用分层测试架构，每个包独立测试：
+- **基础设施包**: 纯单元测试，不依赖外部服务
+- **业务模块包**: 单元测试 + 集成测试，验证模块功能
+- **应用层**: 集成测试，验证模块间协作
+- **共享测试工具**: shared-test-util 提供统一的测试基础设施
 
 ## 测试金字塔策略
 
@@ -25,8 +36,10 @@
 - **范围**: 单个函数、类或组件
 - **目标**: 验证独立单元的correctness
 - **位置**:
-  - `packages/server/tests/unit/**/*.test.ts` (服务器单元测试)
-  - `web/tests/unit/**/*.test.{ts,tsx}` (Web组件单元测试)
+  - **基础设施包**: `packages/shared-*/tests/unit/**/*.test.ts`
+  - **业务模块包**: `packages/*-module/tests/unit/**/*.test.ts`
+  - **server包**: `packages/server/tests/unit/**/*.test.ts`
+  - **web应用**: `web/tests/unit/**/*.test.{ts,tsx}`
 - **框架**: Vitest
 - **覆盖率目标**: ≥ 80%
 - **执行频率**: 每次代码变更
@@ -35,9 +48,10 @@
 - **范围**: 多个组件/服务协作
 - **目标**: 验证模块间集成和交互
 - **位置**:
-  - `packages/server/tests/integration/**/*.test.ts` (服务器集成测试)
-  - `web/tests/integration/**/*.test.{ts,tsx}` (Web集成测试)
-- **框架**: Vitest + Testing Library + hono/testing
+  - **业务模块包**: `packages/*-module/tests/integration/**/*.test.ts`
+  - **server包**: `packages/server/tests/integration/**/*.test.ts` (模块集成测试)
+  - **web应用**: `web/tests/integration/**/*.test.{ts,tsx}`
+- **框架**: Vitest + Testing Library + hono/testing + shared-test-util
 - **覆盖率目标**: ≥ 60%
 - **执行频率**: 每次API变更
 
@@ -84,11 +98,36 @@ export default defineConfig({
 
 ### CI/CD环境
 ```yaml
-# GitHub Actions 测试配置 (Monorepo架构)
+# GitHub Actions 测试配置 (模块化包架构)
 name: Test Pipeline
 
 jobs:
-  server-tests:
+  # 基础设施包测试
+  shared-packages-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - run: cd packages/shared-types && pnpm test
+      - run: cd packages/shared-utils && pnpm test
+      - run: cd packages/shared-crud && pnpm test
+      - run: cd packages/shared-test-util && pnpm test
+
+  # 业务模块包测试
+  business-modules-tests:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_PASSWORD: test_password
+          POSTGRES_DB: test_d8dai
+    steps:
+      - run: cd packages/user-module && pnpm test
+      - run: cd packages/auth-module && pnpm test
+      - run: cd packages/file-module && pnpm test
+      - run: cd packages/geo-areas && pnpm test
+
+  # 服务器集成测试
+  server-integration-tests:
     runs-on: ubuntu-latest
     services:
       postgres:
@@ -97,9 +136,9 @@ jobs:
           POSTGRES_PASSWORD: test_password
           POSTGRES_DB: test_d8dai
     steps:
-      - run: cd packages/server && pnpm test:unit
-      - run: cd packages/server && pnpm test:integration
+      - run: cd packages/server && pnpm test
 
+  # Web应用测试
   web-integration-tests:
     runs-on: ubuntu-latest
     services:
@@ -171,40 +210,67 @@ const inactiveUser = createTestUser({ active: false });
 
 ### 本地开发测试
 
-#### packages/server
+#### 基础设施包
 ```bash
-# 运行所有测试
-pnpm test
+# 运行所有基础设施包测试
+cd packages/shared-types && pnpm test
+cd packages/shared-utils && pnpm test
+cd packages/shared-crud && pnpm test
+cd packages/shared-test-util && pnpm test
+
+# 生成覆盖率报告
+cd packages/shared-utils && pnpm test:coverage
+```
+
+#### 业务模块包
+```bash
+# 运行所有业务模块包测试
+cd packages/user-module && pnpm test
+cd packages/auth-module && pnpm test
+cd packages/file-module && pnpm test
+cd packages/geo-areas && pnpm test
 
 # 运行单元测试
-pnpm test:unit
+cd packages/user-module && pnpm test:unit
+
+# 运行集成测试
+cd packages/auth-module && pnpm test:integration
+
+# 生成覆盖率报告
+cd packages/user-module && pnpm test:coverage
+```
+
+#### server包
+```bash
+# 运行所有测试
+cd packages/server && pnpm test
 
 # 运行集成测试
-pnpm test:integration
+cd packages/server && pnpm test:integration
 
 # 生成覆盖率报告
-pnpm test:coverage
+cd packages/server && pnpm test:coverage
 ```
 
-#### web
+#### web应用
 ```bash
 # 运行所有测试
-pnpm test
+cd web && pnpm test
 
 # 运行单元测试
-pnpm test:unit
+cd web && pnpm test:unit
 
 # 运行集成测试
-pnpm test:integration
+cd web && pnpm test:integration
 
 # 运行组件测试
-pnpm test:components
+cd web && pnpm test:components
 
 # 运行E2E测试
-pnpm test:e2e:chromium
+cd web && pnpm test:e2e:chromium
 
 # 生成覆盖率报告
-pnpm test:coverage
+cd web && pnpm test:coverage
 ```
 
 ### CI/CD流水线测试
@@ -322,10 +388,14 @@ describe('UserService', () => {
 - **Testing Library**: 16.3.0
 - **Playwright**: 1.55.0
 - **hono/testing**: 内置（Hono 4.8.5）
+- **shared-test-util**: 1.0.0 (测试基础设施包)
+- **TypeORM**: 0.3.20 (数据库测试)
+- **Redis**: 7.0.0 (会话管理测试)
 
 ### 更新日志
 | 日期 | 版本 | 描述 |
 |------|------|------|
+| 2025-11-11 | 2.8 | 更新包测试结构，添加模块化包测试策略 |
 | 2025-11-09 | 2.7 | 更新为monorepo测试架构，清理重复测试文件 |
 | 2025-10-15 | 2.6 | 完成遗留测试文件迁移到统一的tests目录结构 |
 | 2025-10-14 | 2.5 | 重构测试文件结构，统一到tests目录 |