Ooder 新功能开发必读手册

版本: v1.0
适用范围: Ooder 全模块新功能开发
强制级别: 必须遵循

一、开发前置检查清单

在开始任何新功能开发前，请确认已完成以下检查：

• 阅读并理解本文档所有规范
• 确认功能涉及的数据实体关系
• 设计完整的前后端API闭环
• 确定需要的字典枚举类型
• 规划页面与菜单结构

二、三闭环检查要求

2.1 能力生命周期流程闭环

目标: 确保功能从创建到销毁的完整生命周期可控

检查项:

状态机设计规范:

┌─────────┐    操作    ┌─────────┐    操作    ┌─────────┐
│  初始   │ ───────► │  中间   │ ───────► │  终态   │
└─────────┘          └─────────┘          └─────────┘

代码示例:

@Dict(code = "xxx_status", name = "XXX状态")
public enum XxxStatus implements DictItem {
    DRAFT("DRAFT", "草稿", "草稿状态", "ri-draft-line", 1),
    ACTIVE("ACTIVE", "激活", "激活状态", "ri-check-line", 2),
    SUSPENDED("SUSPENDED", "暂停", "暂停状态", "ri-pause-line", 3);
    
    // 必须实现 DictItem 接口
}

2.2 能力数据实体关系闭环

目标: 确保数据实体之间的关联关系完整一致

检查项:

实体关系图模板:

EntityA ──1:N──► EntityB
    │
    └──N:M──► EntityC
                  │
                  └──1:1──► EntityD

数据一致性保障:

// 正确模式：操作后重新加载
async function removeItem(id) {
    const response = await fetch('/api/v1/items/' + id, { method: 'DELETE' });
    const result = await response.json();
    if (result.code === 200) {
        loadData();  // 重新加载确保数据一致
    }
}

// 错误模式：仅本地删除
function removeItem(id) {
    items = items.filter(i => i.id !== id);  // 不要这样做！
    render();
}

2.3 按钮事件和API闭环

目标: 确保每个用户操作都能正确调用后端服务

检查项:

标准闭环模式:

async function standardAction(params) {
    // 1. 用户确认（可选）
    if (!confirm('确定要执行此操作吗？')) return;
    
    try {
        // 2. 调用后端API
        const response = await fetch('/api/v1/resource/' + id, {
            method: 'POST',
            headers: {'Content-Type': 'application/json'},
            body: JSON.stringify(data)
        });
        const result = await response.json();
        
        // 3. 处理结果
        if (result.code === 200) {
            // 4. 刷新数据
            loadData();
        } else {
            alert('操作失败: ' + result.message);
        }
    } catch (error) {
        console.error('Operation failed:', error);
        alert('操作失败');
    }
}

闭环检查表模板:

create()

POST /api/v1/xxx

XxxController.create()

update()

PUT /api/v1/xxx/{id}

XxxController.update()

remove()

DELETE /api/v1/xxx/{id}

XxxController.delete()

三、字典表规范

3.1 架构设计

后端枚举 ──@Dict注解──► DictService ──API──► 前端DictCache
    │                        │                      │
    └──实现DictItem接口──► 自动注册字典 ──预加载──► 本地缓存

3.2 后端实现规范

字典注解定义:

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface Dict {
    String code();                          // 字典代码（必填）
    String name() default "";               // 字典名称
    String description() default "";        // 字典描述
    boolean cacheable() default true;       // 是否缓存
}

字典项接口定义:

public interface DictItem {
    String getCode();        // 代码
    String getName();        // 名称
    String getDescription(); // 描述
    String getIcon();        // 图标
    int getSort();           // 排序
}

枚举实现范例:

@Dict(code = "participant_type", name = "参与者类型", description = "场景参与者的类型")
public enum ParticipantType implements DictItem {
    
    USER("USER", "用户", "人类用户参与者", "ri-user-line", 1),
    AGENT("AGENT", "Agent", "智能代理参与者", "ri-robot-line", 2),
    SUPER_AGENT("SUPER_AGENT", "超级Agent", "超级智能代理参与者", "ri-robot-2-line", 3);

    private final String code;
    private final String name;
    private final String description;
    private final String icon;
    private final int sort;

    ParticipantType(String code, String name, String description, String icon, int sort) {
        this.code = code;
        this.name = name;
        this.description = description;
        this.icon = icon;
        this.sort = sort;
    }

    @Override
    public String getCode() { return code; }
    @Override
    public String getName() { return name; }
    @Override
    public String getDescription() { return description; }
    @Override
    public String getIcon() { return icon; }
    @Override
    public int getSort() { return sort; }
}

3.3 前端使用规范

字典缓存工具:

// 初始化
await DictCache.init();

// 获取字典
const dict = await DictCache.getDict(DictCache.DICT_CODES.PARTICIPANT_TYPE);

// 获取字典项列表
const items = await DictCache.getDictItems(DictCache.DICT_CODES.PARTICIPANT_TYPE);

// 获取字典项名称
const name = await DictCache.getDictItemName(DictCache.DICT_CODES.PARTICIPANT_TYPE, 'USER');

字典代码常量:

var DICT_CODES = {
    CAPABILITY_TYPE: 'capability_type',
    PARTICIPANT_TYPE: 'participant_type',
    PARTICIPANT_ROLE: 'participant_role',
    SCENE_GROUP_STATUS: 'scene_group_status',
    // ... 新增字典需在此添加
};

3.4 新增字典步骤

1. 创建枚举类，实现

   DictItem

   接口
2. 添加

   @Dict

   注解
3. 在

   DictService.init()

   中注册枚举类
4. 在前端

   DictCache.DICT_CODES

   中添加字典代码常量

四、API响应格式规范

4.1 统一响应结构

{
    "code": 200,
    "status": "success",
    "message": "操作成功",
    "data": {},
    "timestamp": "2026-03-01 10:30:00.000",
    "requestId": "REQ_1234567890_1234"
}

4.2 响应码定义

4.3 分页响应结构

{
    "code": 200,
    "data": {
        "list": [],
        "total": 100,
        "pageNum": 1,
        "pageSize": 20,
        "pages": 5
    }
}

五、命名规范

5.1 包命名规范

dto

model

controller

service

config

5.2 类命名规范

5.3 API路径规范

六、"我的"系列页面设计原则

遵循"以用户为中心"的展示原则：

listByCreator()

TodoService.listMyTodos()

HistoryService.listMyHistory()

七、版本兼容规范

7.1 Java版本要求

• 最低版本: Java 8
• 推荐版本: Java 11+

7.2 API版本管理

• API 路径包含版本号：

  /api/v1/

• 版本升级时保持向后兼容
• 废弃接口需在文档中标注

八、开发流程规范

8.1 标准开发流程

1. 需求分析
   └── 绘制实体关系图
   └── 确定状态机
   
2. 后端开发
   └── 创建DTO/枚举
   └── 实现Service
   └── 实现Controller
   └── 注册字典
   
3. 前端开发
   └── 创建页面
   └── 实现API调用
   └── 使用字典缓存
   
4. 闭环检查
   └── 生命周期闭环
   └── 数据实体闭环
   └── 按钮API闭环
   
5. 测试验证
   └── 功能测试
   └── API测试
   └── 数据一致性测试

8.2 提交前检查

• 所有API都有对应的前端调用
• 所有操作都有错误处理
• 数据操作后正确刷新
• 字典枚举已注册
• 代码编译通过

九、相关文档

十、快速参考

10.1 闭环检查清单

□ 生命周期闭环：创建→查询→更新→删除 API完整
□ 数据实体闭环：关系明确、级联处理、数据一致
□ 按钮API闭环：每个操作都调用后端、操作后刷新

10.2 字典创建清单

□ 创建枚举类实现 DictItem
□ 添加 @Dict 注解
□ 在 DictService 注册
□ 在前端添加 DICT_CODES 常量

10.3 API创建清单

□ 定义请求/响应DTO
□ 实现 Service 接口和实现类
□ 实现 Controller
□ 添加 @CrossOrigin 注解
□ 前端创建对应调用函数