# Image Captcha SMS Protection Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add a required image captcha before sending mobile SMS codes for the H5 verification app, reducing SMS abuse while keeping the existing mobile login flow.

**Architecture:** Reuse the existing `pig-auth` image captcha endpoint `/auth/code/image?randomStr=...`. The H5 login page will fetch and display that image, then send `phone`, `randomStr`, and `imageCode` to a new POST SMS endpoint in `pig-upms`; the backend validates the image captcha from Redis before sending the SMS code. Keep the existing SMS rate limiting and SMS login verification unchanged.

**Tech Stack:** Vue 3 + Vite + Vant + TypeScript frontend; Spring Boot Java backend; Redis via `StringRedisTemplate` / `RedisTemplate`; existing Pig response wrapper `R`.

---

## File Structure

Frontend repository: `/Users/andy/IdeaProjects/hotel-biz-h5`

- Modify `src/api/auth.ts`: add image captcha URL helper and change `sendMobileCode` to POST a structured payload.
- Modify `src/views/login/LoginView.vue`: add image captcha state, input field, refresh behavior, and send-SMS validation.
- Modify `src/api/mock.ts`: accept the new SMS payload shape in mock mode.
- Optional modify `docs/frontend-practices.md`: record that SMS sending requires image captcha.

Backend repository: `/Users/andy/IdeaProjects/one-feel-server`

- Create `pig-upms/pig-upms-api/src/main/java/com/pig4cloud/pig/admin/api/form/SendMobileCodeForm.java`: request body for SMS code sending.
- Modify `pig-upms/pig-upms-biz/src/main/java/com/pig4cloud/pig/admin/controller/PlatformUserController.java`: add POST endpoint and validate request body.
- Create `pig-upms/pig-upms-biz/src/main/java/com/pig4cloud/pig/admin/service/impl/ImageCaptchaVerifier.java`: verify image captcha from Redis and delete it on success.
- Modify `pig-upms/pig-upms-biz/src/main/java/com/pig4cloud/pig/admin/service/impl/PlatformMobileServiceImpl.java`: keep existing send logic; do not move captcha logic here unless controller becomes too large.
- Add focused backend tests under `pig-upms/pig-upms-biz/src/test/java/com/pig4cloud/pig/admin/service/impl/`.

---

### Task 1: Backend Request Form

**Files:**
- Create: `/Users/andy/IdeaProjects/one-feel-server/pig-upms/pig-upms-api/src/main/java/com/pig4cloud/pig/admin/api/form/SendMobileCodeForm.java`

- [ ] **Step 1: Create the request form**

```java
package com.pig4cloud.pig.admin.api.form;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

@Data
@Schema(description = "发送手机验证码请求")
public class SendMobileCodeForm {

	@Schema(description = "手机号")
	private String phone;

	@Schema(description = "图形验证码随机标识")
	private String randomStr;

	@Schema(description = "图形验证码")
	private String imageCode;

}
```

- [ ] **Step 2: Compile API module**

Run:

```bash
cd /Users/andy/IdeaProjects/one-feel-server
mvn -pl pig-upms/pig-upms-api -am -DskipTests compile
```

Expected: build succeeds with no compilation errors.

- [ ] **Step 3: Commit**

```bash
cd /Users/andy/IdeaProjects/one-feel-server
git add pig-upms/pig-upms-api/src/main/java/com/pig4cloud/pig/admin/api/form/SendMobileCodeForm.java
git commit -m "新增发送短信验证码请求表单"
```

---

### Task 2: Backend Image Captcha Verifier

**Files:**
- Create: `/Users/andy/IdeaProjects/one-feel-server/pig-upms/pig-upms-biz/src/main/java/com/pig4cloud/pig/admin/service/impl/ImageCaptchaVerifier.java`
- Test: `/Users/andy/IdeaProjects/one-feel-server/pig-upms/pig-upms-biz/src/test/java/com/pig4cloud/pig/admin/service/impl/ImageCaptchaVerifierTest.java`

- [ ] **Step 1: Write the failing unit test**

```java
package com.pig4cloud.pig.admin.service.impl;

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.data.redis.core.ValueOperations;

import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;

class ImageCaptchaVerifierTest {

	private StringRedisTemplate redisTemplate;

	private ValueOperations<String, String> valueOperations;

	private ImageCaptchaVerifier verifier;

	@BeforeEach
	void setUp() {
		redisTemplate = mock(StringRedisTemplate.class);
		valueOperations = mock(ValueOperations.class);
		when(redisTemplate.opsForValue()).thenReturn(valueOperations);
		verifier = new ImageCaptchaVerifier(redisTemplate);
	}

	@Test
	void verifyAndDeletePassesAndDeletesKeyWhenCodeMatches() {
		when(valueOperations.get("DEFAULT_CODE_KEY:abc123")).thenReturn("8");

		assertDoesNotThrow(() -> verifier.verifyAndDelete("abc123", "8"));

		verify(redisTemplate).delete("DEFAULT_CODE_KEY:abc123");
	}

	@Test
	void verifyAndDeleteRejectsBlankValues() {
		assertThrows(IllegalArgumentException.class, () -> verifier.verifyAndDelete("", "8"));
		assertThrows(IllegalArgumentException.class, () -> verifier.verifyAndDelete("abc123", ""));
	}

	@Test
	void verifyAndDeleteRejectsMissingRedisCode() {
		when(valueOperations.get("DEFAULT_CODE_KEY:abc123")).thenReturn(null);

		assertThrows(IllegalArgumentException.class, () -> verifier.verifyAndDelete("abc123", "8"));
	}

	@Test
	void verifyAndDeleteRejectsWrongCode() {
		when(valueOperations.get("DEFAULT_CODE_KEY:abc123")).thenReturn("8");

		assertThrows(IllegalArgumentException.class, () -> verifier.verifyAndDelete("abc123", "9"));
	}

}
```

- [ ] **Step 2: Run test to verify it fails**

Run:

```bash
cd /Users/andy/IdeaProjects/one-feel-server
mvn -pl pig-upms/pig-upms-biz -Dtest=ImageCaptchaVerifierTest test
```

Expected: FAIL because `ImageCaptchaVerifier` does not exist.

- [ ] **Step 3: Implement the verifier**

```java
package com.pig4cloud.pig.admin.service.impl;

import cn.hutool.core.util.StrUtil;
import com.pig4cloud.pig.common.core.constant.CacheConstants;
import lombok.RequiredArgsConstructor;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.stereotype.Component;

@Component
@RequiredArgsConstructor
public class ImageCaptchaVerifier {

	private final StringRedisTemplate redisTemplate;

	public void verifyAndDelete(String randomStr, String imageCode) {
		if (StrUtil.hasBlank(randomStr, imageCode)) {
			throw new IllegalArgumentException("图形验证码不能为空");
		}

		String key = CacheConstants.DEFAULT_CODE_KEY + randomStr;
		String savedCode = redisTemplate.opsForValue().get(key);
		if (StrUtil.isBlank(savedCode)) {
			throw new IllegalArgumentException("图形验证码已过期，请刷新后重试");
		}

		if (!StrUtil.equalsIgnoreCase(savedCode, imageCode.trim())) {
			throw new IllegalArgumentException("图形验证码不正确");
		}

		redisTemplate.delete(key);
	}

}
```

- [ ] **Step 4: Run test to verify it passes**

Run:

```bash
cd /Users/andy/IdeaProjects/one-feel-server
mvn -pl pig-upms/pig-upms-biz -Dtest=ImageCaptchaVerifierTest test
```

Expected: PASS.

- [ ] **Step 5: Commit**

```bash
cd /Users/andy/IdeaProjects/one-feel-server
git add pig-upms/pig-upms-biz/src/main/java/com/pig4cloud/pig/admin/service/impl/ImageCaptchaVerifier.java \
  pig-upms/pig-upms-biz/src/test/java/com/pig4cloud/pig/admin/service/impl/ImageCaptchaVerifierTest.java
git commit -m "增加图形验证码校验器"
```

---

### Task 3: Backend POST SMS Endpoint

**Files:**
- Modify: `/Users/andy/IdeaProjects/one-feel-server/pig-upms/pig-upms-biz/src/main/java/com/pig4cloud/pig/admin/controller/PlatformUserController.java`
- Uses: `/Users/andy/IdeaProjects/one-feel-server/pig-upms/pig-upms-api/src/main/java/com/pig4cloud/pig/admin/api/form/SendMobileCodeForm.java`
- Uses: `/Users/andy/IdeaProjects/one-feel-server/pig-upms/pig-upms-biz/src/main/java/com/pig4cloud/pig/admin/service/impl/ImageCaptchaVerifier.java`

- [ ] **Step 1: Add imports**

Add these imports if absent:

```java
import cn.hutool.core.lang.Validator;
import com.pig4cloud.pig.admin.api.form.SendMobileCodeForm;
import com.pig4cloud.pig.admin.service.impl.ImageCaptchaVerifier;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.PostMapping;
```

- [ ] **Step 2: Inject the verifier**

Find the controller fields and constructor style. Add a field:

```java
private final ImageCaptchaVerifier imageCaptchaVerifier;
```

If `PlatformUserController` uses Lombok `@RequiredArgsConstructor`, this field is enough. If it has an explicit constructor, add `ImageCaptchaVerifier imageCaptchaVerifier` to that constructor and assign it.

- [ ] **Step 3: Add the new POST endpoint next to the existing GET endpoint**

```java
@PostMapping("/sendMobileCode")
public R<Boolean> sendMobileCode(@RequestBody SendMobileCodeForm form,
		@RequestHeader(value = SecurityConstants.CLIENT_CONFIG_ID_PARAMETER_NAME, required = false) String clientConfigId) {
	assertValidSmsClientConfig(form.getPhone(), clientConfigId);
	assertValidImageCode(form);
	imageCaptchaVerifier.verifyAndDelete(form.getRandomStr(), form.getImageCode());
	return platformMobileService.sendSmsCode(form.getPhone(), clientConfigId);
}
```

- [ ] **Step 4: Add strict validation helpers**

Add these private methods near `assertValidSmsClientConfig`:

```java
private void assertValidImageCode(SendMobileCodeForm form) {
	if (form == null || StrUtil.hasBlank(form.getRandomStr(), form.getImageCode())) {
		throw new CheckedException("图形验证码不能为空");
	}
}

private void assertValidSmsClientConfig(String phone, String clientConfigId) {
	if (StrUtil.hasBlank(phone, clientConfigId)) {
		throw new CheckedException("手机号或clientConfigId不能为空");
	}
	if (!Validator.isMobile(phone)) {
		throw new CheckedException("手机号格式不正确");
	}
	ClientConfigEntity clientConfig = clientConfigService.getById(clientConfigId);
	if (Objects.isNull(clientConfig) || StrUtil.isBlank(clientConfig.getClientTenantId())) {
		log.error("短信验证码发送失败，客户端配置不存在或未配置租户，clientConfigId={}", clientConfigId);
		throw new CheckedException("验证码发送失败");
	}
	try {
		Long.parseLong(clientConfig.getClientTenantId());
	}
	catch (NumberFormatException ex) {
		log.error("短信验证码发送失败，客户端租户配置非法，clientConfigId={}, clientTenantId={}", clientConfigId,
				clientConfig.getClientTenantId());
		throw new CheckedException("验证码发送失败");
	}
}
```

Important: replace the existing `assertValidSmsClientConfig` body instead of creating a duplicate method.

- [ ] **Step 5: Keep the old GET endpoint temporarily**

Do not delete this method in the first rollout:

```java
@GetMapping("/sendMobileCode/{phone}")
public R<Boolean> sendMobileCode(@PathVariable String phone,
		@RequestHeader(value = SecurityConstants.CLIENT_CONFIG_ID_PARAMETER_NAME, required = false) String clientConfigId) {
	assertValidSmsClientConfig(phone, clientConfigId);
	return platformMobileService.sendSmsCode(phone, clientConfigId);
}
```

Reason: keeping it avoids breaking other clients immediately. After H5 and other clients migrate, remove the GET endpoint in a separate cleanup.

- [ ] **Step 6: Compile backend**

Run:

```bash
cd /Users/andy/IdeaProjects/one-feel-server
mvn -pl pig-upms/pig-upms-biz -am -DskipTests compile
```

Expected: build succeeds with no compilation errors.

- [ ] **Step 7: Commit**

```bash
cd /Users/andy/IdeaProjects/one-feel-server
git add pig-upms/pig-upms-biz/src/main/java/com/pig4cloud/pig/admin/controller/PlatformUserController.java
git commit -m "短信验证码发送增加图形验证码校验"
```

---

### Task 4: Frontend API Contract

**Files:**
- Modify: `/Users/andy/IdeaProjects/hotel-biz-h5/src/api/auth.ts`
- Modify: `/Users/andy/IdeaProjects/hotel-biz-h5/src/api/mock.ts`

- [ ] **Step 1: Update `src/api/auth.ts` types and helpers**

Replace the existing `sendMobileCode` implementation with:

```ts
export interface SendMobileCodePayload {
  phone: string
  randomStr: string
  imageCode: string
}

export const getImageCodeUrl = (randomStr: string) =>
  joinUrl(env.authBase, 'code/image') + `?randomStr=${encodeURIComponent(randomStr)}&t=${Date.now()}`

export const sendMobileCode = async (payload: SendMobileCodePayload) => {
  if (env.useMock) return mockApi.sendMobileCode(payload)
  return await http.post<boolean>(joinUrl(env.adminBase, 'platformUser/sendMobileCode'), payload, {
    headers: {
      clientId: env.clientId,
      clientConfigId: env.clientConfigId
    }
  }) as unknown as boolean
}
```

- [ ] **Step 2: Update `src/api/mock.ts`**

Change the mock method signature:

```ts
async sendMobileCode(payload: { phone: string; randomStr?: string; imageCode?: string }) {
  await wait()
  if (!payload.phone) return { data: false, msg: '请输入手机号' }
  if (!payload.imageCode) return { data: false, msg: '请输入图形验证码' }
  return { data: true, msg: '5678nianxx' }
}
```

- [ ] **Step 3: Run frontend typecheck to verify expected failures**

Run:

```bash
cd /Users/andy/IdeaProjects/hotel-biz-h5
yarn typecheck
```

Expected: FAIL because `LoginView.vue` still calls `sendMobileCode(phone.value)`.

- [ ] **Step 4: Commit only if the expected failure is documented**

Do not commit a failing frontend state. Continue to Task 5 before committing frontend changes.

---

### Task 5: Frontend Login Page UI

**Files:**
- Modify: `/Users/andy/IdeaProjects/hotel-biz-h5/src/views/login/LoginView.vue`

- [ ] **Step 1: Update imports**

Change:

```ts
import { computed, ref } from 'vue'
import { sendMobileCode } from '@/api/auth'
```

to:

```ts
import { computed, onMounted, ref } from 'vue'
import { getImageCodeUrl, sendMobileCode } from '@/api/auth'
```

- [ ] **Step 2: Add captcha state**

Add below `const code = ref('')`:

```ts
const imageCode = ref('')
const captchaRandomStr = ref('')
const captchaUrl = ref('')
```

- [ ] **Step 3: Add captcha refresh helpers**

Add below `let timer: number | undefined`:

```ts
const createRandomStr = () => `${Date.now()}${Math.random().toString(36).slice(2, 10)}`

const refreshCaptcha = () => {
  captchaRandomStr.value = createRandomStr()
  captchaUrl.value = getImageCodeUrl(captchaRandomStr.value)
  imageCode.value = ''
}
```

- [ ] **Step 4: Update send eligibility**

Replace:

```ts
const canSend = computed(() => /^1\d{10}$/.test(phone.value) && seconds.value === 0)
```

with:

```ts
const canSend = computed(() => /^1\d{10}$/.test(phone.value) && imageCode.value.trim().length > 0 && seconds.value === 0)
```

- [ ] **Step 5: Update `handleSend` validation and payload**

Replace the beginning of `handleSend` with:

```ts
const handleSend = async () => {
  if (!/^1\d{10}$/.test(phone.value)) {
    showToast('请输入正确手机号')
    return
  }
  if (!imageCode.value.trim()) {
    showToast('请输入图形验证码')
    return
  }
  sending.value = true
  try {
    const result = await sendMobileCode({
      phone: phone.value,
      randomStr: captchaRandomStr.value,
      imageCode: imageCode.value.trim()
    })
    const message = typeof result === 'object' && result && 'msg' in result ? result.msg : ''
    if (message) {
      code.value = String(message)
      showToast(`验证码：${message}`)
    } else {
      showToast('验证码已发送')
    }
    startCountdown()
  } catch (error) {
    refreshCaptcha()
    showToast(error instanceof Error ? error.message : '验证码发送失败')
  } finally {
    sending.value = false
  }
}
```

- [ ] **Step 6: Initialize captcha on mount**

Add below `handleLogin`:

```ts
onMounted(refreshCaptcha)
```

- [ ] **Step 7: Add captcha field to template**

Insert this `van-field` between phone and SMS code fields:

```vue
<van-field
  v-model="imageCode"
  type="text"
  name="imageCode"
  maxlength="8"
  placeholder="请输入图形验证码"
  autocomplete="off"
  clearable
>
  <template #left-icon><ShieldCheck :size="18" /></template>
  <template #button>
    <button class="captcha-image-button" type="button" @click="refreshCaptcha">
      <img v-if="captchaUrl" :src="captchaUrl" alt="图形验证码" />
      <span v-else>刷新</span>
    </button>
  </template>
</van-field>
```

- [ ] **Step 8: Add scoped styles**

Add before the closing `</style>`:

```css
.captcha-image-button {
  display: inline-flex;
  width: 100px;
  height: 40px;
  align-items: center;
  justify-content: center;
  overflow: hidden;
  border: 0;
  border-radius: var(--radius);
  background: var(--surface-soft);
  color: var(--primary-deep);
  padding: 0;
}

.captcha-image-button img {
  display: block;
  width: 100px;
  height: 40px;
  object-fit: cover;
}
```

- [ ] **Step 9: Run frontend checks**

Run:

```bash
cd /Users/andy/IdeaProjects/hotel-biz-h5
yarn typecheck
yarn build:test
```

Expected: both pass. `vite build` may still show the existing router dynamic/static import warning; that warning is unrelated.

- [ ] **Step 10: Commit frontend changes**

```bash
cd /Users/andy/IdeaProjects/hotel-biz-h5
git add src/api/auth.ts src/api/mock.ts src/views/login/LoginView.vue
git commit -m "登录短信发送增加图形验证码"
```

---

### Task 6: End-to-End Manual Verification

**Files:**
- No code changes expected.

- [ ] **Step 1: Start backend services needed for auth, upms, gateway, and Redis**

Use the existing local backend startup process for `/Users/andy/IdeaProjects/one-feel-server`. Confirm these routes are reachable through the gateway:

```text
GET /auth/code/image?randomStr=manual-test
POST /admin/platformUser/sendMobileCode
POST /auth/oauth2/token
```

- [ ] **Step 2: Start frontend**

Run:

```bash
cd /Users/andy/IdeaProjects/hotel-biz-h5
yarn dev
```

Expected: Vite starts and prints a local URL.

- [ ] **Step 3: Verify captcha image loads**

Open `/login`.

Expected:
- Login title shows `核销端`.
- Phone input is visible.
- Image captcha input is visible.
- Captcha image loads from `/auth/code/image`.
- Clicking the image refreshes the URL and clears the image code input.

- [ ] **Step 4: Verify empty captcha is blocked by frontend**

Enter a valid phone number and leave image captcha empty. Click `获取验证码`.

Expected:
- No SMS request is sent.
- Toast says `请输入图形验证码`.

- [ ] **Step 5: Verify wrong captcha is rejected by backend**

Enter a valid phone number and a wrong image captcha. Click `获取验证码`.

Expected:
- `POST /admin/platformUser/sendMobileCode` returns a failure response.
- Toast shows backend error.
- Captcha image refreshes.

- [ ] **Step 6: Verify correct captcha sends SMS**

Enter a valid phone number and the correct image captcha. Click `获取验证码`.

Expected:
- SMS send endpoint returns success.
- Countdown starts.
- Existing SMS frequency limit still applies if clicking repeatedly.

- [ ] **Step 7: Verify login still works**

Enter the SMS code and submit login.

Expected:
- Login calls `/auth/oauth2/token`.
- After token success, frontend calls `/hotelStaff/organizationMember/bindUserInfoAndGetUserMemberInfoByPhone`.
- Bound users enter `/home`.
- Unbound users see `未绑定组织，请联系管理员`.

---

### Task 7: Documentation Update

**Files:**
- Modify: `/Users/andy/IdeaProjects/hotel-biz-h5/docs/frontend-practices.md`

- [ ] **Step 1: Add SMS captcha note**

Add this bullet under `## 登录与组织关系`:

```markdown
- 发送短信验证码前必须先通过图形验证码校验；前端展示 `/auth/code/image` 生成的验证码图片，后端在 `/admin/platformUser/sendMobileCode` 校验 `randomStr` 和 `imageCode` 后才发送短信。
```

- [ ] **Step 2: Run docs diff check**

Run:

```bash
cd /Users/andy/IdeaProjects/hotel-biz-h5
git diff --check docs/frontend-practices.md
```

Expected: no output.

- [ ] **Step 3: Commit docs**

```bash
cd /Users/andy/IdeaProjects/hotel-biz-h5
git add docs/frontend-practices.md
git commit -m "补充短信图形验证码约定"
```

---

## Rollout Notes

- Keep the old GET endpoint during the first deployment to avoid breaking unknown clients.
- H5 should switch to the new POST endpoint immediately after backend deployment.
- After production confirms no clients call `GET /admin/platformUser/sendMobileCode/{phone}`, remove the GET endpoint in a later cleanup.
- Do not remove existing Redis SMS frequency limits; image captcha is an additional layer, not a replacement.
- Do not rely on frontend captcha checks for security; backend validation is required.

## Execution Checkpoints

### Checkpoint 0: Baseline Safety

**Purpose:** Confirm both repositories are in a known state before touching code.

**Scope:** No code changes.

**Verification commands:**

```bash
cd /Users/andy/IdeaProjects/hotel-biz-h5
git status --short --branch
yarn typecheck

cd /Users/andy/IdeaProjects/one-feel-server
git status --short --branch
mvn -pl pig-upms/pig-upms-api -am -DskipTests compile
```

**Pass criteria:**
- Current branch and dirty files are understood.
- Existing frontend typecheck passes.
- Backend API module compiles before changes.

**Stop condition:** If baseline build fails for unrelated reasons, record the failure and do not start feature work until the owner decides whether to fix baseline first.

### Checkpoint 1: Backend Contract Ready

**Purpose:** Add the new SMS request body without changing runtime behavior.

**Scope:** Task 1 only.

**Verification commands:**

```bash
cd /Users/andy/IdeaProjects/one-feel-server
mvn -pl pig-upms/pig-upms-api -am -DskipTests compile
git show --stat --oneline HEAD
```

**Pass criteria:**
- `SendMobileCodeForm` exists with `phone`, `randomStr`, and `imageCode`.
- API module compiles.
- Commit contains only the request form.

**Rollback point:** Revert the request-form commit only.

### Checkpoint 2: Captcha Verifier Proven

**Purpose:** Prove Redis image captcha validation works before wiring it into the SMS endpoint.

**Scope:** Task 2 only.

**Verification commands:**

```bash
cd /Users/andy/IdeaProjects/one-feel-server
mvn -pl pig-upms/pig-upms-biz -Dtest=ImageCaptchaVerifierTest test
git show --stat --oneline HEAD
```

**Pass criteria:**
- Matching captcha passes and deletes `DEFAULT_CODE_KEY:{randomStr}`.
- Blank, missing, and wrong captcha values fail.
- Unit test passes.
- Commit contains only verifier and verifier test.

**Stop condition:** If the project lacks test dependencies for this isolated unit test, stop and decide whether to add test dependencies or verify with an integration test instead.

**Rollback point:** Revert the verifier commit only.

### Checkpoint 3: Backend Endpoint Protected

**Purpose:** Make SMS sending require backend image captcha validation while preserving the old GET endpoint for compatibility.

**Scope:** Task 3 only.

**Verification commands:**

```bash
cd /Users/andy/IdeaProjects/one-feel-server
mvn -pl pig-upms/pig-upms-biz -am -DskipTests compile
git diff --check
git show --stat --oneline HEAD
```

**Pass criteria:**
- New `POST /admin/platformUser/sendMobileCode` accepts `SendMobileCodeForm`.
- Backend validates phone format, `clientConfigId`, `randomStr`, and `imageCode`.
- Captcha verification runs before `platformMobileService.sendSmsCode`.
- Existing `GET /sendMobileCode/{phone}` is still present.
- Existing SMS rate limits are untouched.

**Manual smoke check after backend starts:**

```text
POST /admin/platformUser/sendMobileCode
body: {"phone":"13800000000","randomStr":"wrong","imageCode":"0000"}
Expected: failure response, no SMS sent.
```

**Rollback point:** Revert the backend endpoint commit. Old GET endpoint remains available.

### Checkpoint 4: Frontend Contract Switched

**Purpose:** Move H5 from URL-phone GET sending to structured POST sending.

**Scope:** Task 4 and Task 5.

**Verification commands:**

```bash
cd /Users/andy/IdeaProjects/hotel-biz-h5
yarn typecheck
yarn build:test
git diff --check src/api/auth.ts src/api/mock.ts src/views/login/LoginView.vue
git show --stat --oneline HEAD
```

**Pass criteria:**
- Login page displays phone input, image captcha input, captcha image, SMS code input, and login button.
- `sendMobileCode` sends `phone`, `randomStr`, and `imageCode` to `POST /admin/platformUser/sendMobileCode`.
- Empty image captcha is blocked in the frontend with `请输入图形验证码`.
- Failed SMS send shows a toast and refreshes captcha.
- Mock mode still works.

**Manual smoke check with frontend only:**

```text
1. Start H5 in mock mode.
2. Open /login.
3. Try sending with empty image captcha.
4. Expected: toast says 请输入图形验证码 and no countdown starts.
5. Enter any image captcha in mock mode and send.
6. Expected: countdown starts and mock SMS code appears.
```

**Rollback point:** Revert the frontend commit. Backend POST endpoint can remain deployed without affecting old clients.

### Checkpoint 5: End-to-End Gate

**Purpose:** Verify the complete browser -> gateway -> auth/upms -> Redis flow before release.

**Scope:** Task 6.

**Verification steps:**

```text
1. Start Redis, gateway, pig-auth, pig-upms, and H5.
2. Open /login.
3. Confirm captcha image loads from /auth/code/image.
4. Enter wrong image captcha and click 获取验证码.
5. Expected: SMS endpoint returns failure and no countdown starts.
6. Refresh captcha, enter correct image captcha, and click 获取验证码.
7. Expected: SMS send succeeds and countdown starts.
8. Enter SMS code and login.
9. Expected: token endpoint succeeds, organization binding endpoint runs, bound user enters /home.
```

**Pass criteria:**
- Wrong captcha cannot send SMS.
- Correct captcha can send SMS.
- Captcha cannot be reused after one successful SMS send.
- Existing SMS frequency limit still blocks repeated sends.
- Login flow after receiving SMS code is unchanged.

**Stop condition:** If correct captcha still fails, inspect Redis key serialization between `ImageCodeEndpoint` and `ImageCaptchaVerifier` before changing frontend code.

### Checkpoint 6: Documentation And Release Readiness

**Purpose:** Lock the new behavior into project docs and prepare release notes.

**Scope:** Task 7 and release review.

**Verification commands:**

```bash
cd /Users/andy/IdeaProjects/hotel-biz-h5
git diff --check docs/frontend-practices.md

cd /Users/andy/IdeaProjects/one-feel-server
git log --oneline -3

cd /Users/andy/IdeaProjects/hotel-biz-h5
git log --oneline -3
```

**Pass criteria:**
- Docs say SMS sending requires image captcha.
- Backend commits and frontend commits are clearly separated.
- Release notes mention that old GET SMS endpoint is temporarily retained.

**Release decision:** Deploy backend first, then deploy H5. Do not deploy H5 before the backend POST endpoint is available.

## Self-Review

- Spec coverage: The plan covers existing image captcha reuse, backend POST endpoint, Redis verification, frontend login UI, API contract, tests, manual verification, and documentation.
- Placeholder scan: No `TBD`, `TODO`, or vague "handle edge cases" steps remain; each task includes concrete file paths and code.
- Type consistency: Frontend `SendMobileCodePayload` fields match backend `SendMobileCodeForm` fields: `phone`, `randomStr`, `imageCode`.