认证 API

认证接口覆盖验证码登录注册、密码登录注册和健康信息完成标记。除 POST /api/auth/complete-health-info 外，认证入口不要求 Bearer JWT。

Endpoint 索引

Method	Path	鉴权	用途
POST	/api/auth/send-sms	无	发送短信验证码。
POST	/api/auth/register	无	验证码注册；手机号已存在时直接登录。
POST	/api/auth/login	无	验证码登录；用户不存在时自动创建。
POST	/api/auth/register-password	无	手机号密码注册。
POST	/api/auth/login-password	无	手机号密码登录。
POST	/api/auth/complete-health-info	Bearer JWT	标记健康信息已完成。

Endpoint 契约

POST /api/auth/send-sms

项	内容
Request	phone，大陆手机号格式
Response	success、message
Errors	422 手机号格式；429 频率限制；500 短信失败
Consumer	AuthApiClient.sendSmsCode
Handler	auth.send_sms_code
DB Touchpoints	写 sms_verifications；读近期验证码记录做限流
Tests	tests/api/test_auth.py、tests/api/test_auth_dependency.py、test/api/auth_api_client_test.dart

POST /api/auth/register

项	内容
Request	phone、6 位 code
Response	success、message、token、user_id
Errors	400 验证码无效；422 参数格式；500 注册失败
Consumer	AuthApiClient.register
Handler	auth.register_user
DB Touchpoints	读写 sms_verifications；读写 users；写 login_logs
Tests	tests/api/test_auth.py

POST /api/auth/login

项	内容
Request	phone、6 位 code
Response	success、message、token、user_id
Errors	400 验证码无效；422 参数格式；500 登录失败
Consumer	旧验证码登录链路
Handler	auth.login_user
DB Touchpoints	读写 sms_verifications；读写 users；写 login_logs
Tests	tests/api/test_auth.py

POST /api/auth/register-password

项	内容
Request	phone、password、confirm_password
Response	success、message、token、user_id、health_info_completed=false
Errors	400 密码不一致/手机号已存在/密码规则失败；422 参数格式；500 注册失败
Consumer	AuthApiClient.registerWithPassword、密码注册页
Handler	auth.register_with_password
DB Touchpoints	写 users；写 login_logs
Tests	tests/services/test_auth_service.py、Flutter auth tests

POST /api/auth/login-password

项	内容
Request	phone、password
Response	success、message、token、user_id、health_info_completed
Errors	400 认证服务校验失败；401 手机号或密码错误；422 参数格式；500 登录失败
Consumer	AuthApiClient.loginWithPassword、密码登录页
Handler	auth.login_with_password
DB Touchpoints	读 users；写 login_logs
Tests	tests/services/test_auth_service.py、test/screens/auth/password_login_screen_test.dart

POST /api/auth/complete-health-info

项	内容
Request	空 body
Response	success、message
Errors	401 token 无效；500 标记失败
Consumer	AuthApiClient.completeHealthInfo
Handler	auth.complete_health_info
DB Touchpoints	更新 users.health_info_completed
Tests	tests/api/test_auth_dependency.py

Request 字段

字段	类型	约束	用于
phone	string	^1[3-9]\d{9}$	短信、验证码登录注册、密码登录注册
code	string	长度 6	验证码注册/登录
password	string	6-128 字符；具体强度由 AuthService 校验	密码注册/登录
confirm_password	string	必须与 password 一致	密码注册

Response 形态

{
  "success": true,
  "message": "登录成功",
  "token": "<jwt>",
  "user_id": "<user-id>",
  "health_info_completed": true
}

token 只在认证成功时返回。正式文档和日志中不得写入真实 JWT。

来源锚点

• Router: apps/backend_service/app/api/auth.py
• Dependency: apps/backend_service/app/api/auth_dependencies.py
• Service: apps/backend_service/app/services/auth_service.py
• Flutter: apps/flutter_app/lib/api/auth_api_client.dart
• Tests: apps/backend_service/tests/api/test_auth.py、apps/backend_service/tests/api/test_auth_dependency.py、apps/flutter_app/test/api/auth_api_client_test.dart