likeshop/CLAUDE.md

CLAUDE.md

使用方式

开始任何任务前先阅读根目录 AGENTS.md。它是完整架构与开发规范的事实源，本文件是同一规则的执行摘要；二者冲突时先以实际代码核实，再修正文档。架构、接口契约或构建发布方式变化时，必须同步更新两个文件。

项目记忆

这是 Likeshop 单商户 B2C 商城免费企业版 v3.5.1，不是参考项目 php-amdj 的新技术栈：

• server/：PHP 7.x + ThinkPHP 5.1 单体工程。
• admin：server/application/admin/ 中的服务端渲染后台，使用 Think 模板、Layui/Layui Admin、jQuery；没有独立 admin 前端工程。
• mobile：uniapp/ 中的 Vue 2 + uni-app + Vuex + uView JavaScript 工程，面向 H5、微信小程序和 App。
• PC 商城：最新 php-b2c Nuxt 2/Vue 2 源码位于 pc/；server/public/pc/ 是生成部署目录。
• server/public/mobile/：H5 编译产物，不是源码。
• 当前业务代码没有可用自动化测试套件，也没有完整的前端 CLI 开发、lint 或 type-check 流程。

不要引入 Vue 3、TypeScript、Vite、Element Plus、Pinia、ThinkPHP 8 等参考项目约定，除非用户明确批准独立升级任务。

目录速记

• server/application/admin/controller|logic|validate|view/：后台 HTTP、业务、校验和页面。
• server/application/api/controller|logic|validate|http/：移动端 API 与 token 中间件。
• server/application/common/model|logic|server|cache/：跨端公共能力。
• server/application/index/：站点根路径的 PC/mobile 选择。
• server/config/、server/route/：全局配置和显式路由。
• server/public/static/：后台与公共静态资源。
• server/public/install/db/like.sql：新安装数据库基线，默认表前缀 ls_。
• uniapp/pages/：主包页面；uniapp/bundle/pages/：分包页面。
• uniapp/api/：业务接口封装；uniapp/utils/request.js：统一请求和响应拦截。
• uniapp/store/：Vuex；uniapp/components/：业务组件和本地 uView。
• uniapp/pages.json、uniapp/manifest.json：页面/分包与平台配置。
• docker/：旧版开发容器配置，仅作为环境参考。

禁止把功能实现写进 server/vendor/、server/thinkphp/、server/runtime/、真实 uploads、uniapp/unpackage/ 或压缩后的 server/public/mobile/。

请求链路

Mobile API

uniapp 页面 -> uniapp/api/*.js -> utils/request.js -> /api/<controller>/<action> -> API Login middleware -> ApiBase controller -> validate/logic -> common model/server

• 登录 token 使用 token header；消费票据功能开启时，需登录接口还要求 X-Consume-Token。
• controller 继承 ApiBase。
• 免登录 action 配置在 $like_not_need_login。
• 统一返回 code/msg/data/show/time。
• code = 1 成功，code = 0 业务失败，code = -1 登录失效。
• 分页沿用 page_no/page_size，默认 15，最大 100。
• 新接口先添加/修改 uniapp/api/ 封装，页面不要直接拼完整 URL。
• GET /api/account/captcha 提供一次性图形验证码；发送短信的 sms/send、user/send 及账号密码登录 account/login 必须同时提交 captcha_key 与 captcha。
• admin 登录使用 admin/account/captcha 获取一次性验证码，后台登录请求同样必须提交 captcha_key 与 captcha。
• 密码传输统一使用 account/passwordKey 获取短时公钥（API 和 admin 各自模块路径）；密码字段以 RSA: 前缀密文提交，并携带 password_key_id。服务端在 API/Admin 的 Login middleware 中解密后再进入 controller 校验和业务逻辑，密钥默认 120 秒且只消费一次。新增密码字段必须加入 PasswordCryptoService 及三端公共请求层的字段白名单。
• server/.env 的 [consume_token] enabled 控制用户 API 的附加消费票据校验，默认关闭；ttl_seconds 被限制在 1 到 600 秒。PC/uni-app 从 POST /api/account/consumeToken 签发短时、会话绑定且 TTL 内可复用的票据，统一请求层负责缓存和注入。开启前先部署新 PC/mobile 构建，多实例环境使用共享缓存。

Admin

Layui 模板 -> 同 action AJAX/表单 -> AdminBase controller -> validate/logic -> model/server -> _success/_error

• admin 使用 Session 登录，Login/Auth 中间件负责登录和角色权限。
• action 常同时处理 GET 渲染和 AJAX；沿用邻近 controller 的 isAjax() + fetch() 模式。
• 页面在 application/admin/view/<controller>/<action>.html，静态资源在 public/static/。
• 交互优先复用 Layui table/form/layer 和 like.ajax，不要为单页引入新 SPA 框架。
• 新增菜单或受控 action 时同步角色权限、缓存逻辑和安装 SQL 中的菜单/权限数据。

安全基线

• config/app.php 的 app_debug 默认 true（未配置 .env 时调试模式开启）、app_trace 默认 false；生产部署在 .env 显式 [app] app_debug = false 关闭调试；判断开关用 filter_var(..., FILTER_VALIDATE_BOOLEAN)，.env 解析值是字符串，不能 === true 严格比较。
• trace 输出的 debug.request.header 会掩码 token/X-Consume-Token/authorization/cookie/set-cookie。
• admin/upgrade/index|choosePage|handleUpgrade|addUpdatePkgLog 与 admin/upgrade/fixAncestorRelation 仅超管（admin id=1）可用；存量环境执行 server/public/install/db/security_3.5.1.sql 移除菜单 245 授权并清权限缓存。
• 提现申请在事务内锁行重读余额 + 条件原子 setDec，checkMoney() 拒绝 0/负数/非数字且最低提现金额未配置时拒绝。
• 远程下载经 check_url_safety()（仅 http/https，拒绝回环/私网/链路本地/云元数据地址），安全 HTTP 助手限时 10s/30s、不跟随重定向、150MB 上限并用 CURLOPT_RESOLVE 固定 IP；download_file()、海报合成、check_file_exists() 远程分支统一走该助手。
• 微信 URL 验证仅在 echostr GET 分支做 token/timestamp/nonce 排序 SHA1 + hash_equals 校验，POST 回调仍走 EasyWeChat。

PC 商城边界

管理后台不是 PC 商城。PC 前台源码位于 pc/，后端接入位于以下位置：

• server/route/route.php 的 /pc/:any。
• server/application/index/controller/Index.php 的桌面模板选择。
• admin 的 PC 配置入口和数据库开关；PC 构建使用 Nuxt 2 的 npm run generate，发布脚本会将 dist/ 复制到 server/public/pc/。

PC 页面需求直接在 pc/ 源码中实现，必须保持现有 API、账号、支付、SEO 和 /pc/ history 部署约定；不要修改生成后的 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 依赖树。
• npm run dev 启动开发服务，默认访问 http://localhost:1800/pc/。
• npm run generate 生成静态产物到 pc/dist/；确认发布后再运行 bash autoRelease.sh 复制到 server/public/pc/。
• npm run build + npm run start 是 Nuxt Node 生产运行方式，不替代静态发布。旧 package-lock.json 如含 registry.nlark.com/旧淘宝源，需先修复锁文件下载地址。

后端开发规则

• 保持 PHP 7.x / ThinkPHP 5.1 兼容，不使用 PHP 8 专属语法。
• 遵循当前 controller -> validate/logic -> model/server 分层。
• controller 只处理 HTTP 上下文、校验和响应，复杂业务进入 logic。
• 公共模型/逻辑/第三方能力优先放 application/common/；新增前搜索已有实现。
• 项目历史上公共服务目录名是 server/，不要在普通任务中批量改名。
• API 用 ApiBase::_success/_error，admin 用 AdminBase::_success/_error，不要自造返回结构。
• 业务配置优先通过 ConfigServer 和配置表，不硬编码环境值。
• 多表写入遵循邻近 logic 的事务模式。
• 数据表名不手写 ls_，让 ThinkPHP 的 prefix 配置处理。
• 当前无 migration 框架。表结构变更要同时考虑 like.sql 新安装基线和存量环境升级步骤。

Mobile 开发规则

• 使用现有 Vue 2 Options API、Vuex、uView 和 JavaScript 风格。
• 新页面注册到 pages.json；按体积和业务归入主包或 bundle 分包。
• 复用 api/、utils/、Vuex、mixin 和现有组件，避免页面内重复基础能力。
• 使用 uni-app 条件编译处理 H5、MP-WEIXIN、APP-PLUS 差异。
• 登录、支付、分享、定位、WebView 变更必须逐平台检查。
• H5 history base 是 /mobile/；修改它时同步 manifest.json、后端路由和 Nginx。
• 平台 AppID、SDK key、支付/微信/短信配置不得写入文档、输出或新硬编码。

uniapp/package.json 没有标准 uni-app CLI 工具链。编译使用匹配版本的 HBuilderX：

• H5 输出：uniapp/unpackage/dist/build/web/。
• 微信小程序/App：在 HBuilderX 对应发行入口构建并用目标平台工具验证。
• npm run build 只是执行 autoRelease.sh：它会删除 server/public/mobile/，再复制已有 web 构建。它不是编译命令，普通源码任务禁止顺手运行。

任务执行流程

1. 识别改动端：admin、mobile、API、PC 接入、数据库或部署。
2. 阅读入口及邻近实现，追踪到 controller、logic、model/server 和表/配置。
3. 确认接口参数、返回码、登录/权限和调用端，再开始修改。
4. 用最小范围实现，并同步所有真实调用方；不做无关升级或格式化。
5. 表结构变更同时规划新装与存量升级；权限变更同步菜单/角色数据。
6. mobile 变更检查页面注册与多平台分支；发布产物仅在明确发布任务中更新。
7. 执行可用验证，明确报告无法运行的检查。

跨端开发计划至少写明：用户入口、API、权限、数据/配置、兼容性、验证方式、是否交付编译产物。当前 PC 迁入已完成首轮，后续架构演进应先固化环境和关键业务基线，再补测试、拆分非破坏性 build/deploy，之后才做公共逻辑收敛和 PHP/ThinkPHP 升级。该路线不是自动授权。

安全与变更边界

• 不提交或复述 .env、数据库密码、token、证书、keystore、AppID、地图/支付/短信/微信/存储密钥。
• 仓库已有敏感资产也不要擅自删除、轮换或打印；需要处理时先确认影响。
• 不修改版权/授权逻辑，不移除版权标识。
• 不执行 composer update、数据库安装/写入、线上发布、清缓存、删除构建目录或 Git 提交，除非用户明确要求。
• 不覆盖用户已有修改，不回退无关文件。
• server/public/mobile/、server/runtime/、uploads 和 uniapp/unpackage/ 都不是常规源码修改目标。

验证速记

服务端可用时：

• composer install
• composer validate --no-check-publish
• php think list
• php -l path/to/changed.php

Admin 至少手测相关登录/权限、列表、提交、弹层和刷新；API 至少覆盖相关的未登录、已登录、参数错误、成功分支；mobile 至少在目标平台运行，涉及平台能力时补测 H5/微信小程序/App。

当前桌面环境可能没有 PHP、Composer 或 HBuilderX CLI。工具不可用时如实说明，不能声称测试通过。Docker Compose 锁定旧版依赖且包含历史路径，启动前必须检查，不默认用于生产。

文档同步

新增顶级工程、引入 PC 源码、升级框架、改变统一 API/认证/分页、移动端构建目录或部署路径时，同一个任务中更新 AGENTS.md 与本文件。只写实际仓库可验证的信息，不把商业版或规划能力描述为当前实现。