xiaoqu_mcp_service/xiaoqu-franchisee/AGENTS.md

# AGENTS.md — xiaoqu-franchisee

> 本文件面向 AI 编程助手。阅读本文档前，默认你对本项目一无所知。文中信息全部来自仓库实际内容，不做任何假设或泛化。

---

## 1. 项目概览

`xiaoqu-franchisee`（artifactId: `xiaoqu-franchisee`，groupId: `me.iiv.xiaoqu`）是北京小趣智品后台体系中的一环，聚焦代理商/加盟商业务。它是一套基于 **Java 8 + Spring MVC + MyBatis-Plus** 的后端服务，打包为 `ROOT.war`，部署到外部 Tomcat 运行。

项目与另外两个仓库协同工作：

- `xiaoqu-publicbeanandmap`：提供公共 Bean、Mapper、Service 接口（ beans/b0、b1、b2 / mapper/m0、m1、m2 / service/s0、s1、s2 ）。
- `vue-manage-system`：后台管理前端（Vue 2 + Vite/Webpack）。

本仓库只包含 Controller 层、少量本地 Service/Util/AOP/Job/Redis 实现，以及 Spring 配置。

### 1.1 核心定位

- 面向 PC 后台管理端提供 REST 风格接口。
- 负责代理商、客户、仓库、工单、资产、财务、营销等业务域。
- 通过数据库表 `webpage` / `page_field` / `button` / `webpage_authority` 等实现菜单、字段、按钮级权限，前端表格/搜索区由后端元数据驱动。

---

## 2. 技术栈

| 层级 | 技术 |
|------|------|
| 语言 | Java 8 |
| 构建工具 | Apache Maven 3.x |
| Web 容器 | 外部 Tomcat 7+（`tomcat7-maven-plugin:2.2`） |
| IOC / MVC | Spring Framework 5.0.0.RELEASE |
| ORM | MyBatis-Plus 3.4.0 |
| 数据库连接池 | Alibaba Druid 1.2.6 |
| 数据库 | MySQL 5.7+（驱动 `mysql-connector-java:5.1.49`） |
| 缓存 | Redis（Jedis + Spring Data Redis 2.1.0），多 db（3/4/5/6/7/13） |
| 分布式锁 | Redisson 3.12.5 |
| 定时任务 | XXL-Job 2.2.0（执行器配置在 `xxl-job-executor.properties`） |
| 文档/测试 | Swagger 2 / swagger-bootstrap-ui 1.9.6（生产环境关闭） |
| 日志 | Log4j 1.2.17 + SLF4J 1.7.7 |
| JSON | Jackson 2.10、Fastjson（历史代码混用） |
| 工具库 | Lombok 1.18.18、Hutool、Apache Commons、HttpClient 4.5.2、EasyPOI 4.3.0 等 |
| 本地 JAR | `lib/cnap-sdk-1.0.0.jar`（菜鸟物流 SDK，pom 中已注释依赖） |

### 2.1 关键外部依赖

- `me.iiv.xiaoqu:xiaoqu-public:1.0-SNAPSHOT`
- `me.iiv.iivframework:xiaoqu-PublicBeanAndMap:1.0-SNAPSHOT`
- `me.iiv.xiaoqu:ElasticsearchPublic:0.0.1-SNAPSHOT`

修改 `xiaoqu-publicbeanandmap` 后必须先执行 `mvn clean install`，否则 `xiaoqu-franchisee` 会沿用旧 jar。

---

## 3. 项目结构

```
xiaoqu-franchisee/
├── pom.xml                              # Maven 主配置、多环境 profile
├── src/main/java/me/iiv/iivframework/
│   ├── Constants/                       # 常量、错误码、硬件故障枚举
│   ├── aop/                             # AOP 切面（防重复提交、日志切面等）
│   ├── controller/                      # Spring MVC Controller，按业务域分包
│   │   ├── account/                     # 账户/财务相关
│   │   ├── customer/                    # 客户/代理商
│   │   ├── warehouse/                   # 仓库出入库
│   │   ├── installOrder/、deliveryOrder/、workOrder/ ...
│   │   ├── input/、output/              # 部分公共入参/出参 DTO
│   │   ├── export/                      # Excel 导出 DTO（@Excel 注解）
│   │   └── excelModel/                  # Excel 模板模型
│   ├── core/                            # 拦截器、CORS、Swagger 配置、启动监听
│   ├── downTask/、downTask/impl/        # 下载任务抽象与实现
│   ├── exception/                       # 全局异常处理
│   ├── jobhandler/                      # XXL-Job 任务处理器
│   ├── redis/、redis/impl/              # Redis 业务封装
│   ├── service/                         # 本仓库本地 Service（公共 Service 在 xiaoqu-publicbeanandmap）
│   ├── service/es/                      # ES 相关封装
│   ├── task/、task/entity/              # 本地定时任务
│   └── utils/、utils/excel/、utils/poi/、utils/text/  # 工具类
├── src/main/resources/
│   ├── app-db.xml                       # 3 个 Druid 数据源 + 3 个 SqlSessionFactory + 事务配置
│   ├── beans.xml                        # Spring 根容器：扫描、MapperScanner、导入 redis/job 配置
│   ├── springmvc.xml                    # Spring MVC 子容器：Controller 扫描、拦截器、视图解析器
│   ├── myBatis-base.xml                 # MyBatis-Plus 配置（分页插件、日志实现）
│   ├── redis-context.xml                # Redis/Redisson 多库连接工厂与 Template
│   ├── applicationcontext-xxl-job.xml   # XXL-Job 执行器扫描与注册
│   ├── config.properties                # 占位符化配置，打包时由 Maven profile 注入
│   ├── xxl-job-executor.properties      # XXL-Job 执行器配置
│   └── log4j.properties                 # 日志配置
├── src/main/webapp/
│   ├── WEB-INF/web.xml                  # Servlet 3.1、Spring ContextLoaderListener、DispatcherServlet
│   ├── WEB-INF/views/                   # JSP 视图
│   ├── QrCode/、tempFile/、template/    # 静态/临时/模板文件
├── src/test/resources/webdefault.xml    # Jetty 本地运行默认描述符
├── doc/                                 # 开发文档与设计方案
│   ├── development-conventions.md       # 当前仓库核心开发规范
│   ├── agent-message-notice-dev.md
│   ├── customer-product-list-dev.md
│   └── out-certificate-dev.md
├── lib/                                 # 本地 jar
└── logs/                                # 运行日志（.gitignore 忽略）
```

### 3.1 与公共模块的边界

- **本仓库**：`me.iiv.iivframework.controller.*`、少量本地 service/utils/jobhandler。
- **xiaoqu-publicbeanandmap**：`me.iiv.iivframework.beans.b*`、`mapper.m*`、`service.s*`。
- 新增业务表时，Entity / Mapper / Service 接口应优先放在 `xiaoqu-publicbeanandmap`，本仓库只写 Controller + input/output/export DTO。

### 3.2 Controller 分包约定

```
controller/<业务域>/
├── XxxController.java              # @Controller + @RequestMapping + @Api
├── input/XxxInput.java             # 入参（@RequestBody）
├── output/XxxOutput.java           # 列表/详情出参
└── entity/（部分历史代码）          # 业务相关 POJO
```

导出类统一放 `controller/export/XxxExport.java`，使用 `@Excel` 注解。

---

## 4. 构建与运行

### 4.1 环境要求

- JDK 1.8
- Maven 3.x
- MySQL 5.7+
- Redis
- Tomcat 7+（部署目标）

### 4.2 Maven 构建

```bash
# 1. 先安装公共模块（若 xiaoqu-publicbeanandmap 有改动）
cd ../xiaoqu-publicbeanandmap && mvn clean install -DskipTests

# 2. 打包本仓库
cd ../xiaoqu-franchisee && mvn clean package -DskipTests
```

产物：`target/ROOT.war`，部署到 Tomcat 的 `webapps/ROOT.war`。`pom.xml` 中 `finalName` 固定为 `ROOT`。

### 4.3 本地开发运行

可以用 Jetty 插件（已在 pom 配置）：

```bash
mvn jetty:run
```

默认端口由 profile 中的 `webserver.port` 决定（dev 为 `8091`）。Jetty 默认描述符使用 `src/test/resources/webdefault.xml`。

### 4.4 自动化部署

pom 中配置了 `tomcat7-maven-plugin`：

```bash
mvn tomcat7:redeploy -P dev
```

- 配置项 `tomcatUrl`、`username`、密码在 `pom.xml` 的 plugin 配置中写死。
- 实际部署时通常通过 Jenkins（Linux 构建机）执行，**严格区分大小写**。

### 4.5 多环境 profile

pom.xml 中定义了 4 个 profile：

| profile | 默认 | 说明 |
|---------|------|------|
| `dev` | ✅ | 本地/开发环境，端口 `8091` |
| `test182` | ❌ | 测试环境，端口 `8090` |
| `prd` | ❌ | 生产环境，端口 `6080` |
| `pre` | ❌ | 预生产环境，端口 `6080` |

profile 中通过 Maven 属性注入到 `config.properties`/`xxl-job-executor.properties`/`log4j.properties`。切换环境时只需加 `-P <profileId>`。

### 4.6 数据库环境

| 数据源 | schema（dev） | schema（test） | schema（prd） | 用途 |
|--------|---------------|---------------|---------------|------|
| dataSource0 / m0 | `xiaoqu_comples_d` | `test` | `xiaoqu_comples_p` | 权限/菜单/用户 |
| dataSource1 / m1 | `xiaoqu_mall_d` | `xiaoqu_mall_d` | `xiaoqu_mall` | 商城 |
| dataSource2 / m2 | `xiaoqu_franchisee_d` | `xiaoqu_franchisee_d` | `xiaoqu_franchisee` | 业务数据 |

- dev/test 数据库均在 `192.168.1.181:3306`。
- prd/pre 使用阿里云 RDS。

---

## 5. 开发规范

项目主要遵循 `doc/development-conventions.md` 中总结的规范，下面提取与本仓库后端开发强相关的部分。

### 5.1 新增页面/菜单的数据库变更规范

新增后台页面必须修改权限库（dev: `xiaoqu_comples_d`，test: `test`，prd: `xiaoqu_comples_p`）中的 4 张表：

1. `webpage`：菜单本体。
2. `webpage_authority`：菜单与权限组关系。
3. `page_field`：页面字段定义（搜索区、列表列、详情字段）。
4. `field_webpage_authority`：字段级权限。
5. 如有按钮，补充 `button` + `button_webpage_authority`。

#### 权限 SQL 铁律

- **不要硬编码 `authority_id`**（除 PM 明确说“只给系统管理员”）。应动态复用同 `parent_id` 下兄弟菜单的授权并集。
- **不要硬编码自增主键**。使用 `LAST_INSERT_ID()` 获取 `webpage.id`、`button.id` 等，再用于后续关联。
- SQL 必须有 `START TRANSACTION; ... COMMIT;` + 校验段。
- 上线前必须在 prod 做 sanity check：确认 `parent_id`、确认无重复 path/button_en_name。

### 5.2 `page_field.class_name` 一致性

`page_field.class_name` 必须与后端 DTO 的全限定类名**严格一致**（包括包名）。后台“权限组管理 → 配置页面内容权限”会通过反射加载这个类，路径不一致会直接报错。

示例（来自 `customer-product-list-dev.md`）：

```
me.iiv.iivframework.controller.customerProduct.output.CustomerProductListOutput
```

### 5.3 Controller 编码风格

- 使用字段级 `@Autowired`，默认包可见（不加 `private`），与历史代码保持一致。
- 不要混用 `@Resource`，除非需要按 name 注入（如 RedisTemplate）。
- 获取当前用户：

```java
User user = UserUtils.getUser(request);
Long userId = user == null ? 0L : user.getId();
```

- 软删字段统一为 `soft_delete`（0=正常，1=删除），查询默认 `WHERE soft_delete = 0`。
- 更新必须设置 `modify_time` 和 `modify_id`。

### 5.4 查询构造

- 优先使用 MyBatis-Plus 的 `LambdaQueryWrapper` / `QueryWrapper`。
- 通用查询可用 `WrapperUtils.getWrapper(false)`（自带 `soft_delete = 0`）和 `WrapperUtils.beanToWrapper(wrapper, input)` 自动把 input 转成查询条件。
- 排序字段注意 SQL 注入风险，只接受白名单字段。

### 5.5 文件上传

- 通用上传接口：`POST /uploadFile/warehouseCertificate`。
- 不要在通用接口里硬编码 `aggregate_id / file_type / in_out_allocation_type`；业务提交时再 UPDATE 这三个字段。
- 用户取消未提交的图片会留在 DB 中 `aggregate_id = 0`，由定时任务清理。

### 5.6 导出

导出 DTO 放 `controller/export/`，使用 `@Excel` 注解。参考现有 `WarehouseOutExport`、`CustomerProductListExport` 等。

---

## 6. 测试

### 6.1 单元测试

- 测试框架：JUnit 4.12（scope=test）。
- 当前仓库没有大量单元测试覆盖，主要依赖接口冒烟测试和人工回归。
- 运行方式：

```bash
mvn test
```

### 6.2 接口测试

- 本地启动后访问 Swagger UI：`http://localhost:<port>/doc.html`（生产环境关闭）。
- 调用需要登录的接口时，header 中必须携带 `uuid`、`timeStamp`、`signature`。
- Swagger 全局参数已配置 `uuid` header。

### 6.3 冒烟 checklist（新增页面）

1. 管理员登录后左侧菜单正常显示。
2. 列表接口返回数据正常。
3. 后台“权限组管理 → 配置页面内容权限”能看到页面字段。
4. 各搜索条件逐一验证。
5. 导出功能正常。
6. 跨环境（dev → test → prd）重新执行 SQL 并校验。

---

## 7. 部署流程

### 7.1 后端上线步骤

```bash
# 1. 公共模块如有改动先 install
cd xiaoqu-publicbeanandmap && mvn clean install -DskipTests

# 2. 打包 WAR
cd xiaoqu-franchisee && mvn clean package -DskipTests -P <profile>

# 3. 部署到 Tomcat（ war 名 ROOT.war ）
```

### 7.2 前端配合

前端仓库 `vue-manage-system` 构建命令：

```bash
yarn dev          # 本地开发，端口 8079
yarn build-test   # test 包
yarn build-pre    # 预生产
yarn build        # 生产
```

### 7.3 CI 注意事项

Jenkins 构建机是 Linux，**严格区分大小写**。常见失败原因：

- import 路径大小写不一致。
- 文件名大小写不一致。
- 前端 deep import element-ui 内部模块（如 `element-ui/lib/image-viewer`）。

---

## 8. 安全与敏感信息

### 8.1 已有敏感信息（代码中已存在）

pom.xml 的各 profile 中直接写入了内网 IP、数据库密码、阿里云 OSS AccessKey、Redis 密码、ES 密码、短信账户、邮箱密码等。这些信息已通过版本控制流传，修改时注意不要泄露到公开仓库。

### 8.2 认证机制

- PC 端通过 `uuid` + `timeStamp` + `signature` 进行请求鉴权。
- `SystemInterceptor` 会校验 uuid 是否有效、时间戳是否过期、签名是否正确。
- 部分开放接口（登录、短信、Swagger、部分 `/open/*`、部分 `/warehouseHardStock/*`）在白名单中跳过校验。
- `PermissionInterceptor` 负责按钮/接口级权限校验。

### 8.3 CORS

- `MyCORSFilter` 在 `web.xml` 中全局配置，并读取 `AllowOrigin` 属性。
- `allowIp` 用于防盗链校验（当前代码中部分被注释）。

---

## 9. 常见业务域速查

| 业务域 | Controller 包 | 典型前缀 |
|--------|--------------|----------|
| 账户/财务 | `controller/account/` | `/account*`、`/messageNotice` |
| 客户/代理商 | `controller/customer/` | `/agent*`、`/property*` |
| 仓库 | `controller/warehouse/` | `/myWarehouse*`、`/warehouse*` |
| 工单 | `controller/installOrder/`、`controller/deliveryOrder/`、`controller/workOrder/` 等 | `/install*`、`/delivery*`、`/workOrder*` |
| 资产 | `controller/asset/` | `/asset*` |
| 营销 | `controller/marketing/` | `/marketing*` |
| 统计 | `controller/statistics/` | `/statistics*` |

---

## 10. 如何开始修改

1. 确认需求涉及的数据库（权限库 + 业务库）。
2. 如果涉及新增业务表，Entity/Mapper/Service 应放在 `xiaoqu-publicbeanandmap`（先 install 到本地 Maven）。
3. 在本仓库 `controller/<业务域>/` 下新增 Controller、input/output/export DTO。
4. 新增页面时按 §5.1 写权限库 SQL，并在 `doc/<feature>-dev.md` 记录。
5. 本地 Jetty 或 Tomcat 运行验证。
6. 提交前确保 `mvn clean package -DskipTests` 通过。

---

## 11. 参考文档

- `doc/development-conventions.md`：开发规范、Git 约定、前后端协作、CI 注意事项。
- `doc/agent-message-notice-dev.md`：新增菜单+字段+权限 SQL 的完整示例（含动态授权）。
- `doc/customer-product-list-dev.md`：列表查询+导出 Controller 的完整示例。
- `doc/out-certificate-dev.md`：仓库凭证上传相关需求示例。

---

版本：基于仓库 2026-06-17 快照整理。