---
description: LGP 新后端开发约定与全项目群已知陷阱
alwaysApply: true
---

# 开发约定与已知陷阱

## 新后端 lgp-admin-plus-api

- 路由由 `UtilsService::autoRouteRegister()` **反射注册**，继承自 `BaseController` 的方法也会被注册成路由。不需要暴露的继承方法必须用 `@Method NO` 覆盖，否则每个控制器白送一套 `create/update/delete`
- 方法名 camelCase 会转成 kebab-case 路径：`myInfo` → `my-info`
- 缺 `@Method` 注解会注册成 `ANY`，务必显式写 `@Method GET` 或 `@Method POST`
- 响应统一走 `jok` / `jerr`，结构固定 `{code, message, result}`，成功 `code=0`。前端拦截器按 `result` 取数据，**不要用 `data`**
- 业务表 Model 覆盖 `$connection = 'business'`；系统表沿用默认 `mysql`
- 免鉴权 Service 继承 `BaseNotAuthService`，不要像老项目那样硬编码路径白名单
- 鉴权真正发生在 `BaseService::__construct`，绕过 BaseService 的方法就没有鉴权。新代码一律走 BaseService
- `nl_menu` 的 `keep_alive` 与 `affix_tab` 输出到 meta 时是**取反**的，插数据别弄反
- 第三方凭据用 `FieldEncryptService` 加密入库，不回显明文
- **库表变更禁止新建 PHP Migration**：写 `database/sql/<YYYY-MM-DD>/01_名字.sql`（当天序号递增、尽量幂等）；系统表同步 `public/nl_admin.sql`，业务表 `cc_*` 只放 sql 目录

## 老项目只读

`lgp-api` / `lgp-wx-api` / `lgp-vben` / `lgp-vben-new` 处于迁移期，除安全修复外不要改动。
查业务逻辑可以读，新功能一律写在 `lgp-admin-plus-api` + `lgp-admin-plus`。

## 已知陷阱

- 老 `lgp-wx-api` 把微信 `session_key` 当 token 直接返回客户端，且 `AuthMiddleware` 先执行控制器再检查 token、只判空不验签。归并时必须改成服务端自签 token
- 老 `lgp-api` 密码是**无盐 sha1**，新后端是 bcrypt，靠 `nl_admin.legacy_password` 惰性升级，遗留列有过期时间
- 老 `cc_role.id=1` 不是超管，而新 `nl_role.id=1` 是超管且代码硬判断全量放行。角色迁移必须做 ID 偏移
- 老前端 10 个模块的批量删除在静默 404（后端只有 `template` 注册了 `delete-batch`）
- `cc_price_sheet` 的 6 个材质列是死 schema，`create()` 从不赋值、前端已注释，实际只有 `routine` 在用
- 图片水印不是后端接口，是前端拼 OSS URL 参数 `?watermark/2/text/...`
- 小程序 `baseURL` 硬编码在 `api/interceptor.js` 且靠注释切换，极易把测试地址发上线
- 小程序无分包配置，uview-plus 全量进主包

## 安全红线

不要把任何密钥写进源码。老项目里七牛 AK/SK（`UploadService.php`）、微信 AppSecret（`WeChatService.php`）明文硬编码，
`.env.example` 里还提交了真实数据库密码——这些是待清理的历史欠账，不要照抄这个做法。