iotlcm/AGENTS.md

项目约束规范

xiuAdmin框架说明文档

先阅读 http://xiuadmin.com/sys/catalog.html

范围界定

1. 本仓库包含两部分代码：
   • 后端：基于 GoFrame v2 框架，存放于 server/ 目录
   • 前端：Vue + Vben Admin 技术栈，存放于 app/ 目录
2. GoFrame 项目专属规范仅适用于 server/ 下后端开发，或用户明确要求进行 GoFrame 开发的场景。
3. 仅修改前端代码时，不得套用 GoFrame 后端开发规范。
4. vue/ 目录下前端开发需遵循 Vben Admin 5.x 开发规范，同步沿用 vue/apps/web-antd 中已落地的 Ant Design Vue 页面风格。

GoFrame 后端开发规范

1. 控制器、服务、中间件、路由、配置、ORM、自动生成代码均严格遵循 GoFrame v2 官方编码惯例。
2. 禁止手动编辑自动生成的 DAO、DO、Entity 文件，统一使用项目内置代码生成流程更新。
3. 新增逻辑前优先复用项目现有服务、工具函数与通用设计模式，避免重复新增抽象层。
4. 数据库新增、更新操作必须使用自动生成的 DAO/DO 结构体；禁止将 g.Map、map[string]interface{} 作为 ORM 数据载体。
5. 后端新增业务报错统一使用 gerror 组件封装并返回错误信息。
6. 常规 ORM 操作交由 GoFrame 自动维护 created_at、updated_at、deleted_at 字段；逻辑删除统一调用 Delete() 方法。

前端开发规范

1. 必须使用中文进行对话以及编写文档。
2. 编写代码、修改文档或做业务判断前，必须先查询是否有可使用的本地 SKILL、项目文档、知识库、已有实现或现成工具，再决定行动方案。
3. 如果上下文过长、信息开始混乱或可能遗忘已确认内容，应提醒用户：建议压缩上下文。
4. 用户指定修改某个部分时，只处理指定范围；未经用户同意，不修改其他未指定部分。
5. 不要覆盖用户或其他工具已经产生的改动。若目标文件已有人工改动，应先理解并兼容现状。
6. 编写界面前必须先确认 Wot UI、uni-app 内置组件、项目现成组件和 UnoCSS 是否能满足需求；不能跳过这一步直接手搓样式或 UI。
7. 默认禁止手搓 CSS 和基础 UI 组件。只有在 UI 库、项目现成组件、UnoCSS 均无法满足，或存在明确平台兼容/业务封装需要时，才允许例外。
8. 使用例外时，必须在最终汇报中说明：为什么不能用 UnoCSS、为什么不能用 UI 库或现成组件、手写范围控制在哪里。
9. 若新增界面代码绕过 UnoCSS 或 UI 库且未说明例外依据，本轮任务视为未完成，必须先返工再汇报完成。

信息确认原则

1. 避免仅凭推测给出答案。回答或修改前，应优先基于以下来源确认信息：
   • 当前项目文件、已有实现、配置、测试结果；
   • 用户明确说明；
   • docs/README.md 及相关业务文档；
   • 管理平台后端和前端当前实现；
   • 本地 SKILL、项目文档、知识库或现成工具；
   • 官方文档或联网查询结果。
2. 当需求不明确、存在多种实现方式、影响范围较大、或可能破坏现有逻辑时，必须先向用户确认。
3. 当需求明确、范围清楚、风险较低时，可以直接执行，并在完成后说明处理内容和验证结果。
4. 涉及时效性信息，例如版本、法规、价格、接口文档、第三方库最新用法、新闻等，应优先使用官方来源或联网查询。

行为准则

1. 没有确切指令时，不得擅自替用户做高风险决策。
2. 在多轮对话中，已确认或用户未提出异议的内容必须保持一致。若用户变更需求，应明确记录并按新需求调整。
3. 需要参考案例或材料时，优先参考项目内类似实现；找不到或不确定时，再联网查询最新资料。
4. 对于多模块、高风险或探索性任务，应按模块推进，并在关键节点向用户确认。
5. 对于范围明确的常规任务，可以一次完成实现、校验和汇报。
6. 保持专业，坚持最佳实践。若用户需求明显不符合最佳实践，应说明风险并提供可选方案。
7. 当判断用户的方案、行动或前提存在明显问题时，以基于事实和最佳实践进行辩论为荣，以不分青红皂白附和用户为耻。
8. 保持客观、冷静、专业，避免过度奉承或无关情绪化表达。

系统菜单权限

1. 登录系统界面后，左侧菜单栏菜单都是动态路由菜单。菜单数据都放在 sys_menu表。菜单栏里有权限标识（不带前缀）。权限标识有相关的前缀。 "cpr:" // 角色权限码前缀+角色权限 "cpm:" // 菜单权限码前缀+菜单权限 "cpd:" // 部门权限码前缀+部门编码 "cpp:" // 岗位权限码前缀+岗位编码 "cpu:" // 用户权限码前缀+用户名 "cpc:current:user" // 当前登录用户默认权限
2. 如果登录的是超级管理员账号 admin，默认返回所有权限。
3. 如果登录的不是超级管理员账号：
   1. 登录用户取得用户的所有角色；
   2. 根据角色取得所有角色绑定的菜单；
   3. 获取菜单中的权限标识。

项目概述

iotlcm-app 是 IOTLCM 的用户侧小程序项目，定位为：

物联卡用户服务小程序 + 代理商轻量工作台

技术栈：

• uni-app
• Vue 3
• TypeScript
• Vite 5
• UnoCSS
• Wot UI v2
• unibest

输出端：

• H5
• 微信小程序
• APP