Files

2026-07-01 12:54:49 +08:00

27 KiB

Raw Blame History

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

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:

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

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

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:

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

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:

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

Expected: PASS.

Step 5: Commit

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:

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:

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

@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:

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:

@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:

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

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:

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:

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:

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.

Files:

Modify: /Users/andy/IdeaProjects/hotel-biz-h5/src/views/login/LoginView.vue
Step 1: Update imports

Change:

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

to:

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

Step 2: Add captcha state

Add below const code = ref(''):

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

Step 3: Add captcha refresh helpers

Add below let timer: number | undefined:

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:

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

with:

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:

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:

onMounted(refreshCaptcha)

Step 7: Add captcha field to template

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

<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>:

.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:

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

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:

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

Step 2: Start frontend

Run:

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 ## 登录与组织关系:

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

Step 2: Run docs diff check

Run:

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

Expected: no output.

Step 3: Commit docs

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:

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:

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:

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:

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:

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:

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:

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:

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:

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.

27 KiB Raw Blame History Unescape Escape

Image Captcha SMS Protection Implementation Plan

File Structure

Task 1: Backend Request Form

Task 2: Backend Image Captcha Verifier

Task 3: Backend POST SMS Endpoint

Task 4: Frontend API Contract

Task 5: Frontend Login Page UI

Task 6: End-to-End Manual Verification

Task 7: Documentation Update

Rollout Notes

Execution Checkpoints

Checkpoint 0: Baseline Safety

Checkpoint 1: Backend Contract Ready

Checkpoint 2: Captcha Verifier Proven

Checkpoint 3: Backend Endpoint Protected

Checkpoint 4: Frontend Contract Switched

Checkpoint 5: End-to-End Gate

Checkpoint 6: Documentation And Release Readiness

Self-Review

27 KiB

Raw Blame History