yangxuan/openclaw-config
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fcb30e1c6984421f0ed483ce70f6320d910d898b
openclaw-config/workspace-planner/memory/2026-08-04.md
T
杨轩 fcb30e1c69 骨架代码规范
2026-08-04 14:56:20 +08:00

12 KiB
Raw Blame History

2026-08-04 工作日志

mica 项目 - SMDM 物料管理模块开发规范

🔴 强制性红线 (违反即停止)

# 红线 违规示例 正确做法
1 表前缀必须过滤 DmpMdItemInfo ItemInfo
2 API 必须放在 apis.smdm 包 smd.api.ItemApi apis.smdm.ItemApi
3 查询只能用 Mapper 使用 MyBatis-Plus 原生 MyBatis XML
4 改删必须 Feign 远程调用 本地直接 UPDATE/DELETE 调用 SMDM 服务 API
5 实体必须继承 BaseDomain 独立定义审计字段 extends BaseDomain
6 只使用指定 13 个业务字段 添加表中其他字段 仅用规范内字段
7 代码必须生成到 smd 目录 com.witsoft.mica.item.* com.witsoft.mica.smd.*

📋 已确认的开发规范

1. 包路径规范

  • 代码生成目录: /root/projects/wit/mica-server/src/main/java/com/witsoft/mica/smd/
  • 包前缀: com.witsoft.mica.smd
  • API 包路径: com.witsoft.mica.apis.smdm
  • 子包结构: 
    smd/
├── controller/    # 控制器层
├── service/       # 服务层接口
├── service/impl/  # 服务层实现
├── mapper/        # MyBatis Mapper 接口
├── entity/        # 数据库实体类
├── dto/           # 数据传输对象
└── vo/            # 视图对象

2. 表名前缀过滤规则

  • 过滤前缀: dmp_md_
  • 示例:
    • dmp_md_item_info → ItemInfo
    • dmp_md_xxx → Xxx

3. 实体类规范

  • 基础字段 (业务必需):

    字段说明 数据库字段 Java 字段
    物料编码 item_code itemCode
    物料名称 item_name itemName
    规格型号 item_spec itemSpec
    物料类型 item_type itemType
    物料分类 item_categorys_code itemCategorysCode
    物料属性 properties properties
    主单位 unit_code unitCode
    辅单位 assist_unit_code assistUnitCode
    物料描述 item_desc itemDesc
    供应商 vendor_code vendorCode
    默认仓库 good_warehouse goodWarehouse
    批次控制 batch_control batchControl (默认 0/关)
    领料属性 picking_property pickingProperty (默认 AD/按单领料)
    状态 status status

  • 审计字段 (继承 BaseDomain):

    import com.witsoft.gen.base.BaseDomain;

public class ItemInfo extends BaseDomain {
    // 业务字段...
}
    • id, ecid, createdBy, createTime, updatedBy, updateTime

4. 数据访问规范

  • 查询权限: 仅有数据库查询权限
  • 查询方式: 使用原生 MyBatis Mapper，不使用 MyBatis-Plus
  • 修改/删除: 通过 Feign 远程调用 SMDM 服务

5. 架构模式

mica-server (本地)          smdm (远程服务)
     │                           │
     ├── Controller              │
     ├── Service                 │
     ├── Mapper ──(查询)──→ 数据库
     └── Feign Api ──(改删)──→ WorkshopApi 模式

6. Feign 远程调用模式

API 包路径: com.witsoft.mica.apis.smdm

参考现有 WorkshopApi:

@FeignClient(name = "smdm", path = "/smdm/smd/web/workshop")
public interface WorkshopApi {
    @PostMapping("/getListPage")
    ResponseModel queryWorkshopPageList(@RequestBody Map<String, Object> workshop);
    
    @PostMapping("/create")
    ResponseModel insertWorkshop(@RequestBody Map<String, Object> workshop);
}

📝 注释与日志规范

1. 类注释 (Javadoc 风格)

参考现有 WorkshopController.java:

/**
 * @Description : 物料信息管理
 * @ModifyBrief :
 * @Author : yangxuan
 * @Date : 2026/8/4
 * @Version : 1.0
 */

规范:

  • @Author 固定为 yangxuan
  • @Date 精确到日 (2026/8/4)
  • @ModifyBrief 留空，后续修改时补充

2. 方法注释

/**
 * @Description : 物料信息列表分页查询
 * @ModifyBrief :
 * @Author : yangxuan
 * @Date : 2026/8/4
 * @Version : 1.0
 * @Param : itemQueryDTO
 * @Return : PageDomain<ItemVO>
 */

规范:

  • 公共接口方法必须添加方法注释
  • 私有方法可选添加
  • @Author 固定为 yangxuan

3. 日志规范

框架: SLF4J + Lombok @Slf4j

使用场景:

  • 请求入口：log.info("物料查询请求：itemCode={}", dto.getItemCode())
  • 异常捕获：log.error("物料查询失败", e)
  • 关键业务节点：log.info("物料创建成功：itemCode={}", result.getItemCode())
  • Feign 调用：log.debug("Feign 调用 - 创建物料，入参：{}", JsonUtils.toJson(dto))

示例:

@Slf4j
@RestController
public class ItemController {
    
    public ResponseModel<PageDomain<ItemVO>> queryPageList(@RequestBody ItemQueryDTO dto) {
        log.info("物料查询请求：ecid={}", dto.getEcid());
        try {
            return itemService.queryPageList(dto);
        } catch (Exception e) {
            log.error("物料查询失败", e);
            return ResponseModel.failed("查询失败");
        }
    }
}

4. 字段注释

单行注释即可：

/** 物料编码 */
private String itemCode;

/** 物料名称 */
private String itemName;

🐛 已修正的问题清单 (1-12)

以下问题在开发过程中发现并已修正，后续开发必须遵守：

# 问题 修正方案 涉及文件
1 ResponseModel 静态引用错误 使用 ResponseModel.succeed(data) 静态方法 ItemController.java, ItemServiceImpl.java
2 分页 XML / 详情 MP 混合使用 分页查询用原生 XML，详情查询用 BaseMapper.selectById ItemMapper.xml, ItemServiceImpl.java
3 移除编码查询条件 从 DTO 和 XML 移除 itemCode 模糊搜索 ItemQueryDTO.java, ItemMapper.xml
4 Feign 调用添加日志 debug 级别：入参 + 耗时 + 返回 ItemServiceImpl.java
5 Controller 层 ecid 处理 GlobalUtils.getEcid() 在 Controller 层获取并传递给 Service ItemController.java
6 恢复分页 XML 查询 保留完整的分页查询 SQL ItemMapper.xml
7 使用 PageDomain (非 PageHelper) 手动分页：先 count 查询总数，再 LIMIT 查询数据 ItemServiceImpl.java
8 删除 queryByCode 方法 删除所有 queryByCode 相关代码 ItemMapper.java, ItemService.java, ItemController.java
9 ResponseModel 泛型参数化 所有返回类型使用 ResponseModel<T> ItemController.java, ItemServiceImpl.java
10 Map 类型转换警告 使用 Convert.convert(Map.class, dto) 或 @SuppressWarnings ItemController.java, ItemServiceImpl.java
11 XML 使用 <sql> + <include> 片段 公共列定义和查询条件使用 SQL 片段复用 ItemMapper.xml
12 ItemApi ResponseModel 泛型 Feign 接口返回 ResponseModel<Void> ItemApi.java

问题 1 详解：ResponseModel 静态引用

错误:

return ResponseModel.success(result);  // ❌ success 不是静态方法

正确:

return ResponseModel.succeed(result);  // ✅ 使用静态方法 succeed

问题 2 详解：分页 XML / 详情 MP

分页查询 (原生 XML):

// ItemMapper.xml
<select id="queryPageList" resultType="com.witsoft.mica.smd.vo.ItemVO">
    SELECT <include refid="selectItemColumns"/>
    FROM dmp_md_item_info t
    <include refid="queryConditions"/>
    ORDER BY t.create_time DESC
    LIMIT #{dto.pageNo}, #{dto.pageSize}
</select>

详情查询 (MyBatis-Plus):

// ItemServiceImpl.java
ItemInfo item = itemMapper.selectById(id);

问题 5 详解：Controller 层 ecid 处理

Controller:

@PostMapping("/getPageList")
public ResponseModel<PageDomain<ItemVO>> queryPageList(@RequestBody ItemQueryDTO dto) {
    String ecid = GlobalUtils.getEcid();
    dto.setEcid(ecid);
    log.info("物料查询请求：ecid={}", ecid);
    return itemService.queryPageList(dto);
}

Service (直接使用传入的 ecid):

@Override
public PageDomain<ItemVO> queryPageList(ItemQueryDTO dto) {
    // 直接使用 dto.getEcid()，不再自己获取
    List<ItemVO> list = itemMapper.queryPageList(dto);
    // ...
}

问题 7 详解：使用 PageDomain

Service 手动分页:

@Override
public PageDomain<ItemVO> queryPageList(ItemQueryDTO dto) {
    int pageNo = dto.getPageNo() != null ? dto.getPageNo() : 1;
    int pageSize = dto.getPageSize() != null ? dto.getPageSize() : 10;
    
    // 查询总数
    long total = itemMapper.queryPageCount(dto);
    
    // 查询分页数据
    List<ItemVO> list = itemMapper.queryPageList(dto);
    
    // 构建 PageDomain
    PageDomain<ItemVO> page = new PageDomain<>(pageNo, pageSize, total);
    page.setList(list);
    
    return page;
}

问题 11 详解：XML SQL 片段

ItemMapper.xml:

<mapper namespace="com.witsoft.mica.smd.mapper.ItemMapper">
    
    <!-- 公共列定义 -->
    <sql id="selectItemColumns">
        t.id, t.ecid, t.item_code, t.item_name, t.item_spec, t.item_type,
        t.item_categorys_code, t.properties, t.unit_code, t.assist_unit_code,
        t.item_desc, t.vendor_code, t.good_warehouse, t.batch_control,
        t.picking_property, t.status, t.create_time, t.created_by,
        t.update_time, t.updated_by
    </sql>
    
    <!-- 公共查询条件 -->
    <sql id="queryConditions">
        <where>
            <if test="dto.ecid != null and dto.ecid != ''">
                AND t.ecid = #{dto.ecid}
            </if>
            <if test="dto.itemName != null and dto.itemName != ''">
                AND t.item_name LIKE CONCAT('%', #{dto.itemName}, '%')
            </if>
            <if test="dto.itemType != null and dto.itemType != ''">
                AND t.item_type = #{dto.itemType}
            </if>
            <if test="dto.status != null and dto.status != ''">
                AND t.status = #{dto.status}
            </if>
        </where>
    </sql>
    
    <!-- 分页查询 -->
    <select id="queryPageList" resultType="com.witsoft.mica.smd.vo.ItemVO">
        SELECT
        <include refid="selectItemColumns"/>
        FROM dmp_md_item_info t
        <include refid="queryConditions"/>
        ORDER BY t.create_time DESC
        LIMIT #{dto.pageNo}, #{dto.pageSize}
    </select>
    
    <!-- 总数查询 -->
    <select id="queryPageCount" resultType="long">
        SELECT COUNT(*)
        FROM dmp_md_item_info t
        <include refid="queryConditions"/>
    </select>
    
</mapper>

📁 后端完整文件清单 (10 个)

# 文件 路径 状态
1 ItemApi.java apis/smdm/ ✅ 已写入
2 ItemInfo.java smd/entity/ ✅ 已写入
3 ItemMapper.java smd/mapper/ ✅ 已写入
4 ItemMapper.xml resources/mapper/smd/ ✅ 已写入
5 ItemService.java smd/service/ ✅ 已写入
6 ItemServiceImpl.java smd/service/impl/ ✅ 已写入
7 ItemController.java smd/controller/ ✅ 已写入
8 ItemQueryDTO.java smd/dto/ ✅ 已写入
9 ItemFormDTO.java smd/dto/ ✅ 已写入
10 ItemVO.java smd/vo/ ✅ 已写入

📝 待办事项

Backend (mica-server)

  • 创建 apis/smdm/ItemApi.java (Feign 接口)
  • 创建 smd/entity/ItemInfo.java
  • 创建 smd/mapper/ItemMapper.java
  • 创建 smd/mapper/ItemMapper.xml
  • 创建 smd/service/ItemService.java
  • 创建 smd/service/impl/ItemServiceImpl.java
  • 创建 smd/controller/ItemController.java
  • 创建 smd/dto/ItemQueryDTO.java
  • 创建 smd/dto/ItemFormDTO.java
  • 创建 smd/vo/ItemVO.java

Frontend (mica-web)

  • 创建物料管理 API 封装 (app/composables/smd/useItemApi.ts)
  • 创建物料列表页面 (app/pages/smd/item/index.vue)
  • 创建物料详情/编辑表单 (app/pages/smd/item/form.vue)
  • 创建物料详情页面 (app/pages/smd/item/detail.vue)
  • 更新路由配置

🔗 相关资源

  • 数据库：dmp_smdm.dmp_md_item_info
  • 连接：mysql -h 47.99.209.185 -P 50036 -u witsoftd -p mica
  • 项目路径：/root/projects/wit/
  • 规范文档：/root/.openclaw/workspace-planner/memory/2026-08-04.md
Reference in New Issue View Git Blame Copy Permalink