Parcourir la source

📝 docs(architecture): 更新编码标准文档,移除测试策略内容

- 重命名文档标题为"编码标准",移除测试策略相关内容
- 更新RPC客户端架构最佳实践,与统一模拟规范保持一致
- 添加架构原则和关键编码规范章节
- 文档版本更新至2.6

🤖 Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
yourname il y a 1 mois
Parent
commit
c4478b44a1
1 fichiers modifiés avec 40 ajouts et 19 suppressions
  1. 40 19
      docs/architecture/coding-standards.md

+ 40 - 19
docs/architecture/coding-standards.md

@@ -1,33 +1,54 @@
-# 编码标准和测试策略
+# 编码标准
 
 ## 版本信息
 | 版本 | 日期 | 描述 | 作者 |
 |------|------|------|------|
+| 2.6 | 2025-12-15 | 移除测试策略内容,更新RPC客户端最佳实践,与测试策略文档保持一致 | James |
 | 2.5 | 2025-12-12 | 修正测试目录描述,从 `__tests__` 更新为 `tests` | Bob (Scrum Master) |
 | 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |
 
 ## 现有标准合规性
 - **代码风格**: TypeScript严格模式,一致的缩进和命名
 - **linting规则**: 已配置ESLint,支持TypeScript和React
-- **测试模式**: 完整的测试框架已配置(Vitest + Testing Library + Playwright)
-- **文档风格**: 代码注释良好,测试策略文档完整
+- **文档风格**: 代码注释良好,架构文档完整
+- **测试策略**: 独立文档 `testing-strategy.md` 包含完整的测试规范和API模拟策略
 
-## 增强特定标准
-- **测试框架**: 使用Vitest + Testing Library + hono/testing + Playwright
-- **测试位置**: `tests` 文件夹与源码并列(例如:`packages/goods-module-mt/tests/` 与 `packages/goods-module-mt/src/` 并列)
-- **覆盖率目标**: 核心业务逻辑 > 80%
-- **测试类型**: 单元测试、集成测试、E2E测试
+## 架构原则
+- **模块化设计**: 基于monorepo的模块化架构,支持按需安装
+- **类型安全**: 全面使用TypeScript,确保编译时类型检查
+- **依赖注入**: 通过客户端管理器模式实现依赖注入,便于测试和替换
+- **关注点分离**: 业务逻辑、数据访问、UI呈现分层清晰
+- **可扩展性**: 支持单租户和多租户部署模式
 
-## 关键集成规则
-- **现有API兼容性**: 确保测试不破坏现有API契约
-- **数据库集成**: 使用测试数据库,避免污染生产数据
-- **错误处理**: 测试各种错误场景和边界条件
-- **日志一致性**: 测试日志格式和错误信息
+## 关键编码规范
+- **命名约定**: 使用camelCase(变量、函数)、PascalCase(类、接口)、kebab-case(文件、目录)
+- **代码组织**: 遵循功能分组原则,相关代码放在同一目录
+- **错误处理**: 统一使用异常处理,避免静默失败
+- **日志记录**: 结构化日志,包含上下文信息和级别
+- **配置管理**: 环境变量和配置文件分离,支持不同环境配置
+- **安全实践**: 输入验证、输出编码、最小权限原则
 
 ## RPC客户端架构最佳实践
-- **单例模式**: 使用单例模式的客户端管理器确保全局唯一的客户端实例
-- **延迟初始化**: 客户端应在首次使用时初始化,避免过早创建
-- **类型安全**: 使用Hono的InferRequestType和InferResponseType确保类型一致性
-- **组件调用规范**: 在组件中应使用`clientManager.get().api.$method`而非直接使用导出的客户端实例
-- **测试Mock**: 在测试中正确mock客户端管理器的get()方法调用链
-- **架构一致性**: 确保所有API调用都通过客户端管理器获取实例,保持架构一致性
+
+### 客户端管理器模式
+- **单例模式**: 每个UI包使用单例模式的客户端管理器(如`AdvertisementClientManager`、`UserClientManager`)确保全局唯一的客户端实例
+- **延迟初始化**: 客户端应在首次使用时初始化,避免过早创建,通过`get()`方法实现懒加载
+- **统一基础**: 所有客户端管理器使用`@d8d/shared-ui-components`包中的`rpcClient`函数创建Hono RPC客户端
+- **类型安全**: 使用Hono的InferRequestType和InferResponseType确保API调用的类型一致性
+- **组件调用规范**: 在组件中应使用`clientManager.get().api.$method`而非直接使用导出的客户端实例,保持架构一致性
+
+### API调用结构
+- **Hono风格**: 生成的客户端使用Hono风格的方法调用(`index.$get`、`index.$post`、`:id.$put`、`:id.$delete`等)
+- **嵌套路径**: 支持`$path()`方法访问嵌套API端点(如`client.$path('api/areas').$get()`)
+- **参数传递**: 使用`param`对象传递路径参数,`json`对象传递请求体,`query`对象传递查询参数
+
+### 跨UI包集成支持
+- **统一模拟**: 为简化测试复杂度,特别是跨UI包集成测试场景,测试时应统一模拟`@d8d/shared-ui-components/utils/hc`中的`rpcClient`函数
+- **跨包优势**: 统一模拟点支持多个UI包组件的API模拟,无需分别模拟各个客户端管理器
+- **测试规范**: 详细的API模拟策略见[测试策略文档](./testing-strategy.md#api模拟规范)
+
+### 架构一致性要求
+- **统一入口**: 所有API调用必须通过客户端管理器获取实例
+- **错误处理**: 客户端应提供统一的错误处理机制
+- **配置管理**: 支持不同环境的API基础URL配置
+- **生命周期**: 提供`reset()`方法用于测试或重新初始化