166 lines
5.3 KiB
Markdown
166 lines
5.3 KiB
Markdown
# API 一致性分析报告：NestJS v1 vs api.niucloud.com
|
||
|
||
## 📊 总体对比概览
|
||
|
||
| 指标 | NestJS v1 | Java (官方) | 差距 |
|
||
|------|-----------|-------------|------|
|
||
| 总路由数 | 701 | 2,030 | -1,329 |
|
||
| 模块覆盖率 | 约35% | 100% | -65% |
|
||
| 关键业务模块完整性 | 部分缺失 | 完整 | 需补齐 |
|
||
|
||
## 🚨 关键发现
|
||
|
||
### 1. 重大缺失模块（P0优先级）
|
||
|
||
#### 商品管理模块（adminapi/goods）
|
||
- **缺失率**：100%（0/124）
|
||
- **关键缺失接口**：
|
||
- `GET /adminapi/shop/goods/attr` - 商品属性管理
|
||
- `GET /adminapi/shop/goods/attr/list` - 商品属性列表
|
||
- `GET /adminapi/shop/goods/category` - 商品分类管理
|
||
- `GET /adminapi/shop/goods/spec` - 商品规格管理
|
||
|
||
#### 订单管理模块（adminapi/order）
|
||
- **缺失率**：100%（0/42）
|
||
- **关键缺失接口**：
|
||
- `GET /adminapi/shop/order/config` - 订单配置
|
||
- `GET /adminapi/shop/order/invoice` - 发票管理
|
||
- `POST /adminapi/shop/order/delivery` - 订单发货
|
||
|
||
#### 营销模块（adminapi/marketing）
|
||
- **缺失率**：100%（0/69）
|
||
- **关键缺失接口**：
|
||
- `GET /adminapi/shop/goods/coupon` - 优惠券管理
|
||
- `GET /adminapi/shop/goods/coupon/init` - 优惠券初始化
|
||
- `POST /adminapi/shop/goods/coupon` - 创建优惠券
|
||
|
||
#### 物流模块（adminapi/delivery）
|
||
- **缺失率**：100%（0/53）
|
||
- **关键缺失接口**：
|
||
- `GET /adminapi/shop/delivery/company` - 物流公司管理
|
||
- `GET /adminapi/shop/delivery/company/list` - 物流公司列表
|
||
|
||
### 2. 前台API缺失（P1优先级）
|
||
|
||
#### 商品前台接口（api/goods）
|
||
- **缺失率**：100%（0/31）
|
||
- **关键缺失接口**：
|
||
- `GET /api/shop/goods/category` - 商品分类查询
|
||
- `GET /api/shop/goods/category/tree` - 分类树形结构
|
||
- `GET /api/shop/goods` - 商品列表
|
||
|
||
#### 订单前台接口（api/order）
|
||
- **缺失率**：93%（14/15）
|
||
- **关键缺失接口**：
|
||
- `GET /api/shop/order` - 订单列表
|
||
- `GET /api/shop/order/{order_id}` - 订单详情
|
||
- `POST /api/shop/order` - 创建订单
|
||
|
||
#### 购物车接口（api/cart）
|
||
- **缺失率**：100%（0/9）
|
||
- **关键缺失接口**：
|
||
- `GET /api/shop/cart` - 购物车列表
|
||
- `POST /api/shop/cart` - 添加购物车
|
||
- `DELETE /api/shop/cart/{id}` - 删除购物车商品
|
||
|
||
### 3. 路由命名不一致问题
|
||
|
||
#### 路径重复问题（MIXED类型）
|
||
- **问题描述**：路由路径出现重复前缀
|
||
- **示例**：
|
||
- `MIXED /adminapi/shop/goods/attr/adminapi/shop/goods/attr`
|
||
- `MIXED /api/shop/goods/category/api/shop/goods/category`
|
||
- `MIXED /serve/{site_id}/serve/{site_id}`
|
||
|
||
#### HTTP方法缺失
|
||
- **PUT方法缺失**：如`PUT /adminapi/diy/diy/{id}`
|
||
- **DELETE方法缺失**：如`DELETE /adminapi/verify/verifier/{id}`
|
||
- **POST配置接口缺失**：如`POST /adminapi/pay/channel/set/{channel}/{type}`
|
||
|
||
### 4. 路径参数风格差异
|
||
|
||
| 官方文档 | NestJS实现 | 一致性 |
|
||
|----------|------------|--------|
|
||
| `{key}` | `:key` | ✅ 语义一致，格式差异 |
|
||
| `{type}` | `:type` | ✅ 语义一致，格式差异 |
|
||
| `{site_id}` | `:site_id` | ✅ 语义一致，格式差异 |
|
||
|
||
## 🎯 实施优先级建议
|
||
|
||
### P0优先级（电商核心链路）
|
||
1. **商品管理模块** - 商品属性、分类、规格管理
|
||
2. **订单管理模块** - 订单配置、发货、发票管理
|
||
3. **购物车模块** - 购物车增删改查
|
||
4. **支付模块** - 支付配置、退款管理
|
||
|
||
### P1优先级（商品触达与履约）
|
||
1. **营销模块** - 优惠券、营销活动管理
|
||
2. **物流模块** - 物流公司、配送配置
|
||
3. **商品前台** - 商品展示、分类查询
|
||
|
||
### P2优先级（平台管理能力）
|
||
1. **站点管理** - 站点配置、账户管理
|
||
2. **系统管理** - 系统配置、权限管理
|
||
3. **会员管理** - 会员等级、积分管理
|
||
|
||
### P3优先级（内容与插件）
|
||
1. **CMS模块** - 文章分类、内容管理
|
||
2. **插件管理** - 插件安装、配置
|
||
3. **兑换模块** - 积分兑换、商品兑换
|
||
|
||
## 🔧 具体修复建议
|
||
|
||
### 1. 路由规范化
|
||
- 清除所有`MIXED`重复前缀
|
||
- 统一使用RESTful命名规范
|
||
- 确保路径参数一致性
|
||
|
||
### 2. HTTP方法补齐
|
||
- 为资源类接口补齐PUT/DELETE方法
|
||
- 添加必要的POST配置接口
|
||
- 遵循RESTful设计原则
|
||
|
||
### 3. 模块落地位置
|
||
```
|
||
libs/wwjcloud-core/src/controllers/adminapi/{domain}/
|
||
libs/wwjcloud-core/src/controllers/api/{domain}/
|
||
```
|
||
|
||
### 4. 实施里程碑
|
||
|
||
#### 里程碑M1（P0完成）
|
||
- 完成商品管理全量接口
|
||
- 完成订单管理核心接口
|
||
- 补齐购物车和支付接口
|
||
- 清理相关模块MIXED路径
|
||
|
||
#### 里程碑M2（P1完成）
|
||
- 落地营销和物流模块
|
||
- 补齐商品前台接口
|
||
|
||
#### 里程碑M3（P2完成）
|
||
- 补齐站点和系统管理
|
||
- 完成会员管理缺口
|
||
|
||
#### 里程碑M4（P3完成）
|
||
- 补齐CMS和插件管理
|
||
- 完成兑换模块
|
||
|
||
## 📈 预期成果
|
||
|
||
完成所有修复后，预计：
|
||
- **路由覆盖率**：从35%提升至95%+
|
||
- **API一致性**：与官方文档保持100%对齐
|
||
- **业务功能完整性**：支持完整的电商业务流程
|
||
- **代码质量**：消除所有路由命名不一致问题
|
||
|
||
## 🚀 下一步行动
|
||
|
||
1. 立即启动P0优先级模块开发
|
||
2. 建立自动化测试确保API兼容性
|
||
3. 定期运行路由对比脚本验证进度
|
||
4. 与前端团队协调接口对接计划
|
||
|
||
---
|
||
|
||
*本报告基于路由对比数据生成，建议定期更新以反映最新进展* |