架构优化计划

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

---

# Schema 统一优化方案

## &#128202; 当前状态分析

### 问题描述

项目中存在两个独立的 schema 定义文件，导致：
1. 代码维护困难
2. 容易产生不一致
3. 引用路径混乱
4. 新人难以理解项目结构

### 文件对比

| 文件 | 大小 | 表数量 | 引用次数 |
|------|------|--------|----------|
| `src/infrastructure/database/shared/schema.ts` | 91KB | 53个 | 8次 |
| `src/storage/database/shared/schema.ts` | 69KB | 48个 | 30次 |

### 差异分析

#### Infrastructure 独有的表（23个）
```
apiAlertHistories        - API 警报历史
apiAlertRules           - API 警报规则
apiMonitorLogs          - API 监控日志
apiMonitorMetrics       - API 监控指标
channelConfigs          - 渠道配置
invitationRecords       - 邀请记录
marketActivationCodes   - 市场激活码
marketCategories        - 市场分类
marketOrders            - 市场订单
mediaCategories         - 媒体分类
mediaResources          - 媒体资源
miniprogramLoginLogs    - 小程序登录日志
miniprogramUsers        - 小程序用户
salaryNotifyRecords     - 薪资通知记录
salaryNotifyTemplates   - 薪资通知模板
surveyVotes             - 投票记录
userInstalledApps       - 用户安装的应用
wechatAutoReplies       - 微信自动回复
wechatFans              - 微信粉丝
wechatMenus             - 微信菜单
wechatMessages          - 微信消息
wechatReplies           - 微信回复
wechatTemplates         - 微信模板
weworkApps              - 企业应用
weworkAuthCorps         - 企业认证企业
weworkDepartments       - 企业部门
weworkUsers             - 企业用户
```

#### Storage 独有的表（22个）
```
emailGlobalVariables     - 邮件全局变量
emailTemplateVersions    - 邮件模板版本
emailTriggerConfigs      - 邮件触发配置
employeeExportPermissions - 员工导出权限
employeePermissionLogs   - 员工权限日志
employees               - 员工表
loginPageConfigs         - 登录页配置
marketReviews           - 市场评论
orders                  - 订单（新版本）
partners                - 合作伙伴
payrollDetails          - 工资单明细
payrollSheets           - 工资单
platformConfig          - 平台配置
rolePermissions         - 角色权限
smsQuota                - 短信配额
smsRechargeRecords      - 短信充值记录
smsSendRecords          - 短信发送记录
smsServiceConfig        - 短信服务配置
smsTemplates            - 短信模板
smsVerificationCodes    - 短信验证码
smtpConfigs             - SMTP 配置
tenants                 - 租户（新版本）
```

#### 共同的表（26个）
```
appPermissions
companyApps
crmFollowRecords
dataExports
emailSendRecords
emailTemplates
employeeFeedback
employeeSocialInsurance
globalPaymentConfigs
globalPaymentRecords
notificationSettings
saasCompanies
saasOrders
saasTenants
saasUsers
salaryConfigs
salaryItemConfigs
salarySlipDetails
salarySlipSends
salarySlips
socialInsuranceConfigs
systemSettings
taxRateTables
tenantTransactions
users
```

---

## &#127919; 优化方案

### 方案 A：统一到 Storage Schema（推荐）

#### 优点
- ✅ Storage schema 引用次数更多（30 vs 8）
- ✅ 文件更小（69KB vs 91KB）
- ✅ 包含更多现代业务表（SMS、Email 配置等）
- ✅ 影响范围较小

#### 执行步骤
1. 将 Infrastructure 独有的 23 个表迁移到 Storage schema
2. 更新所有引用 Infrastructure schema 的文件（8个）
3. 删除 Infrastructure schema 文件
4. 更新 Drizzle 配置
5. 验证构建和运行

#### 影响范围
- 需要修改的文件：约 8 个
- 需要迁移的表：23 个
- 预计工作量：2-3 小时

---

### 方案 B：按模块拆分

#### 优点
- ✅ 清晰的模块划分
- ✅ 易于管理大型项目
- ✅ 降低单文件复杂度

#### 执行步骤
1. 创建多个 schema 文件：
   - `schema-core.ts` - 核心表（users, tenants, companies 等）
   - `schema-salary.ts` - 薪资相关表
   - `schema-communication.ts` - 通信相关表（Email, SMS, WeChat）
   - `schema-crm.ts` - CRM 相关表
   - `schema-monitor.ts` - 监控相关表
2. 创建统一的索引文件 `index.ts`
3. 更新所有引用
4. 验证构建

#### 影响范围
- 需要修改的文件：约 40 个
- 需要创建的文件：6 个
- 预计工作量：4-6 小时

---

### 方案 C：保持现状 + 添加注释

#### 优点
- ✅ 无需修改代码
- ✅ 零风险

#### 缺点
- ❌ 没有解决实际问题
- ❌ 维护困难

---

## &#128161; 推荐方案：方案 A

### 理由
1. **影响最小**：只需修改 8 个文件
2. **效果显著**：统一后维护更容易
3. **风险可控**：Storage schema 已经被广泛使用
4. **可扩展**：未来如果需要再拆分，可以从统一的基础上进行

### 详细步骤

#### 第 1 步：备份当前文件
```bash
cp src/infrastructure/database/shared/schema.ts src/infrastructure/database/shared/schema.ts.backup
cp src/storage/database/shared/schema.ts src/storage/database/shared/schema.ts.backup
```

#### 第 2 步：迁移 Infrastructure 独有的表到 Storage
```typescript
// 在 src/storage/database/shared/schema.ts 末尾添加

// ==================== API 监控相关 ====================
export const apiAlertHistories = pgTable("api_alert_histories", { ... });
export const apiAlertRules = pgTable("api_alert_rules", { ... });
export const apiMonitorLogs = pgTable("api_monitor_logs", { ... });
export const apiMonitorMetrics = pgTable("api_monitor_metrics", { ... });

// ==================== 渠道相关 ====================
export const channelConfigs = pgTable("channel_configs", { ... });

// ==================== 市场相关 ====================
export const marketActivationCodes = pgTable("market_activation_codes", { ... });
export const marketCategories = pgTable("market_categories", { ... });
export const marketOrders = pgTable("market_orders", { ... });

// ==================== 媒体相关 ====================
export const mediaCategories = pgTable("media_categories", { ... });
export const mediaResources = pgTable("media_resources", { ... });

// ==================== 小程序相关 ====================
export const miniprogramLoginLogs = pgTable("miniprogram_login_logs", { ... });
export const miniprogramUsers = pgTable("miniprogram_users", { ... });

// ==================== 薪资通知相关 ====================
export const salaryNotifyRecords = pgTable("salary_notify_records", { ... });
export const salaryNotifyTemplates = pgTable("salary_notify_templates", { ... });

// ==================== 投票相关 ====================
export const surveyVotes = pgTable("survey_votes", { ... });

// ==================== 用户应用相关 ====================
export const userInstalledApps = pgTable("user_installed_apps", { ... });

// ==================== 微信相关 ====================
export const wechatAutoReplies = pgTable("wechat_auto_replies", { ... });
export const wechatFans = pgTable("wechat_fans", { ... });
export const wechatMenus = pgTable("wechat_menus", { ... });
export const wechatMessages = pgTable("wechat_messages", { ... });
export const wechatReplies = pgTable("wechat_replies", { ... });
export const wechatTemplates = pgTable("wechat_templates", { ... });

// ==================== 企业微信相关 ====================
export const weworkApps = pgTable("wework_apps", { ... });
export const weworkAuthCorps = pgTable("wework_auth_corps", { ... });
export const weworkDepartments = pgTable("wework_departments", { ... });
export const weworkUsers = pgTable("wework_users", { ... });
```

#### 第 3 步：更新引用路径
需要修改以下文件：
```
src/infrastructure/scheduler/index.ts
src/infrastructure/scheduler/salarySlipScheduler.ts
src/infrastructure/database/repositories/SalarySlipRepository.ts
src/infrastructure/database/repositories/SalarySlipSendRepository.ts
src/infrastructure/database/repositories/TenantRepository.ts
src/infrastructure/database/repositories/UserRepository.ts
src/infrastructure/database/repositories/CompanyRepository.ts
src/infrastructure/repositories/PaymentRepository.ts
```

将所有：
```typescript
import { ... } from '@/infrastructure/database/shared/schema';
```

改为：
```typescript
import { ... } from '@/storage/database/shared/schema';
```

#### 第 4 步：删除 Infrastructure schema
```bash
rm src/infrastructure/database/shared/schema.ts
rm src/infrastructure/database/shared/schema-legacy.ts
```

#### 第 5 步：更新 Drizzle 配置
```typescript
// drizzle.config.ts
export default defineConfig({
  schema: './src/storage/database/shared/schema.ts',  // 改为 storage
  out: './drizzle',
  driver: 'pg',
  dbCredentials: {
    connectionString: process.env.DATABASE_URL || 'postgresql://...',
  },
});
```

#### 第 6 步：验证
```bash
# 1. 检查类型
npx tsc --noEmit

# 2. 构建项目
npx next build

# 3. 运行测试
pnpm test  # 如果有的话
```

---

## ⚠️ 风险评估

| 风险 | 等级 | 缓解措施 |
|------|------|----------|
| 类型错误 | 中 | 先运行 tsc 检查 |
| 运行时错误 | 低 | 充分测试 |
| 数据库迁移 | 无 | 仅代码变更，不涉及数据库 |
| 破坏性变更 | 低 | 内容完全相同，只是路径改变 |

---

## &#128203; 检查清单

- [ ] 备份现有 schema 文件
- [ ] 迁移 Infrastructure 独有的表
- [ ] 更新所有引用路径（8 个文件）
- [ ] 删除 Infrastructure schema
- [ ] 更新 Drizzle 配置
- [ ] 运行类型检查
- [ ] 执行构建测试
- [ ] 验证应用运行
- [ ] 更新文档

---

## &#127919; 预期效果

- ✅ 统一 schema 定义
- ✅ 减少维护成本
- ✅ 提高代码清晰度
- ✅ 降低新人学习成本
- ✅ 为未来优化（如按模块拆分）打好基础

---

## &#128197; 执行时间表

- **准备阶段**：30 分钟（备份、分析）
- **执行阶段**：1-2 小时（迁移、修改）
- **测试阶段**：30 分钟（验证）
- **总计**：2-3 小时

---

## &#128640; 后续优化

完成 schema 统一后，可以考虑：
1. 添加 JSDoc 注释
2. 优化表结构
3. 添加索引优化
4. 实现按模块拆分（方案 B）