📐 Admin 编码规范

Admin 是后台业务操作端，界面要以可读、稳定、密集、高效为优先。

🗂️ 文件组织

src/views/{Module}/api
src/views/{Module}/{feature}/index.vue
src/views/{Module}/{feature}/edit.vue
src/views/{Module}/{feature}/components

System 模块采用：

src/views/System

建议按模块开发页面，新模块可以按同样结构扩展，不要把所有页面继续堆在一个模块目录。

🔀 Vue 写法

• 优先使用 Composition API。
• 新页面使用 TypeScript。
• 页面状态使用 ref、reactive、computed 明确表达。
• 复杂表单默认值单独抽成函数，避免多个引用共享同一对象。
• 弹窗组件通过 props / emits 与父页面交互，不直接修改父组件状态。

📡 请求写法

• API 封装统一放在模块 api 目录。
• 请求 URL 不写 adminapi。
• 页面不直接调用 axios。
• 页面不重复处理通用错误提示。
• 删除、审核、清理缓存等危险操作需要确认弹窗。

🧿 路由与菜单

• 菜单组件路径必须相对 src/views，不带 .vue。
• 页面移动后同步更新后台菜单数据或 Seeder。
• 需要刷新菜单权限时调用 refreshUserAccess()。

🔘 权限按钮

按钮权限建议统一用 perms 判断。页面不要只靠“是否管理员”判断业务权限。

常见权限：

动作	说明
add	新增
edit	编辑
delete	删除
status	启用/禁用
detail/read	查看
export	导出
audit/handle	审核

🌟 表格与列表

• 查询表单字段要与 API 参数一致。
• 列表操作列保持可扫描，危险操作放二次确认。
• 金额、状态、时间等展示应统一格式。
• 列表刷新入口要清晰，保存后回到列表需刷新。

📚 表单

• 新增和编辑共用弹窗/页面时，要明确初始化逻辑。
• 编辑前先拉详情，不要直接复用列表行的残缺数据。
• 保存只提交后端需要的字段。
• 上传字段保存相对/完整 URL 由后端模型处理，前端不要手动截域名。

🏗️ 样式

• 后台页面避免营销式大面积装饰。
• 信息密集页面使用清晰分组、表格、筛选区和操作区。
• 复用全局布局组件和现有样式变量。
• 页面内样式尽量 scoped。
• 图标优先使用已有图标库和项目 SVG 图标。

✅ 构建检查

# 进入管理端项目目录
cd frontend/admin

# 执行 TypeScript 类型检查
npm run type-check

# 构建管理端生产产物
npm run build

提交前至少确认：

• 页面能通过动态路由加载。
• API URL 与后端路由一致。
• 登录失效、无权限、空列表、接口错误有合理状态。