docs: 增加项目规范和邮件来源入口PRD

docs/import/reusable/frontend-development-guidelines.md

@@ -0,0 +1,234 @@
+# 通用前端开发规范
+
+## 1. 文档定位
+
+本文记录可跨项目复用的前端开发约定，适用于以页面展示、交互、状态管理、接口调用和用户体验为核心的前端项目。
+
+复制到新项目后，应根据实际技术栈、目录结构、启动命令、接口契约、设计系统和业务约束做项目级补充。当前项目的业务专属规则不应写入本文。
+
+## 2. 技术栈原则
+
+具体版本以项目内依赖文件为准，例如 `client/package.json`、锁文件和构建配置。
+
+通用要求：
+
+- 使用 TypeScript 时应开启严格类型检查。
+- 构建、Lint、类型检查、测试命令必须可重复执行。
+- 不引入与项目规模不匹配的大型模板或重型依赖。
+- UI 组件库、路由、状态管理和请求库应在项目级文档中明确。
+- 生成代码应进入专门目录，并标记为禁止手工修改。
+- 新项目必须明确 Node.js、包管理器、框架、语言、构建工具、Lint、类型检查和测试框架的兼容关系。
+- TypeScript 版本必须与类型检查、Lint 和框架工具链支持范围一致。
+- Vue 单文件组件项目应配置 `vue-tsc` 或等价工具覆盖 `.vue` 文件类型检查。
+
+## 3. 目录约定
+
+推荐目录：
+
+```text
+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. 配置规范
+
+常见公开配置示例：
+
+```text
+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. 测试与检查命令
+
+前端项目应至少提供：
+
+```bash
+cd client
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+如果项目不是 pnpm，应在项目级文档中替换为实际命令。
+
+聚焦开发时可运行：
+
+```bash
+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？
+- [ ] 涉及可视化结果时，是否做过浏览器、截图或响应式验证？
+- [ ] 是否运行了项目前端检查命令或说明了无法运行原因？