befly-tpl 3.2.2 → 3.2.3

package/temp/api-route-conflict-analysis.md

@@ -1,441 +0,0 @@
-# API 路由冲突分析报告
-
-**日期**：2025-10-19
-**分析人**：AI Assistant
-
-## 📋 问题描述
-
-用户提出的问题：
-
-> 如果 admin 组件中有 list 接口，tpl 项目的 apis 目录下有 admin/list.ts，这2个接口路径会不会重复，会不会冲突？
-
-具体场景：
-
-1. **Addon API**：`packages/tpl/addons/admin/apis/list.ts`
-2. **项目 API**：`packages/tpl/apis/admin/list.ts`
-
-## 🔍 深度分析
-
-### 1. 路由生成规则
-
-根据 `packages/core/lifecycle/loader.ts` 的代码分析（Line 493-497）：
-
-```typescript
-// 构建路由：addon 接口添加前缀 /api/{addonName}/{apiPath}
-if (isAddon) {
-    api.route = `${api.method.toUpperCase()}/api/${addonName}/${apiPath}`;
-} else {
-    api.route = `${api.method.toUpperCase()}/api/${apiPath}`;
-}
-apiRoutes.set(api.route, api);
-```
-
-**关键发现**：
-
-- **Addon API** 会添加 addon 名称前缀：`/api/{addonName}/{apiPath}`
-- **项目 API** 只有基础前缀：`/api/{apiPath}`
-- 路由以 `Map` 结构存储，key 为 `${METHOD}${PATH}`
-
-### 2. 实际路径映射
-
-#### 场景 A：Addon 中的 list.ts
-
-**文件位置**：
-
-```
-packages/tpl/addons/admin/apis/list.ts
-```
-
-**生成的路由**：
-
-```
-POST/api/admin/list
-```
-
-**计算过程**：
-
-- `isAddon = true`
-- `addonName = 'admin'`
-- `apiPath = 'list'`（相对于 apis 目录的路径）
-- `method = 'POST'`（默认）
-- 结果：`POST/api/admin/list`
-
-#### 场景 B：项目中的 admin/list.ts
-
-**文件位置**：
-
-```
-packages/tpl/apis/admin/list.ts
-```
-
-**生成的路由**：
-
-```
-POST/api/admin/list
-```
-
-**计算过程**：
-
-- `isAddon = false`
-- `apiPath = 'admin/list'`（相对于 apis 目录的路径）
-- `method = 'POST'`（默认）
-- 结果：`POST/api/admin/list`
-
-### 3. 冲突分析结论
-
-**⚠️ 会发生路由冲突！**
-
-两个接口生成的路由完全相同：
-
-```
-POST/api/admin/list
-```
-
-## 🚨 冲突后果
-
-### 1. Map 覆盖问题
-
-```typescript
-apiRoutes.set(api.route, api);
-```
-
-- `apiRoutes` 是 `Map` 结构
-- 如果 key 相同，后加载的会**覆盖**先加载的
-- **最终只有一个接口生效**
-
-### 2. 加载顺序
-
-根据 `packages/core/lifecycle/lifecycle.ts` 的加载顺序（Line 70-120）：
-
-```typescript
-// 实际的加载顺序
-1. 先加载所有 addon 的 APIs（按 addon 名称顺序）
-2. 再加载项目（app）的 APIs
-```
-
-**验证代码**：
-
-```typescript
-// 1. 先加载 addon APIs
-for (const addon of addons) {
-    if (hasApis) {
-        await Loader.loadApis(addon, this.apiRoutes, {
-            isAddon: true,
-            addonName: addon
-        });
-    }
-}
-
-// 2. 后加载 app APIs
-await Loader.loadApis('app', this.apiRoutes);
-```
-
-**如果发生冲突**：
-
-- Addon 的 `list.ts` 先注册 → `POST/api/admin/list`
-- 项目的 `admin/list.ts` 后注册 → **覆盖** addon 的接口
-- **结果**：addon 的接口失效，项目接口生效，且**没有任何警告**
-
-### 3. 实际影响
-
-❌ **严重问题**：
-
-- 用户无法预期哪个接口会生效
-- 调试困难，没有冲突警告
-- 可能导致接口行为异常
-
-## 🎯 为什么会设计成这样？
-
-### 当前的路径设计逻辑
-
-```
-Addon API 路径格式：
-/api/{addonName}/{apiPath}
-
-项目 API 路径格式：
-/api/{apiPath}
-```
-
-**设计意图**：
-
-- Addon 用 addon 名称作为命名空间隔离
-- 项目 API 可以自由组织目录结构
-
-### 存在的问题
-
-**场景 1**：Addon 名称与项目目录重名
-
-```
-✅ Addon: addons/admin/apis/list.ts → /api/admin/list
-❌ 项目: apis/admin/list.ts → /api/admin/list
-⚠️ 冲突！
-```
-
-**场景 2**：Addon 名称与项目目录不重名
-
-```
-✅ Addon: addons/admin/apis/list.ts → /api/admin/list
-✅ 项目: apis/user/list.ts → /api/user/list
-✅ 不冲突
-```
-
-**场景 3**：项目 API 在根目录
-
-```
-✅ Addon: addons/admin/apis/list.ts → /api/admin/list
-✅ 项目: apis/list.ts → /api/list
-✅ 不冲突
-```
-
-## 📊 实际案例验证
-
-### 当前项目结构
-
-**Addon APIs**：
-
-```
-packages/tpl/addons/admin/apis/
-├── login.ts → POST/api/admin/login
-├── register.ts → POST/api/admin/register
-├── menuList.ts → POST/api/admin/menuList
-├── roleList.ts → POST/api/admin/roleList
-└── ... (共16个文件)
-```
-
-**项目 APIs**：
-
-```
-packages/tpl/apis/
-├── article/
-│   ├── list.ts → POST/api/article/list
-│   ├── create.ts → POST/api/article/create
-│   └── ...
-├── user/
-│   ├── list.ts → POST/api/user/list
-│   └── login.ts → POST/api/user/login
-└── test/
-```
-
-**当前状态**：
-
-- ✅ **没有冲突**：因为项目 API 使用 `article/`、`user/` 等目录
-- ✅ **addon 名称为 `admin`**，项目中没有 `admin/` 目录
-
-### 潜在冲突场景
-
-**如果创建**：
-
-```
-packages/tpl/apis/admin/list.ts
-```
-
-**冲突分析**：
-
-```
-Addon: addons/admin/apis/list.ts → POST/api/admin/list ❌
-项目: apis/admin/list.ts → POST/api/admin/list ❌
-⚠️ 路由冲突！
-```
-
-## 💡 解决方案建议
-
-### 方案 1：修改 Addon 路由前缀（推荐）
-
-**修改 loader.ts**：
-
-```typescript
-// 当前
-if (isAddon) {
-    api.route = `${api.method.toUpperCase()}/api/${addonName}/${apiPath}`;
-}
-
-// 建议改为
-if (isAddon) {
-    api.route = `${api.method.toUpperCase()}/api/addon/${addonName}/${apiPath}`;
-}
-```
-
-**效果**：
-
-```
-Addon: addons/admin/apis/list.ts → POST/api/addon/admin/list ✅
-项目: apis/admin/list.ts → POST/api/admin/list ✅
-✅ 不冲突！
-```
-
-**优点**：
-
-- 完全隔离 addon 和项目 API
-- 路径更清晰，一看就知道是 addon 接口
-- 符合命名空间最佳实践
-
-**缺点**：
-
-- 需要修改现有接口路径（破坏性变更）
-- 前端调用需要更新
-
-### 方案 2：添加冲突检测
-
-**修改 loader.ts**：
-
-```typescript
-// 在注册路由前检查
-if (apiRoutes.has(api.route)) {
-    const existing = apiRoutes.get(api.route);
-    Logger.error(`路由冲突检测：${api.route}`);
-    Logger.error(`已存在的接口：${existing.name}`);
-    Logger.error(`新接口：${api.name}`);
-    throw new Error(`路由冲突：${api.route} 已被注册`);
-}
-apiRoutes.set(api.route, api);
-```
-
-**优点**：
-
-- 立即发现冲突
-- 不改变路由规则
-- 强制开发者解决冲突
-
-**缺点**：
-
-- 不解决根本问题
-- 开发者需要手动避免冲突
-
-### 方案 3：项目规范约束（临时方案）
-
-**在 AGENTS.md 中添加规范**：
-
-```markdown
-## API 路由命名规范
-
-### 禁止事项
-
-❌ 禁止在项目 apis 目录下创建与 addon 名称相同的目录
-
-### 允许的目录结构
-
-✅ apis/article/
-✅ apis/user/
-✅ apis/product/
-❌ apis/admin/ (admin 是 addon 名称)
-❌ apis/befly/ (befly 是 addon 名称)
-
-### Addon 名称清单
-
-- admin
-- befly
-- demo
-```
-
-**优点**：
-
-- 不需要修改代码
-- 立即可用
-
-**缺点**：
-
-- 依赖开发者自觉
-- 容易被遗忘
-- 没有技术保障
-
-### 方案 4：混合方案（最佳实践）
-
-结合方案 1 和方案 2：
-
-1. **立即**：添加冲突检测（方案 2）
-2. **短期**：添加项目规范（方案 3）
-3. **长期**：修改 addon 路由前缀为 `/api/addon/{name}/`（方案 1）
-
-## 📋 影响评估
-
-### 如果保持现状（不修改）
-
-**风险等级**：🔴 **高风险**
-
-**可能出现的问题**：
-
-1. 开发者创建 `apis/admin/` 目录
-2. 路由冲突，addon 接口失效
-3. 前端调用报错，但日志没有明确提示
-4. 调试困难，浪费时间
-
-**发生概率**：
-
-- ⚠️ **中高概率**：`admin` 是常见的目录名
-
-### 如果添加冲突检测
-
-**风险等级**：🟡 **中等风险**
-
-**效果**：
-
-- ✅ 能立即发现冲突
-- ✅ 阻止错误部署
-- ⚠️ 开发者需要重命名目录
-
-### 如果修改 addon 路由前缀
-
-**风险等级**：🟢 **低风险**
-
-**效果**：
-
-- ✅ 彻底解决冲突问题
-- ✅ 路径更清晰
-- ⚠️ 需要迁移现有接口
-
-## 🎯 最终建议
-
-### 立即执行（当前版本）
-
-**1. 添加冲突检测**：
-
-```typescript
-// 在 loader.ts 的 apiRoutes.set() 之前
-if (apiRoutes.has(api.route)) {
-    const existing = apiRoutes.get(api.route);
-    throw new Error(`❌ 路由冲突：${api.route}\n` + `已存在：${existing.name} (${isAddon ? 'Addon' : '项目'})\n` + `新接口：${api.name} (${isAddon ? 'Addon' : '项目'})\n` + `解决方案：避免项目 apis 目录与 addon 名称重名`);
-}
-apiRoutes.set(api.route, api);
-```
-
-**2. 更新 AGENTS.md**：
-
-- 添加 API 路由命名规范
-- 列出所有 addon 名称
-- 禁止在项目中使用同名目录
-
-### 后续优化（下一个版本）
-
-**修改 addon 路由前缀**：
-
-- Addon API：`/api/addon/{name}/{path}`
-- 项目 API：`/api/{path}`
-- 完全隔离，永久解决冲突
-
-## 📝 总结
-
-**问题答案**：
-
-> **会冲突！** 如果 addon admin 中有 `list.ts`，项目中又创建 `apis/admin/list.ts`，两个接口会生成相同的路由 `POST/api/admin/list`，后加载的会覆盖先加载的。
-
-**核心原因**：
-
-- Addon API 路径格式：`/api/{addonName}/{apiPath}`
-- 项目 API 路径格式：`/api/{apiPath}`
-- 当项目目录名与 addon 名称相同时，会产生冲突
-
-**解决方向**：
-
-1. **短期**：添加冲突检测 + 项目规范
-2. **长期**：修改 addon 路由前缀为 `/api/addon/{name}/`
-
-**当前状态**：
-
-- ✅ 项目中没有 `apis/admin/` 目录，暂时没有冲突
-- ⚠️ 需要预防未来可能的冲突
-
----
-
-**分析人**：AI Assistant
-**建议优先级**：🔴 **高优先级**（添加冲突检测）
-**最后更新**：2025-10-19

package/temp/interactive-cli-guide.md

@@ -1,199 +0,0 @@
-# Befly CLI 交互式脚本管理器使用指南
-
-## 📋 核心特性
-
-### 1. 纯交互模式
-
-- 运行 `bunx befly` 进入交互模式
-- 通过数字选择要执行的脚本
-- 所有参数通过交互式问答添加
-
-### 2. 脚本分类
-
-- **内置脚本**：来自 `core/scripts`（如 `syncDb`、`syncDev`）
-- **项目脚本**：来自 `tpl/scripts`（如 `syncDev`）
-- **组件脚本**：来自 `tpl/addons/*/scripts`（如 `initMenu`、`syncDev`）
-
-### 3. 脚本执行规则
-
-- 选择哪个数字，就执行对应的脚本
-- 即使有同名脚本，也会精确执行选中的那个
-- 列表按来源分组：内置脚本 → 项目脚本 → 组件脚本
-
-例如，有 3 个 `syncDev`：
-
-```
-1. syncDb (内置)
-2. syncDev (内置)
-3. syncDev (项目)
-4. initMenu (组件)
-5. syncDev (组件)
-```
-
-- 选择 2 → 执行内置的 syncDev
-- 选择 3 → 执行项目的 syncDev
-- 选择 5 → 执行组件的 syncDev
-
-## 🎯 使用方法
-
-### 启动交互模式
-
-```bash
-bunx befly
-# 或者
-bunx befly <任何参数>  # 参数会被忽略，统一进入交互模式
-```
-
-### 显示效果
-
-```
-🚀 Befly CLI - 脚本管理器
-
-📦 内置脚本:
-   1. syncDb
-   2. syncDev
-
-📦 项目脚本:
-   3. syncDev
-
-📦 组件脚本:
-   4. initMenu
-   5. syncDev
-
-请输入脚本编号 (输入 0 或直接回车退出):
-```
-
-### 操作流程
-
-1. **选择脚本**：输入数字（1-5），或输入 0/回车退出
-2. **添加参数**：提示是否添加 `--plan` 参数（y/n，默认 n）
-3. **确认执行**：提示是否执行（y/n，默认 y）
-
-### 示例：选择脚本 1（syncDb）并添加 --plan
-
-```bash
-bunx befly
-
-请输入脚本编号 (输入 0 或直接回车退出): 1
-
-✅ 已选择: syncDb
-是否添加 --plan 参数? (y/n，直接回车默认为 n): y
-是否执行? (y/n，直接回车默认为 y): y
-
-# 开始执行 syncDb --plan
-```
-
-## 开发说明
-
-### 添加新脚本
-
-1. **内置脚本**：在 `core/scripts/` 下创建 `.ts` 文件
-2. **项目脚本**：在 `tpl/scripts/` 下创建 `.ts` 文件
-3. **组件脚本**：在 `tpl/addons/<addonName>/scripts/` 下创建 `.ts` 文件
-
-CLI 会自动扫描这些目录，无需配置。
-
-### 脚本命名规范
-
-- 使用小驼峰或下划线命名（如 `syncDb`、`initMenu`）
-- 文件扩展名为 `.ts`
-- 脚本名称会自动去除 `.ts` 后缀
-
-### 脚本模板
-
-```typescript
-#!/usr/bin/env bun
-import { Env, Logger } from 'befly';
-
-// 从命令行参数获取 --plan 标志
-const DRY_RUN = process.argv.includes('--plan');
-
-async function main() {
-    if (DRY_RUN) {
-        Logger.info('[计划] 这里描述脚本将要执行的操作');
-        return;
-    }
-
-    // 实际执行逻辑
-    Logger.info('开始执行...');
-    // ...
-}
-
-main().catch((error) => {
-    Logger.error('执行失败:', error);
-    process.exit(1);
-});
-```
-
-## 🔍 常见问题
-
-### Q: 如何知道执行了哪个来源的脚本？
-
-A: 在日志中会显示脚本路径，或者在脚本内添加日志标识：
-
-```typescript
-Logger.info('【项目脚本】syncDev 开始执行...');
-```
-
-### Q: 为什么我的脚本没有显示？
-
-A: 检查以下几点：
-
-1. 文件扩展名是否为 `.ts`
-2. 文件是否在正确的目录下（`core/scripts`、`tpl/scripts` 或 `tpl/addons/*/scripts`）
-3. 文件名是否符合命名规范
-
-### Q: 如何执行特定来源的脚本？
-
-A: 使用数字选择即可精确执行：
-
-```bash
-bunx befly
-
-# 列表显示：
-# 1. syncDb (内置)
-# 2. syncDev (内置)
-# 3. syncDev (项目)
-# 4. initMenu (组件)
-# 5. syncDev (组件)
-
-# 输入 2 → 执行内置的 syncDev
-# 输入 3 → 执行项目的 syncDev
-# 输入 5 → 执行组件的 syncDev
-```
-
-### Q: 如何快速执行脚本而不每次都要交互？
-
-A: 目前仅支持交互模式，这样可以：
-
-- 避免误执行错误的脚本
-- 清晰看到所有可用脚本
-- 灵活添加 --plan 等参数
-- 执行前再次确认
-
-如果需要自动化执行，建议直接使用 `bun` 运行脚本文件：
-
-```bash
-# 直接执行脚本文件
-bun packages/core/scripts/syncDb.ts --plan
-bun packages/tpl/scripts/syncDev.ts
-```
-
-### Q: --plan 参数有什么用？
-
-A: 用于预演模式，脚本会输出将要执行的操作但不实际执行，适合：
-
-- 查看脚本将做什么
-- 验证参数是否正确
-- 避免误操作
-
-## 📊 技术实现
-
-- **脚本扫描**：使用 `Bun.Glob` 扫描目录
-- **脚本执行**：使用 `Bun.spawn` 执行子进程
-- **交互输入**：使用 Node.js `readline` 模块
-- **纯交互模式**：所有执行都通过数字选择，无传统命令行模式
-
----
-
-**最后更新**: 2025-10-19