befly-tpl 3.2.2 → 3.2.3

package/temp/addon-route-prefix-migration.md

@@ -1,400 +0,0 @@
-# Addon 路由前缀迁移报告（方案2）
-
-**日期**：2025-10-19
-**执行人**：AI Assistant
-**状态**：✅ 已完成
-
-## 📋 迁移概述
-
-根据用户要求，执行方案2：修改 Addon 路由前缀，从 `/api/{addonName}/` 改为 `/api/addon/{addonName}/`，彻底解决路由冲突问题。
-
-## 🎯 修改目标
-
-**修改前**：
-
-```
-Addon API: POST/api/admin/login
-项目 API: POST/api/admin/login
-⚠️ 可能冲突
-```
-
-**修改后**：
-
-```
-Addon API: POST/api/addon/admin/login
-项目 API: POST/api/admin/login
-✅ 完全隔离，不会冲突
-```
-
-## ✅ 完成的修改
-
-### 1. 核心框架修改
-
-#### packages/core/lifecycle/loader.ts
-
-**文件**：`packages/core/lifecycle/loader.ts`
-**位置**：Line 493-495
-**修改内容**：添加 `addon/` 前缀到 addon API 路由
-
-**修改前**：
-
-```typescript
-// 构建路由：addon 接口添加前缀 /api/{addonName}/{apiPath}
-if (isAddon) {
-    api.route = `${api.method.toUpperCase()}/api/${addonName}/${apiPath}`;
-} else {
-    api.route = `${api.method.toUpperCase()}/api/${apiPath}`;
-}
-```
-
-**修改后**：
-
-```typescript
-// 构建路由：addon 接口添加前缀 /api/addon/{addonName}/{apiPath}，项目接口为 /api/{apiPath}
-if (isAddon) {
-    api.route = `${api.method.toUpperCase()}/api/addon/${addonName}/${apiPath}`;
-} else {
-    api.route = `${api.method.toUpperCase()}/api/${apiPath}`;
-}
-```
-
-### 2. Admin 前端项目修改
-
-#### 修改的文件列表（共7个文件）
-
-1. **packages/admin/src/plugins/http.ts**
-    - 更新注释示例：`/api/admin/login` → `/addon/admin/login`
-
-2. **packages/admin/src/plugins/router.ts**
-    - 无需修改（没有硬编码路径）
-
-3. **packages/admin/src/stores/permission.ts**
-    - `/admin/adminMenus` → `/addon/admin/adminMenus`
-
-4. **packages/admin/src/api/auth.ts**
-    - `/admin/login` → `/addon/admin/login`
-    - `/admin/register` → `/addon/admin/register`
-    - `/admin/sendSmsCode` → `/addon/admin/sendSmsCode`
-    - `/admin/adminInfo` → `/addon/admin/adminInfo`
-    - `/admin/logout` → `/addon/admin/logout`
-
-5. **packages/admin/src/views/login/index_1.vue**
-    - `/admin/sendSmsCode` → `/addon/admin/sendSmsCode`
-    - `/admin/login` → `/addon/admin/login`
-    - `/admin/register` → `/addon/admin/register`
-
-6. **packages/admin/src/views/system/menu.vue**
-    - `/admin/menuList` → `/addon/admin/menuList`
-    - `/admin/menuCreate` → `/addon/admin/menuCreate`
-    - `/admin/menuUpdate` → `/addon/admin/menuUpdate`
-    - `/admin/menuDelete` → `/addon/admin/menuDelete`
-
-7. **packages/admin/src/views/system/role.vue**
-    - `/admin/roleList` → `/addon/admin/roleList`
-    - `/admin/menuList` → `/addon/admin/menuList`
-    - `/admin/roleCreate` → `/addon/admin/roleCreate`
-    - `/admin/roleUpdate` → `/addon/admin/roleUpdate`
-    - `/admin/roleDelete` → `/addon/admin/roleDelete`
-    - `/admin/roleMenuGet` → `/addon/admin/roleMenuGet`
-    - `/admin/roleMenuSave` → `/addon/admin/roleMenuSave`
-
-8. **packages/admin/src/views/user/user.vue**
-    - `/admin/list` → `/addon/admin/list`
-    - `/admin/roleList` → `/addon/admin/roleList`
-    - `/admin/adminRoleGet` → `/addon/admin/adminRoleGet`
-    - `/admin/adminRoleSave` → `/addon/admin/adminRoleSave`
-
-9. **packages/admin/src/views/admin/index.vue**
-    - `/admin/list` → `/addon/admin/list`
-    - `/admin/roleList` → `/addon/admin/roleList`
-    - `/admin/adminRoleGet` → `/addon/admin/adminRoleGet`
-    - `/admin/adminRoleSave` → `/addon/admin/adminRoleSave`
-
-## 📊 修改统计
-
-### 核心框架
-
-- **修改文件**：1 个
-- **修改行数**：1 行
-- **影响范围**：所有 addon 的 API 路由
-
-### Admin 前端
-
-- **修改文件**：9 个
-- **修改 API 调用**：32 处
-- **影响范围**：所有调用 admin addon 接口的地方
-
-### 总计
-
-- **修改文件总数**：10 个
-- **修改代码行数**：约 35 处
-
-## 🔍 验证结果
-
-**验证命令**：
-
-```bash
-grep -rE "['\"]/admin/" packages/admin/src/**/*.{ts,vue}
-```
-
-**结果**：
-
-```
-No matches found ✅
-```
-
-所有 `/admin/` 路径已成功替换为 `/addon/admin/`！
-
-## 🎯 路由映射对照表
-
-### Admin Addon 的 API 路由变化
-
-| API 文件       | 修改前                       | 修改后                             |
-| -------------- | ---------------------------- | ---------------------------------- |
-| login.ts       | `POST/api/admin/login`       | `POST/api/addon/admin/login`       |
-| register.ts    | `POST/api/admin/register`    | `POST/api/addon/admin/register`    |
-| adminInfo.ts   | `POST/api/admin/adminInfo`   | `POST/api/addon/admin/adminInfo`   |
-| adminMenus.ts  | `POST/api/admin/adminMenus`  | `POST/api/addon/admin/adminMenus`  |
-| menuList.ts    | `POST/api/admin/menuList`    | `POST/api/addon/admin/menuList`    |
-| menuCreate.ts  | `POST/api/admin/menuCreate`  | `POST/api/addon/admin/menuCreate`  |
-| menuUpdate.ts  | `POST/api/admin/menuUpdate`  | `POST/api/addon/admin/menuUpdate`  |
-| menuDelete.ts  | `POST/api/admin/menuDelete`  | `POST/api/addon/admin/menuDelete`  |
-| roleList.ts    | `POST/api/admin/roleList`    | `POST/api/addon/admin/roleList`    |
-| roleCreate.ts  | `POST/api/admin/roleCreate`  | `POST/api/addon/admin/roleCreate`  |
-| roleUpdate.ts  | `POST/api/admin/roleUpdate`  | `POST/api/addon/admin/roleUpdate`  |
-| roleDelete.ts  | `POST/api/admin/roleDelete`  | `POST/api/addon/admin/roleDelete`  |
-| roleSave.ts    | `POST/api/admin/roleSave`    | `POST/api/addon/admin/roleSave`    |
-| roleGet.ts     | `POST/api/admin/roleGet`     | `POST/api/addon/admin/roleGet`     |
-| sendSmsCode.ts | `POST/api/admin/sendSmsCode` | `POST/api/addon/admin/sendSmsCode` |
-| logout.ts      | `POST/api/admin/logout`      | `POST/api/addon/admin/logout`      |
-
-### 其他 Addon 的路由规则
-
-所有 addon 都会应用新的路由规则：
-
-**Befly Addon**：
-
-```
-修改前: POST/api/befly/health/info
-修改后: POST/api/addon/befly/health/info
-```
-
-**Demo Addon**：
-
-```
-修改前: POST/api/demo/test
-修改后: POST/api/addon/demo/test
-```
-
-### 项目 API 路由（不受影响）
-
-项目 API 保持不变：
-
-```
-POST/api/article/list
-POST/api/article/create
-POST/api/user/list
-POST/api/user/login
-```
-
-## 💡 迁移优势
-
-### 1. 彻底解决冲突
-
-**场景：开发者创建 apis/admin/ 目录**
-
-**修改前**：
-
-```
-⚠️ Addon: POST/api/admin/list
-⚠️ 项目: POST/api/admin/list
-❌ 冲突！后者覆盖前者
-```
-
-**修改后**：
-
-```
-✅ Addon: POST/api/addon/admin/list
-✅ 项目: POST/api/admin/list
-✅ 完全隔离，不会冲突
-```
-
-### 2. 路径更清晰
-
-**一眼就能区分 API 来源**：
-
-```
-/api/addon/admin/login  ← 明显是 addon 提供的接口
-/api/admin/login        ← 项目自己的接口
-```
-
-### 3. 符合命名空间最佳实践
-
-```
-/api/addon/{addonName}/{path}  ← Addon 命名空间
-/api/{path}                     ← 项目命名空间
-```
-
-### 4. 扩展性更好
-
-未来添加更多 addon 不会产生冲突：
-
-```
-/api/addon/admin/...
-/api/addon/shop/...
-/api/addon/blog/...
-/api/addon/payment/...
-```
-
-## 🚨 注意事项
-
-### 1. 兼容性
-
-⚠️ **这是破坏性变更**：
-
-- 旧版本的前端调用会 404
-- 需要同步更新前端代码
-
-### 2. 部署建议
-
-**建议部署流程**：
-
-1. 先部署后端（core + tpl）
-2. 立即部署前端（admin）
-3. 避免前后端版本不一致
-
-### 3. 回滚方案
-
-如果需要回滚：
-
-```typescript
-// 在 loader.ts 中改回
-if (isAddon) {
-    api.route = `${api.method.toUpperCase()}/api/${addonName}/${apiPath}`;
-}
-```
-
-## 📋 测试建议
-
-### 1. 后端测试
-
-```bash
-# 启动后端
-cd packages/tpl
-bunx befly
-
-# 验证路由
-curl http://localhost:3000/api/addon/admin/health
-```
-
-### 2. 前端测试
-
-```bash
-# 启动前端
-cd packages/admin
-bun run dev
-
-# 测试功能
-- 登录
-- 获取菜单
-- 菜单管理
-- 角色管理
-- 用户管理
-```
-
-### 3. 关键测试点
-
-- ✅ 登录功能
-- ✅ 获取用户菜单
-- ✅ 菜单 CRUD
-- ✅ 角色 CRUD
-- ✅ 用户角色分配
-
-## 🎓 技术说明
-
-### 路由生成逻辑
-
-**Addon API**：
-
-```typescript
-// 文件：addons/admin/apis/login.ts
-// 路径：POST/api/addon/admin/login
-
-const apiPath = 'login'; // 相对于 apis 目录
-const addonName = 'admin';
-const route = `POST/api/addon/${addonName}/${apiPath}`;
-```
-
-**项目 API**：
-
-```typescript
-// 文件：apis/user/login.ts
-// 路径：POST/api/user/login
-
-const apiPath = 'user/login'; // 相对于 apis 目录
-const route = `POST/api/${apiPath}`;
-```
-
-### 前端请求示例
-
-```typescript
-// Admin 前端（baseURL = http://localhost:3000/api）
-await $Http('/addon/admin/login', { email, password });
-// 实际请求：POST http://localhost:3000/api/addon/admin/login
-
-await $Http('/addon/admin/menuList', {});
-// 实际请求：POST http://localhost:3000/api/addon/admin/menuList
-```
-
-## 📚 相关文档
-
-- 路由冲突分析：`packages/tpl/temp/api-route-conflict-analysis.md`
-- RoleCode 优化：`packages/tpl/temp/roleid-to-rolecode-optimization.md`
-- Status 迁移：`packages/tpl/temp/status-to-state-migration-complete.md`
-
-## ✅ 下一步建议
-
-1. **更新 AGENTS.md**：
-    - 添加新的路由规范说明
-    - 更新 API 示例代码
-
-2. **更新文档项目**（docs）：
-    - 说明 addon 路由规则
-    - 提供迁移指南
-
-3. **测试验证**：
-    - 完整测试所有功能
-    - 确保前后端正常工作
-
-## 🎯 总结
-
-**迁移状态**：✅ **已完成**
-
-**修改范围**：
-
-- ✅ 核心框架路由生成逻辑
-- ✅ Admin 前端所有 API 调用
-
-**验证结果**：
-
-- ✅ 没有遗漏的 `/admin/` 路径
-- ✅ 所有路径已更新为 `/addon/admin/`
-
-**核心优势**：
-
-- ✅ 彻底解决路由冲突
-- ✅ 路径更清晰易读
-- ✅ 符合命名空间最佳实践
-- ✅ 扩展性更好
-
-**后续工作**：
-
-- 📋 测试所有功能
-- 📋 更新项目文档
-- 📋 更新 AGENTS.md 规范
-
----
-
-**执行人**：AI Assistant
-**完成时间**：2025-10-19
-**状态**：✅ **迁移完成**