# 编码标准和测试策略

## 版本信息
| 版本 | 日期 | 描述 | 作者 |
|------|------|------|------|
| 2.5 | 2025-12-26 | 添加Mini UI包开发规范章节 | Bob (Scrum Master) |
| 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |

## 现有标准合规性
- **代码风格**: TypeScript严格模式，一致的缩进和命名
- **linting规则**: 已配置ESLint，支持TypeScript和React
- **测试模式**: 完整的测试框架已配置（Vitest + Testing Library + Playwright）
- **文档风格**: 代码注释良好，测试策略文档完整
- **UI包开发**: 必须遵循[UI包开发规范](./ui-package-standards.md)（基于史诗008经验总结）
- **Mini UI包开发**: 必须遵循[Mini UI包开发规范](./mini-ui-package-standards.md)（基于史诗011和017经验总结）

## 增强特定标准
- **测试框架**: 使用Vitest + Testing Library + hono/testing + Playwright
- **测试位置**: `tests/` 文件夹与源码并列
- **覆盖率目标**: 核心业务逻辑 > 80%
- **测试类型**: 单元测试、集成测试、E2E测试

## 关键集成规则
- **现有API兼容性**: 确保测试不破坏现有API契约
- **数据库集成**: 使用测试数据库，避免污染生产数据
- **错误处理**: 测试各种错误场景和边界条件
- **日志一致性**: 测试日志格式和错误信息

## UI包开发提示

### 必须遵循的规范
开发UI包时，**必须**参考并遵循[UI包开发规范](./ui-package-standards.md)，该规范基于史诗008（AllIn UI模块移植）的经验总结。

### 关键检查点（基于史诗008经验）
1. **API路径映射验证**：开发前必须验证故事中的API路径映射与实际后端路由定义的一致性
2. **类型推断最佳实践**：必须使用RPC推断类型，而不是直接导入schema类型
3. **测试选择器优化**：必须为关键交互元素添加`data-testid`属性
4. **表单组件模式**：必须使用条件渲染两个独立的Form组件
5. **API调用一致性**：必须根据实际路由名称修正API调用

### 常见错误避免
- ❌ 不要直接导入schema类型（可能导致Date/string类型不匹配）
- ❌ 不要使用`getByText()`查找可能重复的文本元素
- ❌ 不要在单个Form组件上动态切换props
- ❌ 不要使用故事中描述但实际不存在的路由名称

### 参考实现
- 广告管理UI包：`packages/advertisement-management-ui`
- 平台管理UI包：`allin-packages/platform-management-ui`
- 渠道管理UI包：`allin-packages/channel-management-ui`（史诗008.002）

## Mini UI包开发提示

### 必须遵循的规范
开发Mini UI包（Taro小程序UI包）时，**必须**参考并遵循[Mini UI包开发规范](./mini-ui-package-standards.md)，该规范基于史诗011（用人方小程序）和史诗017（人才小程序）的实施经验总结。

### 关键检查点（基于史诗011和017经验）

#### 1. Taro小程序布局规范
- **View组件默认横向布局**：View容器内的子元素默认是横向布局（`flex-row`），必须显式添加 `flex flex-col` 类才能实现垂直布局
- **Text组件默认内联显示**：Text组件默认是内联显示（类似span），需要使用`flex flex-col`强制垂直排列

**正确示例**：
```typescript
// ✅ 正确: 使用 flex flex-col 实现垂直布局
<View className="flex flex-col">
  <Text>姓名: 张三</Text>
  <Text>性别: 男</Text>
  <Text>年龄: 35</Text>
</View>

// ❌ 错误: 缺少 flex flex-col，子元素会横向排列
<View>
  <Text>姓名: 张三</Text>
  <Text>性别: 男</Text>
  <Text>年龄: 35</Text>
</View>
```

#### 2. 图标使用规范
- **必须使用Heroicons图标类**：不要使用emoji或文本符号
- **图标类命名格式**：`i-heroicons-{icon-name}-{size}-{style}`
- **必须添加尺寸类**：如 `w-5 h-5`、`text-lg` 等

**正确示例**：
```typescript
// ✅ 正确: 使用Heroicons图标类
<View className="i-heroicons-chevron-left-20-solid w-5 h-5 text-gray-600" />
<View className="i-heroicons-user-20-solid w-6 h-6 text-blue-500" />
<View className="i-heroicons-bell-20-solid w-4 h-4 text-gray-400" />

// ❌ 错误: 使用emoji
<Text>🔔</Text>
<Text>👤</Text>
<View>←</View>
```

**常用图标**：
- `chevron-left-20-solid` - 左箭头（返回按钮）
- `user-20-solid` - 用户
- `bell-20-solid` - 通知铃
- `document-text-20-solid` - 文档
- `chart-bar-20-solid` - 图表
- `calendar-20-solid` - 日历
- `phone-20-solid` - 电话
- `lock-closed-20-solid` - 锁
- `qr-code-20-solid` - 二维码

#### 3. Navbar导航栏集成规范
- **TabBar页面（一级）**：使用Navbar无返回按钮（`leftIcon=""`、`leftText=""`）
- **非TabBar页面（二级）**：使用Navbar带返回按钮（`leftIcon="i-heroicons-chevron-left-20-solid"`）
- **Navbar组件来源**：`@d8d/mini-shared-ui-components/components/navbar`

#### 4. 测试框架选择
- **Mini项目使用Jest**：不是Vitest（与Web应用不同）
- **测试配置文件**：`jest.config.cjs`
- **测试工具包**：`@d8d/mini-testing-utils`
- **测试规范**：必须遵循[Mini UI包测试规范](./mini-ui-testing-standards.md)（基于故事017.003实施经验）

#### 5. API客户端模式
- **每个UI包独立管理**：每个Mini UI包包含自己的API客户端和RPC类型
- **使用相对路径导入**：UI包内部必须使用相对路径，不要使用别名
- **RPC推断类型**：必须使用RPC推断类型，而不是直接导入schema类型

### 常见错误避免
- ❌ 不要忘记添加 `flex flex-col` 实现垂直布局
- ❌ 不要使用emoji代替Heroicons图标
- ❌ 不要忘记为图标添加尺寸类（`w-5 h-5`、`text-lg`等）
- ❌ 不要在Mini UI包内部导入中使用别名（`@/`、`~/`等）
- ❌ 不要使用Vitest作为Mini项目的测试框架（应使用Jest）

### 参考实现
- 用人方小程序UI包：`mini-ui-packages/yongren-dashboard-ui`
- 人才小程序UI包：`mini-ui-packages/rencai-dashboard-ui`
- 共享组件包：`mini-ui-packages/mini-shared-ui-components`