# global-rules

# =========================
# 1. 架构与代码规范（强约束）
# =========================

- 严格分层，不允许跨层调用：
  后端：Controller → Service → Mapper → Entity
  前端：pages → components → api → utils → store

- 命名统一：
  DB：snake_case
  Java：camelCase + PascalCase类
  Vue组件：PascalCase
  权限：module:feature:action（必须与sys_menu一致）

- 代码必须具备可维护性：
  - 不允许过度抽象
  - 不允许无需求扩展
  - 禁止 magic number（必须常量化）

- 注释规则：
  关键类/接口必须说明用途 + 入参出参 + 权限
  复杂逻辑必须说明业务规则

# =========================
# 2. 数据与接口契约（强一致）
# =========================

- 所有数据结构必须来源PRD，不得擅自修改字段/类型
- 接口必须先定义契约（request/response/error code）再实现
- 所有接口必须使用统一Response结构
- 所有异常必须标准化处理，不允许裸奔返回

# =========================
# 3. 安全与系统红线（禁止违规）
# =========================

- 禁止修改核心模块（权限/菜单/流程/字典/表单）除非明确PRD授权
- 禁止自动修改数据库结构（必须先输出SQL + 人工确认）
- 所有权限必须RBAC校验，不得存在无权限接口
- 多租户数据必须严格隔离，禁止越权查询

- 高危操作必须包含：
  二次确认 + 操作日志 + 事务控制 + 逻辑删除（禁止物理删除）

- 禁止自动执行终端命令（rm/drop/git push -f等必须人工确认）
- 禁止随意升级依赖或新增未确认依赖

# =========================
# 4. 交付闭环（必须执行）
# =========================

每个任务必须完整闭环：

1. 分析问题 / 明确需求
2. 输出修改方案
3. 代码实现（单文件优先）
4. 给出验证方式（test / API / UI）
5. 提交git（Conventional Commits）

- 必须生成测试用例（接口 / UI / 边界）
- 必须更新相关文档（API / PRD / README）
- 超过100行修改必须分段review

# =========================
# 5. Git与协作规范
# =========================

- 禁止在main分支开发
- 必须feature分支开发
- 必须pull最新代码后再修改
- 冲突必须人工确认解决方案，不得自动合并
- commit必须符合：
  feat|fix|docs|refactor(module): description + PRD引用
  
# =========================
# 6. 禁止占位与假功能
# =========================
- 禁止任何“占位UI / 敬请期待 / 未实现入口”
- 未实现功能 = 不渲染入口（菜单/按钮必须真实可执行）
- 所有交互必须可追溯到真实 API / Controller / IPC

# =========================
# 7. 配置与运行时单一真相（SSOT）
# =========================
- 禁止前后端/运行时双轨配置（UI/DB/Runtime必须同源）
- 所有可配置项必须具备三件套：
  1) 启动参数
  2) 注入策略
  3) 页面回读验证
- 同一功能面只能有一种实现路径（禁止 JS + Native 双实现并存）

# =========================
# 8. 禁止静默失败（P0）
# =========================
- 所有 async 必须：
  - log error
  - 用户可见错误提示
  - 可观测指标记录
- 禁止空 catch / 吞异常
- 桌面端与打包态必须分别验证（dev ≠ production）

# =========================
# 9. 接口与数据库契约优先（P0）
# =========================
- 必须先定义接口契约（request/response/error code）再编码
- 数据结构必须来自PRD，不得随意新增字段
- JSON字段类型必须统一（禁止同字段多类型）
- DB变更必须通过 migration，不允许代码先行
- 查询必须分页，禁止 findAll 默认全表

# =========================
# 10. 前端交互稳定性规则（P1）
# =========================
- 弹窗/下拉必须显式控制生命周期（禁止纯CSS状态）
- 所有操作必须具备：
  loading状态 + 防重复提交 + 成功/失败反馈
- 列表操作禁止全量刷新（必须局部更新）
- 编辑/授权类操作必须回显数据

# =========================
# 11. 禁止重复实现与碎片化开发（P1）
# =========================
- 新功能必须先检查是否已有类似Service/Util
- 相似能力必须合并实现，不允许重复造轮子
- 禁止一个功能拆成多个无意义Step往返开发

# =========================
# 12. 运行时与系统稳定性（P1）
# =========================
- 所有系统必须具备明确状态机（store/lifecycle）
- 启动/退出必须避免异步竞态（必须可追踪）
- 探针/重试必须有限制（禁止无限重试/全量扫描）

# =========================
# 13. 环境与依赖显式管理（P1）
# =========================
- 所有依赖必须显式声明（main/renderer/preload分离）
- 禁止隐式依赖或运行时报错依赖缺失
- 打包态必须有 fail-fast 检查

# =========================
# 14. 交付闭环（P1）
# =========================
每个功能必须完成：
1. 实现
2. 冒烟测试
3. 构建验证
4. 至少1条E2E路径
5. commit记录

- 禁止只开发不验证
- 禁止 dev 成功但 prod 未验证

# =========================
# 15. DB与迁移安全（P0）
# =========================
- 所有结构变更必须 migration
- 必须支持空库双跑验证
- 禁止代码引用未存在字段
- 唯一键变更必须明确 delete → flush → insert

# =========================
# 16. 返工驱动规则（关键）
# =========================
- 同一问题修复 ≥2次 → 必须升级为架构规则
- ≥3次 → 必须进入 global-rules
- 重复bug必须转为设计问题处理，而不是补丁修复

# =========================
# 18. Playwright page.evaluate（P0）
# =========================
- **禁止**向 `page.evaluate` / `waitForFunction` / `locator.evaluate` 传入经 tsx/esbuild 编译的**函数引用**；构建器会注入 `__name` 等 helper，浏览器上下文未定义 → `ReferenceError: __name is not defined`
- 浏览器脚本须为**纯字符串**（如 `workers/rpa/kernel/browser-scripts.ts`、`workers/rpa/fix-place/browser-eval-scripts.ts`），写法 `(arg) => { ... }`，调用 `page.evaluate(script, arg)`
- 新增 RPA 浏览器逻辑时先加字符串脚本 + 单测断言不含 `__name`

# =========================
# 17.# 核心响应协议：深度思考优先

在回答任何技术问题、编写代码或调试前，**必须**严格执行以下思维流程，禁止直接给出直觉性答案：

1.  **需求解构**：先分析用户真实意图、技术栈约束及潜在边界条件，而非仅看字面问题。
2.  **方案推演**：在内部评估至少2种可行路径，权衡复杂度、性能与可维护性，选择最优解。
3.  **风险预判**：主动识别当前方案可能的坑点（如并发安全、内存泄漏、API兼容性），并提前规避。
4.  **验证闭环**：代码生成后需在逻辑上自洽检查，确保无语法错误、符合最佳实践且能真正解决问题。

> ⚠️ 执行要求：以上思考过程应内化于推理阶段，无需向用户展示冗长的思考标签。最终输出必须是经过验证的、可直接落地的精准答案。若问题模糊，先追问关键信息再作答，绝不猜测。
# =========================