核心规范

# 核心规范

> **优先级**：&#128308; 最高 - 必须遵守

---

## 1. 禁止修改清单

以下文件/组件已标准化，**严禁修改**：

| 类型 | 文件路径 | 原因 |
|------|---------|------|
| 主导航栏 | `src/components/layouts/ProLayoutWrapper.tsx` | 全局复用，修改影响所有页面 |
| 全局Provider | `src/components/AntdAppProvider.tsx` | 已配置主题算法，修改破坏暗色模式 |
| 主题修复CSS | `src/app/dark-theme-fix.css` | 已统一配置，新增需评审 |
| 全局布局 | `src/app/layout.tsx` | 根布局，修改影响全局 |

**需要评审才能修改的文件**：

| 类型 | 文件路径 | 评审要求 |
|------|---------|---------|
| AdminLayout | `src/components/layouts/AdminLayout.tsx` | 需确认影响范围 |
| globals.css | `src/app/globals.css` | 需确认影响范围 |
| 主题上下文 | `src/contexts/ThemeContext.tsx` | 需确认影响范围 |

---

## 2. 主题配置原理

### 主题切换机制

```
┌─────────────────────────────────────────────┐
│  ThemeProvider                               │
│  src/contexts/ThemeContext.tsx               │
│  └→ useTheme() 获取当前主题状态              │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│  AntdAppProvider                             │
│  src/components/AntdAppProvider.tsx          │
│  └→ algorithm: darkAlgorithm/defaultAlgorithm│
│  └→ 动态生成组件样式（优先级最高）            │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│  dark-theme-fix.css                          │
│  src/app/dark-theme-fix.css                  │
│  └→ 微调样式（仅特殊场景）                    │
└─────────────────────────────────────────────┘
```

### ⚠️ 核心原则

**Ant Design 的 ConfigProvider 动态生成样式，优先级高于任何 CSS 覆盖！**

```tsx
// ❌ 错误：CSS覆盖无效（治标不治本）
.dark .ant-modal-content { background: #1f2937 !important; }

// ✅ 正确：Provider层面配置
algorithm: isDark ? antdTheme.darkAlgorithm : antdTheme.defaultAlgorithm
```

### 主题问题排查流程

```
遇到主题样式问题时，按以下顺序排查：

1. Provider 配置
   └→ ConfigProvider.algorithm 是否正确切换？
   └→ 检查文件：AntdAppProvider.tsx

2. 主题上下文
   └→ ThemeProvider 是否正确传递暗色状态？
   └→ 检查文件：ThemeContext.tsx

3. CSS 覆盖
   └→ 仅用于微调和特殊场景
   └→ 检查文件：dark-theme-fix.css

⚠️ 同一问题修了 3-5 次 CSS 都无效时，必须停下来重新分析根因！
```

---

## 3. 颜色规范

### 禁止硬编码颜色

```tsx
// ❌ 错误：硬编码颜色
<div className="bg-[#07C160] text-[#333]">
<div style={{ color: '#000', background: '#fff' }}>

// ✅ 正确：使用语义化变量
<div className="bg-primary text-muted-foreground">
<div className="bg-card text-card-foreground">
<div className="bg-background text-foreground">
```

### 禁止使用 Tailwind 原色

```tsx
// ❌ 错误：Tailwind 原色
<div className="bg-blue-500 text-gray-600 border-slate-200">

// ✅ 正确：语义化变量
<div className="bg-primary text-muted-foreground border-border">
```

### 暗色模式边框最佳实践

```tsx
// ❌ 错误：硬边框，视觉生硬
border: 1px solid #374151

// ✅ 正确：柔和内发光边框
box-shadow: 0 0 0 1px rgba(255, 255, 255, 0.06)

// ✅ 正确：渐变背景增强层次感
background: linear-gradient(180deg, #1f2937 0%, #1a1f2e 100%)
```

### 主题适配要求

**必须同时适配亮色/暗色主题**

```tsx
// ❌ 错误：只适配亮色
<div className="bg-white text-black">

// ✅ 正确：自动适配
<div className="bg-background text-foreground">
```

---

## 4. 日期组件国际化配置 &#128308;

### 问题现象

DatePicker、RangePicker 等日期选择器显示英文（Jan, Feb, Mon, Tue...）

### 根本原因

Ant Design 6 使用 **dayjs** 作为日期库：
- Ant Design 的 `ConfigProvider locale={zhCN}` 只影响组件文案
- **dayjs 默认是英文**，DatePicker 内部依赖 dayjs 的 locale

### 解决方案（已配置）

**全局配置文件**：`src/lib/dayjs-locale.ts`

```typescript
// src/lib/dayjs-locale.ts
import dayjs from 'dayjs';
import 'dayjs/locale/zh-cn';
import relativeTime from 'dayjs/plugin/relativeTime';
import weekday from 'dayjs/plugin/weekday';
// ...其他插件

dayjs.locale('zh-cn');
```

**在 Provider 中导入**：

```typescript
// src/components/AntdAppProvider.tsx
'use client';
import zhCN from 'antd/locale/zh_CN';
import '@/lib/dayjs-locale'; // &#128308; 必须导入

export default function AntdAppProvider({ children }) {
  return (
    <ConfigProvider locale={zhCN}>
      {children}
    </ConfigProvider>
  );
}
```

### ⚠️ 开发注意事项

| 规则 | 说明 |
|------|------|
| ✅ 直接使用 DatePicker | 已全局配置中文 |
| ❌ 不要局部设置 `dayjs.locale()` | 重复设置，可能导致问题 |
| ❌ 不要单独导入 `dayjs/locale/zh-cn` | 已全局配置 |

```tsx
// ❌ 错误：局部设置（不需要）
import dayjs from 'dayjs';
import 'dayjs/locale/zh-cn';
dayjs.locale('zh-cn');

// ✅ 正确：直接使用
import { DatePicker } from 'antd';
<DatePicker /> // 自动显示中文
```

---

## 5. 布局规范 &#128308;

### 禁止创建独立 layout.tsx

```tsx
// ❌ 错误：创建独立 layout.tsx
// src/app/tenant/users/layout.tsx
export default function Layout({ children }) {
  return <div>{children}</div>
}

// ✅ 正确：使用 AdminLayout
import { AdminLayout } from '@/components/layouts/AdminLayout'

export default function UsersPage() {
  return (
    <AdminLayout role="tenant">
      {/* 页面内容 */}
    </AdminLayout>
  )
}
```

### 新页面开发模板

**模板文件位置：** `src/components/templates/PageTemplate.tsx`

```tsx
"use client";

import { AdminLayout } from "@/components/layouts/AdminLayout";
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
import { Button } from "@/components/ui/button";

// &#128308; 根据页面位置选择正确的角色
const ROLE = "tenant" as const;  // platform | tenant | employee | agent

export default function NewPage() {
  return (
    <AdminLayout role={ROLE} username="管理员">
      <div className="space-y-6 p-6">
        {/* 页面标题 */}
        <div className="flex items-center justify-between">
          <h1 className="text-2xl font-bold text-foreground">页面标题</h1>
          <Button>操作按钮</Button>
        </div>

{/* 内容卡片 */}
        <Card>
          <CardHeader>
            <CardTitle>卡片标题</CardTitle>
          </CardHeader>
          <CardContent>
            <p className="text-muted-foreground">页面内容</p>
          </CardContent>
        </Card>
      </div>
    </AdminLayout>
  );
}
```

### 角色与目录对应表

| role 参数 | 目录位置 | 用户身份 | 示例 |
|-----------|----------|----------|------|
| `platform` | `src/app/admin/` | 超级管理员 | 后台管理、企业审核 |
| `tenant` | `src/app/tenant/` | 企业管理员 | 人事管理、工资发放 |
| `employee` | `src/app/employee/` | 员工 | 工资条查看、个人设置 |
| `agent` | `src/app/agent/` | 代理商 | 客户管理、佣金查看 |

### 页面结构规范

```
src/app/[角色]/
├── (dashboard)/          # 带侧边栏的仪表盘页面
│   └── feature/
│       └── page.tsx      # 使用 AdminLayout
├── feature/
│   └── page.tsx          # 使用 AdminLayout
└── layout.tsx            # ❌ 禁止创建！
```

### AdminLayout Props

| 属性 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `role` | `'platform' \| 'tenant' \| 'employee' \| 'agent'` | ✅ | 用户角色 |
| `username` | `string` | ❌ | 显示的用户名 |
| `userAvatar` | `string` | ❌ | 用户头像 URL |
| `children` | `React.ReactNode` | ✅ | 页面内容 |

---

## 6. 通用规范

### ✅ 允许的操作

| 操作 | 说明 |
|------|------|
| 直接使用组件 | 自动适配明暗主题 |
| 使用 `style={{ width: '100%' }}` | 控制宽度 |
| 使用 `placeholder` | 提示文字 |
| 使用 `disabled` | 禁用状态 |
| 使用 `size="small/large"` | 尺寸调整 |

### ❌ 禁止的操作

| 操作 | 原因 |
|------|------|
| `style={{ background: '#fff' }}` | 破坏暗色主题 |
| `className="bg-white"` | 破坏暗色主题 |
| `style={{ color: '#000' }}` | 破坏暗色主题 |
| `className="text-gray-500"` | 破坏暗色主题 |
| `style={{ borderColor: '#e5e5e5' }}` | 破坏暗色主题 |
| 自定义 Modal/Drawer 边框 | 已在 dark-theme-fix.css 配置 |

---

## 7. Tailwind 语义化类名速查表

| 用途 | 亮色模式 | 暗色模式 | 类名 |
|------|---------|---------|------|
| 主背景 | #fff | #0a0a0a | `bg-background` |
| 卡片背景 | #fff | #1f2937 | `bg-card` |
| 次要背景 | #f5f5f5 | #262626 | `bg-muted` |
| 主文字 | #0a0a0a | #fafafa | `text-foreground` |
| 次要文字 | #737373 | #a3a3a3 | `text-muted-foreground` |
| 边框 | #e5e5e5 | #262626 | `border-border` |
| 主色 | #07C160 | #07C160 | `bg-primary` / `text-primary` |