# Design: 云小调平台技术设计文档

## Context

"云小调"是一个劳动争议AI调解智能体Web应用，需要构建一个功能完整、UI精美、交互流畅的前端系统。项目当前处于初始化阶段，已有基础React脚手架，需要在此基础上完成9个核心业务页面的开发。

### 约束条件
- 必须严格按照document/原型/目录下的HTML原型文件进行UI实现（100%还原）
- 必须使用Ant Design 4.24.12作为UI框架（项目规则明确要求）
- 前期所有数据采用本地Mock提供，为后续API对接预留接口
- 开发语言使用JavaScript（项目现状）

### 利益相关方
- 调解员：主要用户，需要高效的案例检索和法条查询工具
- 基层综治工作人员：辅助用户，需要简单易用的操作界面
- 当事人：间接用户，通过计算器和协议预览了解调解结果
- 开发团队：需要清晰的代码结构和良好的可维护性

## Goals / Non-Goals

### Goals
1. **快速搭建MVP**：完成9个页面的基本功能实现，支持完整业务流程演示
2. **UI高度还原**：与原型HTML保持100%视觉一致，包括颜色、布局、交互效果
3. **组件化开发**：提取可复用组件，降低代码重复度
4. **Mock数据驱动**：通过服务层抽象，为后续API对接预留扩展点
5. **代码规范统一**：遵循React和AntD最佳实践，保持代码整洁

### Non-Goals
1. ❌ 不实现后端API和数据库
2. ❌ 不实现用户权限和登录认证系统
3. ❌ 不实现AI智能分析能力（仅预留UI入口）
4. ❌ 不考虑IE浏览器兼容性（仅支持现代浏览器）
5. ❌ 不实现移动端适配（聚焦PC端）

## Decisions

### Decision 1: 使用React + Ant Design技术栈
**选择**: React 19.2.3 + Ant Design 4.24.12 + React Router DOM 6.22.3

**理由**:
- React是当前主流的前端框架，组件化思想适合本项目
- Ant Design提供丰富的企业级组件，能快速实现原型效果
- React Router是React生态的标准路由方案

**替代方案考虑**:
- Vue + Element UI：团队React经验更丰富
- 纯HTML+jQuery：不利于后续维护和扩展

### Decision 2: 服务层抽象 + Mock数据
**选择**: 创建独立的services层，通过Promise包装Mock数据

**理由**:
- 服务层作为数据请求的统一入口，便于后续替换真实API
- Mock数据可以完整模拟业务场景，支持前端独立开发
- 通过300ms延迟模拟网络请求，测试加载状态

**实现方式**:
```javascript
// services/caseService.js
export const fetchCaseList = (params) => {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve(mockCaseList);
    }, 300);
  });
};
```

### Decision 3: 按功能模块组织组件
**选择**: 采用pages + components分层结构，components按功能模块划分

**理由**:
- 清晰的目录结构便于查找和维护
- 功能模块化便于团队协作开发
- 符合React项目的最佳实践

**目录结构**:
```
src/
├── pages/           # 页面级组件（路由组件）
│   ├── CaseSearchPage.jsx
│   ├── LawSearchPage.jsx
│   └── ...
├── components/      # 业务组件（按功能模块）
│   ├── case/        # 案例相关组件
│   ├── law/         # 法条相关组件
│   ├── tools/       # 工具类组件
│   └── common/      # 通用组件
├── services/        # 服务层
├── mocks/          # Mock数据
└── utils/          # 工具函数
```

### Decision 4: 使用AntD组件而非自定义样式
**选择**: 优先使用AntD原生组件，最小化自定义CSS

**理由**:
- AntD组件已经过大量项目验证，稳定可靠
- 保持视觉风格一致性
- 减少样式维护成本

**例外情况**:
- 原型HTML中的特殊渐变效果（Header背景）
- 特定的卡片hover效果
- 自定义的步骤条样式（调解看板）

### Decision 5: 采用函数组件 + Hooks
**选择**: 全部使用函数组件，通过useState、useEffect管理状态

**理由**:
- 函数组件是React官方推荐的现代写法
- Hooks提供简洁的状态管理和副作用处理
- 代码更简洁、易读

**示例模式**:
```javascript
const CaseSearchPage = () => {
  const [loading, setLoading] = useState(false);
  const [data, setData] = useState({ list: [], pageInfo: {} });
  
  useEffect(() => {
    loadData();
  }, []);
  
  // ...
};
```

## Risks / Trade-offs

### Risk 1: UI还原度挑战
**风险**: 原型HTML使用自定义CSS，AntD组件可能无法完全匹配视觉效果

**缓解措施**:
- 通过AntD的style props和className进行微调
- 对于关键视觉元素（如渐变Header），使用内联样式覆盖
- 定期与原型进行视觉比对

### Risk 2: 9个页面同步开发的一致性
**风险**: 多个页面同时开发，可能出现组件重复、样式不一致

**缓解措施**:
- 先完成3个样板页面（案例搜索、法条搜索、欠薪计算器）
- 提取通用组件（PaginationBar、Breadcrumb等）
- 建立组件复用指南文档

### Risk 3: Mock数据与真实API的差异
**风险**: Mock数据结构可能与后续真实API不匹配

**缓解措施**:
- 基于PRD文档设计Mock数据结构
- 服务层提供统一接口，降低后续改动成本
- Mock数据作为API接口文档参考

### Trade-off 1: 开发速度 vs 代码质量
**选择**: 优先保证核心功能实现，代码质量次之

**理由**: 当前处于MVP阶段，需要快速验证业务流程

**后续优化**: 在完成基本功能后，进行代码重构和优化

### Trade-off 2: 组件粒度
**选择**: 采用中等粒度的组件划分（页面 -> 区域 -> 元素）

**理由**: 平衡复用性和开发效率，避免过度抽象

**示例**: CaseSearchForm作为一个完整表单组件，而不是拆分成多个Field组件

## Migration Plan

不适用（新项目初始化，无迁移需求）

## Open Questions

1. **Q**: 案例详情页和法条详情页的Mock数据结构是否需要包含完整内容？
   **A**: 是的，需要包含PRD中定义的所有字段，以便完整演示业务流程。

2. **Q**: 是否需要实现响应式布局？
   **A**: 当前版本不需要，聚焦PC端（≥1366×768），移动端适配留待后续版本。

3. **Q**: 图片资源（如材料审核的缩略图）如何处理？
   **A**: 使用占位图片URL（如placeholder.com），或在public/目录放置几张示例图片。

4. **Q**: 是否需要单元测试？
   **A**: 当前版本不强制要求，优先完成功能实现，测试可在后续迭代中补充。

## Implementation Notes

### 开发顺序建议
1. **阶段1**: 基础设施（已完成✅）
   - App.js布局和路由
   - 通用组件（PaginationBar等）

2. **阶段2**: 核心业务模块（已完成✅）
   - 案例搜索
   - 法条搜索
   - 欠薪计算器

3. **阶段3**: 详情页和推荐（进行中🚧）
   - 案例详情
   - 法条详情
   - 类案推荐

4. **阶段4**: 文档管理
   - 材料审核
   - 协议编辑

5. **阶段5**: 调解看板（主页）
   - 集成所有模块

### 组件复用模式
- **搜索表单**: CaseSearchForm和LawSearchForm结构相似，但不强制抽象
- **列表卡片**: CaseCard和LawCard共享卡片样式，但内容差异较大
- **分页组件**: PaginationBar可被所有列表页复用

### 注意事项
- 所有时间格式统一使用：YYYY-MM-DD
- 金额格式统一使用：XX,XXX.XX 元
- 所有Mock数据的id字段采用字符串类型（如'case-001'）
- 路由路径统一使用小写+短横线（kebab-case）