huangjingfen/docs/license-commercial-auth-license_replacement_execution_94b55501.plan.md

---
name: license replacement execution
overview: 把现有合规替换方案落成可执行推进计划：按阶段改动、测试、提交，优先处理常用 out/supplier/admin 路径，客服、企业微信和库存链路最后处理。
todos:
  - id: baseline
    content: 固定基线依赖清单、测试记录模板和核心接口响应基线
    status: completed
  - id: out-token
    content: 实现 AccessTokenService 并替换 out 外部账号 token 解析依赖
    status: completed
  - id: search-builder
    content: 实现 SearchConditionBuilder 并替换通用 SearchDaoTrait 依赖
    status: completed
  - id: base-controller
    content: 新增 AppBaseController 并按 out、supplier、admin 分入口迁移
    status: completed
  - id: license-endpoints
    content: 清理授权/版权接口为自有系统信息，不返回伪造授权状态
    status: completed
  - id: config-closeout
    content: 移除 config/app.php 的 BaseAuth 配置依赖并全库收口搜索
    status: completed
  - id: deferred-modules
    content: 最后迁移企业微信 DAO、库存链路和未使用客服模块
    status: completed
isProject: false
---

# 合规替换执行计划

## 执行原则

- 以 `pro_v3.5.1/.cursor/plans/compliant-license-dependency-replacement.plan.md` 为源方案，不做绕过授权、伪造授权或替换加密商业文件的改动。
- 每个阶段独立完成：改动、自动化检查、手工接口回归、测试记录、单独提交。
- 阶段未通过验收不得进入下一阶段；不得把多个阶段混在同一个提交里。
- 客服模块、企业微信 DAO、库存扣减/回滚当前项目未使用，全部移到最后阶段处理。

## 阶段 0：基线与测试记录模板

目标：先固定当前状态，避免后续把已有问题误判为新回归。

改动范围：
- `pro_v3.5.1/.cursor/plans/compliant-license-dependency-replacement.plan.md`
- 可新增一份阶段测试记录文档，例如 `docs/license-replacement-test-record.md`

执行内容：
- 记录 `BaseAuth`、`BaseController`、`auth_crmeb`、版权接口依赖清单。
- 记录当前可访问接口的基线响应：`/adminapi/login/info`、`/adminapi/menusList`、`/adminapi/home/header`、`/adminapi/jnotice`。
- 确认当前项目没有可直接运行的 root PHPUnit/Composer test 脚本，把自动化检查缺口写入记录。
- 建立统一测试记录格式：命令、环境、接口、身份、关键参数、HTTP 状态码、业务 `status`、关键字段、结果。

验收与提交：
- 基线清单完整。
- 没有代码行为改动。
- 单独提交：`docs(plan): record license replacement baseline`

## 阶段 1：替换外部账号 token 解析

目标：优先移除常用、低风险的 `BaseAuth::parseToken()` 依赖，不处理客服 token。

改动范围：
- 新建 `app/services/auth/AccessTokenService.php`
- 修改 `app/services/out/OutAccountServices.php`
- 按项目现有测试条件补充或记录测试缺口；若能引入 PHPUnit，再补 `tests/hjf/AccessTokenServiceTest.php`

执行内容：
- 复用 `crmeb\utils\JwtAuth` 和 `CacheService` 的 token bucket 语义。
- 保持外部账号 token 格式、过期、缓存失效、禁用账号语义兼容。
- `app/services/kefu/LoginServices.php` 只记录为最后阶段遗留，不在本阶段修改。

手工回归：
- 外部账号获取 token。
- 外部账号刷新 token。
- 使用有效 token 访问受保护接口。
- 伪造 token、过期 token、禁用/退出后的 token 均失败。
- 后台核心 smoke 接口不受影响。

验收与提交：
- 所有外部账号回归通过。
- `kefu` 未被修改。
- 单独提交：`feat(auth): add local access token service` 和/或 `refactor(out): remove BaseAuth token parsing dependency`

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

目标：移除常用列表查询中 `SearchDaoTrait` 对 `BaseAuth::________` 的依赖。

改动范围：
- 新建 `app/services/dao/SearchConditionBuilder.php`
- 修改 `crmeb/traits/SearchDaoTrait.php`
- 若能补测试：`tests/hjf/SearchConditionBuilderTest.php`

执行内容：
- 模型存在 `searchXxxAttr` 搜索器的字段进入 `withSearch`。
- 普通合法字段保留为直接查询条件。
- 非法字段过滤，避免拼接 SQL。
- `timeKey` 等既有特殊逻辑保持兼容。
- 企业微信 `app/dao/work/*Dao.php` 暂不处理，最后阶段统一迁移。

手工回归：
- 商品列表：关键词、分类、上下架状态、分页、空结果。
- 订单列表：订单号、用户、状态、时间范围、分页。
- 用户列表：手机号/昵称、等级/标签、状态、分页。
- 财务列表：时间范围、类型、分页、空结果。
- 非法字段请求不返回 500，不产生异常 SQL。

验收与提交：
- 常用列表筛选行为与基线一致。
- 后台核心 smoke 接口不受影响。
- 单独提交：`feat(dao): add local search condition builder` 和 `refactor(dao): remove BaseAuth search dependency`

## 阶段 3：引入并分入口切换 AppBaseController

目标：用自有控制器基类替换常用入口对 `crmeb\basic\BaseController` 的继承。

改动范围：
- 新建 `app/common/controller/AppBaseController.php`
- 低风险入口：`app/controller/out/OutAccount.php`
- 中风险入口：`app/controller/supplier/AuthController.php`
- 高风险入口：`app/controller/admin/AuthController.php`
- 暂不处理：`app/controller/kefu/*`

执行内容：
- `AppBaseController` 提供 `request`、`success()`、`fail()`、`validate()`、`initialize()` 调用。
- 响应结构保持与 `app('json')` 一致。
- 先切 `out` 并提交，再切 `supplier` 并提交，最后切 `admin` 并提交。

手工回归：
- `out`：登录/鉴权、token 失效、核心受保护接口。
- `supplier`：登录信息、商品列表、订单列表、上传图片、无权限访问失败。
- `admin`：`/adminapi/login/info`、`/adminapi/menusList`、`/adminapi/home/header`、`/adminapi/jnotice`、表单校验失败响应。
- 上传、导出、表单生成接口单独确认响应结构。

验收与提交：
- 三类入口各自回归通过后分别提交。
- 建议提交：`feat(controller): add app base controller`、`refactor(out): migrate out controller to app base controller`、`refactor(supplier): migrate supplier auth controller to app base controller`、`refactor(admin): migrate admin auth controller to app base controller`

## 阶段 4：清理版权和授权接口

目标：删除或隐藏原厂授权申请/购买入口，只保留自有系统信息和版权配置，不返回伪造授权状态。

改动范围：
- `route/admin.php`
- `route/api.php`
- `route/supplier.php`
- 常用控制器：`app/controller/admin/Common.php`、`app/controller/api/v1/Common.php`、`app/controller/supplier/Common.php`
- 新建 `app/services/system/LocalCopyrightService.php`
- `app/controller/kefu/Common.php` 最后阶段处理

执行内容：
- `check_auth`、`auth`、`auth_apply`、`crmeb_*` 相关入口改为合规的自有系统信息或隐藏。
- `saveCopyright()`、`getCopyright()` 改为读取/保存本地配置。
- 不返回 `AUTHORIZED`、授权天数、原厂授权成功等伪造字段。

手工回归：
- 后台不再展示申请 CRMEB 授权/购买版权入口。
- 页脚版权、系统版本、备案等展示正常。
- 授权/版权接口返回自有系统信息或明确禁用结果。
- 后台核心 smoke 接口不受影响。

验收与提交：
- 合规字段确认通过。
- 前端页面无 500 或空白页。
- 单独提交：`refactor(license): replace copyright endpoints with local system metadata`

## 阶段 5：移除配置依赖并做全库收口

目标：常用自有代码不再依赖 `BaseAuth` 和 `auth_crmeb`。

改动范围：
- `config/app.php`
- 全库搜索确认剩余引用

执行内容：
- 移除 `use crmeb\basic\BaseAuth`。
- 删除或替换 `'auth_crmeb' => BaseAuth::AUTH_CRMEB`。
- 全库确认 `BaseAuth|BaseController|auth_crmeb|__z6uxy|__qsG` 的剩余引用只属于最后阶段暂不使用模块或已授权保留模块。

手工回归：
- `php think` 能启动或明确记录当前环境授权基线问题。
- admin/supplier/out 核心接口 smoke 通过。
- 不再触发基础类授权异常。

验收与提交：
- 搜索结果附到测试记录。
- 常用路径依赖收口完成。
- 单独提交：`chore(config): remove BaseAuth app config dependency`

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

目标：处理低使用率/高风险模块，避免阻塞前期常用路径上线。

### 6.1 企业微信 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`

验收：
- 未启用企业微信时返回明确错误。
- 启用环境可查客户、成员、群发、欢迎语列表。
- 非法字段不拼接 SQL。
- 单独提交：`refactor(work): remove BaseAuth enterprise wechat dao dependency`

### 6.2 库存扣减/回滚

改动范围：
- 新建 `app/services/product/StockMutationService.php`
- 修改 `app/dao/BaseDao.php`
- 若可补测试：`tests/hjf/StockMutationServiceTest.php`

验收：
- 并发下单不产生负库存。
- 库存不足不创建异常订单。
- 取消/退款正确回滚库存和销量。
- 规格库存、商品总库存、活动库存分别验证。
- 单独提交：`feat(stock): add local stock mutation service` 和 `refactor(dao): remove BaseAuth stock mutation dependency`

### 6.3 客服模块

改动范围：
- `app/services/kefu/LoginServices.php`
- `app/controller/kefu/AuthController.php`
- `app/controller/kefu/Login.php`
- `app/controller/kefu/Common.php`

验收：
- 当前项目未启用客服时，接口返回明确错误，不触发基础类授权依赖。
- 如业务方启用客服，再回归客服登录、会话列表、订单查询、聊天记录、上传图片。
- 过期 token、伪造 token、禁用客服账号均失败。
- 单独提交：`refactor(kefu): remove BaseAuth dependencies from unused kefu module`

## 阶段门禁

每个阶段提交前必须满足：

- 改动只包含当前阶段文件。
- 自动化检查已执行或明确记录缺口。
- 相关手工接口回归已记录。
- 后台核心 smoke 没有退化。
- 剩余风险和未处理模块已记录。

## 回滚策略

- 每个阶段一个或多个独立提交，失败时优先回滚当前阶段提交。
- 阶段 3 按 `out`、`supplier`、`admin` 分入口回滚。
- 阶段 4 如前端未同步，保留兼容字段，但不得返回伪造原厂授权状态。
- 阶段 6 库存链路必须预发验证后上线，失败时回滚 `BaseDao.php` 和 `StockMutationService`。