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 联调需用户在开发者工具授权验收。未改动生产域名或伪造注册凭证。