# 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 映射文件
```

## 常用命令

编译验证：
```bash
cd service
mvn compile
```

运行测试：
```bash
cd service
mvn test
```

打包：
```bash
cd service
mvn package -DskipTests
```

启动服务：
```bash
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`），核心流程：

1. **需求分析** (Team A) → `phase/01-requirement`
2. **架构设计** (Team B) → `phase/02-architecture`
3. **编码实现** (Team C) → `phase/03-coding`（含编译自检门控）
4. **测试验收** (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 远程仓库信息 |