gxwebsoft
9b5875e6fb
- 新增配送模式三态选择（0全国/1指定配送/2指定不发货） - 编辑表单中增加“配送模式”单选，mode=2时复用多选地区组件选择不发货地区 - 保存时根据模式调整 regionMode 和 regionIds 字段，确保模式与地区同步 - 列表页配送地区列新增不发货黑名单显示，聚合城市码为省份名并支持省名去重 - 加载地区时建立城市ID到省份ID映射，实现城市码聚合显示省名功能 - 适配旧数据兼容性，支持单值旧数据和全国模式显示 - 表单校验强化，指定配送/不发货模式下必须选择有效地区 - 完成端到端链路功能闭环，前端支持黑名单配置，后端按租户生效配送限制
68 lines
6.8 KiB
Markdown
68 lines
6.8 KiB
Markdown
# 项目长期记忆
|
||
|
||
## 项目结构
|
||
|
||
### 关键项目路径
|
||
- **管理后台**：`/Users/gxwebsoft/VUE/guilixu-admin`（Vue3 + Ant Design Vue）
|
||
- **用户端小程序**：`/Users/gxwebsoft/VUE/guilixu-taro`（Taro + React）
|
||
- **商家端小程序**：`/Users/gxwebsoft/VUE/xinlong-shop-taro`（Taro + React）
|
||
|
||
### ⚠️ 跨项目教训（重要）
|
||
- 商家端发货/门店/订单相关功能在 **xinlong-shop-taro**，不要改到 guilixu-taro
|
||
- 用户端订单详情等功能在 **guilixu-taro**
|
||
- 跨项目改动前，先用 grep/glob 在多个候选项目里确认"哪个项目有该功能源码"，再动手
|
||
- 已发生两次误改 guilixu-taro 的教训（useClerk 全局上下文、订单详情 deliveryType 修复）
|
||
|
||
## 业务约定
|
||
|
||
### deliveryType 配送方式枚举
|
||
- `0` = 快递配送
|
||
- `1` = 无需发货 / 自提
|
||
- `2` = 商家送货
|
||
|
||
来源：管理后台 `src/views/shop/shopOrder/components/deliveryModal.vue`
|
||
|
||
## Java 后端架构（重要）
|
||
|
||
### 双后端 / MODULES_API_URL 模式（2026-07-25 分析结论）
|
||
- **mp-java**（`/Users/gxwebsoft/JAVA/mp-java`）= 独立的「modules 服务」，用 `modules` 库；cms(235类)、shop 等业务模块都在它这里，持续高频开发。
|
||
- **guilixu-java**（`/Users/gxwebsoft/JAVA/guilixu-java`）= 桂礼序主后端，用 `db_guilixu` 库；是 mp-java 的「子集分叉」。
|
||
- **guilixu-admin 前端已预设双基地址**：`SERVER_API_URL`(主后端) + `MODULES_API_URL`(localStorage ApiUrl / VITE_API_URL)。
|
||
- ⚠️ **运行时实际指向以 `localStorage ApiUrl` 为准**（2026-08-06 用户纠正）：**guilixu-admin 的「商城」接口实际调 `https://shop-api.websoft.top`（= guilixu-java）**，并非 mp-java。**判断"改哪个后端才生效"不能默认 MODULES_API_URL=mp-java，必须查 ApiUrl 运行时配置。** cms 接口另走 `VITE_CMS_API_URL`=cms-api.websoft.top（mp-java）。
|
||
- **结论（仅限 cms 模块）：guilixu-java 里的 cms 包(152类)是 mp-java cms 的旧分叉子集、且前端并不调它（前端调 modules 服务），属重复/死代码，应删除而非复制或扩展。**
|
||
- 复制「整个 cms 到 guilixu-java」不可行：mp-java 完整 cms 的 CmsApp/CmsWebsiteService 依赖 `project` 模块（guilixu-java 没有），会编译失败。
|
||
- 注意：mp-java 与 guilixu-java 是独立 git 仓库（`git.websoft.top/gxwebsoft/mp-java.git` 与 `guilixu-java.git`），各自独立部署、独立库。
|
||
|
||
### ⚠️ 双后端改动同步规则（2026-08-05 修正）
|
||
- **cms 模块**改动：仅 mp-java（guilixu-java 的 cms 是死代码）。
|
||
- **shop 等共享业务模块**（如 `ShopGoodsController` / Service / Mapper / task）：**mp-java 与 guilixu-java 都有活代码且结构一致（同 `com.gxwebsoft.shop` 包）**，用户确认改动要**两端同步**（例：2026-08-05 shopGoods `/data` 统计优化，两端各改 6 处）。
|
||
- 改动前先 grep 两端确认文件是否存在，避免只改一处导致另一端行为不一致。
|
||
|
||
### ⚠️ 运费模板不发货地区需求（2026-08-06 结论，已按用户纠正修正）
|
||
- 需求：运费模板支持「不发货地区(黑名单)」，ShopExpressTemplateDetail 加 regionMode/regionIds 字段 + DeliveryRegionChecker 下单校验。
|
||
- **后端（guilixu-java）已完整实现**：entity/param/迁移SQL/DeliveryRegionChecker/RegionCodeResolver/OrderBusinessService 接入（第 87 行调用 validateDeliveryRegionIfNeeded）均就位。
|
||
- **关键事实（用户 2026-08-06 18:09 纠正）：guilixu-admin 的「商城」接口实际调 `https://shop-api.websoft.top`（= guilixu-java）**。前端 shopExpressTemplateDetail 用默认 `@/utils/request`，baseURL = MODULES_API_URL = localStorage ApiUrl || VITE_API_URL；本部署的 ApiUrl 即 shop-api.websoft.top/api。故 guilixu-java 是生效后端，其实现正确生效，不是死代码。
|
||
- **结论：本功能（admin 配置）无需改 mp-java**（本部署 商城不走 mp-java）。
|
||
- **端到端链路已确认打通（2026-08-12）**：用户端 `guilixu-taro` 的 `BaseUrl = https://shop-api.websoft.top/api`（config/env.js 全环境），`TenantId='10606'`，下单 `POST /shop/shop-order` 即走 guilixu-java(db_guilixu)；且单租户下买家 tenantId=10606（微信支付证书也依赖此值），故 `DeliveryRegionChecker` 按 `tenant_id=10606` 能命中黑名单。✅ 功能完整闭环。
|
||
- **✅ 后台 UI 已支持「不发货黑名单」模式（2026-08-12 完成）**：`shopExpressTemplateDetailEdit.vue` 已加「配送模式」三态 radio（0全国/1指定配送/2指定不发货）；mode=2 复用 `RegionMultiSelect` 选地区，保存写 `region_mode=2` + `region_ids`(城市码逗号串)；回显按 `region_mode` 初始化。列表页 `index.vue` 的「配送地区」列按 `region_mode` 显示「不发货：xxx / 配送：xxx / 默认全国」，并把城市码聚合为省名。后端比对是编码集合 contains，故后台存城市码与 SQL 存省份码都正确拦截、互不冲突。
|
||
- 仍可用 SQL 直接 INSERT 黑名单明细（region_mode=2, region_ids=偏远省码, status=0, tenant_id=10606）作为备选，无需经过 UI。
|
||
- 接口方案文档：`docs/运费模板-不发货地区-接口方案.md`。
|
||
|
||
### shopGoods status 字段（上架/下架）
|
||
- `0` = 已上架 / 上架
|
||
- `1` = 待上架 / 下架
|
||
- `2` = 待审核，`3` = 审核不通过
|
||
- 编辑表单「状态」radio 绑定 `form.status`：0=上架、1=下架。
|
||
- 一键上下架、批量上下架均通过 `updateShopGoods({ ...record, status })` 直接改 status 实现（不额外用 isShow 字段）。
|
||
- 列表 tag 仍显示：0=已上架、1=待上架、2=待审核、3=审核不通过。
|
||
|
||
### 运费模板配送地区多选（2026-08-11 已实现前端）
|
||
- 需求：配送地区选择从「省+市单选级联」升级为「省+市两级多选穿梭弹窗」（仿客户截图双栏：左候选/右已选）。
|
||
- 前端组件：`src/components/RegionMultiSelect/index.vue`（树形可展开，省级"选择"=选该省全部市，市级可单独选；@update:value 城市编码数组）。
|
||
- **直接对接后端已有的 `regionMode`(0=全国/1=指定配送白名单/2=不发货黑名单) + `regionIds`(逗号分隔城市编码串) 机制，无需后端改动**。城市编码即 `regions-data.json` 的 city value(6位)，与 `regionIds` 完全一致。
|
||
- 数据字段：model 用 `regionMode` / `regionIds`（已有字段，非新建）；旧 `provinceId`/`cityId` 仅作回显兼容。
|
||
- 列表多值展示：`index.vue` customRender 遍历 `regionIds` 反查 regionMap，超 22 字截断 + tooltip。
|
||
- 下单校验 `DeliveryRegionChecker` 读 `regionIds` 直接生效（regionMode=2 为不发货黑名单）。
|
||
- ⚠️ 教训：第一版误用 `provinceIds`/`cityIds` 字段名，与后端 `regionMode`/`regionIds` 不匹配，MyBatis-Plus 自动忽略未知字段导致"没存"。改字段名对接即可，不必新增后端字段。
|
||
|