Forge-Hotel 编码习惯与规范

本文档记录个人在 Forge 项目中的编码习惯和偏好，所有代码编写（含 AI 辅助生成）必须遵循以下规范。

适用范围: forge-hotel 模块及后续所有业务模块 最后更新: 2026-09-28

一、后端编码习惯

1.1 依赖注入

使用 @Autowired 字段注入，不使用 @RequiredArgsConstructor 构造器注入
每个依赖字段单独加 @Autowired 注解
示例： java @RestController @RequestMapping("/hotel/dish") public class HotelDishController { @Autowired private HotelDishService hotelDishService; }

1.2 Controller 查询参数

分页查询接口的筛选参数必须用实体类接收，禁止逐个 @RequestParam
只有 @PathVariable（路径参数如 id）和确实无法用实体类表达的参数（如安全校验参数）才单独接收
状态更新类接口（如 /{id}/status）属于操作类，可保持 @RequestParam
示例： ```java // ✅ 正确 public RespInfo> dishPage(PageQuery pageQuery, HotelDish query) { ... }

// ❌ 错误 public RespInfo> dishPage(PageQuery pageQuery,

@RequestParam(required = false) Long categoryId,
@RequestParam(required = false) String status,
@RequestParam(required = false) String name) { ... }

- Service 接口和 Mapper 方法签名同步使用实体类参数
- Mapper XML 中用 `@Param("query")` 标注，引用时用 `#{query.fieldName}`

### 1.3 URL 路径风格（传统 JDK 7 风格）

- **禁止使用 `{id}` 路径占位符**，统一使用方法名 + `@RequestParam` 方式传递 ID
- 所有带 ID 参数的接口，ID 作为查询参数而非路径参数
- 示例：
```java
// ✅ 正确 - 使用 @RequestParam
@GetMapping("/dish/detail")
public RespInfo<HotelDishVO> dishDetail(@RequestParam Long id) { ... }

@PostMapping("/dish/remove")
public RespInfo<Void> dishDelete(@RequestParam Long id) { ... }

@PutMapping("/dish/updateStatus")
public RespInfo<Void> dishUpdateStatus(@RequestParam Long id, @RequestParam String status) { ... }

// ❌ 错误 - 禁止使用 @PathVariable 和 {id}
@GetMapping("/dish/{id}")
public RespInfo<HotelDishVO> dishDetail(@PathVariable Long id) { ... }

@PostMapping("/dish/remove/{id}")
public RespInfo<Void> dishDelete(@PathVariable Long id) { ... }

路径命名规则：
- 详情查询：/xxx/detail（原 /{id}）
- 删除：/xxx/remove（原 /remove/{id} 或 /{id}）
- 状态更新：/xxx/updateStatus（原 /{id}/status）
- 其他操作：直接用动词方法名，如 /xxx/accept、/xxx/reject、/xxx/toggle
前端调用时，ID 放在 params 中： ```javascript // ✅ 正确 request.get('/hotel/dish/detail', { params: { id } }) request.post('/hotel/dish/remove', null, { params: { id } }) request.put('/hotel/dish/updateStatus', null, { params: { id, status } })

// ❌ 错误 request.get(/hotel/dish/${id}) request.post(/hotel/dish/remove/${id})


### 1.4 Java 版本限制（JDK 7 及以下风格）

- **禁止使用 Java 8+ 特性**，包括：
  - Lambda 表达式（`() -> {}`）
  - 方法引用（`ClassName::methodName`）
  - Stream API（`.stream().filter().map().collect()`）
  - 增强 switch 表达式（`case "X" -> value`）
- 替代方案：
  - Lambda → 匿名内部类
  - Stream → 传统 for 循环 + if 判断
  - 方法引用 → 直接调用或使用字符串列名
  - 增强 switch → 传统 switch + break
- 示例：
```java
// ✅ 正确 - 传统 switch
for (Long id : dto.getIds()) {
    switch (dto.getOperation()) {
        case "ON_SALE":
            dishUpdateStatus(id, "ON_SALE");
            break;
        case "DELETE":
            dishDelete(id);
            break;
        default:
            throw new BusinessException("不支持的操作类型: " + dto.getOperation());
    }
}

// ❌ 错误 - 增强 switch
for (Long id : dto.getIds()) {
    switch (dto.getOperation()) {
        case "ON_SALE" -> dishUpdateStatus(id, "ON_SALE");
        case "DELETE" -> dishDelete(id);
        default -> throw new BusinessException("不支持的操作类型: " + dto.getOperation());
    }
}

// ✅ 正确 - 传统 for 循环过滤
List<String> boundShortCodes = new ArrayList<>();
for (HotelQrCode e : entities) {
    if (Objects.equals(e.getTenantId(), tenantId) && e.getRoomId() != null) {
        boundShortCodes.add(e.getShortCode());
    }
}

// ❌ 错误 - Stream API
List<String> boundShortCodes = entities.stream()
    .filter(e -> Objects.equals(e.getTenantId(), tenantId))
    .filter(e -> e.getRoomId() != null)
    .map(HotelQrCode::getShortCode)
    .toList();

// ✅ 正确 - 匿名内部类
HotelQrCode qrCode = TenantContextHolder.executeIgnore(new java.util.function.Supplier<HotelQrCode>() {
    @Override
    public HotelQrCode get() {
        return getBaseMapper().selectByShortCodeIgnoreTenant(shortCode);
    }
});

// ❌ 错误 - Lambda 表达式
HotelQrCode qrCode = TenantContextHolder.executeIgnore(() ->
    getBaseMapper().selectByShortCodeIgnoreTenant(shortCode)
);

// ✅ 正确 - QueryWrapper + 字符串列名
QueryWrapper<HotelDishSpecGroup> wrapper = new QueryWrapper<>();
wrapper.eq("dish_id", dishId)
       .eq("tenant_id", tenantId)
       .orderByAsc("sort_order");

// ❌ 错误 - LambdaQueryWrapper + 方法引用
LambdaQueryWrapper<HotelDishSpecGroup> wrapper = new LambdaQueryWrapper<>();
wrapper.eq(HotelDishSpecGroup::getDishId, dishId)
       .eq(HotelDishSpecGroup::getTenantId, tenantId)
       .orderByAsc(HotelDishSpecGroup::getSortOrder);

// ✅ 正确 - UpdateWrapper + 字符串列名
UpdateWrapper<HotelQrCode> updateWrapper = new UpdateWrapper<>();
updateWrapper.eq("id", qrCodeId)
             .set("room_id", null)
             .set("room_no", null);
getBaseMapper().update(null, updateWrapper);

// ❌ 错误 - LambdaUpdateChainWrapper + 方法引用
new LambdaUpdateChainWrapper<>(getBaseMapper())
    .eq(HotelQrCode::getId, qrCodeId)
    .set(HotelQrCode::getRoomId, null)
    .set(HotelQrCode::getRoomNo, null)
    .update();

MyBatis-Plus Wrapper 选择：
- 使用 QueryWrapper / UpdateWrapper（字符串列名）
- 禁止使用 LambdaQueryWrapper / LambdaUpdateChainWrapper（方法引用）
- 原因：方法引用属于 Java 8+ 特性，不符合传统 JDK 7 风格

1.5 统一返回封装

所有接口统一使用 RespInfo 封装返回值
成功：RespInfo.success(data) 或 RespInfo.success()（无返回值时）
失败：RespInfo.error(msg) 或抛出 BusinessException

1.6 实体类规范

实体继承 TenantEntity（自带 tenantId + 审计字段）
主键使用 @TableId(value = "id", type = IdType.ASSIGN_ID)（雪花算法）
逻辑删除字段：@TableLogic(value = "0", delval = "id")，类型为 Long（bigint），删除时写入主键 ID
使用 Lombok：@Data + @EqualsAndHashCode(callSuper = true) + @Serial
每个字段必须有 Javadoc 注释

示例：

@Data
@EqualsAndHashCode(callSuper = true)
@TableName("hotel_business_hours")
public class HotelBusinessHours extends TenantEntity {
@Serial
private static final long serialVersionUID = 1L;

/** 主键ID（雪花算法） */
@TableId(value = "id", type = IdType.ASSIGN_ID)
private Long id;

/** 状态: ENABLED-启用, DISABLED-禁用 */
private String status;

/** 删除标记（0=未删除，删除时写入主键ID） */
@TableLogic(value = "0", delval = "id")
private Long delFlag;
}

1.5 SQL 编写规范

SQL 必须写在 Mapper XML 中，禁止在 Service 层用 LambdaQueryWrapper 构建查询
例外：仅 selectById、insert、updateById、deleteById 等 MyBatis-Plus 内置方法允许
原因：DataScopeInterceptor 按 mapperMethod 精确匹配改写 SQL
Mapper XML 中的查询必须显式过滤未删除数据：AND del_flag = 0
原因：自定义 XML SQL 不会被 MP 自动补全逻辑删除条件
FOR UPDATE 语句禁止写 LIMIT（实际踩过的坑）：租户拦截器 TenantLineInnerInterceptor 会用 JSqlParser 4.9 对所有查询 SQL 重新解析序列化，序列化时把 LIMIT 1 FOR UPDATE 重排为 FOR UPDATE LIMIT 1，MySQL 直接语法错误（审批同意/驳回时报 SQLSyntaxErrorException）；纯 FOR UPDATE（无 LIMIT）往返不变
- 规则：Mapper XML 锁行查询只写 WHERE 唯一条件 + FOR UPDATE，不加 LIMIT，并在 XML 中加防回归注释；条件不唯一时先把条件改唯一，而不是靠 LIMIT 兜
- 已修复参考：FlowTaskMapper.selectByTaskIdForUpdate、CapabilityApprovalMapper.selectForUpdate

1.6 操作日志

每个 Controller 方法必须加 @OperationLog 注解
格式：@OperationLog(module = "模块名", type = OperationType.XXX, desc = "操作描述")
操作类型：QUERY / ADD / UPDATE / DELETE

1.7 包结构

controller/     # REST 控制器
domain/         # 数据库实体（Entity）
dto/            # 请求 DTO（新增/修改用）
vo/             # 响应 VO（查询返回用）
mapper/         # MyBatis Mapper 接口
service/        # 服务接口
  └── impl/     # 服务实现
constant/       # 常量

1.8 Service 层规范

Service 之间禁止互相注入（避免循环依赖）
跨 Service 协调逻辑上提到 Controller 层
事务注解：@Transactional(rollbackFor = Exception.class)
校验方法命名：validateXxx(Xxx entity/dto)
存在性校验方法命名：requireXxx(Long id)（不存在直接抛异常）

二、前端编码习惯

2.1 页面组件选择

标准 CRUD 页面：使用 AiCrudPage 组件（自动处理搜索栏、工具栏、表格、分页布局）
分页位置：右下角（AiCrudPage 内置）
配置少的简单列表：不加多余筛选条件，保持界面简洁
页面容器样式：height: 100%

2.2 AiCrudPage 配置规范

api-config 格式： javascript :api-config="{ list: 'get@/hotel/xxx/page', detail: 'get@/hotel/xxx/detail', add: 'post@/hotel/xxx', update: 'put@/hotel/xxx', delete: 'post@/hotel/xxx/remove', }"
注意：detail 和 delete 路径中不包含 :id，ID 由组件自动作为查询参数传递
tableColumns 和 editSchema 必须定义为 computed（确保字典异步加载后响应式更新）
操作列使用 h('a', { class: 'text-primary cursor-pointer hover:opacity-80', onClick: ... }) 模式
刷新方法：crudRef.value?.refresh()（不是 reload；等价于 loadList）
编辑方法：crudRef.value?.handleEdit(row)
删除方法：crudRef.value?.handleDelete(row)（组件自带二次确认弹窗与 :id 占位符替换；不存在 openDelete，误调会点击即抛 TypeError）
读取当前表格数据：crudRef.value?.getTableData()（返回 dataSource，可用于轮询判断某行状态是否已变更，见 9.8）

2.3 字段命名

前端字段统一使用 camelCase 命名
与后端 API 返回字段保持一致

2.4 表格渲染规范

空值处理：空值字段显示空白，不使用 - 作为占位符
图片列：
- 列宽设置 100px
- 用 div 包裹 AuthImage 组件，设置 overflow: hidden 防止图片溢出
- 禁止直接用 NAvatar 的 src 属性
状态标签：使用 NTag 组件，配合颜色映射 javascript const statusColorMap = { ENABLED: 'success', DISABLED: 'default' } render: row => h(NTag, { type: statusColorMap[row.status] || 'default', size: 'small' }, { default: () => statusLabelMap[row.status] || row.status })

2.5 操作按钮样式

使用 UnoCSS 语义化颜色类区分操作类型：

类名	颜色	场景
`text-primary`	蓝	编辑、查看、授权
`text-warning`	黄	刷新缓存、重置、封禁
`text-error`	红	删除、强制下线
`text-success`	绿	启用、发布、通过
`text-info`	灰蓝	详情、统计

2.6 字典使用

禁止硬编码下拉选项和状态标签
下拉使用 DictSelect 组件或 useDict() composable
标签展示使用 DictTag 组件
Schema 中的字典选项必须用 computed 包裹

2.7 图片预览

采用全屏覆盖层实现（Teleport to="body"）
position: fixed + 半透明黑色背景
右上角 × 关闭按钮，支持点击背景或 ESC 关闭
左右箭头切换图片，底部圆点指示器 + 页码计数
图片自适应：max-width: 85vw + max-height: 80vh

2.8 时间段选择

时间类字段使用下拉选择（Select），不使用手动输入框
时间选项按业务场景设定间隔（如每 30 分钟一档：09:00, 09:30, 10:00...23:30）

2.9 API 文件规范

导入路径：import { request } from '@/utils'（不是 @/utils/request）
函数命名：getXxxPage / getXxxDetail / createXxx / updateXxx / deleteXxx
按模块用注释分隔：// ==================== 模块名 ====================
每个函数加 JSDoc 注释

2.10 API 路径风格（与后端保持一致）

禁止使用模板字符串拼接 ID（如 /hotel/dish/${id}）
所有带 ID 的接口，ID 作为查询参数传递
示例： ```javascript // ✅ 正确 - ID 放在 params 中 export function getDishDetail(id) { return request.get('/hotel/dish/detail', { params: { id } }) }

export function deleteDish(id) { return request.post('/hotel/dish/remove', null, { params: { id } }) }

export function updateDishStatus(id, status) { return request.put('/hotel/dish/updateStatus', null, { params: { id, status } }) }

// ❌ 错误 - 禁止使用模板字符串拼接 ID export function getDishDetail(id) { return request.get(/hotel/dish/${id}) }

export function deleteDish(id) { return request.post(/hotel/dish/remove/${id}) }

- 路径映射规则（与后端 Controller 对应）：
  - 详情：`/xxx/:id` → `/xxx/detail` + `{ params: { id } }`
  - 删除：`/xxx/remove/:id` → `/xxx/remove` + `{ params: { id } }`
  - 状态更新：`/xxx/:id/status` → `/xxx/updateStatus` + `{ params: { id, status } }`
  - 其他操作：`/xxx/:id/action` → `/xxx/action` + `{ params: { id } }`

### 2.11 只读列表页与工具栏/导出按钮展示习惯

- **只读列表页（仅查询 + 详情 + 导出）同样使用 `AiCrudPage`**，不要手写筛选栏 + `NDataTable`，保证与菜品规格等页面外观一致：
  - 隐藏写操作：`:hide-add="true"`、`:hide-batch-delete="true"`、`:hide-selection="true"`
  - 富详情（描述区 + 子表）不用组件内建 detail，用自定义操作列触发自己的弹窗
- **导出按钮位置**（二选一，按页面需要）：
  - 内建导出：`:show-export="true"` + `export-api` + `export-file-name`，按钮在工具栏**左侧**；当工具栏溢出操作只有导出 1 项时直接显示为独立按钮，≥2 项才折叠进「更多」下拉
  - 靠表格工具栏**右侧**（与刷新/密度/列设置等图标同一排）：用 `#table-toolbar-right` 插槽放自定义按钮，导出参数用 `crudRef.value?.getSearchParams()` 获取（已经过 `before-search` 转换）
- **日期范围筛选**：search-schema 用 `type: 'daterange'`（或 `datetimerange`），在 `before-search` 钩子中拆为 `beginTime`/`endTime` 并删除原字段；该钩子结果**同时作用于列表查询与导出**；后端列表接口必须同步支持 `beginTime`/`endTime`，否则筛选是「死」的
- **日期范围转换必须统一走共享工具 `@/utils/date-range`，禁止各页面手写取下标直传**（此类转换事故已反复出现多次）：
  - `applyDateRange(params, 'createTime', 'beginTime', 'endTime')` 一步完成「范围 → begin/end + 删原字段」，兼容毫秒时间戳 / 字符串 / Date 等组件产出形态；范围为空时同时移除 begin/end
  - `datetimerange` 传第 5 个参数 `true`，直传 `YYYY-MM-DD HH:mm:ss`
  - 后端时间归一化方法（如 `normalizeTime`）必须兼容多格式：13 位毫秒时间戳、`yyyyMMdd`、`yyyy-MM-dd`、带 `T` 的 ISO、`yyyy-MM-dd HH:mm:ss`；且结束端为零点 `00:00:00` 时抬升为 `23:59:59`，防止结束日期整天被排除
- 示例（只读列表 + 右侧导出）：
```vue
<AiCrudPage
  ref="crudRef"
  api="/restaurant/dishOrder"
  :api-config="{ list: 'get@/restaurant/dishOrder/page' }"
  :search-schema="searchSchema"
  :columns="tableColumns"
  :before-search="beforeSearch"
  row-key="id"
  :hide-add="true"
  :hide-batch-delete="true"
  :hide-selection="true"
>
  <template #table-toolbar-right>
    <NButton size="small" quaternary :loading="exportLoading" @click="handleExport">导出</NButton>
  </template>
</AiCrudPage>

// 日期范围 → beginTime/endTime（同时作用于列表与导出）
// 统一走共享工具，禁止手写 range[0]/range[1] 直传
import { applyDateRange } from '@/utils/date-range'

function beforeSearch(params) {
  return applyDateRange(params, 'createTime', 'beginTime', 'endTime')
}

// 右侧自定义导出：取组件已转换的搜索参数
async function handleExport() {
  const params = crudRef.value?.getSearchParams?.() || {}
  const response = await exportOrder(params)
  downloadBlobResponse(response, '导出.xlsx')
}

三、数据库编码习惯

3.1 表结构规范

所有业务表必须包含：id, tenant_id, create_by, create_time, create_dept, update_by, update_time
字符集 utf8mb4，引擎 InnoDB
主键用 bigint（雪花算法），不用自增
金额字段用 bigint，单位分
时间字段用 datetime（对应 Java LocalDateTime）
状态字段用 varchar，值为大写英文（如 ENABLED / DISABLED、ON_SALE / OFF_SHELF）

3.2 逻辑删除规范

业务表默认使用逻辑删除
del_flag 字段类型 bigint NOT NULL DEFAULT 0
删除时写入当前行主键 ID（不是固定值 1）
实体必须显式声明 @TableLogic(value = "0", delval = "id")

3.3 Flyway 迁移脚本

命名格式：V<版本号>__<lower_snake_case_description>.sql
版本号必须大于 1.0.0，单调递增
脚本必须具备防重复保护：
- 建表：CREATE TABLE IF NOT EXISTS
- 插入：INSERT ... SELECT ... WHERE NOT EXISTS
- 新增列/索引前查 information_schema
INSERT 必须显式写列名，禁止依赖表字段顺序
业务内置数据 tenant_id 必须为 1，禁止写 0
菜单资源 SQL 使用动态 parent_id（子查询），避免硬编码 ID
字典数据格式：sys_dict_type + sys_dict_data，dict_value 与后端枚举值保持一致

3.4 字典规范

字典类型命名：小写下划线，业务级用 hotel_ 前缀，系统级用 sys_ 前缀
dict_value 必须与后端枚举/状态值严格一致
dict_label 只负责展示文案
list_class 负责标签样式（success/primary/warning/info/default）
每个字典数据单独一行 INSERT + WHERE NOT EXISTS 防重复

四、API 设计习惯

4.1 RESTful 风格（传统 JDK 7 风格）

操作	HTTP 方法	路径	说明
分页查询	GET	`/xxx/page`	筛选参数用实体类接收
查询全部	GET	`/xxx/all` 或 `/xxx/list`	不分页列表
查询详情	GET	`/xxx/detail`	ID 作为 `@RequestParam`，不是路径参数
新增	POST	`/xxx`	RequestBody
修改	PUT	`/xxx`	RequestBody
删除	POST	`/xxx/remove`	ID 作为 `@RequestParam`，不是路径参数
状态切换	POST	`/xxx/toggle`	ID 作为 `@RequestParam`
状态更新	PUT	`/xxx/updateStatus`	`@RequestParam Long id, @RequestParam String status`
批量操作	POST	`/xxx/batch`	RequestBody

禁止使用 {id} 路径占位符
所有带 ID 的接口统一使用方法名 + @RequestParam 方式
示例： ```java // ✅ 正确 @GetMapping("/dish/detail") public RespInfo dishDetail(@RequestParam Long id) { ... }

@PostMapping("/dish/remove") public RespInfo dishDelete(@RequestParam Long id) { ... }

@PutMapping("/dish/updateStatus") public RespInfo dishUpdateStatus(@RequestParam Long id, @RequestParam String status) { ... }

// ❌ 错误 - 禁止使用 @PathVariable @GetMapping("/dish/{id}") public RespInfo dishDetail(@PathVariable Long id) { ... }


### 4.2 权限标识

- 格式：`模块:资源:操作`，如 `hotel:dish:query`、`hotel:businessHours:add`
- 按钮权限资源类型 `resource_type = 3`

---

## 五、交互设计习惯

### 5.1 列表页面

- 配置项少的列表页不加多余筛选（如营业时段不加餐段筛选）
- 分页统一在右下角
- 操作列包含：编辑 + 状态切换 + 删除

### 5.2 批量操作

- 有批量生成的管理页面，应同步提供批量删除、批量下载（ZIP）、单条下载功能
- 保证操作完整性与用户体验一致性

### 5.3 危险操作

- 删除、解绑等不可逆操作必须弹出**二次确认**
- 已绑定的二维码显示"解绑"按钮而非"重新绑定"

### 5.4 扫码绑定

- 绑定成功后，点击"完成"跳转至扫码绑定主界面（无参数状态）
- 解绑后返回扫码界面

---

## 六、多租户习惯

### 6.1 租户上下文

- 业务数据 `tenant_id` 必须设为 `1`（默认租户），禁止设 `0`
- 免登录场景（如扫码）：先忽略租户过滤查到实体，再根据实体的 `tenantId` 动态设置租户上下文
- 使用 `TenantContextHolder.getTenantId()` 获取当前租户 ID
- 兜底逻辑：`return tenantId == null ? 1L : tenantId;`

---

## 七、其他习惯

### 7.1 注释风格

- **注释必须详细完整**，能让其他人快速理解代码意图和业务背景，不依赖外部文档
- 实体类每个字段必须有 Javadoc 注释，说明字段含义、取值范围、关联关系
- Controller 每个方法必须有 Javadoc（描述接口用途、参数含义、返回值说明）
- Service 接口方法必须有 Javadoc（含参数说明、业务规则、异常场景）
- ServiceImpl 中复杂业务逻辑必须加块注释，说明业务背景和决策原因
- 状态机流转、条件分支、边界处理等关键逻辑必须加行内注释
- 跨模块调用、特殊设计决策需加注释说明"为什么这样做"
- 禁止无意义注释（如 `// 获取名称` 紧跟 `getName()`），注释应解释意图而非复述代码

### 7.2 安全红线

- 禁止硬编码密钥、AK/SK、数据库密码
- 禁止在日志中打印手机号、身份证、银行卡
- API Key/Secret 返回前端必须脱敏（保留前4后4，中间 `****`）

### 7.3 构建与验证（Windows PowerShell 环境）

> **本环境关键约束**：
> - Shell：PowerShell（不支持 `&&`，必须用 `;` 分隔命令）
> - Maven：不在 PATH 中，必须用完整路径 `D:\java_install\apache-maven-3.9.16\bin\mvn.cmd`
> - pnpm：执行策略禁止 `.ps1` 脚本，必须用 `.cmd` 后缀（`pnpm.cmd` 而非 `pnpm`）
> - H5 构建脚本是 `build:h5`（不是 `build`）

#### 后端命令

```powershell
# 全量构建（从 forge-server 根目录）
Set-Location D:\java_project\forge-admin\forge-server; D:\java_install\apache-maven-3.9.16\bin\mvn.cmd clean install -DskipTests

# 仅编译 hotel 模块及其依赖（快速验证编译）
Set-Location D:\java_project\forge-admin\forge-server; D:\java_install\apache-maven-3.9.16\bin\mvn.cmd compile -pl forge-business/forge-hotel -am -DskipTests

# 启动 admin 服务（默认 localhost:8580）
Set-Location D:\java_project\forge-admin\forge-server\forge-admin-server; D:\java_install\apache-maven-3.9.16\bin\mvn.cmd spring-boot:run

# 启动 flow 服务（默认 localhost:8581）
Set-Location D:\java_project\forge-admin\forge-server\forge-flow; D:\java_install\apache-maven-3.9.16\bin\mvn.cmd spring-boot:run

前端命令（forge-admin-ui）

Set-Location D:\java_project\forge-admin\forge-admin-ui

# 安装依赖
pnpm.cmd install

# 开发模式（默认 localhost:5173）
pnpm.cmd dev

# 生产构建
pnpm.cmd build

# Lint 检查 + 自动修复
pnpm.cmd lint:fix

H5 命令（forge-h5-ui）

Set-Location D:\java_project\forge-admin\forge-h5-ui

# 安装依赖
pnpm.cmd install

# 开发模式
pnpm.cmd dev:h5

# 生产构建（⚠️ 必须是 build:h5，不是 build）
pnpm.cmd build:h5

PowerShell 常见坑（AI 执行前必读）

问题	错误写法	正确写法
命令链分隔	`cd path && mvn ...`	`Set-Location path; mvn.cmd ...`
Maven 不在 PATH	`mvn clean install`	`D:\java_install\apache-maven-3.9.16\bin\mvn.cmd clean install`
pnpm 被策略拦截	`pnpm build`	`pnpm.cmd build:h5`
H5 构建命令	`pnpm build`	`pnpm.cmd build:h5`（`build` 不存在会报错）
执行 .bin 脚本	`node node_modules/.bin/vite build`	用 `pnpm.cmd` 统一入口，不要直接调 node_modules 下的文件

八、列表页 + 表单弹窗组件拆分习惯

参考实现：views/restaurant/creditCustomer.vue（列表页）+ views/restaurant/components/CreditCustomerFormModal.vue（表单弹窗组件）

8.1 拆分原则

表单字段多时，表单代码写在独立组件文件，不与列表页混在同一个 vue；但交互上仍以弹窗形式打开，不做独立路由页面
表单弹窗组件统一放 views/<模块>/components/ 目录：unplugin-vue-router 的 routesFolder 排除 **/components/**，不会生成多余路由，也无需注册 sys_resource 菜单
命名 XxxFormModal.vue；props 固定 show（v-model）+ row（null 为新增），送审成功后 emit('saved', payload)，刷新与后续衔接交给父页面
仅当确实需要带参数的独立页面（如点菜详情 dishOrder）才用路由子页面 + sys_resource 隐藏菜单（resource_type=2、visible=0），且 component 字段必须与文件路径完全一致，否则 404

8.2 列表页（父页面）写法

AiCrudPage 加 hide-add + #toolbar-start 插槽自定义新增按钮打开表单弹窗；不传 edit-schema，操作列编辑同样打开表单弹窗
监听 saved 事件刷新并衔接流程： javascript function handleFormSaved(payload) { crudRef.value?.refresh() const origin = formRow.value // 新增或暂存：送审后直接衔接审批人选择；审批中编辑仅保存 if (!origin || origin.approvalStatus === '1') openSubmit({ id: payload.id, customerName: payload.customerName }) else message.success('保存成功') }

8.3 表单弹窗组件写法

NModal preset="card" + 固定宽度（如 900px）、:mask-closable="false"；标题按 row 区分新增/编辑
表单体：NGrid :cols="2" + NFormItemGi，长文本字段 :span="2"；日期用 NDatePicker + v-model:formatted-value + value-format="yyyy-MM-dd"
用 row prop 区分新增/编辑：有 row 调 getXxxDetail(row.id) 回填；保存 payload 带 id 走同一个 save 接口
填报类表单底部主按钮叫送审（不叫保存）：送审 = 校验 + 保存，成功后 emit saved 并关闭，是否衔接审批人选择由父页面决定
ID 保持字符串直传，禁止转 Number

九、流程（审批流）书写与配置习惯

参考实现：挂账客户审批（restaurant/creditCustomer.vue + 后端 CreditCustomerServiceImpl + CreditCustomerFlowDefinition）

9.1 流程详情展示：统一用公共组件 FlowProcessDetailModal

组件路径：@/components/flow/FlowProcessDetailModal.vue，封装「业务信息区 + 流转记录（步骤条 + 表格）+ 流程图」，内部自动加载审批历史、格式化时间/历时、映射状态标签
任何业务流程传参即用，禁止再写一套弹窗/时间轴/表格列代码： vue <FlowProcessDetailModal v-model:show="flowDetailVisible" :process-instance-id="row.processInstanceId" :finished="row.approvalStatus === '5'" business-title="客户信息" :business-items="businessItems" />
参数约定：
- process-instance-id：流程实例ID，核心参数，为空展示空态
- finished：流程是否已结束（点亮步骤条「结束」节点）
- business-items：[{ label, value, dictType? }]，带 dictType 自动渲染 DictTag；需完全自定义业务区时用 #business 插槽
- business-title / title / column：业务区标题 / 弹窗标题 / 业务区每行条数（默认 2）
弹窗尺寸已内置百分比规范：width: 92%; max-width: 1600px，内容区 min-height: 72vh; max-height: 88vh; overflow: auto，业务页面不要自行覆盖
列表页审批状态列可点击查看流程：DictTag 不接受 onClick，必须用 h('span', { style, onClick }, [h(DictTag, {...})]) 包裹
审批历史统一由组件内部 flowApi.getProcessHistory(processInstanceId) 获取，业务页面禁止自行调用和维护历史数据

9.2 业务表与流程绑定配置

业务表必须含 business_key、process_instance_id 字段；businessKey 格式固定 <objectCode>:<recordId>
审批状态用数字字典值（如 1-暂存 2-审批中 3-已驳回 4-已退回 5-已完成），字典类型按业务命名（如 restaurant_credit_approval_status）；前端一律 useDict + DictTag 字典驱动，禁止硬编码选项/标签
状态门禁用函数集中定义：canSubmit / canEdit / canWithdraw / canDelete / canToggle，操作列按门禁渲染按钮；审批状态数字值 ↔ 操作矩阵（以挂账客户为例，撤回见 9.6）：1暂存→提交审批+编辑+删除；2审批中→撤回；3撤回 / 4驳回→编辑+删除；5已完成→变更挂账状态
流程模型懒创建：首次提交审批时 ensureFlowModel() 自动创建并发布；getModelByKey 查询必须过滤 del_flag = 0，否则已删除模型会导致重复创建
业务状态维护依赖双回调：task-created / task-completed 回调 + PROCESS_COMPLETED 监听都要维护状态，不能只靠其一；状态写入必须幂等、可从活动任务节点修复
BPMN 节点表单、字段权限、审批人策略在流程设计器中维护；代码初始化逻辑不得覆盖设计器已编辑的 BPMN XML
前端流程变量与 API payload 中 ID 一律字符串，禁止雪花 Long 转 JavaScript Number

9.3 流程相关 Flyway 脚本习惯

流程绑定种子数据（ai_business_binding 等）与菜单/字典同脚本维护，全部 NOT EXISTS 防重复、tenant_id = 1
存量数据回填审批状态时，无流程Key的历史数据视为「已完成」，保证老数据不被门禁锁死
字典值变更（如字符串改数字）必须同脚本更新业务表存量数据 + 删旧字典 + 插新字典，三步齐全

9.4 审批详情弹窗：公共骨架 + 业务插件（formUrl 组件契约）

参考实现：views/flow/todo.vue（公共骨架）+ views/restaurant/CreditCustomerApproveForm.vue（挂账业务插件）+ views/business/purchase-order-test.vue（采购单业务插件）

架构结论

审批详情弹窗（待办 / 已办 / 首页待办点入均为同一套，只读态靠 readOnly 切换）是「公共骨架 + 业务插件」结构：业务方只提供三样东西，其余全部是共用组件，审批弹窗本身零改动
公共部分（禁止重写、禁止复制一套）：

区域	载体	数据来源
弹窗骨架 + 右侧审批记录	`@/components/flow/FlowTaskDetailShell.vue`	`flowApi.getProcessHistory(processInstanceId)`
基本信息区（当前节点/流程名称/分类/发起人/部门/时间/状态）	`views/flow/todo.vue` 内置模板	任务行数据（sys_flow_task join 模型）
查看流程图	`DingFlowViewer`	processInstanceId
业务表单动态加载器	`@/components/common/FlowBusinessForm.vue`	按 formUrl 动态加载 `@/views` 下组件
业务表单上下文接口	`@/api/business-app` 的 `businessTaskFormContext`	后端 `BusinessFlowService` 按 providerKey 路由到 Provider
审批提交链路	`completeBusinessTaskAction` / 统一同意/驳回/转办接口	平台统一

业务差异部分（每个流程一套，仅三样）：
1. 前端表单组件：由模型配置 formUrl 指定，FlowBusinessForm 用 import.meta.glob('@/views/**/*.vue') 按路径加载
2. 后端 Provider：实现 BusinessCodeFormProvider（providerKey 与配置一致），提供字段目录 fields、记录数据 recordData、节点保存 saveContext
3. 配置：sys_flow_model.form_json（formUrl / providerKey / formKey）、BPMN 节点、节点字段权限、审批策略（allowApprove / requireComment 等）
数据流：打开弹窗 → 公共代码调上下文接口 → 后端按 providerKey 找 Provider 取业务数据 → 以 initialTaskContext 传入业务组件（组件禁止重复请求）→ 提交时业务组件 emit('submit', { action, comment, variables }) → 公共代码走统一审批接口

formUrl 红线（实际踩过的坑）

formUrl 是 @/views 下的「组件路径」，不是路由地址：如 /restaurant/CreditCustomerApproveForm 对应 src/views/restaurant/CreditCustomerApproveForm.vue；FlowBusinessForm 按路径匹配（含大小写不敏感兜底、includes 匹配）
严禁把 formUrl 指向列表页或其它业务页面：曾指向 creditCustomer.vue 导致整个 CRUD 列表被嵌进审批区，且审批意见、同意/驳回按钮全部缺失（列表页组件不提供审批契约）
formUrl 运行时优先级：sys_flow_node_config 节点配置 > sys_flow_model.form_json（顶层与 formRef 两处）> Provider 常量；改 Java 常量不影响存量模型，必须 Flyway 同步修复 form_json（参考 V1.0.139__fix_credit_customer_flow_form_url.sql，REPLACE 两处 + LIKE 防重复）
formType=business-code 且 formUrl 为空时降级为平台内置渲染（AiForm 字段目录 + 审批意见 + 按钮）；有自定义组件时优先组件模式

已办/通知页面渲染模式（与待办共用 FlowBusinessForm）

已办（views/flow/done.vue）和通知（views/flow/notification.vue）页面与待办页面共用同一套组件架构，通过 readOnly 属性切换可写/只读态
已办页面渲染优先级（useBusinessManagedForm 分支）：
1. 优先 FlowBusinessForm（businessFormContext.formUrl 存在时）：加载同一个业务组件（如 CreditCustomerApproveForm.vue），传入 read-only=true，展示表格布局（与待办一致）
2. 降级 AiForm（无 formUrl 时）：用 readonlyBusinessFormFields（toReadonlyField 转换后的 schema）渲染，表单布局
通知页面：独立逻辑，通常展示业务摘要 + 自定义详情区（如订单明细），不强制走 FlowBusinessForm
关键原则：有自定义业务组件（formUrl）的流程，待办/已办必须用同一个组件渲染，保证样式一致；不能待办用组件、已办用 AiForm

业务表单组件契约（照 CreditCustomerApproveForm.vue 仿写）

props 固定一套：taskId / businessKey / processInstanceId / taskDefKey / processDefKey / variables / approvalPolicy / initialTaskContext / readOnly / submitting / submittingAction；emits：submit、cancel
数据加载顺序：initialTaskContext.recordData 直接用 → 不匹配则 useBusinessTaskFormContext().load(...) → 最后兜底业务详情接口；readOnly 模式隐藏操作区
字段显隐/编辑一律走 useBusinessTaskFormContext 的 canShowField / canEditField；节点可编辑字段 = 组件按节点定义的编辑清单 ∩ 字段权限
提交前先保存本节点可写字段（businessTaskForm.save），再 emit('submit', { action, comment, variables })；variables 必须带网关变量（如 approvalResult: 'approve' | 'reject'）与业务主键
cancel 事件由公共骨架绑定为关闭弹窗；组件内「关闭」按钮直接 emit('cancel')

提交链路共用机制（todo.vue 内建，业务方零成本）

审批意见可选 + 默认补全：意见不做必填；handleExternalFormSubmit（业务表单组件）与 submitApprove（内置表单）两条提交路径提交前统一走 resolveActionComment，留空时按动作补默认意见（DEFAULT_ACTION_COMMENTS：approve→同意、reject→驳回、return→退回），绕过前端 validateApprovalInput 与后端 policy.requireComment 的双拦截；不要改成放后端/BPMN 校验，否则存量模型全部要重部署
批量/快捷同意精准拦截：assertQuickActionAllowed 仅在节点存在「必填可写字段」时拦截批量同意（hasRequiredWritableBusinessFormFields：writable && required && 非 readonly/disabled）；无必填字段的 business-code 节点（如老板审核仅可选备注）允许批量同意/驳回；有必填字段的节点（如申请人修改 customerName 必填）仍引导进详情处理
批量通道与详情审批等价：批量走 executeQuickAction → completeBusinessTaskAction，网关变量（approvalResult/approved）由后端 mergeActionVariables 在 complete 时补齐，不依赖前端组件传参，不存在网关走错风险

审批区 UI 习惯（用户确认版）

业务信息展示不用 n-descriptions（其表格列宽随内容伸缩，上下长短不一）：用自定义 CSS Grid 均分两列（repeat(2, minmax(0, 1fr)) + 1px gap 做分隔线），label 固定 120px 灰底、值列 flex: 1 填满；长文本字段 grid-column: 1 / -1 通栏
审批意见可选（不做必填校验）、label 加粗；操作按钮固定：转办（公共 slot）+ 同意 + 驳回修改（修改节点为保存并重提/终止申请）+ 关闭
不加节点标题栏（如「老板审核」tag）与「当前节点只查看」类 alert 提示

新流程接入清单

后端：XxxFlowDefinition（常量 + 字段目录 + 默认 formRef JSON）+ XxxCodeFormProvider + Service 双回调维护状态
前端：@/views/<模块>/XxxApproveForm.vue 按上述契约新建
配置：formUrl 指向新组件（form_json 顶层与 formRef 两处）、providerKey 与 Provider 一致
库中已存在的存量模型：Flyway 脚本同步替换 formUrl
验证：待办打开审批 → 信息区均分展示、审批意见与按钮齐全；已办只读打开无操作按钮

9.5 提交端审批人自适应（有配置直接提交，没配置才选人）

参考实现：CreditCustomerController#/requiresApproverSelection + CreditCustomerServiceImpl.requiresApproverSelection + creditCustomer.vue openSubmit

交互规则：点「提交审批」先探测老板节点配置——已配置直接提交不弹任何框；仅当什么都没配置（或仍是旧 ${bossId} 变量表达式）才弹选人框（必选）
判定规则（解析已部署模型 BPMN 节点开标签，与运行时真相一致）：

节点配置	requiresApproverSelection	提交端表现
`flowable:candidateGroups` 非空（角色/岗位/部门候选组）	false	直接提交
`flowable:candidateUsers` 非空（候选人员）	false	直接提交
`flowable:assignee` 固定值（无 `${}`）	false	直接提交
`flowable:assignee` 为发起人/上级/负责人等表达式	false	引擎自行解析，直接提交
无候选人且无 assignee，或节点不存在	true	弹框选老板
`flowable:assignee="${bossId}"`（旧模板）	true	弹框选老板，提交传 approverId 写变量

为什么以 BPMN 为准：设计器配置角色/人员/岗位最终落到 BPMN 的候选组/候选人/assignee 属性，运行时任务分配由 Flowable 按这些属性原生执行；sys_flow_node_config 只服务于设计器/AI 上下文与 calculateApprovers，不用于本判定
双保险：前端探测只决定「弹不弹框」；后端 submitApproval 用同一判定再校验（approverId == null && requiresApproverSelection() 抛「请选择审批人」），绕过前端直接调接口也拦得住
选人下拉数据源：复用 GET /system/user/page（兼容 records/list/rows 三种返回形态，label 优先 realName），业务侧不另建老板候选接口
三处同步红线：改节点审批人方式（设计器改或代码改）时同步检查 ① 前端提交弹窗 ② 后端提交校验 ③ Java BPMN 种子模板（XxxFlowBpmn），缺一处新环境就会按种子模板走回旧路；同时保持 ensureFlowModel 不覆盖设计器已编辑的 BPMN（见 9.2）
生效提示：flow 侧 Mapper XML / Java 改动需重启 flow 服务才生效（重启 admin 无效）；业务侧 Java 改重启 admin；前端 HMR 即时生效

9.6 发起人撤回审批中流程（撤回链路与接入）

参考实现：creditCustomer.vue handleWithdraw + flowApi.withdrawProcess + FlowTaskServiceImpl.withdraw + CreditCustomerServiceImpl.markCanceled

平台已内置撤回链路，业务方零新增后端接口，前端一个确认弹窗 + 一次 API 调用即可接入
撤回入口：flowApi.withdrawProcess({ processInstanceId, userId, reason }) → POST /api/flow/task/withdraw（flow.js 是默认导出对象，非命名导出）
- userId 取 useUserStore().userId（import { useUserStore } from '@/store'）
- payload 三字段固定：processInstanceId + userId + reason
后端链路（全部平台侧，闭环自动落业务状态）：

步骤	位置	动作
1 校验	`FlowTaskServiceImpl.assertSubmitterWithdrawAllowed`	校验 `allowSubmitterWithdraw` 属性非 FALSE + `isProcessSubmitter` 是提交人
2 删实例	`runtimeService.deleteProcessInstance(id, "用户撤回")`	物理删除运行时实例，FlowTask 状态置 6
3 事件	`FlowTaskEventListener` case `PROCESS_CANCELLED`	FlowBusiness 置 canceled + 发布 `FlowEventMessage.PROCESS_CANCELED`
4 回调	业务 `@FlowCallback(ON_CANCELED)`	`markCanceled` 把业务 `approvalStatus` 置为撤回态（如 '3'）

撤回门禁：仅「审批中(2) 且有 processInstanceId」的行显示撤回按钮：canWithdraw = row => row.approvalStatus === '2' && !!row.processInstanceId；按钮用 text-warning 黄色 + 二次确认
撤回态(3)/驳回态(4) 编辑保存后回到暂存(1)，形成「撤回/驳回 → 编辑 → 暂存 → 重新送审」闭环（后端 creditSave 门禁放行 {1,3,4}，且 3/4 保存后 reset 为 DRAFT）

9.7 撤回/驳回后重新发起 = 新流程实例（含平台发起幂等修复）

撤回不是「暂停后恢复」，而是「作废旧实例 → 修改资料 → 发起新实例」：
- 旧实例被 deleteProcessInstance 物理删除（ACT_RU_* 消失，痕迹留在 ACT_HI_* 与 sys_flow_task）
- submitApproval 再次 startProcess 生成新 processInstanceId，直接覆盖业务表 process_instance_id
- businessKey（<objectCode>:<recordId>）与业务记录 ID 不变；页面流程详情展示新实例时间轴，旧实例痕迹需走历史查询
平台发起幂等校验坑（已修）：FlowInstanceServiceImpl.startProcess 原逻辑「sys_flow_business 存在非运行态记录 → 一律抛『业务流程已存在且不可重复发起』」，与前端 useFlow.canStart（canceled 后允许重发）自相矛盾，堵死了「发起→撤回→重发」闭环
- 修复：新增 isRestartableEndedBusiness，旧流程未成功走完（撤回/驳回/终止）且运行实例已不存在时，flowBusinessMapper.deleteById 清除旧关联再重发；该表只保留 businessKey 当前一轮关联

9.8 流程异步回调导致的前端刷新时序（轮询刷新）

参考实现：creditCustomer.vue refreshUntilStatusChanged

撤回/审批完成后接口立即返回，但业务状态由跨服务异步回调落库，前端刷新早于回调会查到旧状态：
- 链路：flow 服务 FlowEventPublisher.publish（@Async + Redis Pub/Sub flow:event:all）→ admin 服务 FlowClientHelperAutoConfiguration 订阅 → @FlowCallback → 改业务状态
- 现象：撤回后列表仍显示「审批中」，手动刷新才变「撤回」
修复模式：轮询刷新直到该行离开旧状态（带上限兜底，避免回调异常时无限轮询）： javascript function refreshUntilStatusChanged(rowId, expectedOldStatus, attempt = 0) { crudRef.value?.refresh() if (attempt >= 5) return setTimeout(() => { const latest = (crudRef.value?.getTableData() || []).find(i => String(i.id) === String(rowId)) if (!latest || latest.approvalStatus !== expectedOldStatus) return // 已流转或已删除则停 refreshUntilStatusChanged(rowId, expectedOldStatus, attempt + 1) }, 800) }
适用于所有「操作接口同步返回、业务状态靠异步事件回调落库」的场景（撤回、审批通过/驳回等）

9.9 多状态字段操作：下拉菜单显式选目标状态，禁用单按钮盲循环

参考实现：creditCustomer.vue 挂账状态列（restaurant_credit_status 三态）+ CreditCustomerServiceImpl.creditUpdateStatus

踩坑：挂账状态三态（0正常/1暂停/2黑名单），后端 creditToggleStatus 做 0→1→2→0 盲循环，前端按钮却按两态显示文案（status==='0' ? '暂停挂账' : '恢复正常'）→ 从「暂停」点一下文案写「恢复正常」实际却跳「黑名单」，文案与行为不符 + 易误操作
规则：≥ 3 个状态、或状态语义不对等的字段，操作用 NDropdown 下拉菜单显式选目标状态，不用单按钮循环：
- 选项来自字典（useDict），自动排除当前状态，点哪个变哪个
- 后端接口接收目标状态入参（creditUpdateStatus(id, creditStatus)），校验目标值必须是字典合法值，与当前相同则跳过；不再做循环推导
- 选中后二次确认弹窗再落库
两态且语义对等（启用/停用）才可用单按钮 toggle

十、AI 执行纪律（防止跑偏规则）

本节是 AI 编程助手执行任务时的强制约束，防止在终端命令、代码调查等环节浪费时间。

10.1 终端命令纪律

命令失败最多重试 1 次：第 1 次失败后，必须先查本节「7.3 PowerShell 常见坑」表，禁止盲目尝试不同写法
禁止探索文件系统找工具路径：Maven、Node、pnpm 等工具路径已记录在 7.3 节，直接用，不要 where.exe、Get-ChildItem、find 等搜索
禁止用 cmd /c 绕过 PowerShell 限制：所有命令必须用 PowerShell 原生语法（; 分隔 + .cmd 后缀）
构建命令统一用本文档记录的命令：不要自己猜测命令，先读 7.3 节复制粘贴

10.2 任务执行纪律

严格按待办列表顺序执行：完成当前 Task 后直接进入下一个，不要“顺便看看”其他代码
不做任务范围外的调查：如果当前任务是「接入营业时间校验」，不要去核实「权限机制」「数据库表结构」等无关内容
调查必须有明确目标：只有在当前 Task 明确要求「确认某文件内容」时才去读代码，不要主动发散
遇到不确定的环境配置，先查记忆再查代码：工具路径、数据库连接等已在记忆中的信息，直接检索，不要花时间在文件系统中搜索

10.3 时间分配纪律

单个终端命令耗时不超过 30 秒：如果构建/安装卡住超过 30 秒，检查是否命令写错，不要反复尝试
单个调查任务不超过 3 次工具调用：如果需要读超过 3 个文件才能确认一件事，说明调查范围太大，应该缩小范围或直接问用户
文档更新集中处理：所有文档回填集中在最后一个 Task 完成，不要每完成一个 Task 就去改文档

编码习惯与规范.md 47 KB Vēsture Neapstrādāts