压缩摘要

> **文档版本**: v2.0.1
> **最后更新**: 2026-05-19
> **状态**: [最新] [核心文档]

# 压缩摘要

## 用户需求与目标
- 原始目标: 开发平台核心功能，按优先级逐个实现 P0-P3 任务
  - P0: 统一配置继承逻辑（已完成）
  - P1: 身份权限 + 应用体系（已完成）
  - P2: 合作伙伴完善（待开发）
  - P3: 分成机制 + 推广裂变（待开发）
- 当前目标: AI进化机制实现（P0-P3 已完成），提升开发准确性和效率
- 偏好:
  - 开发前必须执行预检，先搜向量知识库，再搜最佳实践
  - 发现正确方式后必须记录最佳实践

## 项目概览
- 概述: 基于Next.js的工资计算工具集，包含五险一金、个税、养老金、延迟退休四个独立计算器，以及薪税学院和渠道合作页面。新增统一用户身份管理体系和AI进化机制。
- 技术栈: Next.js 16, React 19, TypeScript 5, Tailwind CSS 4, shadcn/ui, Ant Design
- 编码规范: Airbnb

## 关键决策
- 采用统一配置表 `unified_configs` 管理所有配置，支持多级继承（app_instance > company > partner > platform）
- 配置类型包括：smtp, sms, wechat_mp, wechat_mini, storage, payment, theme, login_page, notification
- **数据库分区架构（CRITICAL）**: 主数据库采用 PostgreSQL 分区表架构，按 `company_id` 进行 LIST 分区
- **AI进化机制**: 通过开发前预检、错误自动学习、红线检测、决策追溯提升开发效率

---

## &#128680; 关键红线（CRITICAL）- 必须遵守

### ⛔ 数据库分区架构
**主数据库采用 PostgreSQL 分区表架构，按 `company_id` 进行 LIST 分区！**

| 已分区表 | 分区键 |
|----------|--------|
| `saas_users` | company_id |
| `salary_slips` | company_id |
| `saas_orders` | company_id |

**开发约束：**
1. **分区表主键必须包含分区列**: `PRIMARY KEY (company_id, id)`
2. **查询必须带 company_id 过滤** 以触发分区裁剪
3. **创建新分区表使用原生 SQL**，Drizzle ORM 不支持

### ⛔ 数据模型双轨问题
- **正确**: `src/storage/database/shared/schema.ts` + `*Manager.ts`
- **废弃**: `src/db/schema.ts`（禁止使用）

```typescript
// ✅ 正确 - 使用 Manager 模式
import { saasCompanyManager } from '@/storage/database/saasCompanyManager';
const company = await saasCompanyManager.getById(companyId);

// ❌ 错误 - 直接操作废弃的表
db.select().from(tenants);  // 表不存在！
```

### ⛔ 前端开发红线
1. **禁用 `any` 类型** - 必须明确类型定义
2. **客户端组件标记** - 使用 `'use client'` 指令
3. **禁止不纯函数** - `Math.random()`, `Date.now()` 必须在 `useEffect` 中使用
4. **禁止非法嵌套** - `<p>` 不能嵌套 `<div>`

### ⛔ API 开发规范
1. **统一响应格式**: `ApiResponse<T>` 类型
2. **Zod 验证请求**: 所有输入必须验证
3. **错误处理**: try-catch 包裹所有异步操作

---

## &#128027; 常见错误速查

| 错误 | 原因 | 解决方案 |
|------|------|----------|
| TS2802 迭代器展开报错 | ES2017 target 不支持 | 使用 `Array.from()` 替代 `[...]` |
| Hydration 错误 | 服务端/客户端不一致 | 使用 `useEffect` + `useState` |
| 分区表查询慢 | 未带 company_id | 添加 `where(eq(table.companyId, companyId))` |
| Manager 未定义 | 导入路径错误 | 从 `@/storage/database/*Manager` 导入 |

---

## ⚡ 快速命令

| 命令 | 用途 | 时机 |
|------|------|------|
| `pnpm precheck <关键词>` | 开发前预检 | **每次开发前必执行** |
| `pnpm best-practice:record` | 记录最佳实践 | 发现正确方式后 |
| `pnpm memory:sync` | 同步记忆到知识库 | 手动更新时 |
| `pnpm ai:search "<关键词>"` | 快速搜索知识库 | 查找信息时 |

---

## &#128193; 核心文件位置

| 类型 | 位置 |
|------|------|
| 数据模型 | `src/storage/database/shared/schema.ts` |
| Manager 类 | `src/storage/database/*Manager.ts` |
| API 路由 | `src/app/api/` |
| 业务服务 | `src/services/` |
| 开发规范 | `docs/00-开发规范/` |
| 最佳实践 | `docs/00-开发规范/最佳实践/` |

---

## &#128260; AI 自动化流程

### 开发前（自动触发）
```
用户说"开发/实现/修复XXX"
    ↓
AI 执行 pnpm precheck <关键词>
    ↓
阅读预检报告：向量知识库 → 最佳实践 → 红线 → 历史错误
    ↓
开始编码
```

### Git 提交时（自动触发）
| Hook | 触发条件 | 自动执行 |
|------|----------|----------|
| pre-commit | 每次提交 | `redline:check` 检测红线违规 |
| post-commit | `fix:` 前缀 | `learn:error` 学习错误模式 |
| post-commit | `decision:` 前缀 | `decision:record` 记录决策 |

### 定时任务
| 时间 | 任务 |
|------|------|
| 每小时 :05 | 记忆同步 + 清理 |
| 每天 23:55 | 记忆快照 |

---

## &#128203; 最近记忆（自动更新）

### 最近修复
- Git: 修复导出PDF多个问题

1. 修复分组图标显示"通知"问题
   - 添加getGroupKey函数从groupId提取分组名称
   - 修改groupIconMap查找逻辑使用分组名称而非完整groupId

2. 提高导出PDF清晰度
   - scale从1.5提高到2
   - 图片格式从JPEG改为PNG

3. 在PDF封面添加公司名称
   - 导出前获取租户公司信息
   - 在封面标题上方显示公司名称

4. 修复特殊分组渲染问题
   - 修改renderEmergencyContacts、renderFamilyInfo、renderWorkExperience、renderEducation、renderHobbies、renderSelfEvaluation函数
   - 使用完整的groupId参数而非硬编码简单格式
   - 确保所有分组内容正确渲染
- Git: 修复导出PDF时lab/lch颜色函数不支持的问题

html2canvas不支持现代CSS颜色函数(lab, lch, oklch)，扩展颜色检查范围并使用合适的默认颜色替代：
- 背景色默认#ffffff
- 边框色默认#e5e7eb
- 文字色默认#333333
- Git: 移除列表视图内部滚动条，避免双重滚动条

移除列表视图中内部容器的max-h-[500px] overflow-y-auto样式，只保留模态框本身的滚动条
- Git: 彻底修复对象渲染报错问题

问题根因：多处使用 `val || '-'` 模式，如果 val 是对象，`|| '-'` 不会返回 '-'（因为对象是 truthy 的），导致对象被直接渲染

修复内容：
1. renderExperienceDynamic函数：添加getFieldValue函数安全处理字段值
2. renderEducationDynamic函数：添加getFieldValue函数安全处理字段值
3. 动态列表视图：修复value字段的对象检查逻辑
- Git: 彻底修复对象渲染报错问题

修复以下位置的对象渲染问题：
1. renderListView函数：工作经历Table时间字段render函数添加对象检查
2. renderExperienceDynamic函数：修复exp.startDate和exp.endDate处理
3. renderEducationDynamic函数：修复edu.startDate和edu.endDate处理
4. renderExperience函数：添加safeStr辅助函数，修复所有字段处理
5. renderEducation函数：修复所有字段处理

问题根因：模板字符串直接使用对象属性，如果属性是对象会导致React报错"Objects are not valid as a React child"

### 最近功能

### 最近决策

---

## TODO
- P2: 合作伙伴完善（待开发）
- P3: 分成机制 + 推广裂变（待开发）