befly-tpl 3.2.1 → 3.2.3

package/temp/roleid-to-rolecode-optimization.md

@@ -1,321 +0,0 @@
-# RoleId → RoleCode 查询优化报告
-
-**日期**：2025-10-19
-**状态**：✅ 已完成
-
-## 📋 背景
-
-用户要求将角色查询从使用 `roleId`（数据库主键）改为使用 `roleCode`（业务唯一标识符），原因如下：
-
-1. **业务稳定性**：`roleCode` 是业务层面的唯一标识，不会因数据迁移等操作而改变
-2. **可读性更好**：代码中的 `'dev'`、`'admin'` 等角色编码比数字 ID 更有意义
-3. **解耦数据库**：减少对数据库主键的依赖，提高系统灵活性
-
-## 🎯 修改目标
-
-将所有通过 `roleId` 查询角色的地方改为使用 `roleCode`：
-
-```typescript
-// ❌ 修改前：使用 roleId
-where: {
-    id: admin.roleId;
-}
-
-// ✅ 修改后：使用 roleCode
-where: {
-    code: admin.roleCode;
-}
-```
-
-## ✅ 完成的修改
-
-### 1. adminMenus.ts - 获取用户菜单
-
-**修改内容**：
-
-- 判断条件：`admin.roleId` → `admin.roleCode`
-- 查询条件：`where: { id: admin.roleId }` → `where: { code: admin.roleCode }`
-
-**修改前**：
-
-```typescript
-if (!admin || !admin.roleId) {
-    return Yes('获取菜单成功', []);
-}
-
-const role = await befly.db.getOne({
-    table: 'addon_admin_role',
-    where: { id: admin.roleId }
-});
-```
-
-**修改后**：
-
-```typescript
-if (!admin || !admin.roleCode) {
-    return Yes('获取菜单成功', []);
-}
-
-const role = await befly.db.getOne({
-    table: 'addon_admin_role',
-    where: { code: admin.roleCode }
-});
-```
-
-### 2. roleSave.ts - 保存用户角色
-
-**修改内容**：
-
-- API 参数：`roleId: Fields._id` → `roleCode: '角色编码|string|2|50|null|1|^[a-zA-Z0-9_]+$'`
-- 查询条件：`where: { id: ctx.body.roleId }` → `where: { code: ctx.body.roleCode }`
-- 数据更新：`roleId: ctx.body.roleId` → `roleId: role.id`（从查询结果获取）
-
-**修改前**：
-
-```typescript
-fields: {
-    adminId: Fields._id,
-    roleId: Fields._id
-},
-handler: async (befly, ctx) => {
-    const role = await befly.db.getOne({
-        table: 'addon_admin_role',
-        where: { id: ctx.body.roleId }
-    });
-
-    await befly.db.updData({
-        table: 'addon_admin_admin',
-        where: { id: ctx.body.adminId },
-        data: {
-            roleId: ctx.body.roleId,
-            roleCode: role.code,
-            roleType: roleType
-        }
-    });
-}
-```
-
-**修改后**：
-
-```typescript
-fields: {
-    adminId: Fields._id,
-    roleCode: '角色编码|string|2|50|null|1|^[a-zA-Z0-9_]+$'
-},
-handler: async (befly, ctx) => {
-    const role = await befly.db.getOne({
-        table: 'addon_admin_role',
-        where: { code: ctx.body.roleCode }
-    });
-
-    await befly.db.updData({
-        table: 'addon_admin_admin',
-        where: { id: ctx.body.adminId },
-        data: {
-            roleId: role.id,
-            roleCode: role.code,
-            roleType: roleType
-        }
-    });
-}
-```
-
-### 3. roleGet.ts - 获取用户角色
-
-**修改内容**：
-
-- 判断条件：`admin.roleId` → `admin.roleCode`
-- 查询条件：`where: { id: admin.roleId }` → `where: { code: admin.roleCode }`
-
-**修改前**：
-
-```typescript
-let roleInfo = null;
-if (admin.roleId) {
-    roleInfo = await befly.db.getOne({
-        table: 'addon_admin_role',
-        where: { id: admin.roleId }
-    });
-}
-```
-
-**修改后**：
-
-```typescript
-let roleInfo = null;
-if (admin.roleCode) {
-    roleInfo = await befly.db.getOne({
-        table: 'addon_admin_role',
-        where: { code: admin.roleCode }
-    });
-}
-```
-
-### 4. adminInfo.ts - 获取用户信息
-
-**修改内容**：
-
-- 判断条件：`admin.roleId` → `admin.roleCode`
-- 查询条件：`where: { id: admin.roleId }` → `where: { code: admin.roleCode }`
-
-**修改前**：
-
-```typescript
-let roleInfo = null;
-if (admin.roleId) {
-    roleInfo = await befly.db.getOne({
-        table: 'addon_admin_role',
-        where: { id: admin.roleId }
-    });
-}
-```
-
-**修改后**：
-
-```typescript
-let roleInfo = null;
-if (admin.roleCode) {
-    roleInfo = await befly.db.getOne({
-        table: 'addon_admin_role',
-        where: { code: admin.roleCode }
-    });
-}
-```
-
-## 🔍 验证结果
-
-使用 `grep` 搜索确认所有 `roleId` 查询已替换：
-
-```bash
-grep -rE "where:\s*\{\s*id:\s*.*\.roleId" packages/tpl/addons/admin/**/*.ts
-# 结果：No matches found ✅
-```
-
-## 📊 修改统计
-
-- **修改文件总数**：4 个
-- **修改 API 接口**：4 个
-    - adminMenus.ts
-    - roleSave.ts
-    - roleGet.ts
-    - adminInfo.ts
-
-## 🎓 优化要点
-
-### 1. 为什么使用 roleCode 更好？
-
-**稳定性**：
-
-```typescript
-// ❌ roleId 可能因数据迁移、导入导出等操作而改变
-// 如果数据库重建，ID 会重新生成
-
-// ✅ roleCode 是业务标识，始终保持不变
-// 'dev', 'admin', 'user' 等编码在任何环境都一致
-```
-
-**可读性**：
-
-```typescript
-// ❌ 使用 ID，不知道具体是什么角色
-if (admin.roleId === 1) { ... }
-
-// ✅ 使用编码，一目了然
-if (admin.roleCode === 'admin') { ... }
-```
-
-**解耦**：
-
-```typescript
-// ❌ 紧耦合数据库主键
-// 多环境（开发/测试/生产）ID 可能不一致
-
-// ✅ 使用业务标识
-// 所有环境都使用相同的 roleCode
-```
-
-### 2. admin 表同时保留 roleId 和 roleCode 的原因
-
-**roleId（数字）**：
-
-- 数据库外键关联
-- 查询性能优化（数字索引更快）
-- 保持数据完整性
-
-**roleCode（字符串）**：
-
-- 业务逻辑判断
-- 跨系统数据同步
-- 代码可读性和维护性
-
-### 3. 最佳实践
-
-```typescript
-// ✅ 推荐：查询时使用 roleCode
-const role = await befly.db.getOne({
-    table: 'addon_admin_role',
-    where: { code: admin.roleCode }
-});
-
-// ✅ 推荐：更新时同时更新 roleId 和 roleCode
-await befly.db.updData({
-    table: 'addon_admin_admin',
-    where: { id: adminId },
-    data: {
-        roleId: role.id, // 保持外键关联
-        roleCode: role.code, // 保持业务标识
-        roleType: roleType
-    }
-});
-
-// ✅ 推荐：业务逻辑判断使用 roleCode
-if (admin.roleCode === 'dev' || admin.roleCode === 'admin') {
-    // 管理员权限
-}
-```
-
-## 🚀 后续建议
-
-1. **统一查询规范**：
-    - 所有角色相关查询都使用 `roleCode`
-    - 数据库关联可以保留 `roleId`
-
-2. **数据完整性**：
-    - 确保 admin 表的 `roleCode` 字段始终与对应角色同步
-    - 在 `roleSave.ts` 中已实现同步更新逻辑
-
-3. **前端适配**：
-    - 前端传参改为使用 `roleCode` 而非 `roleId`
-    - 下拉选择等组件显示 `code + name` 组合
-
-4. **文档更新**：
-    - 更新 API 文档，说明使用 `roleCode` 参数
-    - 在 AGENTS.md 中添加角色查询规范
-
-## 📝 影响范围
-
-### API 接口变更
-
-**roleSave.ts**：
-
-- 参数变更：`roleId` → `roleCode`
-- 调用方需要传递 `roleCode` 而非 `roleId`
-
-### 内部查询优化
-
-- adminMenus.ts：内部查询优化，不影响接口
-- roleGet.ts：内部查询优化，不影响接口
-- adminInfo.ts：内部查询优化，不影响接口
-
-## ✅ 测试建议
-
-1. **登录测试**：验证用户登录后菜单权限正常
-2. **角色分配**：测试 `roleSave` 接口使用 `roleCode` 参数
-3. **用户信息**：验证 `adminInfo` 接口返回正确的角色信息
-4. **菜单缓存**：确认 Redis 缓存的菜单数据正常
-
----
-
-**优化负责人**：AI Assistant
-**审核状态**：✅ 已完成
-**最后更新**：2025-10-19

package/temp/status-to-state-migration-complete.md

@@ -1,176 +0,0 @@
-# Status → State 字段迁移完成报告
-
-**日期**：2025-10-19
-**状态**：✅ 已完成
-
-## 📋 背景
-
-用户指出项目中自定义的 `status` 字段与框架保留的 `state` 字段功能重复，违反了框架设计规范。框架已提供统一的 `state` 字段来管理所有记录状态：
-
-- `state = 0`：已删除（软删除）
-- `state = 1`：正常/激活（默认）
-- `state = 2`：已禁用
-
-## 🎯 迁移目标
-
-1. 删除所有表定义中的自定义 `status` 字段
-2. 更新所有 API 代码，移除 `status` 字段的引用
-3. 统一使用框架的 `state` 字段进行状态管理
-4. 更新类型定义和注释说明
-
-## ✅ 完成的修改
-
-### 1. 表定义文件（已在之前完成）
-
-| 文件                | 修改内容                  |
-| ------------------- | ------------------------- |
-| `tables/menu.json`  | ✅ 删除 `status` 字段定义 |
-| `tables/role.json`  | ✅ 删除 `status` 字段定义 |
-| `tables/admin.json` | ✅ 删除 `status` 字段定义 |
-
-### 2. 脚本文件
-
-| 文件                  | 修改内容                                                                  |
-| --------------------- | ------------------------------------------------------------------------- |
-| `scripts/syncMenu.ts` | ✅ 移除 `status` 字段操作<br>✅ 更新注释说明<br>✅ 查询和缓存改用 `state` |
-| `scripts/syncDev.ts`  | ✅ 移除 `status: 1` 赋值                                                  |
-
-### 3. API 文件（本次完成）
-
-| 文件                 | 修改内容                                                                                                            |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `apis/menuCreate.ts` | ✅ 移除 `status: adminMenuTable.status`<br>✅ 添加注释说明 state 自动管理                                           |
-| `apis/menuUpdate.ts` | ✅ 移除 `status` 字段验证<br>✅ 移除 `status: ctx.body.status` 更新<br>✅ 添加注释说明禁用/启用用法                 |
-| `apis/menuList.ts`   | ✅ 将 fields 中的 `'status'` 改为 `'state'`                                                                         |
-| `apis/roleCreate.ts` | ✅ 移除 `status: adminRoleTable.status`<br>✅ 移除 `status: ctx.body.status` 插入<br>✅ 添加注释说明 state 自动管理 |
-| `apis/roleUpdate.ts` | ✅ 移除 `status` 字段验证<br>✅ 移除 `status: ctx.body.status` 更新<br>✅ 添加注释说明禁用/启用用法                 |
-| `apis/login.ts`      | ✅ 改为检查 `state === 2`（已在之前完成）                                                                           |
-| `apis/register.ts`   | ✅ 移除 `status: 1` 赋值（已在之前完成）                                                                            |
-| `apis/adminMenus.ts` | ✅ 移除 `status` 查询（已在之前完成）                                                                               |
-| `apis/adminInfo.ts`  | ✅ 更新注释，将 `status` 改为 `state`                                                                               |
-
-### 4. 类型定义
-
-| 文件             | 修改内容                                                                              |
-| ---------------- | ------------------------------------------------------------------------------------- |
-| `types/index.ts` | ✅ Admin 接口：`status: 0 \| 1` → `state: 0 \| 1 \| 2`<br>✅ 添加注释说明各状态值含义 |
-
-## 🔍 验证结果
-
-使用 `grep` 搜索确认所有 `status` 引用已清理：
-
-```bash
-grep -r "status" packages/tpl/addons/admin/**/*.ts
-# 结果：No matches found ✅
-```
-
-## 📊 迁移统计
-
-- **修改文件总数**：13 个
-- **删除字段定义**：3 个表
-- **更新 API 接口**：9 个
-- **更新脚本文件**：2 个
-- **更新类型定义**：1 个
-
-## 🎓 关键要点
-
-### 1. 框架自动管理的字段
-
-以下字段由框架自动添加和管理，**禁止**在表定义 JSON 中声明：
-
-- `id` - 主键 ID（由 Redis `genTimeID()` 生成）
-- `created_at` - 创建时间戳
-- `updated_at` - 更新时间戳
-- `deleted_at` - 删除时间戳（软删除）
-- `state` - 状态字段（0/1/2）
-
-### 2. State 字段使用规范
-
-```typescript
-// ✅ 正常记录（默认）
-await befly.db.insData({
-    table: 'addon_admin_menu',
-    data: { name: '菜单名' }
-    // state 自动设置为 1
-});
-
-// ✅ 禁用记录
-await befly.db.updData({
-    table: 'addon_admin_menu',
-    where: { id: menuId },
-    data: { state: 2 } // 手动设置为禁用
-});
-
-// ✅ 启用记录
-await befly.db.updData({
-    table: 'addon_admin_menu',
-    where: { id: menuId },
-    data: { state: 1 } // 恢复为正常
-});
-
-// ✅ 软删除
-await befly.db.delData({
-    table: 'addon_admin_menu',
-    where: { id: menuId }
-    // 自动设置 state=0, deleted_at=当前时间
-});
-
-// ✅ 查询时自动过滤已删除记录
-const menus = await befly.db.getAll({
-    table: 'addon_admin_menu'
-    // 自动添加 where: { state$gt: 0 }
-});
-```
-
-### 3. 禁止事项
-
-❌ **禁止在表 JSON 中定义 state 字段**：
-
-```json
-// ❌ 错误
-{
-    "status": "状态|number|0|1|1|1|null",
-    "state": "状态|number|0|2|1|1|null"
-}
-
-// ✅ 正确：不定义任何状态字段，由框架自动添加
-{
-    "name": "名称|string|2|50|null|1|null"
-}
-```
-
-❌ **禁止手动设置 state=0**：
-
-```typescript
-// ❌ 错误：不要手动设置 state=0
-await befly.db.updData({
-    table: 'addon_admin_menu',
-    where: { id: menuId },
-    data: { state: 0 }
-});
-
-// ✅ 正确：使用 delData 方法
-await befly.db.delData({
-    table: 'addon_admin_menu',
-    where: { id: menuId }
-});
-```
-
-## 🚀 后续建议
-
-1. **统一状态管理**：所有 addon 和业务表都应遵循 state 字段规范
-2. **文档更新**：更新 AGENTS.md，明确禁止自定义状态字段
-3. **代码审查**：定期检查是否有新的自定义状态字段
-4. **前端适配**：前端组件需要适配 state 字段（0/1/2）而非旧的 status 字段
-
-## 📝 参考资料
-
-- 框架规范：`core/docs/` 目录
-- 迁移指南：`temp/remove-status-field.md`
-- 总指令文件：`AGENTS.md`
-
----
-
-**迁移负责人**：AI Assistant
-**审核状态**：✅ 已完成
-**最后更新**：2025-10-19