dm-design/web/merchant/CLAUDE.md

# 信息管理系统演示项目开发约束

## 🎯 项目定位

**这是一个纯演示项目**，重点在于展示清晰的布局设计和流畅的交互体验。项目不包含实际的业务功能，所有数据均为模拟数据，主要用于：
- 界面原型展示

## 🚨 核心架构约束（必须严格遵守）

### CSS内嵌原则 - 项目核心约束
**所有页面专用CSS必须内嵌到对应的HTML文件中**

#### ✅ 强制要求

1. **CSS内容集成** - 每个页面的专用样式必须写在页面HTML底部的`<style>`标签中
2. **禁止独立CSS文件** - 不允许在css/目录创建页面专用的CSS文件
3. **一文件原则** - 每个页面的HTML、CSS必须在同一个文件中
4. **即时加载** - 页面打开时样式立即生效，无延迟无闪烁

#### ❌ 严禁事项
- **禁止创建独立CSS文件** - 任何页面专用样式都不能单独存储为.css文件
- **禁止JavaScript动态加载CSS** - 不允许在JS中动态创建link标签加载CSS
- **禁止外部样式依赖** - 页面不能依赖外部CSS文件才能正常显示

### 文件分离原则
1. **HTML内容独立存储** - 所有页面内容存储在 `pages/` 目录的独立HTML文件中
2. **JavaScript功能独立存储** - 所有页面功能存储在 `js/` 目录的独立JS文件中
3. **CSS样式内嵌存储** - 所有页面样式内嵌在对应HTML文件的底部

## 📁 标准文件结构

```
merchant/
├── index.html              # 主框架页面
├── styles.css              # 全局通用样式（框架样式）
├── script.js               # 核心框架逻辑
├── js/                     # 页面功能模块目录
│   ├── feature-name.js        # 页面功能逻辑
│   └── ...
├── pages/                  # 页面内容目录
│   ├── feature-name.html      # 页面内容+内嵌CSS
│   └── ...
└── CLAUDE.md               # 本项目文档
```

## 🛠️ 开发流程规范

### 1. 新增页面的标准流程

#### Step 1: 创建HTML文件（必需）
```bash
# 在pages/目录创建页面文件
pages/feature-name.html
```

#### Step 2: HTML文件标准结构
```html
<!-- 页面内容区域 -->
<div class="page-content">
    <!-- 页面HTML结构 -->
    <h2>页面标题</h2>
    <!-- 其他页面内容 -->
</div>

<!-- 页面专用样式（必需） -->
<style>
/* 页面专用CSS样式 */
.page-content {
    /* 样式定义 */
}
/* 其他样式规则 */
</style>
```

#### Step 3: 创建JavaScript文件（可选）
```bash
# 在js/目录创建功能文件
js/feature-name.js
```

#### Step 4: JavaScript文件标准结构
```javascript
/**
 * 页面功能模块
 * 功能描述
 */

// 页面初始化函数（必需）
function initFeatureName() {
    console.log('页面已初始化');
    // 初始化逻辑，不包含CSS加载
}

// 功能函数
function someFunction() {
    // 功能实现
}

// 暴露到全局作用域供HTML调用
window.someFunction = someFunction;
```

### 2. CSS样式处理规范

#### 内嵌CSS标准写法
```html
<style>
/* 页面名称专用样式 */

/* 主要布局样式 */
.main-container {
    display: flex;
    flex-direction: column;
    gap: 20px;
}

/* 组件样式 */
.component-card {
    background: white;
    border-radius: 8px;
    padding: 20px;
    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

/* 交互样式 */
.btn:hover {
    background-color: #0056b3;
}

/* 响应式样式 */
@media (max-width: 768px) {
    .main-container {
        padding: 10px;
    }
}
</style>
```

#### CSS组织原则
1. **样式分组** - 按布局、组件、交互、响应式分组编写
2. **注释清晰** - 每个样式区块添加注释说明
3. **命名规范** - 使用语义化的CSS类名
4. **优先级管理** - 避免使用!important，合理利用CSS优先级

### 3. 页面集成规范

#### 动态加载页面内容
```javascript
// 正确的页面加载方式
async function loadPageHTML() {
    try {
        const response = await fetch('pages/feature-name.html');
        const htmlContent = await response.text();
        document.getElementById('container').innerHTML = htmlContent;
        // 页面加载完成，CSS自动生效
    } catch (error) {
        console.error('页面加载失败:', error);
    }
}
```

## 🎨 样式系统规范

### 全局样式职责
- `styles.css`: 仅包含框架级别的通用样式
  - 基础reset样式
  - 通用组件样式（按钮、表单等）
  - 布局框架样式
  - 公共工具类

### 页面样式职责
- 每个页面HTML中的`<style>`标签：
  - 该页面特有的布局样式
  - 页面内组件的专用样式
  - 页面内的交互效果样式
  - 该页面的响应式适配样式

### 样式冲突防范
1. **命名空间** - 为页面特有样式使用特殊前缀
2. **作用域控制** - 样式选择器尽量具体化
3. **优先级管理** - 页面样式优先级高于全局样式

## 📐 UI设计原则

### 布局设计
- **响应式优先** - 所有页面必须支持移动端适配
- **弹性布局** - 使用Flexbox和Grid进行布局
- **统一间距** - 使用统一的间距系统（8px基础单位）
- **清晰层次** - 通过间距、颜色、字体建立清晰的信息层次

### 色彩系统
```css
/* 主色调 */
--primary-color: #2563eb;      /* 主色 */
--primary-hover: #1d4ed8;      /* 主色悬停 */
--success-color: #10b981;      /* 成功色 */
--danger-color: #ef4444;       /* 危险色 */
--warning-color: #f59e0b;      /* 警告色 */

/* 中性色 */
--text-primary: #1f2937;       /* 主要文本 */
--text-secondary: #6b7280;     /* 次要文本 */
--border-color: #e5e7eb;       /* 边框色 */
--background-gray: #f9fafb;    /* 灰色背景 */
```

### 交互设计
- **视觉反馈** - 所有可交互元素必须有悬停效果
- **加载状态** - 异步操作需要显示加载状态
- **错误处理** - 操作失败要有明确的错误提示
- **操作确认** - 重要操作需要用户确认

## 📋 开发检查清单

### 新增页面前检查
- [ ] 是否按照HTML+CSS内嵌结构创建？
- [ ] 是否避免了创建独立的CSS文件？
- [ ] 页面样式是否完整内嵌在HTML底部？
- [ ] JavaScript中是否避免了CSS加载逻辑？
- [ ] 文件命名是否遵循kebab-case规范？
- [ ] 是否使用了中文界面文本？

## 🎪 演示项目特殊说明

### 数据处理
- **全部使用模拟数据** - 所有数据都在JavaScript中硬编码
- **无后端依赖** - 不需要任何服务器端支持
- **本地存储** - 可以使用localStorage模拟数据持久化

### 功能实现
- **视觉优先** - 重视视觉效果而非功能完整性
- **交互完整** - 确保用户操作有完整的反馈流程
- **流程演示** - 关键业务流程要能完整演示

### 扩展准备
- **模块化设计** - 每个页面独立，便于后续扩展
- **数据结构清晰** - 模拟数据结构接近真实业务数据
- **接口预留** - 为未来对接真实API预留接口

---

**记住：这是一个演示项目，重点在于清晰的视觉呈现和流畅的交互体验。CSS内嵌是本项目的核心架构原则，必须严格遵守。**