CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

洒渔镇苹果产业供需对接平台，服务于云南昭通洒渔镇苹果产业的四类主体（果农/工人/客商/农资商），包含三个子项目：

子项目	目录	说明
后端服务	`service/`	Java 后端 API 服务
微信小程序	`wxapp/`	面向用户的微信小程序端（四类用户角色）
后台管理	`wxbackstage/`	政府管理部门使用的运营管理后台

技术栈

后端: Java 8 / Spring Boot 1.5.9 / Maven 单体项目
数据库: MySQL（crrc 库）
ORM: MyBatis（XML 映射文件位于 src/main/resources/mapper/）
测试: JUnit 4 + Spring Boot Test
小程序: 微信原生开发
视频存储: 阿里云 OSS（前端直传，后端申请凭证）
短信服务: 阿里云短信 API
缓存: Redis（数据大屏统计缓存）

项目结构（Maven 单体项目）

项目采用 Maven 构建，单体 Spring Boot 应用，所有模块在同一项目中：

service/
├── pom.xml                              # Maven 构建配置
└── src/main/
    ├── java/com/fenzhitech/crrc/
    │   ├── controller/wx/               # 小程序端接口（/api/wx/*）
    │   ├── controller/admin/            # 后台管理端接口（/api/admin/*）
    │   ├── service/                     # 业务逻辑层
    │   ├── mapper/                      # MyBatis Mapper 接口
    │   ├── entity/                      # 数据库实体
    │   ├── dto/                         # 数据传输对象
    │   ├── vo/                          # 视图对象
    │   ├── config/                      # 配置类
    │   ├── interceptor/                 # 拦截器（JWT 认证）
    │   ├── util/                        # 工具类
    │   └── task/                        # 定时任务
    └── resources/
        ├── application.properties       # 应用配置
        └── mapper/                      # MyBatis XML 映射文件

常用命令

编译验证：

cd service
mvn compile

运行测试：

cd service
mvn test

打包：

cd service
mvn package -DskipTests

启动服务：

cd service
mvn spring-boot:run

API 设计规范

小程序端接口前缀：/api/wx/*
后台管理端接口前缀：/api/admin/*
认证机制：小程序端微信 code→JWT，后台端账号密码→JWT，独立拦截器
权限模型：RBAC，默认拒绝，显式授权
数据过滤：接口返回过滤敏感字段，手机号通过单独拨号接口获取（记录拨号日志）

数据库设计要点

手机号 AES 加密存储，phone_hash(SHA256) 建唯一索引用于查询
所有业务表带 user_identity_id 字段，实现数据隔离（一人多职场景）
经纬度复合索引用于距离查询（Haversine 公式）
核心表：sys_user、user_identity、grower_profile、worker_profile、recruit_info、buyer_profile、phone_unlock_record、call_log、sms_daily_limit、market_price

关键业务规则

招工发布：免审核直接发布，敏感关键词自动标记+待复核列表
工人状态：手动切换+3天无操作自动恢复"空闲"，信用机制（投诉1警告→2限24h→3锁定）
联系授权：客商勾选批次→解锁果农电话，有效期7天
防骚扰：同一工人每天对同一果农最多1条短信（自然日）
审核SLA：≤24小时提醒，48小时升级给超级管理员
视频上传：前端直传 OSS，≤50MB/720p/2Mbps/≤5分钟，前端清除 EXIF
适老化：正文≥18px(rem)、按钮≥88×88px、高对比度、语音输入

开发流程

本项目采用多 Agent 协同开发流程（详见 docs/multi-agent-git-workflow-v2.1.md），核心流程：

需求分析 (Team A) → phase/01-requirement
架构设计 (Team B) → phase/02-architecture
编码实现 (Team C) → phase/03-coding（含编译自检门控）
测试验收 (Team D) → phase/04-testing（JUnit 4 风格自动化测试）

每个阶段产出 DELIVERY-MANIFEST.md 交付清单，业务领导审批通过后合并到 main。

Git 分支命名

main                          # 主分支
phase/01-requirement          # 各阶段工作分支
phase/02-architecture
phase/03-coding
phase/04-testing
rework/XX-阶段名              # 返工分支
backport/xxx-description      # 回溯分支

Commit Message 格式

[milestone-N] 简述内容
[rework-N] 简述返工内容
[backport-N] 简述回溯修改内容

关键约束

MyBatis XML 中参数必须使用 #{} 语法，禁止 ${}（防 SQL 注入）
拦截器的免登录/免权限路径配置需在新增公开接口时同步检查
测试目录为标准 src/test/java/，不得在 src/main/ 下创建测试文件

文档目录

文档	路径	说明
功能清单	`docs/洒渔镇苹果产业供需对接平台功能清单-V1.0.docx`	原始产品功能需求（45个功能点）
需求规格说明书	`docs/requirements-specification.md`	完整需求文档（功能/数据模型/接口/非功能需求）
需求研讨记录	`docs/requirements-discussion.md`	6角色7议题正反论证+投票过程
阶段规划说明书	`docs/phase-planning.md`	4阶段划分+各阶段功能清单+验收标准+测试重点
阶段划分研讨记录	`docs/phase-planning-discussion.md`	6角色阶段划分讨论过程
开发流程设计	`docs/multi-agent-git-workflow-v2.1.md`	多 Agent 协同开发流程（v2.2）
阶段零任务清单	`docs/phase-0-tasks.md`	环境准备详细任务（9项，0.5周）
阶段一任务清单	`docs/phase-1-tasks.md`	基础设施与用户体系（M1-M4，20功能点）
阶段2a任务清单	`docs/phase-2a-tasks.md`	果农核心功能（M1-M4，14功能点）
阶段2b任务清单	`docs/phase-2b-tasks.md`	工人+客商+农资（M1-M4，13功能点）
阶段三任务清单	`docs/phase-3-tasks.md`	运营功能与统计（M1-M4，14功能点）
数据库配置	`docs/mysql数据库配置.txt`	MySQL 连接配置
Git 远程仓库	`docs/git远程仓库.txt`	Gogs 远程仓库信息

CLAUDE.md 6.4 KB History Raw