编码标准

版本信息

版本	日期	描述	作者
2.6	2025-12-15	移除测试策略内容，更新RPC客户端最佳实践，修正$path()方法描述与实际代码不一致问题	James
2.5	2025-12-12	修正测试目录描述，从 `__tests__` 更新为 `tests`	Bob (Scrum Master)
2.4	2025-09-20	与主架构文档版本一致	Winston

现有标准合规性

代码风格: TypeScript严格模式，一致的缩进和命名
linting规则: 已配置ESLint，支持TypeScript和React
文档风格: 代码注释良好，架构文档完整
测试策略: 独立文档 testing-strategy.md 包含完整的测试规范和API模拟策略

架构原则

模块化设计: 基于monorepo的模块化架构，支持按需安装
类型安全: 全面使用TypeScript，确保编译时类型检查
依赖注入: 通过客户端管理器模式实现依赖注入，便于测试和替换
关注点分离: 业务逻辑、数据访问、UI呈现分层清晰
可扩展性: 支持单租户和多租户部署模式

关键编码规范

命名约定: 使用camelCase（变量、函数）、PascalCase（类、接口）、kebab-case（文件、目录）
代码组织: 遵循功能分组原则，相关代码放在同一目录
错误处理: 统一使用异常处理，避免静默失败
日志记录: 结构化日志，包含上下文信息和级别
配置管理: 环境变量和配置文件分离，支持不同环境配置
安全实践: 输入验证、输出编码、最小权限原则

RPC客户端架构最佳实践

客户端管理器模式

单例模式: 每个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等）
属性访问: 通过属性访问嵌套API端点（如client.provinces.$get()、client[':id'].$get()）
参数传递: 使用param对象传递路径参数，json对象传递请求体，query对象传递查询参数

跨UI包集成支持

统一模拟: 为简化测试复杂度，特别是跨UI包集成测试场景，测试时应统一模拟@d8d/shared-ui-components/utils/hc中的rpcClient函数
跨包优势: 统一模拟点支持多个UI包组件的API模拟，无需分别模拟各个客户端管理器
测试规范: 详细的API模拟策略见测试策略文档

架构一致性要求

统一入口: 所有API调用必须通过客户端管理器获取实例
错误处理: 客户端应提供统一的错误处理机制
配置管理: 支持不同环境的API基础URL配置
生命周期: 提供reset()方法用于测试或重新初始化