[模块名称] 开发文档
一、表结构分析
1. 核心表设计
表 1：[表名]（[核心表 / 主表]）
表字段 |
类型 - 长度 |
描述（业务含义 + 约束） |
id |
[如：bigint] |
主键 |
[业务字段 1] |
[如：varchar (50)] |
[如：设备名称，unique index] |
[业务字段 2] |
[如：int] |
[如：设备类型，0-xxx/1-xxx（枚举）] |
[关联字段] |
[如：int] |
[如：关联 product 表的 id] |
[状态字段] |
[如：tinyint] |
[如：状态，0 - 未激活 / 1 - 正常，默认 0] |
... |
... |
... |
表 2：[表名]（[从表 / 辅助表]）
表字段 |
类型 - 长度 |
描述（业务含义 + 约束） |
id |
[类型] |
主键 |
[外键字段] |
[类型] |
[如：关联主表 id，非空] |
[业务字段] |
[类型] |
[如：运行数据值，保留 2 位小数] |
... |
... |
... |
2. 废弃 / 暂不使用表
表：[表名]（[说明：不需要 / 预留]）
表字段 |
类型 - 长度 |
描述 |
... |
... |
... |
3. 关键设计方案
场景：[如：数据存储策略]
- 方案一：[详细描述，如 “数据存本地”]
- 优缺点：[如：本地修改实时更新，但外部修改无法同步]
- 方案二：[详细描述，如 “实时查询第三方”]
- 延伸思考：[如：是否需要缓存？如何处理缓存失效？]
- 最终方案：[选择方案 x，理由：xxx（结合业务优先级）]
场景：[如：枚举 / 字典设计]
- 设计方式：[如：用枚举（code+desc），不建议常量]
- 示例：[设备类型：0 - 随身设备，1 - 固定设备]
二、接口设计
1. 接口清单
接口描述 |
请求方式 |
是否调用外部服务 |
备注（核心逻辑） |
[分页查询列表] |
GET |
否 |
[如：支持按 xxx 模糊查询 + xxx 精确筛选] |
[新增 xxx] |
POST |
是 |
[如：需先调用第三方注册，返回结果入库] |
[删除 xxx] |
DELETE |
否 |
[如：需级联删除中间表 xxx 数据] |
[详情查询] |
GET |
是 / 否 |
[如：依赖第三方接口返回实时数据] |
[同步数据] |
GET |
是 |
[如：从第三方拉取最新数据更新本地] |
... |
... |
... |
... |
2. 接口参数与响应
接口：[同步数据]
- 请求路径：[如：/api/syncData]
- 请求参数：[如：无 / 设备 id 列表]
- 响应出参：
Result{ code: "[状态码，如200]", msg: "[提示信息，如“同步成功”]", data: "[如：null/同步数量]" }
- 关键逻辑：
- [步骤 1：调用第三方 API 获取数据]
- [步骤 2：比对本地数据，差异更新]
- [异常处理：第三方调用失败返回 code=500，msg=“同步超时”]
3. 特殊场景处理
- 提示信息设计：
- 方案：[如：后端统一生成 msg，通过 code 枚举维护文案]
- 示例：[code=1001 → msg=“设备已存在”]
- 幂等性处理：[如：新增时校验唯一标识，避免重复提交]
三、外部 API 集成
1. 第三方接口详情
接口用途 |
API 地址 / 路径 |
认证方式 |
调用时机 |
[注册设备] |
[如：https://xxx/v5/register] |
[如：AK/SK 认证] |
[新增设备接口触发] |
[查询产品列表] |
[如：https://xxx/v5/products] |
[如：Token 认证] |
[新增设备时选择产品] |
2. 代码示例（核心片段）
// [注册设备调用示例] public void registerDevice(String deviceName) { // 1. 构建请求参数 // 2. 调用第三方API // 3. 处理返回结果（如：解析secret和key入库） }
3. 注意事项
- [如：第三方接口超时时间设置为 5 秒]
- [如：失败重试机制：最多重试 2 次，间隔 1 秒]
四、附件
- 流程图：[如：同步数据时序图]
【图略】 - 补充说明：[如：测试环境第三方接口地址不同]
