Kimirock/likeshop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
likeshop/AGENTS.md
JIA-MAC 7d839eb07d 同步安全基线说明
2026-09-23 14:03:47 +08:00

23 KiB
Raw Permalink Blame History

AGENTS.md

文档定位

本文件适用于整个仓库，是 AI 编码代理和开发者理解本项目时的首要架构说明。CLAUDE.md 是面向 Claude 类工具的同步摘要；如果目录、技术栈、接口约定、构建发布方式或强约束发生变化，必须同时更新这两个文件。

事实优先级：实际代码与配置 > 本文件 > AI_GUIDE.md / README.md。后两者包含历史版本和商业版说明，若与当前仓库不一致，以实际代码为准。

项目定位与当前基线

Likeshop 是单商户 B2C 商城。当前仓库是免费企业版 v3.5.1，包含一个 ThinkPHP 单体服务端、服务端渲染的 PC 管理后台，以及一个 Vue 2 uni-app 移动商城源码。

  • 服务端：PHP >= 7.0、ThinkPHP 5.1.*、MySQL，Composer 管理依赖。
  • 管理后台：admin 模块服务端渲染，Think 模板 + Layui/Layui Admin + jQuery；不是 Vue/React 独立工程。
  • 移动商城：Vue 2 + uni-app + Vuex + 本地 uView 组件，JavaScript 项目；主要通过 HBuilderX 构建。
  • PC 商城：最新 php-b2c Nuxt 2/Vue 2 源码已迁入 pc/；构建产物按发布步骤输出到 server/public/pc/，该目录未必存在于源码工作区。
  • 基础设施：Nginx、PHP-FPM、MySQL、Redis；docker/ 提供旧版 Compose 开发配置。
  • 自动化测试：当前业务代码没有可用的 PHPUnit/Jest/Vitest 测试套件，也没有统一 lint/type-check 脚本。

不要把参考项目 php-amdj 的 Vue 3、TypeScript、Vite、ThinkPHP 8 或多 uni-app 目录约定套用到本仓库。

仓库目录职责

  • server/：唯一服务端工程，同时包含 API、管理后台源码和已部署静态资源。
  • server/application/admin/：PC 管理后台的 controller、logic、validate、model、server、view、middleware 等。
  • server/application/api/：移动商城 JSON API 的 controller、logic、validate、cache、middleware 等。
  • server/application/common/：跨 admin/api 共用的 model、logic、server、cache、validate、middleware。
  • server/application/index/：站点根入口；按设备尝试返回 PC 或 mobile 的 index.html。
  • server/config/：ThinkPHP 全局配置。
  • server/route/route.php：H5、PC、定时任务等显式路由。
  • server/public/：Nginx Web Root、PHP 入口、静态资源及安装资源。
  • server/public/static/：后台 Layui、插件和公共前端资源。
  • server/public/mobile/：uni-app H5 的已编译产物，属于发布结果，不是移动端源码。
  • server/public/install/db/like.sql：新安装环境的数据库结构和初始化数据，默认表前缀为 ls_。
  • server/extend/：非 Composer 扩展代码。
  • server/thinkphp/、server/vendor/：框架和第三方依赖，除非任务明确要求依赖升级，否则不要直接修改。
  • server/runtime/：运行缓存和日志；不要把运行产物纳入功能修改。
  • server/public/uploads/：用户上传数据；不要清理、覆盖或提交真实业务文件。
  • uniapp/：mobile/H5/微信小程序/App 的唯一可编辑源码。
  • uniapp/pages/：主包页面。
  • uniapp/bundle/pages/：分包业务页面。
  • uniapp/components/：业务组件和仓库内置的 uview-ui。
  • uniapp/api/：按业务域拆分的 API 调用封装。
  • uniapp/utils/request.js：统一请求、token 注入和响应处理。
  • uniapp/store/：Vuex store。
  • uniapp/config/：API 地址、版本号和缓存键等运行配置。
  • uniapp/manifest.json、uniapp/pages.json：平台能力、H5 路由、页面与分包注册的权威配置。
  • uniapp/unpackage/：HBuilderX 构建输出；如本地生成，视为临时产物。
  • docker/：旧版容器编排和 Nginx/PHP/MySQL 配置。
  • doc/：安装相关补充资料。

整体请求架构

公共入口

Nginx 的站点根目录应指向 server/public/。请求经 server/public/index.php 进入 ThinkPHP；未检测到 server/config/install.lock 时会跳转安装程序。

ThinkPHP 开启多模块但未强制路由，因此主要 URL 由“模块/控制器/操作”自动解析：

  • /admin/...：管理后台 HTML 或同路由 AJAX。
  • /api/<controller>/<action>：移动端 JSON API。
  • /mobile/...：返回 server/public/mobile/index.html，供 H5 history 路由使用。
  • /pc/...：返回 server/public/pc/index.html；深层 history 路由由 route/route.php 的 .* 规则兜底。
  • /crontab：触发 ThinkPHP 的 crontab 控制台命令。

根路径由 application/index/controller/Index.php 按终端类型选择 PC 或 mobile 构建产物。改入口、伪静态、H5 history 或站点子目录时，要一起检查 Nginx、route/route.php、manifest.json 和 config/app.js。

移动端到后端的数据流

  1. 页面或组件调用 uniapp/api/*.js 的业务函数。
  2. API 封装通过 uniapp/utils/request.js 请求 ${baseURL}/api/。
  3. 请求拦截器清理 null、undefined、空字符串，并注入登录 token；登录请求还会获取并附带短时 X-Consume-Token 票据。
  4. application/api/http/middleware/Login.php 处理跨域、免登录方法和 token 校验；消费票据功能开启时，它会继续校验需登录接口的 X-Consume-Token，再将用户信息写入 request。
  5. API controller 继承 ApiBase，读取参数和分页信息，调用 validate/logic。
  6. logic 调用 application/common 下的模型、公共 logic/server 或第三方集成。
  7. controller 用 _success() / _error() 返回统一 JSON。

统一响应字段为 code、msg、data、show、time：code = 1 表示成功，code = 0 通常表示业务失败，code = -1 表示登录态失效。修改该契约会同时影响所有移动端页面，不能在单个接口随意另造格式。

分页参数统一沿用 page_no、page_size，基类默认每页 15 条并将最大值限制为 100。

服务端架构与开发约定

技术与分层

  • PHP 目标基线以 Composer 和 Docker 配置为准：PHP 7.x，ThinkPHP 5.1。不要在普通功能开发中使用 PHP 8 专属语法。
  • PSR-4 根命名空间是 app\，对应 server/application/。
  • 现有业务分层通常为 controller -> validate/logic -> model/server。
  • controller 负责 HTTP 参数、登录上下文、校验调用和响应，不应堆积复杂业务规则。
  • logic 负责业务编排、查询组装和事务边界。
  • model 负责持久化及模型关联。跨端共享模型优先放 application/common/model/。
  • 本项目历史命名使用 server 表示公共服务类，例如支付、微信、短信、文件和配置服务；新增代码应先沿用邻近模块的命名，不要擅自批量改成 service。
  • 全局通用函数位于 server/application/common.php。新增前先检索 common.php、common logic/server 和现有模型，避免重复实现。

API 模块

  • controller 继承 app\api\controller\ApiBase。
  • 免登录 action 写入 controller 的 $like_not_need_login，值按 action 名小写比较。
  • 登录态通过 token header 传递；不要另加不兼容的认证头而不更新统一请求层。
  • 输入校验优先复用/新增 application/api/validate/ 中的 Validate 类。
  • 返回必须使用基类 _success() / _error()，保持 code/msg/data/show/time 结构。
  • API controller/action 名就是前端调用路径的一部分。重命名时必须同步搜索 uniapp/api/ 和页面调用方。
  • GET /api/account/captcha 返回一次性图形验证码；sms/send、user/send 以及账号密码 account/login 都必须携带 captcha_key 和 captcha，验证码由 application/common/server/CaptchaService.php 消费且只能使用一次。
  • admin 登录页通过 admin/account/captcha 获取同一类一次性图形验证码；后台账号登录也必须提交 captcha_key 和 captcha。
  • 密码传输统一使用 account/passwordKey 获取短时公钥（API 和 admin 各自模块路径）；密码字段以 RSA: 前缀密文提交，并携带 password_key_id。服务端在 API/Admin 的 Login middleware 中解密后再进入 controller 校验和业务逻辑，密钥默认 120 秒且只消费一次。新增密码字段必须加入 PasswordCryptoService 及三端公共请求层的字段白名单。
  • 用户 API 可通过 server/.env 的 [consume_token] enabled = true 开启附加消费票据校验，ttl_seconds 范围为 1 到 600 秒。POST /api/account/consumeToken 使用现有登录 token 签发与用户会话绑定的短时票据；uni-app 与 PC 请求层缓存票据并通过 X-Consume-Token header 携带。票据在 TTL 内可复用，不影响免登录 action；开启前必须先部署包含新请求层的 PC/mobile 构建。多实例部署必须使用共享缓存（通常为 Redis），不能让签发和校验落在彼此隔离的 File cache。

Admin 模块

  • controller 继承 app\admin\controller\AdminBase。
  • 登录态保存在 Session；admin/http/middleware/Login.php 负责登录检查，Auth.php 负责角色权限检查。
  • 同一个 action 常同时承担 GET 页面渲染和 AJAX 数据/写操作：先判断 $this->request->isAjax()，否则 fetch() 对应模板。
  • 输入校验优先使用 application/admin/validate/；业务操作放入 application/admin/logic/。
  • AJAX 返回沿用 _success() / _error()；页面数据使用 assign() / assignJs()。
  • 新增后台菜单或受控 action 时，要同步检查角色权限缓存、菜单/权限初始化数据和 server/public/install/db/like.sql，否则超级管理员以外的角色可能无法访问。

数据库与配置

  • 数据库访问既有 ThinkPHP Model，也有 think\Db；遵循所在模块现有模式，表名不要手写 ls_ 前缀，优先让框架前缀配置处理。
  • 业务配置主要通过 application/common/server/ConfigServer.php 读写 config 表并缓存，不要把后台可配置项重新硬编码进 PHP。
  • 多表写操作要沿用邻近 logic 的事务和异常处理方式，确保失败时完整回滚。
  • 当前没有正式 migration 框架。结构变更至少要同步新安装 SQL，并明确现有环境的升级 SQL/操作步骤；不能只改 like.sql 后假设老库会自动升级。
  • .env 只保存本地/部署环境值。不要提交数据库、Redis、支付、短信、微信、对象存储或地图等密钥。

安全基线

  • config/app.php 的 app_debug 默认 true（未配置 .env 时调试模式开启）、app_trace 默认 false。生产部署应在 .env 显式设置 [app] app_debug = false 关闭调试，需要 trace 时设置 [app] app_trace = true。.env 解析出的值是字符串（如 "1"），判断是否开启时必须用 filter_var($value, FILTER_VALIDATE_BOOLEAN)，不要做 === true 严格比较。
  • 开启 trace 时，ApiBase::_success()/_error() 返回的 debug.request.header 会掩码 token、X-Consume-Token、authorization、cookie、set-cookie，不要在 debug 输出中引入新的敏感字段。
  • 在线升级入口 admin/upgrade/index|choosePage|handleUpgrade|addUpdatePkgLog 以及关系链修复 admin/upgrade/fixAncestorRelation 仅超级管理员（admin id=1）可用；权限同时收敛在控制器 checkSuperAdmin() 和角色授权数据上。存量环境需执行 server/public/install/db/security_3.5.1.sql 移除 ls_role_dev_auth_index 中菜单 245（系统更新）的授权，并清理角色权限缓存。
  • 提现 WithdrawLogic::apply() 在事务内先插提现单，再用 lock(true) 锁行重读可提现余额，最后以 where('earnings', '>=', $money)->setDec() 条件原子扣减并校验受影响行数，防止并发超提。Withdraw.php::checkMoney() 拒绝 0、负数和非数字，最低提现金额未配置时拒绝申请。
  • 远程图片/头像下载必须经过 check_url_safety()：仅允许 http/https，DNS 解析后拒绝回环、私网、链路本地、CGNAT 及云元数据地址（如 169.254.169.254）。安全 HTTP 助手连接超时 10s、总超时 30s、不跟随重定向、最大下载 150MB，并通过 CURLOPT_RESOLVE 固定已校验 IP；download_file()、海报合成、check_file_exists() 的远程分支统一走该助手。StorageDriver->fetch() 在云存储侧发起抓取，调用方仍需先过 check_url_safety()，属于已知残余边界。
  • 微信服务器 URL 验证：WeChatLogic::index() 仅在携带 echostr 的 GET 分支按 token/timestamp/nonce 字典序排序后 SHA1，并用 hash_equals 与 signature 比对，匹配才回显 echostr；oa.token 未配置时验证失败。POST 消息回调仍走 EasyWeChat。

Admin 架构

admin 是 server/ 内的服务端渲染模块，不存在独立安装或前端构建步骤。

  • 页面模板：server/application/admin/view/<controller>/<action>.html。
  • 控制器：server/application/admin/controller/。
  • 业务逻辑：server/application/admin/logic/。
  • 表单校验：server/application/admin/validate/。
  • 样式和脚本：server/public/static/admin/、server/public/static/plug/layui-admin/、模板内联脚本。
  • UI 和交互：Layui 表格/表单/弹层、Layui Admin、jQuery、项目 like.ajax 封装。
  • URL 使用 Think 模板的 {:url("controller/action")} 或邻近代码的同类写法。

开发后台页面时，优先复制同业务形态的现有页面结构，而不是引入 Vue、React、TypeScript 或新的打包器。列表页通常由 Layui table.render 请求同一 action；新增/编辑常使用 iframe 弹层和隐藏 submit 按钮。保持主题变量、弹层尺寸、返回码处理和刷新方式一致。

PC 商城架构边界

必须区分“PC 管理后台”和“PC 商城前台”：

  • PC 管理后台源码完整，位于 server/application/admin/。
  • PC 商城前台源码位于根目录 pc/，是 Nuxt 2.14/Vue 2 + Element UI 工程；server/route/route.php、application/index/controller/Index.php 和配置表负责接入与开关。
  • server/public/pc/ 是 PC 的生成部署目录，不是编辑源码目录。在 pc/ 下运行 npm run generate 生成后，再按发布确认执行 autoRelease.sh；该脚本会删除并重建目标目录。

PC 页面修改应优先复用 pc/ 现有 API、路由、Nuxt 插件和 Element UI 约定；涉及后端新字段时同步检查移动端兼容响应、登录/支付、SEO 与部署路径。不要把 admin 当作 PC 商城，也不要直接在 server/public/pc/ 的构建产物中手写源码。

PC 构建与本地启动

  • 已验证的本地环境为 Node 16.20.2 + npm 8.19.4；Nuxt 2/webpack 4 不要优先使用 Node 24/npm 11。
  • 依赖安装优先使用锁文件：在 pc/ 执行 npm ci --legacy-peer-deps --no-audit --no-fund。不要在同一目录混用 npm 和 pnpm；pnpm 生成的 node_modules/.pnpm/ 会导致 npm 扫描错误的依赖树并触发 ERESOLVE。
  • pc/package-lock.json 是 npm 6 时代的 lockfileVersion: 1。如果锁文件仍含 registry.nlark.com 或 registry.npm.taobao.org，先将下载地址迁移到可用镜像，再安装；单纯设置 npm registry 不一定覆盖锁文件中的 resolved 地址。
  • 本地开发执行 npm run dev，默认端口为 1800，访问 http://localhost:1800/pc/；router.base 固定为 /pc/。
  • 生产静态构建执行 npm run generate，产物在 pc/dist/，应检查 dist/index.html、dist/200.html 和 dist/_nuxt/。
  • npm run build 是 Nuxt 的 Node 生产构建，需配合 npm run start；它不是静态发布命令。静态发布仍使用 npm run generate，确认发布后再在 Git Bash/WSL 中运行 bash autoRelease.sh。

Mobile / uni-app 架构

技术栈与入口

  • Vue 2 Options API，入口为 uniapp/main.js，根生命周期位于 uniapp/App.vue。
  • Vuex store 位于 uniapp/store/。
  • uView 以源码形式放在 uniapp/components/uview-ui/，通过 main.js 注册，并在 pages.json 的 easycom 中映射 u-* 组件。
  • 页面采用主包 pages/ + 分包 bundle/pages/；新增页面必须同步 pages.json。
  • 全局样式入口在 App.vue，主要引入 styles/base.scss 和 uView 样式；公共变量位于 uni.scss。
  • 平台差异使用 uni-app 条件编译，如 #ifdef H5、#ifdef MP-WEIXIN、#ifdef APP-PLUS。

状态、API 与页面约定

  • 页面只通过 uniapp/api/ 的业务函数访问后端，不要在页面散落完整 API URL。
  • 新接口应先加入对应业务 API 文件，再由页面调用。
  • 登录 token、消费票据、回跳和平台登录逻辑集中在 utils/request.js、utils/consumeToken.js、utils/login.js、config/cachekey.js，修改认证流程时必须一起追踪。
  • 复用 utils/tools.js、utils/cache.js、现有 mixin 和组件，不要重复实现 toast、复制、缓存、路由参数等公共能力。
  • 业务状态值先在后端模型/logic 和前端现有用法中确认，不要仅凭数字猜语义。
  • 尺寸和移动布局优先沿用现有 rpx、uView 和 uni-app 原生组件风格。

H5、微信小程序与 App

  • H5 使用 history 路由，base/publicPath 为 /mobile/；改部署子路径要同步后端路由和 Nginx 重写。
  • H5 生产环境默认使用当前域名作为 baseURL；非 H5 平台的 API 域名需要按实际发布环境配置。
  • 微信小程序、H5、App 的登录、支付、分享、定位和 WebView 能力不同，涉及这些功能时必须分别检查条件编译分支。
  • manifest.json 中的平台 ID、权限和 SDK 配置属于环境/发布配置；不要在文档、日志或新代码中复制真实凭据。

构建产物边界

  • 推荐使用与项目版本匹配的 HBuilderX 打开 uniapp/，进行 H5、微信小程序和 App 构建/发行。
  • uniapp/package.json 没有标准 uni-app CLI 依赖，也没有 dev、lint、test 脚本。
  • npm run build 不是编译命令；它只运行 Bash 脚本 autoRelease.sh，删除 server/public/mobile/ 后，把已存在的 unpackage/dist/build/web/ 复制过去。
  • 只有在 HBuilderX 已成功生成 web 构建、任务明确要求更新发布产物、并确认删除目标目录可接受时，才能运行发布脚本。
  • 普通 mobile 源码修改不要顺手改 server/public/mobile/ 的压缩 JS/CSS；发布产物更新应作为独立、可核验的步骤。

跨端功能开发工作流

开始编码前按以下顺序建立影响面：

  1. 明确需求属于 admin、mobile、API、PC 接入点、数据库还是部署配置。
  2. 从用户入口反向追踪完整链路：模板/uni-app 页面 -> JS/API 封装 -> controller -> validate/logic -> model/server -> 表/配置。
  3. 先确认现有接口路径、参数、返回结构、状态码和权限，再决定是否需要改契约。
  4. 搜索同类功能并沿用命名、目录、交互和事务方式，避免为单个需求引入新架构。
  5. 如果改数据结构，规划新安装和存量升级两条路径；如果改 admin 权限，同步菜单和角色授权数据。
  6. 如果改 mobile，多平台检查 H5、微信小程序、App 条件分支，并确认是否需要更新 pages.json/manifest.json。
  7. 按风险运行最小但充分的校验，并在交付说明中写明没有执行的验证。

规划跨端功能时，至少列出：用户入口、后端接口、权限/登录要求、数据表或配置、兼容性影响、验证方式、是否更新编译产物。PC 商城需求还必须先列出源码来源和技术栈决策。

代码修改强约束

  1. 不做无关的框架升级、依赖升级、目录重构或全局格式化。
  2. 不直接修改 server/vendor/、server/thinkphp/、server/runtime/、真实 uploads 或压缩后的 mobile 构建文件来实现源码功能。
  3. 不硬编码或提交密钥、密码、token、证书、keystore、AppID、支付回调密钥等敏感信息；仓库已有敏感资产也不要在输出中复述。
  4. 不破坏现有 API 返回结构、分页字段、token header 和 code 语义，除非所有调用端同步修改并验证。
  5. 不在普通需求中把旧 PHP 7/ThinkPHP 5.1 写法整体“现代化”。新增代码必须兼容项目运行基线。
  6. 不主动删除版权标识或修改授权相关逻辑。
  7. 不主动执行安装、数据库写入、线上发布、清缓存、删除构建目录或 Git 提交，除非任务明确要求且影响已确认。
  8. 工作区可能已有用户修改；只处理任务相关文件，不覆盖或回退无关变更。

常用命令与验证

服务端

在 server/ 下按环境需要使用：

  • 安装锁定依赖：composer install
  • 校验 Composer 配置：composer validate --no-check-publish
  • 查看 ThinkPHP 命令：php think list
  • 本地开发服务（以命令列表实际支持为准）：php think run
  • PHP 语法检查：php -l path/to/changed.php

不要用 composer update 代替常规安装。当前桌面环境未必已配置 PHP/Composer，命令不可用时应明确说明，不得声称验证通过。

容器

仓库 Compose 配置可作为环境参考：docker compose -f docker/docker-compose.yml up -d。它锁定了较旧的 PHP/MySQL/Redis/Nginx，并包含历史 Node 服务和路径；启动前必须检查端口、镜像、卷路径与本地 .env，不要默认它适合生产。

Mobile

  • 在 HBuilderX 中运行到 H5/微信开发者工具/App，完成对应平台冒烟测试。
  • H5 构建后检查 uniapp/unpackage/dist/build/web/。
  • 仅发布任务才在支持 Bash 的环境运行 npm run build，并在运行前备份/确认 server/public/mobile/ 的替换影响。

最低验证清单

  • PHP：所有改动 PHP 文件通过 php -l；关键 controller/action 能走到预期返回。
  • Admin：登录、权限、列表加载、表单提交、弹层关闭与表格刷新至少手工验证相关路径。
  • API：验证未登录、已登录、参数错误、成功四类响应中与改动相关的分支。
  • Mobile：至少验证目标平台；涉及平台 API 时补测 H5/微信小程序/App 的相关分支。
  • 数据库：确认事务、表前缀、安装 SQL和存量升级步骤。
  • 发布：确认源码和构建产物是否都需要交付，避免只改压缩产物或只替换部署目录。

建议演进规划

以下是维护路线建议，不是对 AI 代理的自动授权。只有用户明确安排对应阶段时才实施：

  1. P0 基线固化：整理本地无密钥环境模板、安装数据、关键业务冒烟清单和 API 契约快照。
  2. P1 测试补齐：先覆盖登录、商品、购物车、下单、支付回调、退款和后台权限，再扩大到营销模块。
  3. P2 前端构建可复现：锁定 HBuilderX/uni-app 版本，增加非破坏性 build 与独立 deploy 脚本，把编译和覆盖 public/mobile 分开。
  4. P3 业务边界收敛：在不改变接口的前提下，减少 controller 和重复 logic 中的公共逻辑，逐步补齐服务层和事务测试。
  5. P4 PC 商城迁入（当前已完成首轮）：pc/ 已采用最新 php-b2c Nuxt 2 前台；后续只需按兼容矩阵补齐业务测试、构建环境和发布流程。
  6. P5 基础设施升级：PHP、ThinkPHP、数据库和前端框架升级必须独立立项，先有测试和兼容矩阵，再分阶段迁移，不能夹带在业务需求中。

文档维护

  • 新增顶级工程、改变端职责、替换框架、修改统一 API 契约或发布流程时，同步更新 AGENTS.md 和 CLAUDE.md。
  • 仅记录仓库可验证的事实。商业版、外部系统或尚未引入的源码应明确标注为外部依赖/规划，不得描述成当前能力。
  • 架构说明不要写真实环境地址、账号、密钥或客户数据。
Reference in New Issue View Git Blame Copy Permalink