huangjingfen/docs/license-commercial-auth-compliant-license-dependency-replacement.plan.md

name, overview, isProject

name	overview	isProject
compliant-license-dependency-replacement	合规剥离 CRMEB 商业授权基础依赖，使用项目自有基础服务逐步替换 BaseAuth/BaseController/版权接口依赖，不修改、不替换、不绕过商业授权校验文件。	false

合规替换方案：剥离商业授权基础依赖

目标

在不破解、不绕过、不伪造 CRMEB 商业授权的前提下，把项目运行时对商业加密基础类的依赖逐步迁移到自有实现。迁移完成后：

• 自有业务模块不再依赖 crmeb\basic\BaseAuth。
• 控制器逐步改为继承自有 AppBaseController。
• 授权/版权接口只保留合法展示或系统版本能力，不伪造原厂授权状态。
• 商业 CRMEB PRO 代码仅在已购买授权时保留使用；未授权模块冻结或替换。

禁止事项

• 不替换 config/auth.php 为空文件。
• 不重写 crmeb/basic/BaseAuth.php 来模拟原厂授权类。
• 不 patch Model::maker 授权闭包。
• 不返回伪造的 AUTHORIZED、授权天数、版权购买状态。
• 不删除原厂商业文件来规避授权检查。

当前依赖边界

BaseAuth 依赖点

1. 应用配置

   • config/app.php
   • 当前有 use crmeb\basic\BaseAuth 和 'auth_crmeb' => BaseAuth::AUTH_CRMEB
   • 迁移方向：改为自有配置项或删除无业务用途配置。

2. DAO 通用搜索

   • crmeb/traits/SearchDaoTrait.php
   • BaseAuth::________(array_keys($where), $this->setModel())
   • 迁移方向：替换为自有 SearchConditionBuilder，根据模型搜索器方法过滤可用搜索字段。

3. 企业微信相关 DAO 搜索

   • app/dao/work/WorkMemberDao.php
   • app/dao/work/WorkWelcomeDao.php
   • app/dao/work/WorkGroupMsgSendResultDao.php
   • app/dao/work/WorkClientDao.php
   • app/dao/work/WorkGroupMsgTaskDao.php
   • 当前项目暂不使用该模块功能。
   • 迁移方向：放到最后阶段处理，同样使用 SearchConditionBuilder。

4. 库存扣减/回滚

   • app/dao/BaseDao.php
   • decStockIncSales() 调用 BaseAuth::_____
   • incStockDecSales() 调用 BaseAuth::___
   • 当前项目暂不使用相关下单/库存链路。
   • 迁移方向：放到最后阶段处理，新建 StockMutationService，用事务和条件更新实现原子库存变更。

5. token 解析

   • app/services/kefu/LoginServices.php
   • app/services/out/OutAccountServices.php
   • 当前项目暂不使用客服模块，kefu 相关 token 解析放到最后阶段处理。
   • 迁移方向：复用现有 crmeb\utils\JwtAuth 和 CacheService 模式，封装自有 AccessTokenService。

BaseController 依赖点

直接继承 crmeb\basic\BaseController 的入口：

• app/controller/admin/AuthController.php
• app/controller/supplier/AuthController.php
• app/controller/kefu/AuthController.php
• app/controller/kefu/Login.php
• app/controller/kefu/Common.php
• app/controller/api/v1/Common.php
• app/controller/out/OutAccount.php

间接影响很大：admin、supplier、kefu 下大量控制器继承各自 AuthController。因此迁移必须先做兼容基类，再切换顶层继承。 当前项目暂不使用客服模块，kefu 相关控制器迁移放到最后阶段处理。

版权/授权接口

当前涉及：

• route/admin.php
  • check_auth
  • auth_apply
  • auth
  • crmeb_copyright
  • crmeb_verify
  • crmeb_login
  • crmeb_order
  • crmeb_pay
  • crmeb_product
  • copyright
• app/controller/admin/Common.php
  • check_auth()
  • auth()
  • auth_apply()
  • saveCopyright()
  • getCopyright()
  • crmeb_copyright()
• app/controller/api/v1/Common.php
• app/controller/kefu/Common.php
• app/controller/supplier/Common.php

迁移方向：删除“购买/申请原厂授权”业务入口，保留自有系统信息接口，例如版本、备案、页脚版权配置。不要返回伪造授权。

目标架构

新增自有基础层，避免继续向 crmeb\basic\BaseAuth 和 crmeb\basic\BaseController 扩散：

• app/common/controller/AppBaseController.php

  • 持有 Request
  • 提供 success() / fail()
  • 提供 validate()
  • 调用 initialize()
  • 不包含原厂授权、版权、远程校验逻辑

• app/services/auth/AccessTokenService.php

  • createToken(int $id, string $type, string $authHash, array $extra = [])
  • parseToken(string $token, string $type, callable $resolver, callable $authHashResolver)
  • 复用 JwtAuth 生成与校验 JWT
  • 复用 CacheService token bucket

• app/services/dao/SearchConditionBuilder.php

  • 输入：模型类、请求 where keys
  • 输出：[$with, $whereKey]
  • 策略：只允许模型中存在对应 searchXxxAttr 搜索器的字段进入 withSearch，普通字段进入直接 where

• app/services/product/StockMutationService.php

  • decreaseStockIncreaseSales($model, array $where, int $num, string $stock, string $sales): bool
  • increaseStockDecreaseSales($model, array $where, int $num, string $stock, string $sales): bool
  • 要求库存扣减必须带 $stock >= $num 条件，防止负库存
  • 在订单链路上由外层事务包裹，或内部提供事务版本

• app/services/system/LocalCopyrightService.php

  • 仅管理本项目自有版权文案和图片
  • 来源可以是 system_config 或独立配置
  • 不表达 CRMEB 原厂授权状态

分阶段实施

阶段执行规则

每个阶段必须独立完成“修改 → 自动化/手工测试 → 提交”闭环：

1. 阶段内只修改该阶段范围内的文件，不夹带后续阶段改动。
2. 阶段修改完成后先跑自动化检查，再按该阶段 checklist 做手工接口回归。
3. 阶段验收 checklist 全部通过后，单独创建一个或多个语义清晰的 git commit。
4. 未通过测试的阶段不得提交、不得进入下一阶段，不得把多个阶段混在同一个提交里。
5. 若阶段需要拆成多个提交，每个提交都必须保持 php think 可启动，核心 smoke 测试不退化。
6. 每个阶段提交前必须在提交说明或 PR 描述中记录测试结果：执行时间、环境、接口、期望结果、实际结果。

每个阶段统一测试记录格式：

• 自动化检查：命令、结果、失败项处理结论。
• 手工接口回归：接口、请求方式、登录身份、关键参数、响应码、关键字段、是否通过。
• 兼容确认：前端页面是否可正常打开，已有 token/session 是否仍可用，失败场景是否返回明确错误。
• 提交确认：本阶段测试全部通过后再提交；提交只包含本阶段文件。

阶段 0：基线固定

目的：先把现状记录清楚，避免迁移过程中误把授权绕过当成功。

任务：

1. 恢复或保留原始商业加密文件，建立只读备份。
2. 记录当前 BaseAuth、BaseController、版权方法引用清单。
3. 给核心接口建 smoke 测试清单：
   • admin 登录
   • adminapi/home/header
   • adminapi/jnotice
   • 商品列表
   • 外部接口 token 获取和刷新
4. 客服、企业微信相关 DAO 和库存扣减/回滚链路标记为暂不使用模块，最后阶段迁移前再补充对应回归清单。

验收：

• 清单完整。
• 没有新增绕过授权的改动。
• php think 可正常启动或当前已知授权问题被明确记录为基线问题。
• 手工确认当前可访问接口的原始响应，至少记录状态码和关键字段，作为后续阶段对比基线。
• 阶段 0 测试 checklist 通过后单独提交基线记录或测试清单变更。

阶段 1：替换 token 解析依赖

优先级最高，风险中等，影响边界小。客服模块当前项目暂不使用，客服 token 解析移到最后阶段。

改动：

1. 新建 app/services/auth/AccessTokenService.php。
2. 将 app/services/out/OutAccountServices.php::parseToken() 从 BaseAuth::parseToken() 改为 AccessTokenService。
3. 保持 token 格式和缓存 key 与现有 JwtAuth / CacheService 兼容，避免外部接口调用方重新登录。
4. 仅记录 app/services/kefu/LoginServices.php::parseToken() 依赖，最后阶段统一处理。

验收：

• 外部账号可获取 token、刷新 token、访问受保护接口。
• 过期 token、伪造 token、密码变更后的旧 token 均被拒绝。
• 手工回归外部账号接口：登录/获取 token、刷新 token、访问受保护资源、退出或禁用后访问失败。
• 确认 kefu token 解析未在本阶段修改，只记录为最后阶段遗留项。
• 后台核心 smoke 接口不受影响。
• 阶段 1 测试 checklist 通过后单独提交。

阶段 2：替换通用搜索条件构建依赖

优先级高，影响常用列表查询。企业微信相关 DAO 当前项目暂不使用，延后到最后阶段。

改动：

1. 新建 app/services/dao/SearchConditionBuilder.php。
2. 修改 crmeb/traits/SearchDaoTrait.php，移除 BaseAuth 调用。
3. 规则保持：
   • 模型存在搜索器的字段进入 $with
   • 无搜索器但 where 值有效的字段进入普通 where
   • timeKey 等特殊字段保持原逻辑

验收：

• admin 商品、订单、用户、财务列表可按原筛选条件查询。
• 对非法字段不拼接 SQL。
• 手工回归列表筛选：关键词、状态、时间范围、分页、排序、空结果、非法字段请求。
• 企业微信相关 DAO 不在本阶段修改，只记录为最后阶段遗留项。
• 后台核心 smoke 接口不受影响。
• 阶段 2 测试 checklist 通过后单独提交。

阶段 3：引入自有 AppBaseController

优先级中高，影响面大，必须分入口切换。

改动：

1. 新建 app/common/controller/AppBaseController.php。
2. 先切换低风险入口：
   • app/controller/out/OutAccount.php
3. 再切换中风险入口：
   • app/controller/supplier/AuthController.php
4. 最后切换 admin：
   • app/controller/admin/AuthController.php
5. app/controller/kefu/AuthController.php、app/controller/kefu/Login.php、app/controller/kefu/Common.php 当前项目暂不使用，放到最后阶段统一切换。
6. 保持 success() / fail() 响应结构与 app('json') 一致。
7. 保持 validate() 行为兼容 ThinkPHP 校验器。

验收：

• admin/supplier/out 三类入口均能正常返回 JSON。
• 中间件注入的 request macro 仍能读取。
• 表单校验错误格式不破坏前端。
• 手工回归 out 入口：登录/鉴权、token 失效、核心受保护接口。
• 手工回归 supplier 入口：登录/鉴权、订单列表、商品列表、上传。
• 手工回归 admin 入口：登录信息、菜单、首页统计、通知、表单校验失败返回。
• 导出、上传、表单生成接口单独回归并记录响应结构。
• 客服控制器不在本阶段切换，只记录为最后阶段遗留项。
• 后台核心 smoke 接口不受影响。
• 阶段 3 测试 checklist 通过后按入口拆分提交，至少 out、supplier、admin 分开提交。

阶段 4：清理版权/授权接口

优先级中，主要是合规清理。

改动：

1. 删除或隐藏 CRMEB 原厂授权申请、授权支付、授权订单、授权产品接口入口。
2. check_auth 不再返回伪造授权状态。
3. auth() 改为本系统许可状态接口，例如：
   • edition: "custom"
   • license_source: "self-owned"
   • crm_pro_authorized: false|true，仅在确有合法授权凭证时为 true
4. getCopyright() 改由 LocalCopyrightService 读取本地配置。
5. saveCopyright() 只保存自有版权文案/图片。

验收：

• 前端不再展示“申请 CRMEB 授权/购买版权”的入口。
• 页脚版权、系统版本展示正常。
• 不再出现伪造原厂授权字段。
• 手工回归授权/版权相关接口：确认隐藏或返回自有系统信息，不返回伪造原厂授权成功状态。
• 手工回归后台系统设置页、版权保存页、前台页脚展示。
• 后台核心 smoke 接口不受影响。
• 阶段 4 测试 checklist 通过后单独提交。

阶段 5：移除配置依赖

改动：

1. 修改 config/app.php，去掉 use crmeb\basic\BaseAuth。
2. 删除或替换 'auth_crmeb' => BaseAuth::AUTH_CRMEB。
3. 全库 rg "BaseAuth|BaseController|__z6uxy|__qsG|auth_crmeb"，确认只剩已授权保留模块或无结果。

验收：

• php think 能正常启动。
• 后台核心接口 smoke 测试通过。
• 常用自有代码不再引用 crmeb\basic\BaseAuth；客服、企业微信 DAO 和库存链路引用记录为最后阶段遗留项。
• 手工回归 admin/supplier/out 核心接口，确认移除配置依赖后不触发基础类授权异常。
• 全库搜索结果必须附在阶段测试记录中，明确剩余引用是否全部属于最后阶段暂不使用模块。
• 阶段 5 测试 checklist 通过后单独提交。

阶段 6：最后迁移暂不使用模块

当前项目暂不使用客服、企业微信相关 DAO 和库存扣减/回滚链路，因此放到最后处理，避免把高风险低收益改动放进前期上线范围。

6.1 客服模块

当前项目没有使用客服模块，因此该小阶段排在最后阶段内优先级最低。只有当前面所有常用模块迁移、测试、提交完成后，再处理客服相关依赖。

改动：

1. 将 app/services/kefu/LoginServices.php::parseToken() 从 BaseAuth::parseToken() 改为 AccessTokenService。
2. 将 app/controller/kefu/AuthController.php、app/controller/kefu/Login.php、app/controller/kefu/Common.php 切换为自有 AppBaseController。
3. 保持客服登录、会话、订单、上传图片接口的响应结构兼容现有前端。

验收：

• 客服登录成功后可访问会话列表、订单查询、用户聊天记录、上传图片接口。
• 过期 token、伪造 token、禁用客服账号均被拒绝。
• 未启用客服模块时接口返回明确错误，不触发基础类授权依赖。
• 手工回归客服模块前先确认业务方是否启用；若仍未启用，只验证未启用状态的错误返回和无授权依赖异常。
• 阶段 6.1 测试 checklist 通过后单独提交。

6.2 企业微信相关 DAO 搜索

改动：

1. 修改 5 个 app/dao/work/*Dao.php 中的 BaseAuth::________ 调用。
2. 统一改为 SearchConditionBuilder。
3. 保持字段过滤策略与阶段 2 一致。

验收：

• 企业微信客户、成员、群发、欢迎语列表可查询。
• 非法字段不拼接 SQL。
• 未启用企业微信配置时接口返回明确错误，不触发基础类授权依赖。
• 阶段 6.2 测试 checklist 通过后单独提交。

6.3 库存扣减/回滚

改动：

1. 新建 app/services/product/StockMutationService.php。
2. 修改 app/dao/BaseDao.php::decStockIncSales() 和 incStockDecSales()。
3. 扣库存逻辑必须满足：
   • $num > 0
   • where($where)
   • 扣减时追加 where($stock, '>=', $num)
   • 同一条 SQL 完成 dec($stock, $num)->inc($sales, $num)->update()
   • 返回更新行数是否大于 0
4. 回滚逻辑必须满足：
   • $num > 0
   • inc($stock, $num)->dec($sales, $num)
   • 如需防止销量为负，追加 $sales >= $num

验收：

• 并发下单不会产生负库存。
• 库存不足返回失败，不创建异常订单。
• 退款/取消订单能正确回滚库存和销量。
• 规格库存、商品总库存、活动库存链路分别验证。
• 阶段 6.3 测试 checklist 通过后单独提交。

回滚策略

• 每个阶段单独提交。
• 阶段 1、2、3 可按文件级回滚。
• 阶段 4 是接口/前端合规清理，若前端依赖未同步，先保留兼容字段但不得返回伪造原厂授权。
• 阶段 6 库存链路必须在预发压测通过后上线；失败时回滚 BaseDao.php 和 StockMutationService 引用。

测试清单

自动化测试建议

• AccessTokenServiceTest

  • 正常 token 解析
  • 过期 token
  • 缓存不存在 token
  • 密码/secret 变更后旧 token 失效

• SearchConditionBuilderTest

  • 搜索器字段识别
  • 普通 where 字段保留
  • 非法字段过滤
  • timeKey 兼容

• StockMutationServiceTest

  • 正常扣库存加销量
  • 库存不足失败
  • 回滚库存减销量
  • 并发扣减不负库存

手工回归接口

每次阶段提交前，至少完成本阶段相关接口回归，并把结果记录到阶段测试记录中。记录必须包含：接口、请求方式、登录身份、关键参数、HTTP 状态码、业务 status、关键响应字段、是否通过。

核心后台 smoke

• GET /adminapi/login/info：已登录管理员返回管理员信息；未登录返回明确鉴权失败。
• GET /adminapi/menusList：返回菜单列表，菜单结构和权限过滤正常。
• GET /adminapi/home/header：返回首页统计卡片，关键字段不缺失。
• GET /adminapi/home/order：返回订单统计，时间筛选正常。
• GET /adminapi/home/user：返回用户统计，时间筛选正常。
• GET /adminapi/jnotice：返回通知列表，不触发授权基础类异常。

列表和搜索回归

• 商品列表：关键词、分类、上下架状态、分页、空结果。
• 订单列表：订单号、用户、状态、时间范围、分页。
• 用户列表：手机号/昵称、标签或等级、状态、分页。
• 财务/资金列表：时间范围、类型、分页、空结果。
• 非法字段请求：不会拼接 SQL，不返回 500。

表单、上传和导出

• 商品编辑：读取详情、保存基础信息、保存规格库存。
• 上传接口：图片上传成功，非法文件类型失败。
• 表单生成接口：返回结构兼容前端渲染。
• 导出接口：触发导出任务或返回下载信息，不返回 500。

外部账号和供应商

• 外部账号：获取 token、刷新 token、访问受保护接口、伪造 token 失败、过期 token 失败。
• 供应商：登录、登录信息、商品列表、订单列表、上传图片、无权限访问失败。

暂不使用模块最后回归

• 客服模块：当前项目未使用，最后阶段处理；未启用时确认返回明确错误，不触发基础类授权依赖。
• 企业微信：当前项目未使用，最后阶段处理；未配置时确认返回明确错误，不触发基础类授权依赖。
• 库存链路：最后阶段处理；创建订单、支付成功、取消订单、退款、规格库存、活动库存分别验证。

建议提交拆分

1. feat(auth): add local access token service
2. refactor(out): remove BaseAuth token parsing dependency
3. feat(dao): add local search condition builder
4. refactor(dao): remove BaseAuth search dependency
5. feat(controller): add app base controller
6. refactor(out): migrate out controller to app base controller
7. refactor(supplier): migrate supplier auth controller to app base controller
8. refactor(admin): migrate admin auth controller to app base controller
9. refactor(license): replace copyright endpoints with local system metadata
10. chore(config): remove BaseAuth app config dependency
11. refactor(work): remove BaseAuth enterprise wechat dao dependency
12. feat(stock): add local stock mutation service
13. refactor(dao): remove BaseAuth stock mutation dependency
14. refactor(kefu): remove BaseAuth dependencies from unused kefu module

风险点

• BaseController 影响面很大，不能一次性全量替换所有控制器文件，只切换顶层入口。
• 库存扣减必须保持原子更新，不能先查库存再保存。
• 搜索条件构建如果放宽字段，可能引入非法查询或 SQL 风险。
• token 解析必须保持缓存令牌桶逻辑，否则会导致登出、过期、禁用账号语义变化。
• 如果继续使用 CRMEB PRO 商业模块，仍需要合法授权；本方案只负责自有业务脱离商业基础依赖。