4.0 KiB
4.0 KiB
Admin Web Instructions
项目定位
- 本项目是虫虫出海内部运营与管理后台，仅服务平台员工。
- 当前范围包括工作台、客户管理、头程订单、内部用户、角色管理和菜单权限。
- 不在本项目承载企业客户自助流程、品牌官网、微信小程序、独立 APP 或仓库 PDA 作业。
技术基线
- 使用 Vue 3、TypeScript、Vite、Vue Router、Pinia、Element Plus、Axios 和 Lucide Vue。
- TypeScript 保持严格模式；不要使用
any绕过业务模型，优先从@chongchong/shared复用跨项目类型。 - 使用现有
@别名引用src/。保持 ES Module 和现有无分号代码风格。 - Element Plus 组件使用现有自动导入配置；
ref、computed等 Vue API 必须显式导入。src/auto-imports.d.ts与src/components.d.ts属于生成声明，不手工维护业务内容。 - 不更换框架、路由、状态管理、组件库或构建工具，除非任务明确要求并完成影响评估。
目录与职责
src/views/：路由级页面和业务编排；复杂、可复用的展示或交互下沉到组件。src/components/：无路由依赖的复用组件，输入输出应有明确类型。src/layouts/：应用壳层、导航和全局页面结构。src/router/：路由、标题、登录保护和权限元数据；新增模块时同步维护导航与路由配置。src/stores/：跨页面状态和业务动作；仅页面局部使用的状态留在组件内。src/api/：HTTP 客户端和接口适配；页面与组件不得散落创建 Axios 实例。VITE_API_BASE_URL控制浏览器请求前缀，API_PROXY_TARGET控制 Vite 开发代理上游；后者只由开发服务器读取，不进入客户端构建。新增或变更环境变量时同步更新.env.example，不得提交真实密钥或环境专属凭据。src/types/：后台专属类型；跨应用共享的稳定契约放到packages/shared。src/styles/：设计令牌和全局样式；优先复用现有--cc-*变量和组件样式。
业务与安全约束
- 菜单隐藏和前端路由守卫只改善体验，不能替代服务端鉴权。新增操作必须使用稳定的权限编码，并与 API 权限保持一致。
- 认证统一经过
src/stores/auth.ts和src/api/http.ts；不要在页面中复制令牌读写或手工拼装Authorization。 - 当前登录和部分数据仍可能是模拟实现。接入
services/api时删除对应模拟路径，不允许让生产逻辑静默回退到假数据。 - 删除、停用、改权限等高风险操作必须有明确确认、处理中、成功和失败反馈；失败时保留用户上下文，避免误以为已生效。
- 日志、提示和示例数据不得包含真实账号、令牌、客户隐私或生产数据。
UI 与交互
- 延续现有后台视觉体系：克制的企业级界面、清晰的信息层级和高密度但可扫描的数据展示。
- 优先使用 Element Plus 与现有复用组件；图标使用 Lucide，不用表情符号充当功能图标。
- 表格、筛选、抽屉和表单应按实际语义覆盖适用的加载、空数据、错误、禁用和无权限状态，不为不适用的组件机械增加状态。
- 保持键盘可操作、可见焦点、表单标签和足够的颜色对比度；不要只用颜色表达状态。
- 新页面至少适配现有 320px 最小宽度策略，并检查侧栏、表格、抽屉和表单在窄屏下的退化方式。
本地命令与质量门禁
在 apps/admin-web 目录执行：
pnpm install
pnpm dev
pnpm test
pnpm typecheck
pnpm build
- 日常变更至少运行
pnpm typecheck和受影响测试；交付前运行pnpm test与pnpm build，后者也会执行类型检查。 - 当前项目未声明 lint 脚本，不要声称 lint 已通过。若任务新增或变更质量脚本，应同时更新
package.json、README.md和本文件。 - 不手工修改
dist/或node_modules/；依赖变更必须同步当前项目的package.json与锁文件。