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 / Gradle 多模块构建
数据库: MySQL（crrc 库）
ORM: MyBatis（XML 映射文件位于 src/main/resources/mapper/）
测试: JUnit 4 + Spring Boot Test
小程序: 微信原生开发
视频存储: 阿里云 OSS（前端直传，后端申请凭证）
短信服务: 阿里云短信 API
缓存: Redis（数据大屏统计缓存）

项目结构（CRRC 多模块模式）

项目采用 Gradle 多模块结构，每个模块独立 build.gradle 和 gradlew，根目录无 settings.gradle：

service/
├── com.fenzhitech.crrc.service-common/    # 共享库（DTO/VO/常量），只读，修改需走返工流程
├── com.fenzhitech.crrc.service-user/      # 用户模块
├── com.fenzhitech.crrc.service-bill/      # 账单模块
├── com.fenzhitech.crrc.service-message/   # 消息模块
├── com.fenzhitech.crrc.service-*/         # 其他业务模块
├── com.fenzhitech.crrc.gateway-pc/        # PC 网关
├── com.fenzhitech.crrc.gateway-mobile/    # 移动端网关
└── com.fenzhitech.crrc.gateway-management/# 管理端网关

每个模块内部结构：

com.fenzhitech.crrc.service-xxx/
├── build.gradle
├── gradlew
├── src/main/java/         # 业务代码
├── src/main/resources/    # 配置 + MyBatis XML
└── src/test/java/         # 测试代码

常用命令

编译验证（必须进入具体模块目录执行）：

cd com.fenzhitech.crrc.service-xxx
./gradlew compileJava

依赖链编译（修改 service-common 后，先编译公共库再编译业务模块）：

cd com.fenzhitech.crrc.service-common && ./gradlew compileJava
cd com.fenzhitech.crrc.service-bill && ./gradlew compileJava

运行测试：

cd com.fenzhitech.crrc.service-xxx
./gradlew test

启动服务：

cd com.fenzhitech.crrc.service-xxx
./gradlew bootRun

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] 简述回溯修改内容

关键约束

service-common 是共享库，修改公共 DTO/VO/常量后需优先编译验证，且修改需走返工流程
MyBatis XML 中参数必须使用 #{} 语法，禁止 ${}（防 SQL 注入）
网关层（gateway-pc、gateway-mobile、gateway-management）的免登录/免权限路径配置需在新增公开接口时同步检查
多模块间 Feign 调用路径和包名需与 SERVICE_NAME / SERVICE_CONTEXT_PATH 常量一致
测试目录为标准 src/test/java/，不得在 src/main/ 下创建测试文件

历史遗留拼写（不要误报）

contanst（非 constant）— 常量/枚举包名
bootstrapt（非 bootstrap）— service-file 模块启动包名
annotion（非 annotation）— 框架注解包名

文档目录

文档	路径	说明
功能清单	`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 7.0 KB Cronologia Originale