# 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/         # 测试代码
```

## 常用命令

编译验证（必须进入具体模块目录执行）：
```bash
cd com.fenzhitech.crrc.service-xxx
./gradlew compileJava
```

依赖链编译（修改 service-common 后，先编译公共库再编译业务模块）：
```bash
cd com.fenzhitech.crrc.service-common && ./gradlew compileJava
cd com.fenzhitech.crrc.service-bill && ./gradlew compileJava
```

运行测试：
```bash
cd com.fenzhitech.crrc.service-xxx
./gradlew test
```

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

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

## 关键约束

- `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 远程仓库信息 |