# 前后端联调说明

## 一、启动

**后端（Java）** —— 端口 18080（8080 被本机占用）

```bash
cd F:\shop\java-rewrite\yoshop-java
mvn spring-boot:run -Dspring-boot.run.arguments="--server.port=18080"
```

- `yoshop.auth.mode=redis`（默认，见 application.yml）：真实登录校验，登录态存 Redis
- `--yoshop.auth.mode=off`：临时跳过登录校验（本地调试前端时用）
- Redis 连接复用 `spring.data.redis`，key 前缀 `yoshop:store:token:`，TTL 7 天
- 注意：本机环境变量 `SERVER__PORT` 会覆盖配置端口，启动时务必显式带 `--server.port=18080`

**前端（Vue）** —— 端口 8120

```bash
cd F:\shop\yoshop2.0-store
NODE_OPTIONS=--openssl-legacy-provider ./node_modules/.bin/vue-cli-service serve
```

> Windows cmd 下用 `yarn serve` 亦可（package.json 已带 `--openssl-legacy-provider`）。

访问 http://localhost:8120 ，用后台账号登录。

## 二、改了哪些配置

| 文件 | 改动 | 原因 |
|---|---|---|
| `public/config.js` | `BASE_API` → `/api/store` | 改走 devServer 代理，避免跨域；原线上地址保留为注释 |
| `vue.config.js` | `devServer.proxy` 增加 `/api` → `http://localhost:18080` | 代理把 `/api/store/goods/list` 转发成 `/store/goods/list` |

两个文件均留有 `.bak` 备份，要切回线上 PHP 直接 `cp public/config.js.bak public/config.js`。

**请求走向**

```
浏览器 http://localhost:8120/store/goods/list
  → axios baseURL=/api/store，拼成 /api/store/goods/list
  → webpack devServer 代理，去掉 /api
  → http://localhost:18080/store/goods/list
```

## 三、本轮为联调补齐的接口

| 接口 | 说明 | 与线上 PHP 对比 |
|---|---|---|
| `POST /store/passport/login` | 账号密码登录，bcrypt 校验（PHP `password_verify` 对应 Java `BCrypt.checkpw`），写 7 天登录态 | 参数/错误文案一致 |
| `POST /store/passport/logout` | 删除登录态 | — |
| `GET /store/store.user/info` | 登录后第一个请求，返回 userInfo + roles | **0 差异** |
| `GET /store/home/data` | 后台首页统计（概览/统计/待办/7 日走势） | **0 差异** |

已有：`/store/goods/list`（0 差异）、`/store/goods/detail`（0 差异）。

> 第 2 批（商城信息、分类、文件库、地区、会员、订单、设置、内容、营销等 34 个接口）已完成，
> 逐字段校验 28/28 PASS，详见 `接口实现进度-第2批.md`。
>
> 第 3 批（权限-角色/管理员、商城地址、页面装修、帮助中心、文章分类、文章，共 21 个接口，含增删改）
> 已完成，页面装修 2/2 PASS、写接口 62 项断言全通过，详见 `接口实现进度-第3批.md`。
>
> 第 4 批（商品新增/编辑含多规格、上下架、删除、基础信息、按 ID 取列表、规格列表、图片/视频上传，
> 共 9 个接口）已完成：写接口 42 项断言全通过，读接口 7/7 逐字段 0 差异，详见 `接口实现进度-第4批.md`。
> 进度：151 个接口已实现 91 个。

## 四、验证过的链路

```
[1] 无 token 访问商品列表        → 401 请先登录后再访问
[2] 错误密码登录                → 500 登录失败, 用户名或密码错误
[3] 不存在的用户                → 500 登录失败, 该用户不存在或已删除
[4] 有效 token + 商品列表        → 200，8 条商品
[5] 有效 token + 用户信息        → 200，字段与 PHP 逐一对齐
[6] 有效 token + 首页数据        → 200，字段与 PHP 逐一对齐
[7] 经 8120 代理访问以上三个接口 → 全部 200，链路通
```

## 五、已知限制

1. **已覆盖后台主要列表页与常见增删改**（商品/分类/订单/会员/营销/内容/设置/权限/文件库，含角色、管理员、商城地址、页面装修、帮助、文章分类、文章、商品保存与上下架、图片视频上传）。
   仍缺：订单事件（改价/备注/改地址/取消/发货/退款）、支付设置、配送/运费模板/打印机增删改、优惠券与充值套餐增删改、会员等级增删改、商品评论、客户端设置、统计接口。
   未实现的路由现在会明确返回「接口未实现：/store/xxx/yyy」，不再是无信息的 500。
2. **`checkPrivilege` 未实现**。Java 端只校验登录态，不校验角色对具体 API 的权限（PHP 会查 `store_api` 表）。上线前必须补。
3. **登录态不跨端**。Java 登录写的缓存文件在 `java-rewrite/runtime/cache`，PHP 生产环境的缓存文件在云服务器 `47.121.25.205`，两边互不相通。双跑期如需共用登录，要共享目录。
4. **前端 localStorage 里的 token 只认当前后端**。从线上 PHP 切到 Java 时必须重新登录一次，否则带旧 token 一律 401。
5. **⚠️ 本地库与线上库不是强一致**。实测：PHP 写入的数据本地能读到，但 Java 写入的数据线上 PHP 读不到（新建商品后 PHP 报「商品信息不存在」）。
   说明 `192.168.1.177/shop` 与线上 PHP 库之间是 PHP → 本地的单向同步。
   影响：写接口只能用「库内断言 + Java 读回」验证；**上线前必须把 `application.yml` 的数据源指向线上主库**，否则后台改的数据在线上不生效。

## 六、平台后台（admin）联调

第 9 批已完成 `app/admin` 模块全部业务接口（23 个，`controller/initialize` 为 PHP 基类钩子不实现），
详见 `接口实现进度-第9批-admin.md`。

- 登录：`POST /admin/passport/login`，body `{"username":"admin","password":"***"}` → `{userId, token}`
- 登录态：Redis `yoshop:admin:token:{token}`，值=管理员 JSON（不含 password），TTL 7 天
- 与商家端完全隔离：`/store/**` 走 `StoreAuthInterceptor`，`/admin/**` 走 `AdminAuthInterceptor`；
  拿商家 token 访问 `/admin/**` 一律 401
- 主要接口：`/admin/store/{index,recycle,recovery,edit,move,add}`、`/admin/store.api/{index,add,edit,delete}`、
  `/admin/store.menu/{index,info,add,edit,set_apis,delete}`、`/admin/admin.user/{detail,renew}`、
  `/admin/setting.{cache, science, timer}/...`
- 注意：`/admin/store/recovery` 是「移入回收站」、`/admin/store/move` 是「移出回收站」（PHP 原有命名）
- 一键验证：`python tools/test_admin_api.py`（需服务在 18080，并假定 admin 口令为 `123456`；
  测试时是临时改库内的 bcrypt 哈希跑完再还原，平时请勿依赖该口令）

### admin 前端联调（F:/shop/yoshop2.0-admin）

- 代理：`vue.config.js` devServer `/api → http://127.0.0.1:18080`，pathRewrite `'/api': '/admin'`；
  `public/config.js` 的 `BASE_API: '/api'`（生产改回实际域名）。
- 前端字段已全量转驼峰（16 个文件，含 STable 分页 `currentPage`、`userInfo.adminUserId` 等）。
- `store.menu/setApis` 前端按驼峰调用，Java 端 `/admin/store.menu/setApis` 与 `/set_apis` 两个路径都支持。
- 顺手修了两个前端原有 bug：回收站与 API 权限列表的列配置挂了不存在的 scopedSlots 导致整列空白，已去掉。
- 一键验证：起 Java 18080 + 前端 8110，浏览器登录 admin（测试口令 123456，原哈希备份在
  2026-10-18 工作日志）后逐页点一遍即可。

## 七、客户端（api）联调

客户端 api 共 74 个接口，**已全部实现**（四批），详见 `接口实现进度-第10批-api.md` 起至
`接口实现进度-第13批-api.md`。

- 基础地址：`/api/**`，与 PHP 的 `/index.php?s=/api/xxx` 对应
- 请求头：`platform`（MP-WEIXIN / H5）、`Access-Token`（用户 token，可无）
- 设置项：`/api/setting/data`、`/api/store/data` 里的 `setting` 与 PHP 一致——
  **库内缺项时按 `common\model\store\Setting::defaultData()` 补默认值**（PHP 的 `getAll()` 是
  `resetOptions(defaultData, data)`）。当前库只有 `register / sms / trade` 三项，所以
  `appTheme` / `pageCategoryTemplate` / `points` / `recharge` / `customer` 都来自默认值；
  缺了这层补齐，客户端读 `pageCategoryTemplate.style` 会得到 undefined（分类页空白）
- 登录态：Redis `yoshop:api:token:{token}`，值=用户 ID；`/api/**` 只解析不拦截，
  需登录的接口（购物车、订单、用户中心、售后、充值、收银台等）由接口内部判定并返回 401「请先登录后再访问」
- 登录：`/api/passport/login`（手机号 + 短信验证码，自动注册）、`/api/passport/loginMpWx`（小程序一键登录）、
  `/api/passport/loginMpWxMobile`（小程序授权手机号）；返回 `{userId, token}`，token 有效期 30 天
- **短信验证码当前不校验**：`application.yml` 的 `yoshop.sms.verify-code: false`（默认），
  手机号登录时 `smsCode` 随便填、不填都能登录；接入短信平台后改 `true` 即恢复
  严格校验（空值报「短信验证码不能为空」+ Redis 比对次数 + 用后即焚），无需改代码。
  uniapp 登录页的本地校验也已同步放开（`pages/login/components/main.vue` 的 SUBMIT_LOGIN 分支）。
  注：`/api/user/bindMobile`（绑定手机号）不在该开关范围内，仍会校验真实验证码
- 验证码：`/api/captcha/image` 返回 `{base64, key, md5}`（Redis `yoshop:api:captcha:{key}`，TTL 1800 秒）；
  `/api/captcha/sendSmsCaptcha` 校验图形验证码后按手机号每日限 10 次
  （Redis `yoshop:api:sms:send:{mobile}`），验证码写入 `yoshop:api:sms:{mobile}` → `{"code","times"}`；
  **短信通道未接入**，验证码只落缓存并在日志里打印 `[sms] ... code=xxxxxx`，本地联调可看日志或直接读 Redis
- 收银台：`/api/cashier/orderInfo`（订单 + 用户 + 该客户端可用支付方式）、`/api/cashier/orderPay`、
  `/api/cashier/tradeQuery`；**余额支付已完整实现**（扣余额、写明细、置订单已付款、累计销量）
- 支付回调：`/api/notify/wechatV2`（XML）、`/api/notify/wechatV3`（JSON）、`/api/notify/alipay`（表单）；
  交易记录查找与支付成功分发（商城订单 / 余额充值）已实现，**验签未接入**：
  库内没有支付模板（未配置商户）时跳过验签直接处理，一旦存在支付模板即拒绝回调
- 出参：驼峰，沿用 store / admin 口径；列表分页结构 `{total, perPage, currentPage, lastPage, data}`
- 一键验证：
  - `python tools/test_api_batch1.py`（首页 / 店铺 / 地区 / 文章 / 商品 / 营销，53 项）
  - `python tools/test_api_batch2.py`（购物车 / 结算下单 / 订单 / 评价 / 地址，97 项）
  - `python tools/test_api_batch3.py`（用户中心 / 优惠券 / 明细 / 售后 / 充值 / 上传，99 项）
  - `python tools/test_api_batch4.py`（验证码 / 登录 / 收银台 / 支付回调，73 项；
    `yoshop.sms.verify-code: true` 时为 77 项，脚本会自动按开关选择断言）
  - `python tools/test_uniapp_contract.py`（uniapp 真实 `{form:...}` 结构：setting / 验证码 / 登录 / userInfo，9 项）
- 仍为骨架的部分：第三方支付下单与查询（微信 / 支付宝商户参数未配置）、支付回调验签、
  短信发送通道、微信头像外链下载；未配置时均返回明确文案，不会静默失败