架构结构

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-12
> **最后更新**: 2026-02-12
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

---

# Schema 结构说明文档

## &#128203; 概述

项目使用两个 schema 文件，按职责分离，遵循领域驱动设计（DDD）思想。

---

## &#127959;️ 架构设计

### 分层架构

```
┌─────────────────────────────────────────┐
│         Application Layer (应用层)       │
│  - Services, Commands, Queries         │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│         Domain Layer (领域层)           │
│  - Entities, Value Objects, Aggregates │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│    Infrastructure Layer (基础设施层)     │
│  - Repositories, External Integrations  │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│          Storage Layer (存储层)          │
│  - Database Tables, Schemas            │
└─────────────────────────────────────────┘
```

### Schema 职责划分

| Schema | 职责 | 使用场景 |
|--------|------|----------|
| **Infrastructure Schema** | 基础设施、外部系统集成 | API监控、微信、企业微信、小程序、渠道配置等 |
| **Storage Schema** | 核心业务数据 | 薪资、CRM、用户、订单、权限等 |

---

## &#128193; Schema 文件详情

### 1. Infrastructure Schema

**文件路径**: `src/infrastructure/database/shared/schema.ts`
**文件大小**: 91KB
**表数量**: 53个
**职责**: 基础设施和外部系统集成

#### 模块分类

##### &#128202; API 监控模块（4个表）
- **apiAlertHistories** - API 警报历史记录
  - 用途: 记录 API 触发的警报事件
  - 关键字段: alertRuleId, severity, message
  - 索引: alertRuleId, severity, createdAt

- **apiAlertRules** - API 警报规则配置
  - 用途: 定义 API 监控警报规则
  - 关键字段: name, condition, threshold
  - 索引: name, type, isActive

- **apiMonitorLogs** - API 监控日志
  - 用途: 记录 API 调用监控数据
  - 关键字段: endpoint, method, statusCode, responseTime
  - 索引: endpoint, method, createdAt

- **apiMonitorMetrics** - API 监控指标
  - 用途: 存储 API 性能指标统计数据
  - 关键字段: metricName, value, timestamp
  - 索引: metricName, timestamp

##### &#128172; 微信集成模块（6个表）
- **wechatAutoReplies** - 微信自动回复配置
  - 用途: 配置公众号自动回复规则
  - 关键字段: keyword, replyType, content
  - 索引: keyword, tenantId

- **wechatFans** - 微信粉丝用户
  - 用途: 存储公众号粉丝信息
  - 关键字段: openid, nickname, subscribeStatus
  - 索引: openid, unionid

- **wechatMenus** - 微信自定义菜单
  - 用途: 配置公众号自定义菜单
  - 关键字段: menuType, name, url, appid
  - 索引: parentId, tenantId

- **wechatMessages** - 微信消息记录
  - 用途: 记录与微信用户的消息交互
  - 关键字段: fromUser, toUser, msgType, content
  - 索引: fromUser, toUser, createdAt

- **wechatReplies** - 微信回复记录
  - 用途: 记录系统自动回复的消息
  - 关键字段: messageId, replyType, content
  - 索引: messageId, replyType

- **wechatTemplates** - 微信模板消息
  - 用途: 配置微信模板消息
  - 关键字段: templateId, title, content
  - 索引: templateId, tenantId

##### &#127970; 企业微信集成模块（4个表）
- **weworkApps** - 企业微信应用
  - 用途: 存储企业微信应用配置
  - 关键字段: agentId, appName, corpId
  - 索引: agentId, corpId

- **weworkAuthCorps** - 企业微信授权企业
  - 用途: 存储已授权的企业信息
  - 关键字段: corpId, corpName, authStatus
  - 索引: corpId, authStatus

- **weworkDepartments** - 企业微信部门
  - 用途: 同步企业微信部门结构
  - 关键字段: deptId, name, parentId
  - 索引: deptId, parentId, corpId

- **weworkUsers** - 企业微信用户
  - 用途: 同步企业微信用户信息
  - 关键字段: userid, name, mobile, deptId
  - 索引: userid, mobile, deptId

##### &#128241; 小程序集成模块（2个表）
- **miniprogramLoginLogs** - 小程序登录日志
  - 用途: 记录小程序用户登录日志
  - 关键字段: openId, unionId, loginTime
  - 索引: openId, unionId, loginTime

- **miniprogramUsers** - 小程序用户
  - 用途: 存储小程序用户信息
  - 关键字段: openId, unionId, userInfo
  - 索引: openId, unionId

##### &#127909; 媒体管理模块（2个表）
- **mediaCategories** - 媒体分类
  - 用途: 媒体资源分类管理
  - 关键字段: name, parentId, icon
  - 索引: parentId, name

- **mediaResources** - 媒体资源
  - 用途: 存储图片、视频等媒体资源
  - 关键字段: name, url, size, mimeType
  - 索引: categoryId, tenantId

##### &#128295; 其他基础设施（9个表）
- **channelConfigs** - 渠道配置
  - 用途: 配置各种渠道（短信、邮件等）
  - 关键字段: channelType, configData
  - 索引: channelType, isActive

- **invitationRecords** - 邀请记录
  - 用途: 记录用户邀请信息
  - 关键字段: inviteCode, inviterId, inviteeId
  - 索引: inviteCode, inviterId

- **marketActivationCodes** - 市场激活码
  - 用途: 管理产品激活码
  - 关键字段: code, status, productId
  - 索引: code, productId, status

- **marketCategories** - 市场分类
  - 用途: 市场产品分类
  - 关键字段: name, icon, sortOrder
  - 索引: parentId, sortOrder

- **marketOrders** - 市场订单
  - 用途: 市场购买订单
  - 关键字段: orderNo, userId, productId
  - 索引: orderNo, userId, status

- **salaryNotifyRecords** - 薪资通知记录
  - 用途: 记录薪资通知发送记录
  - 关键字段: notifyType, targetId, status
  - 索引: notifyType, targetId, createdAt

- **salaryNotifyTemplates** - 薪资通知模板
  - 用途: 薪资通知模板配置
  - 关键字段: templateType, title, content
  - 索引: templateType, tenantId

- **surveyVotes** - 投票记录
  - 用途: 记录用户投票
  - 关键字段: surveyId, optionId, userId
  - 索引: surveyId, userId

- **userInstalledApps** - 用户安装的应用
  - 用途: 记录用户安装的应用
  - 关键字段: userId, appId, installTime
  - 索引: userId, appId

---

### 2. Storage Schema

**文件路径**: `src/storage/database/shared/schema.ts`
**文件大小**: 69KB
**表数量**: 48个
**职责**: 核心业务数据

#### 模块分类

##### &#128100; 用户管理模块（2个表）
- **users** - 系统用户
  - 用途: 平台管理员、合作伙伴等用户
  - 关键字段: username, email, role, status
  - 索引: username, email, role

- **employees** - 员工信息
  - 用途: 企业员工基本信息
  - 关键字段: employeeNo, name, mobile, deptId
  - 索引: employeeNo, mobile, tenantId

##### &#128176; 薪资管理模块（5个表）
- **salaryConfigs** - 薪资配置
  - 用途: 企业薪资结构配置
  - 关键字段: configName, tenantId, companyId
  - 索引: tenantId, companyId

- **salaryItemConfigs** - 薪资项目配置
  - 用途: 薪资项目（基本工资、奖金等）
  - 关键字段: itemName, itemType, formula
  - 索引: configId, itemType

- **salarySlips** - 工资条
  - 用途: 员工工资条
  - 关键字段: slipNo, employeeId, salaryPeriod
  - 索引: slipNo, employeeId, salaryPeriod

- **salarySlipDetails** - 工资条明细
  - 用途: 工资条详细项目
  - 关键字段: slipId, itemName, amount
  - 索引: slipId

- **socialInsuranceConfigs** - 社保配置
  - 用途: 社保公积金配置
  - 关键字段: insuranceType, rate, base
  - 索引: tenantId, insuranceType

##### &#128231; 通信管理模块（9个表）
- **emailTemplates** - 邮件模板
  - 用途: 邮件发送模板
  - 关键字段: templateType, subject, content
  - 索引: templateType, tenantId

- **emailSendRecords** - 邮件发送记录
  - 用途: 邮件发送历史
  - 关键字段: toEmail, subject, status
  - 索引: toEmail, status, sentAt

- **emailGlobalVariables** - 邮件全局变量
  - 用途: 邮件模板全局变量
  - 关键字段: variableName, variableValue
  - 索引: variableName

- **emailTemplateVersions** - 邮件模板版本
  - 用途: 邮件模板版本历史
  - 关键字段: templateId, version, content
  - 索引: templateId, version

- **emailTriggerConfigs** - 邮件触发配置
  - 用途: 邮件自动触发规则
  - 关键字段: triggerType, templateId, condition
  - 索引: triggerType, templateId

- **smtpConfigs** - SMTP 配置
  - 用途: 邮件服务器配置
  - 关键字段: host, port, username, password
  - 索引: tenantId, companyId

- **smsTemplates** - 短信模板
  - 用途: 短信发送模板
  - 关键字段: templateType, content
  - 索引: templateType, tenantId

- **smsSendRecords** - 短信发送记录
  - 用途: 短信发送历史
  - 关键字段: mobile, templateId, status
  - 索引: mobile, status, sentAt

- **smsVerificationCodes** - 短信验证码
  - 用途: 短信验证码记录
  - 关键字段: mobile, code, expireTime
  - 索引: mobile, code, expireTime

##### &#128272; 权限管理模块（3个表）
- **rolePermissions** - 角色权限
  - 用途: 角色权限关联
  - 关键字段: roleId, permissionId
  - 索引: roleId, permissionId

- **employeeExportPermissions** - 员工导出权限
  - 用途: 员工数据导出权限
  - 关键字段: employeeId, scope, status
  - 索引: employeeId, scope

- **employeePermissionLogs** - 员工权限日志
  - 用途: 员工权限变更日志
  - 关键字段: employeeId, action, permissionId
  - 索引: employeeId, action, createdAt

##### &#128203; 其他业务模块（29个表）
- **saasCompanies** - SaaS 公司
  - 用途: 租户公司信息
  - 索引: companyNo, tenantId

- **saasTenants** - SaaS 租户
  - 用途: 租户信息
  - 索引: tenantNo, status

- **saasUsers** - SaaS 用户
  - 用途: SaaS 平台用户
  - 索引: username, mobile, tenantId

- **saasOrders** - SaaS 订单
  - 用途: SaaS 订单
  - 索引: orderNo, tenantId, status

- **crmFollowRecords** - CRM 跟进记录
  - 用途: 客户跟进记录
  - 索引: targetId, ownerId, followDate

- **dataExports** - 数据导出记录
  - 用途: 数据导出历史
  - 索引: exportNo, userId, status

- **notificationSettings** - 通知设置
  - 用途: 用户通知偏好
  - 索引: userId, notificationType

- **globalPaymentConfigs** - 全局支付配置
  - 用途: 支付渠道配置
  - 索引: paymentType, isActive

- **globalPaymentRecords** - 全局支付记录
  - 用途: 支付流水
  - 索引: paymentNo, userId, status

- **loginPageConfigs** - 登录页配置
  - 用途: 自定义登录页
  - 索引: tenantId, companyId

- **platformConfig** - 平台配置
  - 用途: 平台全局配置
  - 索引: configKey

- **partners** - 合作伙伴
  - 用途: 合作伙伴信息
  - 索引: partnerNo, code

- **tenants** - 租户
  - 用途: 租户信息（新版本）
  - 索引: tenantNo, status

- **orders** - 订单（新版本）
  - 用途: 业务订单
  - 索引: orderNo, userId, status

- **payrollSheets** - 工资单
  - 用途: 批量工资单
  - 索引: sheetNo, tenantId, salaryPeriod

- **payrollDetails** - 工资单明细
  - 用途: 工资单详细项
  - 索引: sheetId, employeeId

- **marketProducts** - 市场产品
  - 用途: 市场上架产品
  - 索引: productNo, category, status

- **marketReviews** - 市场评论
  - 用途: 产品评价
  - 索引: productId, userId, rating

- **employeeFeedback** - 员工反馈
  - 用途: 员工反馈收集
  - 索引: feedbackNo, employeeId

- **companyApps** - 公司应用
  - 用途: 公司安装的应用
  - 索引: companyId, appId

- **appPermissions** - 应用权限
  - 用途: 应用权限配置
  - 索引: appId, permissionId

- **taxRateTables** - 税率表
  - 用途: 个税税率配置
  - 索引: incomeRange, taxRate

- **tenantTransactions** - 租户交易
  - 用途: 租户交易记录
  - 索引: transactionNo, tenantId, status

- **systemSettings** - 系统设置
  - 用途: 系统全局设置
  - 索引: settingKey

- **employeeSocialInsurance** - 员工社保
  - 用途: 员工社保信息
  - 索引: employeeId, insuranceType

- **salarySlipSends** - 工资条发送记录
  - 用途: 工资条发送历史
  - 索引: slipId, sendType, status

- **users** - 系统用户
  - 用途: 平台用户
  - 索引: username, email

---

## &#128279; 共同的表（26个）

以下表在两个 schema 中都存在，但应该只在 **Storage Schema** 中定义。

| 表名 | 所属模块 | 建议 |
|------|----------|------|
| saasCompanies | 租户管理 | 保留在 Storage |
| saasOrders | 订单管理 | 保留在 Storage |
| saasTenants | 租户管理 | 保留在 Storage |
| saasUsers | 用户管理 | 保留在 Storage |
| salaryConfigs | 薪资管理 | 保留在 Storage |
| salaryItemConfigs | 薪资管理 | 保留在 Storage |
| salarySlipDetails | 薪资管理 | 保留在 Storage |
| salarySlipSends | 薪资管理 | 保留在 Storage |
| salarySlips | 薪资管理 | 保留在 Storage |
| employeeSocialInsurance | 薪资管理 | 保留在 Storage |
| socialInsuranceConfigs | 薪资管理 | 保留在 Storage |
| taxRateTables | 薪资管理 | 保留在 Storage |
| tenantTransactions | 财务管理 | 保留在 Storage |
| systemSettings | 系统管理 | 保留在 Storage |
| salarySlipSends | 薪资管理 | 保留在 Storage |
| salarySlipDetails | 薪资管理 | 保留在 Storage |
| employeeFeedback | 人事管理 | 保留在 Storage |
| surveyVotes | 调查管理 | 保留在 Storage |
| emailTemplates | 邮件管理 | 保留在 Storage |
| notificationSettings | 通知管理 | 保留在 Storage |
| invitationRecords | 邀请管理 | 保留在 Storage |
| emailSendRecords | 邮件管理 | 保留在 Storage |
| companyApps | 应用管理 | 保留在 Storage |
| appPermissions | 权限管理 | 保留在 Storage |
| dataExports | 数据管理 | 保留在 Storage |
| globalPaymentConfigs | 支付管理 | 保留在 Storage |
| globalPaymentRecords | 支付管理 | 保留在 Storage |

**说明**：Infrastructure Schema 通过 import 引用这些表。

---

## &#128214; 使用指南

### 导入 Infrastructure Schema

```typescript
// 用于基础设施、外部集成相关功能
import {
  // API 监控
  apiAlertHistories,
  apiAlertRules,
  apiMonitorLogs,
  apiMonitorMetrics,

// 微信集成
  wechatMenus,
  wechatFans,
  wechatTemplates,

// 企业微信
  weworkUsers,
  weworkDepartments,

// 媒体管理
  mediaResources,
  mediaCategories,
} from '@/infrastructure/database/shared/schema';
```

### 导入 Storage Schema

```typescript
// 用于核心业务数据
import {
  // 用户管理
  users,
  employees,

// 薪资管理
  salarySlips,
  salaryConfigs,
  salaryItemConfigs,

// 企业管理
  saasCompanies,
  saasTenants,
  saasUsers,

// 邮件管理
  emailTemplates,
  emailSendRecords,

// 通信管理
  smsTemplates,
  smsSendRecords,
} from '@/storage/database/shared/schema';
```

### 导入共同表（推荐）

```typescript
// 优先从 Storage 导入
import {
  saasCompanies,
  saasTenants,
  saasUsers,
  salarySlips,
  emailTemplates,
} from '@/storage/database/shared/schema';
```

---

## &#127919; 使用场景

### 场景 1：开发微信公众号功能

```typescript
// ✅ 正确：使用 Infrastructure Schema
import { wechatFans, wechatMenus } from '@/infrastructure/database/shared/schema';

// ❌ 错误：Storage Schema 不包含微信表
import { wechatFans } from '@/storage/database/shared/schema';
```

### 场景 2：开发薪资管理功能

```typescript
// ✅ 正确：使用 Storage Schema
import { salarySlips, salaryConfigs } from '@/storage/database/shared/schema';

// ❌ 错误：Infrastructure Schema 不应该包含业务表
import { salarySlips } from '@/infrastructure/database/shared/schema';
```

### 场景 3：开发人事管理功能

```typescript
// ✅ 正确：使用 Storage Schema
import { employees, employeeFeedback } from '@/storage/database/shared/schema';
```

### 场景 4：开发 API 监控功能

```typescript
// ✅ 正确：使用 Infrastructure Schema
import { apiMonitorLogs, apiAlertRules } from '@/infrastructure/database/shared/schema';
```

---

## &#128295; 最佳实践

### 1. 按职责选择 Schema

| 功能模块 | 推荐Schema |
|----------|------------|
| 薪资、CRM、订单、用户 | Storage Schema |
| 微信、企业微信、小程序 | Infrastructure Schema |
| API 监控、媒体管理 | Infrastructure Schema |
| 邮件、短信、通知 | Storage Schema |

### 2. 避免循环引用

```typescript
// ❌ 错误：避免循环引用
// infrastructure/schema.ts
import { someTable } from '@/storage/database/shared/schema';

// storage/schema.ts
import { someTable } from '@/infrastructure/database/shared/schema';
```

### 3. 表注释规范

```typescript
/**
 * 员工工资条表
 *
 * 用途：存储员工每月的工资条信息
 * 关键索引：slipNo (唯一), employeeId, salaryPeriod
 * 关联表：employees (employeeId), salaryConfigs (configId)
 */
export const salarySlips = pgTable("salary_slips", {
  // ...
});
```

---

## &#128640; 未来优化方向

### 短期（1-2周）
1. ✅ 添加表注释和 JSDoc
2. ✅ 创建使用文档
3. &#128221; 统一表命名规范

### 中期（1-2月）
1. &#128260; 按模块拆分大型 schema 文件
2. &#128260; 添加数据库迁移脚本
3. &#128260; 优化索引设计

### 长期（3-6月）
1. &#128260; 引入 Prisma ORM（可选）
2. &#128260; 实现数据库读写分离
3. &#128260; 添加数据同步机制

---

## &#128222; 问题排查

### Q: 两个 schema 有重复的表怎么办？
A: 应该只在 Storage Schema 中定义，Infrastructure 通过 import 引用。

### Q: 如何判断使用哪个 schema？
A: 根据表的用途判断：基础设施用 Infrastructure，业务数据用 Storage。

### Q: 可以合并两个 schema 吗？
A: 技术上可以，但不推荐。职责分离更符合 DDD 思想。

### Q: 如何添加新表？
A: 根据表的用途选择对应的 schema 文件。

---

## &#128218; 相关文档

- [Schema 优化方案](../05-数据库/DATABASE_SCHEMA.md)
- [数据库迁移指南](../../src/db/migrations)
- [类型定义](../../src/types/common.ts)

---

## &#128221; 变更日志

| 日期 | 版本 | 变更说明 |
|------|------|----------|
| 2026-02-04 | 1.0.0 | 初始版本，创建 Schema 结构说明文档 |

---

**维护者**: 未来鸟FutureBird码巢企业服务引擎开发组
**最后更新**: 2026-02-04