th-hotel-simple/docs/import/reusable/frontend-development-guidelines.md

通用前端开发规范

1. 文档定位

本文记录可跨项目复用的前端开发约定，适用于以页面展示、交互、状态管理、接口调用和用户体验为核心的前端项目。

复制到新项目后，应根据实际技术栈、目录结构、启动命令、接口契约、设计系统和业务约束做项目级补充。当前项目的业务专属规则不应写入本文。

2. 技术栈原则

具体版本以项目内依赖文件为准，例如 client/package.json、锁文件和构建配置。

通用要求：

• 使用 TypeScript 时应开启严格类型检查。
• 构建、Lint、类型检查、测试命令必须可重复执行。
• 不引入与项目规模不匹配的大型模板或重型依赖。
• UI 组件库、路由、状态管理和请求库应在项目级文档中明确。
• 生成代码应进入专门目录，并标记为禁止手工修改。
• 新项目必须明确 Node.js、包管理器、框架、语言、构建工具、Lint、类型检查和测试框架的兼容关系。
• TypeScript 版本必须与类型检查、Lint 和框架工具链支持范围一致。
• Vue 单文件组件项目应配置 vue-tsc 或等价工具覆盖 .vue 文件类型检查。

3. 目录约定

推荐目录：

client/src
├── components
│   └── common
├── composables
├── generated
├── i18n
│   └── locales
├── layouts
├── router
├── services
├── stores
├── styles
├── tests
├── types
└── views

目录规则：

• API 请求封装放入 src/services。
• 手写类型定义放入 src/types。
• OpenAPI 或其他工具生成代码放入 src/generated，禁止手工修改。
• 可复用组合逻辑放入 src/composables。
• 路由定义放入 src/router。
• 客户端状态放入 src/stores。
• i18n 入口和语言包放入 src/i18n。
• 页面级组件放入 src/views。
• 可复用组件放入 src/components。
• 通用布局放入 src/layouts。
• 全局样式和设计 token 放入 src/styles。

4. 组件规范

• 页面组件负责展示、交互和页面编排，不直接承载复杂业务规则。
• Props、Emits、响应式状态和服务返回值必须有明确类型。
• 避免在模板中写复杂业务逻辑，复杂逻辑放入 computed、composable 或服务层。
• 不在组件里直接拼接后端 URL，统一通过 services。
• 不在组件里直接访问浏览器全局存储保存业务事实。
• 不把中文或英文显示文案作为业务判断依据。
• 可复用组件应通过清晰 props 和 emits 对外暴露能力。
• 大组件应按职责拆分，避免一个页面文件同时承担数据请求、复杂表单、表格、弹窗和业务判断。

5. 状态管理规则

客户端状态和服务端数据要分开管理。

客户端状态适合保存：

• 当前用户上下文。
• 语言、主题和页面偏好。
• 轻量 UI 状态。
• 当前页面临时筛选条件或展开状态。

服务端数据适合通过请求缓存库或服务层管理：

• 列表、详情、统计、字典和远程配置。
• Mutation 完成后按 query key 或明确缓存规则失效。
• 不把服务端数据长期复制进客户端全局 Store。
• 不用前端状态绕过后端权限、状态机或业务校验。

6. API 请求规范

• 浏览器默认只调用本项目后端。
• 所有请求封装到 src/services。
• 服务函数返回明确 TypeScript 类型。
• 统一处理 JSON、错误结构、超时、取消请求和认证失效。
• 前端不直接调用数据库、对象存储、持有 Secret 的第三方系统或内部 Provider。
• 前端不发送后端 Secret、Provider API Key、数据库凭证或内部访问密钥。
• 调试页面如果需要触发受控后端能力，应由后端提供 debug-only 包装接口，Secret 保留在后端。

7. 国际化与展示文案

• 新增页面和组件不得把业务逻辑绑定到展示文案。
• 系统固定文案应使用稳定 i18n key。
• 后端应返回稳定业务代码和必要 labelKey，前端按 key 显示。
• 用户输入、外部来源原文和备注应保持原文，不做无依据翻译。
• 日期、时间、数字和货币按当前语言、时区和币种配置格式化。
• API 仍传递结构化原始值，不传本地化展示字符串作为业务参数。

如果项目不需要国际化，也应保留“业务判断不依赖展示文本”的规则。

8. 类型与业务代码

• TypeScript 类型应贴近后端 API 契约。
• 稳定业务代码使用 string union、枚举型常量或后端生成类型，避免散落 magic string。
• 动态字段使用稳定 fieldKey。
• 表单字段展示使用 labelKey 或 i18n key。
• 不用 label、中文标题或英文标题做字段标识。
• 接口字段变更时，同步更新 src/types、services、页面和测试。

9. UI 与交互规范

• UI 应优先服务真实工作流，不堆叠无意义装饰。
• 列表、详情、表单、弹窗、空状态、加载状态和错误状态必须完整。
• 重要操作必须有明确反馈。
• 危险操作必须有确认、权限或后端校验。
• 复杂表单应区分草稿、提交中、提交成功、提交失败和版本冲突。
• 涉及敏感信息时，应默认最小展示。
• 组件样式应遵守项目设计 token，避免随意写一次性颜色、间距和字号。
• 页面文本必须在移动端和桌面端都不溢出、不遮挡。

10. 前端安全规范

• 公开环境变量会暴露到浏览器构建产物，不能保存 Secret。
• 前端不得保存数据库密码、Provider API Key、访问令牌、内部重放密钥或生产凭证。
• 不在 LocalStorage、SessionStorage 或 URL 中保存敏感业务数据。
• 错误提示不展示 Authorization、Cookie、Token、原始敏感正文或附件 URL。
• 测试夹具不得使用真实客户、真实生产数据或真实支付信息。

11. 配置规范

常见公开配置示例：

VITE_API_BASE_URL=http://localhost:8080
VITE_APP_ENV=local
VITE_DEFAULT_LOCALE=zh-CN
VITE_ENABLE_MOCKS=false

规则：

• 公开配置可以放入前端环境变量。
• Secret 一律不进入前端环境变量。
• 生产需要运行时配置时，应由部署系统生成公开配置文件，例如 /app-config.json。
• 需要秘密的外部调用一律经后端代理或适配器。

12. 路由规范

• 新增业务路由前确认对应后端 API、权限边界和页面恢复能力。
• 详情页路由参数使用稳定 ID。
• 页面刷新后必须能通过后端详情接口恢复必要状态，不依赖内存临时状态。
• 未确认的业务入口不要提前硬编码到导航。
• 路由守卫只做访问控制和基础上下文检查，不承载复杂业务流程。

13. 表单规范

• 表单字段应来自稳定契约或明确的本地模型。
• 保存草稿时使用稳定字段名或 fieldKey。
• 不把显示文案作为提交字段名。
• 提交前前端可做基础格式校验，但最终业务校验在后端。
• 发生版本冲突时，应提示用户刷新或重新确认，不静默覆盖。
• 表单错误应能定位到字段或操作区域。

14. Agent 前端开发 Skill 使用原则

如果当前 agent 环境提供前端、设计、浏览器验证或可视化相关 skill，应按任务类型选择使用。Skill 是辅助能力，不替代项目技术栈、组件库、设计 token、接口契约和用户明确要求。

通用原则：

• 新增页面、复杂组件、交互流程或明显视觉调整前，应优先使用设计或前端类 skill 辅助确认方案。
• 重构已有页面视觉时，应优先使用现有项目审视和重构类 skill，避免破坏原有功能。
• 根据截图、设计稿或视觉参考还原页面时，应使用图像到代码或视觉分析类 skill。
• 设计 token、组件规范或样式体系调整时，应使用设计系统类 skill。
• 需要生成图片资产时，可使用图像生成类 skill，但不得替代项目内已有品牌资产或图标规范。
• 涉及可视化结果的前端改动，完成后应通过浏览器、截图或交互测试验证桌面端和移动端表现。
• Skill 建议不得直接引入新的 UI 框架、组件库、状态管理方案或重型依赖；如确有必要，必须先确认。
• 如果相关 skill 不可用，应按同等原则手动完成设计、实现和验证，并在交付说明中说明。

15. 测试与检查命令

前端项目应至少提供：

cd client
pnpm lint
pnpm typecheck
pnpm test
pnpm build

如果项目不是 pnpm，应在项目级文档中替换为实际命令。

聚焦开发时可运行：

cd client
pnpm test -- SomeSpecName.spec.ts

如果命令尚未配置或因环境问题无法运行，必须明确说明，不能假装通过。

16. Git 与协作流程

• 改动前说明目标、范围和将修改的文件。
• 每次只处理一个模块、一个页面或一个纵向切片。
• 不修改与当前任务无关的用户变更。
• 前后端接口变化前，先确认 API 契约和字段映射。
• 修改后运行项目已配置的检查命令。
• Git commit message 使用中文，清楚说明本次提交的业务或技术变更。

17. 前端提交前检查清单

• 是否只调用本项目后端或明确允许的公开服务？
• 是否没有把 Secret 放入前端环境变量、源码、测试或 URL？
• 新文案是否按项目约定处理？
• 是否避免用中文或英文显示文本做业务判断？
• API 请求是否放在 src/services？
• 手写类型是否放在 src/types？
• 可复用逻辑是否放在 src/composables？
• 服务端数据是否没有长期塞进客户端全局 Store？
• 是否没有手工修改 src/generated？
• 是否覆盖加载、空状态、错误、成功和权限不足等关键状态？
• 涉及 UI、交互或视觉变更时，是否使用或说明未使用合适的前端 / 设计 skill？
• 涉及可视化结果时，是否做过浏览器、截图或响应式验证？
• 是否运行了项目前端检查命令或说明了无法运行原因？