frontendtechnical-spec

技术设计规则（前端）\n\n基础技术栈策略：采用基于 TypeScript 的 React 应用实现；架构模式应根据项目需求和规模选择。\n\n环境变量管理与安全\n\n环境变量管理：使用构建工具的环境变量系统，process.env 在浏览器环境不生效；通过配置层集中管理环境变量；用 TypeScript 实现类型安全；正确实现默认值设置和必填校验。示例中以 import.meta.env.API_URL 与 import.meta.env.APP_NAME 提供默认值。\n\n安全（客户端约束）：所有前端代码都是公开的，可在浏览器中看到；绝不在客户端存储机密，不在环境变量中放置 API 密钥、令牌或机密；不将 .env 文件纳入 Git（与后端一致）；禁止记录敏感信息（密码、令牌、个人数据）；错误信息中不含敏感信息。正确做法是后端管理机密，前端通过代理访问，例如请求 /api/data，由后端处理 API 密钥认证。\n\n架构设计\n\nReact 组件架构：强制使用函数组件，类组件已弃用；自定义 Hooks 用于逻辑复用与依赖注入；组件层级为 Atoms -> Molecules -> Organisms -> Templates -> Pages；组件通过 props 接收所有必要数据（Props 驱动）；测试、样式与相关文件与组件同目录存放（Co-location）。\n\n状态管理模式：本地状态用 useState 处理组件特有状态；Context API 用于跨组件树共享状态（主题、认证等）；自定义 Hooks 封装状态逻辑与副作用；服务端状态用 React Query 或 SWR 做 API 数据缓存。\n\n统一数据流原则\n\n客户端数据流：保持一致的单一事实来源——UI 状态放组件状态或 Context，服务端数据来自 API 响应并缓存在 React Query/SWR，表单数据用受控组件配合 React Hook Form。单向流动：数据通过 props 自上而下传递，API 响应 -> 状态 -> Props -> 渲染 -> UI；用户输入 -> 事件处理 -> 状态更新 -> 重新渲染。不可变更新：例如 setUsers(prev => [...prev, newUser])，避免直接 push 后赋值。\n\n数据流中的类型安全：前端到后端为 Props/State（类型保证）-> API 请求（序列化）；后端到前端为 API 响应（unknown）-> 类型守卫 -> 状态（类型保证）。示例中用 isUser 校验返回数据并抛出无效数据错误。\n\n构建与测试：根据 package.json 的 packageManager 字段选择运行命令。构建命令含 dev（开发服务器）、build（生产构建）、preview（预览生产构建）、type-check（类型检查，不输出）、check（Biome 的 lint 与格式化）。测试命令含 test、test:coverage、test:coverage:fresh（刷新缓存）、test:safe（带自动清理）、cleanup:processes（清理 Vitest 进程）。\n\n质量检查要求：实现完成后必须执行质量检查。阶段 1-3 为基础检查（check、build）；阶段 4-5 为测试与最终确认（test、test:coverage:fresh、check:all 综合检查）。覆盖要求：单元测试覆盖率不低于 60%；细分目标为 Atoms 70% 以上、Molecules 65% 以上、Organisms 60% 以上、自定义 Hooks 65% 以上、Utils 70% 以上。\n\n非功能要求：浏览器兼容 Chrome/Firefox/Safari/Edge 最近两个版本；主要页面渲染时间在 5 秒以内。