编码标准和测试策略

版本信息

版本	日期	描述	作者
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包开发规范（基于史诗008经验总结）
Mini UI包开发: 必须遵循Mini UI包开发规范（基于史诗011和017经验总结）

增强特定标准

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

关键集成规则

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

UI包开发提示

必须遵循的规范

开发UI包时，必须参考并遵循UI包开发规范，该规范基于史诗008（AllIn UI模块移植）的经验总结。

关键检查点（基于史诗008经验）

API路径映射验证：开发前必须验证故事中的API路径映射与实际后端路由定义的一致性
类型推断最佳实践：必须使用RPC推断类型，而不是直接导入schema类型
测试选择器优化：必须为关键交互元素添加data-testid属性
表单组件模式：必须使用条件渲染两个独立的Form组件
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包开发规范，该规范基于史诗011（用人方小程序）和史诗017（人才小程序）的实施经验总结。

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

1. Taro小程序布局规范

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

正确示例：

// ✅ 正确: 使用 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 等

正确示例：

// ✅ 正确: 使用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

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

coding-standards.md 5.8 KB Cronologia Originale

编码标准和测试策略

版本信息

现有标准合规性

增强特定标准

关键集成规则

UI包开发提示

必须遵循的规范

关键检查点（基于史诗008经验）

常见错误避免

参考实现

Mini UI包开发提示

必须遵循的规范

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

1. Taro小程序布局规范

2. 图标使用规范

3. Navbar导航栏集成规范

4. 测试框架选择

5. API客户端模式

常见错误避免

参考实现

coding-standards.md 5.8 KB

Cronologia Originale