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 构建

# 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 配置）：

mvn jetty:run

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

4.4 自动化部署

pom 中配置了 tomcat7-maven-plugin：

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）。
• 获取当前用户：

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）。
• 当前仓库没有大量单元测试覆盖，主要依赖接口冒烟测试和人工回归。
• 运行方式：

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 后端上线步骤

# 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 构建命令：

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 快照整理。