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文件（必需）

# 在pages/目录创建页面文件
pages/feature-name.html

Step 2: HTML文件标准结构

<!-- 页面内容区域 -->
<div class="page-content">
    <!-- 页面HTML结构 -->
    <h2>页面标题</h2>
    <!-- 其他页面内容 -->
</div>

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

Step 3: 创建JavaScript文件（可选）

# 在js/目录创建功能文件
js/feature-name.js

Step 4: JavaScript文件标准结构

/**
 * 页面功能模块
 * 功能描述
 */

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

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

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

2. CSS样式处理规范

内嵌CSS标准写法

<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. 页面集成规范

动态加载页面内容

// 正确的页面加载方式
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基础单位）
• 清晰层次 - 通过间距、颜色、字体建立清晰的信息层次

色彩系统

/* 主色调 */
--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内嵌是本项目的核心架构原则，必须严格遵守。