hera-web/docs/account-backend-integration.md

# 注册、资料与头像后端联调

## 本次接通范围

- 微信登录 → 新用户绑定手机号 → 完善资料；已注册用户直接恢复后端账号。
- 编辑页从后端回显，只有个人字段变更才提交资料更新。
- 头像通过现有后端文件存储服务上传。首页左上角、我的、编辑页共用头像组件和资料状态，成功保存后同步更新。
- 未填写生日、时辰、地区的新账号保持空值，不使用预览资料冒充真实账号。
- 登录凭证失效后清除本地会话；失效头像链接通过资料接口刷新，不在前端签名 COS 文件。
- 天宫绑定等已有隔离 Mock 未改成真实后端业务。本次没有提交或推送代码。

## 当前默认部署地址

- 前端默认 API 基址已改为 `http://101.43.139.56/hera`，登录、资料和头像上传均复用该前缀。
- 本地后端服务地址没有改变，但前端如需改回本机，构建前需设置 `HERA_API_BASE_URL=http://127.0.0.1:8080`；该设置在构建时生效。
- 只读探测远端 `/hera/api/user/profile` 当前返回 404，尚不能据此确认服务已经部署可用。服务器需要正确处理 `/hera` 代理或应用上下文路径；部署后未登录访问资料接口应返回 401，而不是 404。
- 服务器头像文件入口需独立配置 `TENCENT_COS_PUBLIC_BASE_URL`，例如 `http://101.43.139.56/hera/file/`，并转发到后端签名控制器。前端不改写后端返回的绝对头像 URL，不会把本地入口自动变成公网入口。
- HTTP/IP 地址为当前联调部署地址，正式小程序发布需配置 HTTPS 合法域名；本次未修改远程服务器、后端配置或存储权限。

## 本地入口与启动

- 前端：`http://127.0.0.1:4173/#/pages/my/index`，真实模式不带 `preview=1`。
- 后端：`http://127.0.0.1:8080`，已按用户授权使用现有本地配置启动。
- `?preview=1` 保留只读样例，不保存资料、不上传头像、不调用注册接口。
- `?avatarDemo=1` 为用户要求的 H5 已登录头像演示，可直接进入我的、选择本地图片并保存，首页/我的/编辑页同步；不创建登录 token，不请求后端或 COS，刷新后重置，不影响真实登录缓存。演示入口：`http://127.0.0.1:4173/?avatarDemo=1#/pages/my/index`。
- 导入前端项目根目录的 `project.config.json`，小程序目录为 `dist/`。修改源码后运行 `npm run build:weapp`，H5 运行 `npm run build:h5`。
- 构建前可设置 `HERA_API_BASE_URL`；真机的 `127.0.0.1` 指向手机本身，必须换成手机可访问的后端地址。
- H5 不具备小程序 `wx.login` 能力，不使用伪造 code 或临时开发 JWT 绕过注册。首次真实登录请用微信开发者工具或微信。

## 开发者工具验收

1. 导入项目并编译。在“我的”或首页点“登录 / 注册”，执行微信登录。新微信用户应看到手机号、验证码输入；老用户应直接恢复对应账号。
2. 新用户输入自己的手机号，点“获取验证码”。现有后端返回开发验证码，界面明确标记“非真实短信”；填入后绑定，进入“完善注册资料”。填写昵称、性别、生日、时辰、省市区并保存，应进入“我的”，再次进入编辑页数据应一致。
3. 点我的头部进入编辑页，依次测试微信头像、相册、拍照；取消选择不提交。选择后仅本页预览，点保存才上传；保存成功后首页、我的、编辑页应显示同一张头像，重新编译/重进后仍由后端回显。
4. 只修改头像：网络面板应出现 `POST /api/user/avatar`，不出现 `PUT /api/user/profile`，资料修改次数不减少。头像最大 5MB，格式限 JPG/PNG/WebP，服务端负责最终校验。
5. 只修改个人字段：保存应出现一次资料 PUT。什么都不改直接保存不消耗次数。连续点击保存不能重复提交。
6. 同时修改头像和资料：先上传头像再保存资料。上传失败时不得提交资料 PUT；若头像成功但资料失败，应明确提示部分成功，重试不重复上传已经保存的头像。
7. 清除登录缓存或使用失效凭证，进入真实模式应提示登录，不展示其他账号或假样例。已登录头像加载失效时应向资料接口重新取链接；网络不可用时保留默认头像，不无限重试。
8. 首页、我的及编辑页在窄屏、常见机型和底部安全区检查头像裁切、表单与导航；真机检查相册/相机权限、取消和失败提示。

## 本次使用的全部账号接口

统一业务响应为 `{ code, message, data }`，成功 `code=0`。资料与上传需要 `Authorization: Bearer <token>`；失效登录 HTTP 401。

| 方法与路径 | 参数 | 返回及用途 |
| --- | --- | --- |
| POST `/api/auth/wx-login` | JSON `{code}`，由真实 `wx.login` 获取 | 新用户 `{sessionKey,phoneBound:false}`；老用户包含 `{phoneBound:true,token,user}` |
| POST `/api/auth/sms` | JSON `{phone}` | `{mockCode}`，当前开发验证码，不是真实短信服务 |
| POST `/api/auth/bind-phone` | JSON `{sessionKey,phone,captcha}` | `{token,user}`，建立/绑定正式账号后进入资料补全或我的 |
| GET `/api/user/profile` | Bearer token | 完整资料，包含 `avatarUrl`、`remainingEdits`，供回显与头像链接续取 |
| PUT `/api/user/profile` | JSON `{nickname,gender,birthday,birthHour,province,city,district}` | 完整资料；受现有后端半年 5 次限制，不附带头像字段 |
| POST `/api/user/avatar` | Bearer token，multipart 字段 `file` | 完整资料；后端调用既有 COS 存储并关联账号，不消耗资料修改次数 |
| GET `/file/access?token=…` | 后端返回的文件专用临时 token，由图片加载访问 | 302 跳转私有 COS 签名地址；不是登录 token，不在前端拼装签名 |

接口均为现有真实接口，不是本次拟定的假接口。数据库保存 `cos://` 对象引用，前端只使用后端返回的访问 URL，不持久化临时签名为对象身份。

## 已验证与边界

- 前端自动测试 59 项通过（包含远端 API 前缀与本地覆盖、日主五行入口图标、隔离头像演示、编辑页样式作用域及 WXSS 兼容回归测试），TypeScript 检查、H5 和微信构建通过。13 个产物 WXSS 均通过本机微信开发者工具自带 `wcsc` 的原生编译检查；这不替代真实登录/上传验收。
- 后端干净构建默认执行的 17 项单元/隔离测试通过：注册/资料/头像控制器链路、账号 CRUD、仅当前表启动、头像限额与格式、401、文件访问、COS 和 Redis 配置测试。4 项需要显式启用的外部集成测试在默认构建中跳过。业务写入测试使用隔离 H2，微信客户端及实际 COS 上传使用测试替身，不代表已向真实 COS 上传成功。另有 1 项当前配置数据库的只读 Mapper 集成检查通过，不读取真实账号记录或写入数据库。
- 已运行的本地后端：无登录和无效凭证请求均返回 401；资料 PUT 跨域预检返回 200 并允许 Authorization、Content-Type。前端入口 HTTP 200。
- 真实联调阶段浏览器验收曾被额度限制阻止；后续用户要求的 H5 已登录演示已在浏览器验证：从相册选择项目测试图片、保存、我的/首页/重新进入编辑页均成功加载同一本地头像。截图保存在 `/private/tmp/hera-avatar-demo-my.png`。这不是实际 COS 上传证据；真实微信授权、真实账号写入和实际 COS 上传/展示仍须完成上述开发者工具验收。
- 本地 API 为 HTTP，现有文件公开入口也可能为 HTTP。上线和真机需确认 HTTPS、合法请求/上传/下载域名、图片重定向域名，以及文件入口和签发端使用一致的配置。不能仅凭后端启动成功认定真实文件入口已经可用。
- 头像文件入口本地联调已修复：仅在后端被 Git 忽略的 `.hera-local.yml` 中将 `hera.cos.public-base-url` 覆盖为 `http://127.0.0.1:8080/file/` 并重启。使用用户本次报错对应的已有头像，只读验证本地入口返回 302、私有 COS HTTPS 图片读取返回 200；没有上传、删除文件或修改存储桶权限。远程 `101.43.139.56/file/access` 探测返回 COS 格式的 403 `AccessDenied`，远程反向代理配置未修改；上线需将文件网关请求转发后端签名入口，而非直接转发 COS 的 `/access` 对象路径。开发者工具重新编译/重进我的，以获取新头像 URL；手机真机不能使用电脑的 `127.0.0.1`。
- 资料 PUT 与头像上传是两个独立接口，部分成功会明确告知，不宣称原子事务；网络超时后服务端是否已提交需重新读取确认，后端当前没有请求幂等键。
- 修复“进入编辑页再返回，默认头像/我的元素变形”：H5 懒加载的编辑页 CSS 曾以全局 `.water-mascot` 覆盖我的页同名图标。编辑页样式现全部限定 `.edit-page`，并使用独立的 `edit-water-mascot` 类，避免双向样式冲突；不涉及头像数据或接口变更。
- 根据用户确认的数据库结构，移除 `user_account.nfc_uid` 对应的实体字段、账号 Mapper 读写与新建表定义，不执行补列或删除数据库字段。`user_virtual_item` 中独立的绑定字段不在本次账号字段移除范围。已重新部署本地后端；实际微信登录仍需开发者工具重新获取 code，不能重放已使用的 code。
- 按系统尚未上线、只采用当前表结构的要求，删除历史用户迁移源码及其测试，解除业务启动对迁移组件的依赖，不再自动补列、修改旧表或搬迁旧账号。保留首次注册和注册后再次登录的正常流程；数据库已有表与记录不删除。干净构建已确认产物没有旧迁移类，清理后的本地后端已重启。

## 与原型差异及待确认

- 保留原有页面视觉与头像选择入口。新增登录失效、资料加载失败、注册补全、上传错误和开发验证码的必要状态提示，不以样例资料掩盖失败。
- 待确认上线短信供应商及验证码策略；现有开发验证码不能作为生产短信能力。
- 待确认测试/生产 HTTPS API 和文件访问域名，真实微信账号与 COS 联调需用户在开发者工具授权验收。未改动生产域名或伪造注册凭证。