# 登录页

## 基本信息

| 项目 | 内容 |
| --- | --- |
| 路由 | `/pages/login/login` |
| 页面目标 | 让商户操作员完成身份认证并进入经营工作台。 |
| 进入方式 | 会话失效后应返回本页；演示阶段默认首屏为首页。 |
| 负责人/更新时间 | 待指定 / 2026-07-28 |

## 功能点

| 编号 | 功能 | 说明 | 当前状态 |
| --- | --- | --- | --- |
| F-001 | 品牌欢迎区 | 展示商户端欢迎语和本地插画。 | 已完成 |
| F-002 | 账号输入 | 支持最长 32 位账号输入；提交时清除首尾空格。 | 已完成 |
| F-003 | 密码输入 | 使用微信安全密码输入类型展示掩码，最长 64 位，避免触发 iOS 系统保存密码提示。 | 已完成 |
| F-004 | 本地校验 | 缺少账号、密码或未同意协议时展示对应错误状态。 | 已完成 |
| F-005 | 协议入口 | 服务协议、隐私政策均可在未登录状态进入现有富文本详情页查看。 | 已完成前端路由 |
| F-006 | 商户登录 | 调用鉴权接口建立商户、操作员和门店会话；开发环境可由独立开关跳过。 | 已接入 |

## 操作说明

1. 用户输入商户账号和登录密码，阅读并勾选协议。
2. 用户点击“登录”后，页面同时校验账号、密码和协议状态。
3. 输入项不完整时，账号、密码标题右侧显示对应红色提示；协议未勾选时显示协议提示。
4. 点击服务协议或隐私政策，可进入对应富文本详情并返回登录页。
5. 登录接口成功后，页面保存短期会话并使用 `uni.reLaunch` 进入首页。
6. 开发环境仅在显式开启跳过登录开关时才允许直接进入首页。

## 接口与数据

| 数据项/动作 | 接口标识 | 参数 | 返回字段 | 状态 |
| --- | --- | --- | --- | --- |
| 账号登录 | `POST /api/merchant/auth/login` | `account`、`password`、`agreed` | 会话令牌、过期时间、操作员、商户和门店列表 | 已接入 |
| 服务协议 | `GET /api/merchant/legal/agreements/user` | 无 | 标题、正文、版本号 | 已接入 |
| 隐私政策 | `GET /api/merchant/legal/agreements/privacy` | 无 | 标题、正文、版本号 | 已接入 |

## 异常处理

| 场景 | 用户可见提示 | 恢复方式 |
| --- | --- | --- |
| 账号未录入 | “账号未录入，请联系管理员” | 核对账号或联系管理员。 |
| 密码未录入 | “请输入登录密码” | 补充密码后重新提交。 |
| 账号或密码错误 | “账号或密码错误”（展示登录接口返回的提示） | 重新输入；正式环境需支持找回或重置密码。后端不区分账号不存在与密码错误，避免账号枚举。 |
| 未同意协议 | “请先阅读并同意相关协议” | 勾选协议后重新提交。 |
| 登录接口失败 | 待接口联调后明确 | 保留输入内容，允许用户重试。 |
| 登录失效 | 待接口联调后明确 | 清理会话并返回登录页。 |

## 验收清单

- [x] 视觉与登录设计图的欢迎区、表单和按钮层级一致。
- [x] 密码不以明文展示，页面不打印密码。
- [x] 本地校验和演示跳转已实现。
- [x] 未登录状态可查看服务协议与隐私政策详情。
- [x] 正式接口、协议正文、令牌刷新和登录失效处理已联调。
- [x] 本页面变更已同步到项目接口与开发进度文档。

开发环境可通过 `config/api.uts` 的 `skipMerchantLoginInDevelopment` 临时直达首页；该开关仅在 `apiEnvironment = 'development'` 时生效，预发和生产环境必须保持登录流程。