任务索引
我要做某件事，该翻哪一页？ 本页按「你要动的那件事」组织，不按概念组织。
用法：在下面的表里找到你那件事，点「去哪」直接跳到那一页的那一节——每页的「怎么扩展」节都是可照做的步骤，不是散文。第三列写的是最容易漏的一步，它通常不报错，所以要提前知道。
本页不含答案，只含路标
每一行的内容都在目标页里。本页存在的唯一理由是：50 页的手册，靠侧栏从上往下找太慢，而「我要加一个 Agent 工具」这种问题应该有唯一入口。
如果你要找的东西本页没有，用站内搜索（Ctrl+K）；找到了却发现本页没收录，那是本页的漏项，请补一行。
先跑起来
| 我要… | 去哪 | 最容易漏的一步 |
|---|---|---|
| 第一次把三仓跑起来 | 后端 + Web：环境准备与启动｜移动端：移动端环境准备与启动 | 🔴 两份全量 SQL dump 都不能单独用，必须「导专业版快照 → 按依赖顺序跑 update/ 增量 → 重启后端」；顺序写在 2026-10-24-system-nav-node.sql 头部 |
| 确认后端连的是哪个库 | 环境准备与启动 | 本地库名是 ainb-professional-init，不是上游的 ruoyi-vue-pro；旧库还留在本机，拿它生成清单会得到过期结果 |
| 不起真实登录态调后端 | 环境准备与启动 | 🔴 三个 profile 现在全是 mock-enable: false，代码路径一行没删——开关一开，Bearer test1 就是超级管理员（坑位索引 A1） |
| 判断一段代码是上游的还是本项目写的 | 仓库结构与改名约定 | 🔴 后端 ainb/ 有 3384 个文件的 blame 停在「项目初始化」那一刀，但不是全都查不到——752 个文件 2026-10-18 后已正常提交（坑位索引 F5）。@author 是唯一可靠信号：「芋道源码」636 个文件、「走进新时代」975 个，本项目自己写的更多 |
| 找一条已知问题的解决办法 | 坑位索引 · 移动端坑位 | 上线前只过两页索引表里标 🔴 的条目，也够挡掉大部分事故 |
后端
| 我要… | 去哪 | 最容易漏的一步 |
|---|---|---|
| 加一个接口（完整五件套） | 接口约定与 CRUD 骨架 · 怎么扩展 | 岗位代码在 dept 包不在 post 包——生成器按「一业务一包」生成，别拿它去"纠正"已有文件的位置 |
| 加一个完整的菜单功能（建表→授权） | 新增一个菜单功能端到端 | 🔴 用超管自测测不出任何权限问题，super_admin 走短路（坑位索引 D3） |
| 用代码生成器起一个新功能 | 路线 B：代码生成器 · infra 域 | 🔴 「上级菜单」不填，产物 SQL 里会是字面量 ${table.parentMenuId}（坑位索引 E1）；生成器不会写你的工程，只有 preview 和 download |
| 新建一张业务表 | 数据库约定与表总览 · 怎么扩展 | 🔴 漏 tenant_id 又没登记 ignore-tables，SQL 层照样拼 WHERE tenant_id = ?；在计量/日志这类「异常被吞」的路径上表现是整条记录静默丢失（坑位索引 C1） |
| 让一个字段能被「清空」 | 坑位索引 C4 | updateById 默认 NOT_NULL，传 null 的字段根本不进 UPDATE 语句；必须在 DO 上写 @TableField(updateStrategy = FieldStrategy.ALWAYS) |
| 新增一个业务模块 / starter | 后端架构与模块依赖 · 怎么扩展 | 模块是扁平 jar，没有上游的 -api / -biz 拆分；starter 登记走 AutoConfiguration.imports，不是 spring.factories |
| 加一个后端 DB 单测 | 测试规范 · 加一个后端 DB 单测 | 🔴 新表要同步补 create_tables.sql 与 clean.sql，否则报错信息会指向 schema-locations、把你带偏（坑位索引 C3） |
| 给 agent / ai 模块加 DB 单测 | 测试规范 · 给 agent / ai 模块加 DB 单测 | 这两个模块没有 application-unit-test.yaml，要先补它 + 两份 SQL 三件套 |
| 写一条「纪律守卫」测试 | 测试规范 · 写一条源码扫描守卫 | 代码里不允许出现 文件:行号 引用，已有守卫扫源码原文（后端 CommentLineRefBanTest、前端 commentLineRefBan.spec.ts） |
| 打包与部署 | 构建与部署 | 🔴 jar 里硬编码 spring.profiles.active: local，忘传参数会连本地库（B1）；仓库自带的三套部署脚本都跑不通（B3） |
Web 管理端
| 我要… | 去哪 | 最容易漏的一步 |
|---|---|---|
| 加一个新页面 | 前端工程结构 · 怎么扩展 | 🔴 component 字符串匹配不上就是整页白屏且零报错，findIndex 返回 -1 没人检查（坑位索引 D1） |
| 加一个新接口调用 | axios 封装与 API 约定 · 怎么扩展 | 不需要注册也不需要改配置；但 upload 返回的是整个响应对象，不是解包后的 data |
| 给一个按钮加权限 | 路由与权限机制 · 怎么扩展 | v-hasPermi 的值必须是数组，传字符串会 throw；前端放行 ≠ 后端放行，两边要一起加（坑位索引 F1） |
| 加一个全局组件 / hook | 通用组件与 hooks · 怎么扩展 | 🔴 auto-*.d.ts 只由 dev server 生成，新组件后要先跑一次 pnpm dev 再 ts:check（坑位索引 F2） |
| 加一个字典类型 | 通用组件与 hooks · 怎么扩展 | 后端建类型 + 前端补 DICT_TYPE 枚举，两边都要动；字典登录后一次性拉取并缓存 |
| 让菜单图标在离线环境显示 | 坑位索引 D5 | 只有 ep: / fa: / fa-solid: / svg-icon: 四个前缀是本地图标，其它要联网拉 Iconify |
| 改了菜单但界面没变 | 坑位索引 D2 | 直接 INSERT INTO system_menu 绕过了 Service 层，@CacheEvict 不会触发；前端的 roleRouters 也要清 |
| 隐藏一个菜单就以为禁止访问了 | 坑位索引 D4 | visible = 0 只影响侧边栏渲染，路由照样注册；status/visible 都是 0 表示开启 |
| 构建前端生产包 | 构建与部署 | 🔴 .env.local 纳入 git 跟踪，pnpm build:prod 时它一定参与合并，会盖掉 .env（坑位索引 B2） |
低代码平台
先看低代码平台开发总览分清五个域的边界——它们是运行时解释，不是代码生成，上游 yudao 一个都没有。
| 我要… | 去哪 | 最容易漏的一步 |
|---|---|---|
| 加一个新的低代码域（比如「报表」） | 总览 · 我要加一个新的低代码域 | 五个域的边界与依赖要先看清，否则新域会和既有域职责重叠 |
| 建表 / 改表（受治理的那种） | 数据模型（开发视角） | DDL 与表结构变更不可回滚；保留字、标识符白名单、框架表黑名单是硬编码不可关的 |
| 加一种字段类型 | 数据模型 · 新增一种字段类型 | 配置项与 DataModelApi 的消费者要一起看——消费者全在 agent 模块 |
| 把一段 SQL 变成可调用接口 | 数据接口 | 编程式鉴权不用 @PreAuthorize；三条防注入是硬约束 |
| 加一种接口类型 / 参数类型 / 内置变量 | 数据接口 · 怎么扩展 | 三个扩展点各自独立，别混 |
| 加一个表单的动作权限 | 总览 · 我要给表单加一个动作权限 · 表单设计后端 | 发布时才登记资源，改了权限动作要重新发布才生效 |
| 加一条提交期的服务端校验 | 表单运行时与扩展点 | 这是全平台最长的一条链路，先看它怎么从 component 字符串走到浏览器 |
| 加一个自研控件 | 总览 · 我要加一个自研控件 · 自研控件开发 | 🔴 src/lib/form-create、src/lib/form-designer 是源码副本、要求与上游零 diff，不要修改或"顺手优化" |
| 加一种单据编号占位符 | 取号管理（开发视角） | 并发不重号靠的是预占与核销，create 有三次撞号重试 |
| 加一种门户卡片 | 门户 | infra_portal 是可配置首页，与上游写死的静态工作台不是一回事 |
权限体系
这一域的缺陷形态不是报错
而是「配了、保存成功了、发布成功了、界面上一切正常，但就是没生效」。所以诊断与排错那一页的「症状 → 根因 → 去哪查 → 报错吗」总表比机制页更值得先读。只读一页的话读它。
权限体系总览 · 怎么扩展 里已经有一张同构的速查表，本节是它的超集（补了跨域的行）。
| 我要… | 去哪 | 最容易漏的一步 |
|---|---|---|
| 排查「配了不生效」 | 诊断与排错 | 🔴 用超管查会看到假的「无权限」，诊断页自己在这一点上有口径分歧 |
| 给一张原生表开行级权限 | 行过滤规则 · 让一张原生表进入行级权限 · 诊断与排错 | 🔴 那张表必须先登记为数据集，否则规则一次都不会被调用 |
| 加一条行级规则模板 | 行过滤规则 · 加一个内置模板 | 🔴 expandBuiltInTemplate ↔ RuleTemplateMetaRegistry.paramSpec 两处要同步 |
| 加一个语义槽位 / 内置变量 | 行过滤规则 · 加一个语义槽位 | 变量的 VARIABLE_METADATA 不更新，规则编辑器下拉里就看不到它 |
| 加一种授权主体类型 | 授权与决策引擎 · 加一种主体类型 | 🔴 9 步顺序不可逆：先加枚举再改闭包，反过来会让存量行算不出来 |
| 加一个动作（动词） | 授权与决策引擎 · 加一个动作 | 🔴 VERB_TO_ACTION 漏一项会让权限串排序错乱（实测 39 行错分） |
| 加一种资源类型 | 权限资源（开发视角） · 加一种资源类型 | default_effect 的出厂值决定「零配置时放行还是拒绝」，想清楚再定 |
改一个资源的 default_effect | 权限资源（开发视角） | 资源页是只读的，界面上改不了 |
| 加一个授权界面 / 动作码 | 前端授权页开发 | 🔴 前端 GRANT_ACTION_OPTIONS 与后端枚举没有任何自动对齐，要手改两边 |
| 理解「塌缩」 | 权限资源 → 授权与决策引擎 → 诊断与排错 | 三处必须连着看：写库侧、判定侧、检测侧是同一件事 |
Agent 模块
enlev-module-agent 是全仓唯一从第一行起完全自研的业务模块，上游没有任何参照物。依赖方向被架构测试钉住：agent → {ai, infra, bpm, system} 单向。
| 我要… | 去哪 | 最容易漏的一步 |
|---|---|---|
| 加一个内置工具（有 Java 代码） | 工具体系 · 加一个内置工具 | 🔴 会写库的工具要先读安全与提示注入防护的「污点与只读闸」，否则会被 V 系列规则或沙箱挡下来，而你会以为是自己代码写错了 |
| 加一个自定义工具（无 Java 代码） | 工具体系 · 加一个自定义工具 | 风险等级与只读闸是网关侧判定的，工具内校验只在网关结构上表达不了时才用 |
| 加一种工作流节点类型 | 工作流引擎 · 加一种节点类型 | 「有执行器」与「合成子图」是两条不同路径，先确认你要哪种 |
| 加一种触发器 | 工作流引擎 · 加一种触发器 | 发布 ≠ 生效，两侧定义不一样 |
| 加一条发布前的 V 系列校验规则 | Plan 预览确认与 HITL · 加一条 V 规则 | 🔴 号段权威在 WorkflowDslValidator 的方法注释里，不在类 javadoc；下一个可用号是 V36，V17 结构上不存在 |
| 加一种变更类型 / HITL 节点 | Plan 预览确认与 HITL · 怎么扩展 | Plan 草稿卡、变更清单、HITL 闸口是三样长得像但完全不同的东西 |
| 加一种 SSE 事件类型 | ReAct 循环与流式对话（后端）+ 前端流式（SSE）（前端） | 🔴 两套事件词表要同步；前端 onerror 必须 throw，否则断连不重试 |
| 加第五条聊天路由 | ReAct 循环与流式对话 · 加第五条聊天路由 | 现有四条是互斥的，先确认你的场景不属于任何一条 |
| 调 maxSteps / 温度 / 截断上限 | ReAct 循环与流式对话 | 工作流侧的 maxSteps 可被节点 config 覆盖，聊天侧不能 |
| 加一个污点源 / 注入模式 | 安全与提示注入防护 | 🔴 POST /admin-api/agent/webhook/{path} 是全模块唯一的 @PermitAll 端点，动它之前先读这一页 |
| 加一个计量场景 / 配额维度 / 模型单价 | 计量与配额 · 怎么扩展 | 这套东西没有计数器、没有锁、也没有 Redis——别按那个假设去改 |
| 加一张表 / 一个 Controller / 一条架构禁令 | 架构总览 · 怎么扩展 | 「声明值 vs 生效值」是全模块共用纪律，架构测试会钉住它 |
| 排查一次对话跑歪了 | ReAct 循环与流式对话（先看它走的是四条路由里的哪一条）→ 计量与配额（那次调用有没有记账、记在哪张表） | 断连提示带执行编号就是为了这种排查，别把它当成噪音 |
上游域（system / infra / bpm / ai）
这四页讲的都是上游模块，但定制方式完全不同。每页开头都有一张实测规模表，先看它，分清哪些是不能乱动的底座。
| 我要… | 去哪 | 最容易漏的一步 |
|---|---|---|
| 加一个 system 子域（如新通知渠道） | system 域开发 · 加一个子域 | 配置文件是复制粘贴传播的，prod 那份连「本地环境」注释都是从 local 抄来的（坑位索引 A4） |
| 加一个权限资源点 | system 域开发 · 加一个权限资源点 | 行权限求值有 fail-open 面，先分清底座与自研的边界 |
| 给表单运行时加一个读取出口 | infra 域开发 | infra 同时承载上游运维面与低代码引擎，23 个 Controller / 218 个端点，先定位到子域 |
| 加一个候选人策略 | bpm 域开发 · 加一个候选人策略 | 🔴 pom 的 <description> 说「基于 Flowable 6」而实际依赖是 8.0.0，照上游文档改会踩空 |
| 加一种 formType | bpm 域开发 · 加一种 formType | bpm 的坑几乎全长在「上游原有的类被本项目改过」这件事上 |
| 接一个流程状态监听器 | bpm 域开发 · 接一个流程状态监听器 | 🔴 事件监听器是同步的，绝不能慢、不能远程调用；不要用 @Order 抢顺序；自己做幂等 |
| 接一个新厂商模型平台 | ai 域开发 · 接一个新厂商平台 | 🔴 这是全平台所有厂商调用的唯一出口，改坏了影响面是全站 |
| 换向量存储 | ai 域开发 · 换向量存储 | 🔴 SimpleVectorStore 的落盘文件名会互相覆盖 |
| 改 AI 菜单 / 权限 | ai 域开发 | 🔴 ai 的应用面菜单已被软删，但代码、端点、Web 页面全都还在——失效方向是 fail-open |
移动端
别按 Web 端的习惯套这一组
移动端与 Web 端共用同一套后端、同一套权限体系，但工程约定几乎处处不同：只能 pnpm、pages.json 是产物不是源码、组件走 easycom 自动注册、不走 Vite proxy（直连后端 :48080）、没有单测。第一小时撞的墙基本都在这几条上。
| 我要… | 去哪 | 最容易漏的一步 |
|---|---|---|
| 第一次把移动端跑起来 | 移动端环境准备与启动 | 🔴 不能跳过 pnpm install：pages.json / manifest.json 由 init-baseFiles 与插件生成，仓库里没有，缺了报的是「找不到模块」而不是「请先安装」 |
| 确认真的连上了后端 | 移动端环境准备与启动 · 怎么验证跑通了 | 四步要验到「登录进去、工作台有卡片」为止；只看到登录页不算通（它不请求后端也能渲染） |
| 加一个移动端页面 | 工程结构与约定式路由 · 怎么扩展 | 🔴 别手改 src/pages.json——它是产物，会被下次生成覆盖。改各页的 definePage()，且改完必须重启 dev server（M8） |
| 写一个列表页 | 移动端页面开发范式 · 一个列表页的完整最小样例 | flex-1 要配 min-h-0，否则 z-paging 高度塌陷（M1）；@query 里必须有 catch，否则永久转圈（M3） |
| 加一个 API 调用 | 请求封装与登录态 · 怎么扩展 | 业务码非 0 走的是 reject，不是 resolve 一个带 error 的对象；漏 catch 会变成未捕获 rejection |
| 让一个页面出现在工作台 | 服务端驱动导航 · 怎么扩展 | 🔴 菜单不在前端写死：要在 Web 仓「App菜单」里建 system_nav_node 节点，route 必须命中 pages.json 里真实存在的路由，否则点了只提示「页面不存在」（M5） |
| 把一张表单发布到 App 端 | 在线表单在移动端 · 怎么扩展 | 55 个 supported 控件里移动端只渲染 43 个，缺 12 个；缺的会显式降级而不是崩，所以「不报错」不等于「渲染对了」 |
加一个 yd-* 组件 | 工程结构与约定式路由 · 怎么扩展 | easycom 规则是 ^yd-(.*) → @/components/yudao-ui/yd-$1/yd-$1.vue；那个目录名刻意不改（M22） |
| 改品牌色 / 加一个颜色 | 移动端页面开发范式 · 怎么扩展 | 「令牌 → CSS 变量 → UnoCSS」三层不许跳过；pnpm check:color 会扫硬编码色 |
| 出一个 H5 / 小程序 / App 包 | 多端构建与发布 · 发布流程 | 🔴 非 H5 端连 pnpm dev:app 的 command 都是 build（只有 mode 是 development）——判断「是不是生产」只能问 mode / NODE_ENV，问 command 会得到相反的答案 |
| 上传微信小程序 | 多端构建与发布 · 发布流程 | 🔴 默认版本号读的是 package.json 的 yudao-version（M15），而 VITE_WX_APPID 等三个身份标识仍是上游的值（M18，未修） |
往 env/.env 里加一个变量 | 多端构建与发布 | 🔴 那个文件是所有 mode 的公共基底，而 Vite 会把 VITE_* 静态内联进产物——写在这里的默认口令会原样进生产包，运行时没有开关能关（M9，已修） |
| 排查移动端的一个症状 | 移动端坑位 | 按症状查（编号 M1–M24）。「列表页一直转圈」先看 M3，「点了没反应、只提示页面不存在」先看 M5 |
排错与上线前
| 症状 / 场景 | 去哪 |
|---|---|
| 按症状查一个已知问题 | 坑位索引 — 跨端 29 条（编号 A1–F6）；移动端另有专页 24 条（编号 M1–M24）。每条「现象 → 根因 → 怎么办」+ 实测证据 |
| 上线前只看一页 | 坑位索引，把索引表里标 🔴 的条目过一遍，再顺着它的 G 节过移动端那几条 |
| 权限配了不生效 | 诊断与排错 末尾的「症状 → 根因 → 去哪查 → 报错吗」总表 |
| 整页白屏、Console 零报错 | 坑位索引 D1 — component 路径匹配不上 |
| 点进去是 403 / 按钮全不见 | 坑位索引 D3 — 你多半在用超管账号自测 |
| 编辑时清空一个字段没生效 | 坑位索引 C4 — MyBatis-Plus 默认 NOT_NULL |
| 工作流不推进了 / 定时任务不跑了 | 坑位索引 A3 — 连接池借出去没还，Flowable 只是最先报错的那个 |
| 生产包少了某个功能（如验证码） | 坑位索引 B2 — .env.local 掺进了生产构建 |
| 部署成功了但连的库不对 | 坑位索引 B1 · B3 — profile 错法是静默的 |
| 测试偶发超时 / e2e 跑不起来 | 坑位索引 F3 · F4 — 重跑即绿；test:e2e 是坏的，不要运行也不要补 |
| 移动端列表页一直转圈、Console 一条未捕获 rejection | M3 — @query 漏 catch，而业务码非 0 走的是 reject |
| 移动端点了菜单只提示「页面不存在」 | M5 — 所有跳转失败共用这一句提示，route 写错 / 页面栈满 / tabbar 页用了 navigateTo 都长这样 |
| 移动端 z-paging 列表高度不对 / 盖住了 navbar | M1 · M2 — flex-1 要配 min-h-0；容器内使用要 :fixed="false" |
| 移动端改了路由 / tabbar 配置没生效 | M8 — pages.config.ts 与 tabbar/config.ts 要重启 dev server |
| 看着像 bug、其实是刻意如此 | 坑位索引 · 还有一类「不是坑，是刻意如此」 — 10 条，不要顺手修 |
相关页面
- 手册导读 —— 三仓与技术栈、按角色的阅读路线、章节地图；
- 坑位索引 —— 按症状查的跨端清单；
- 移动端坑位 —— 按症状查的移动端专属清单；
- 新增一个菜单功能端到端 —— 最常见的那件事的完整走查。