95 lines
5.8 KiB
Markdown
95 lines
5.8 KiB
Markdown
# Hera 后端
|
||
|
||
Spring Boot 后端，提供微信小程序登录、手机号验证码绑定、用户资料、协议和关注我们接口。
|
||
|
||
命理计算使用 `cn.6tail:lunar` 根据公历生日和时辰生成四柱八字，再计算五行分布、日主、喜用和忌用。
|
||
|
||
元宝页提供今日卡牌和每日生活小贴士接口。
|
||
|
||
## 本地启动
|
||
|
||
```bash
|
||
export WECHAT_APP_ID=wxa76a2ef9e8ba612e
|
||
export WECHAT_APP_SECRET='set-via-environment'
|
||
export DB_URL='jdbc:mysql://101.43.139.56:3306/hera?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true'
|
||
export DB_USERNAME=hera_user
|
||
export DB_PASSWORD='请通过部署环境配置'
|
||
mvn spring-boot:run
|
||
```
|
||
|
||
默认地址：`http://localhost:8080`
|
||
|
||
本机敏感配置可放在仓库根目录的 `.hera-local.yml`，使用与 `application.yml` 相同的 YAML
|
||
层级。后端从项目根目录启动时会自动加载，此文件已加入 Git 忽略清单；服务器使用环境变量配置。
|
||
|
||
## 腾讯云 COS 文件存储
|
||
|
||
存储桶为 `hera-1319913268`，地域为 `ap-beijing`，桶权限保持私有读。
|
||
运行环境必须配置 `TENCENT_COS_SECRET_ID`、`TENCENT_COS_SECRET_KEY`。
|
||
推荐仅授权该桶 `hera/avatar/*`、`hera/files/*` 路径的 `cos:PutObject`、`cos:GetObject` 权限。
|
||
密钥不写入配置文件或 Git。未配置密钥时允许服务启动，文件操作会返回配置错误。
|
||
|
||
- `POST /api/user/avatar`：上传 JPG、PNG、WebP 头像，最大 5MB。
|
||
- `POST /api/files`：通过 multipart 字段 `file` 上传普通文件，最大 5MB。
|
||
- `GET /api/files/url?reference=cos%3A%2F%2Fhera%2Ffiles%2F...`：为本人文件续签。
|
||
|
||
所有上述接口需要 Bearer JWT。对象分别存储在 `hera/avatar/{userId}/`、
|
||
`hera/files/{userId}/`，数据库保存 `cos://` 对象标识；不要保存临时签名 URL。
|
||
资料查询返回的头像 URL 和文件上传返回的 URL 有效期为 900 秒；过期后重新获取。
|
||
历史 `/uploads/avatars/` 路径继续按原有本地静态资源配置访问，旧文件没有自动迁移。
|
||
|
||
访问入口默认使用 `http://101.43.139.56/file/access?token=...`，Nginx 保留路径和查询参数
|
||
转发至后端；参考 `deploy/nginx-file.conf.example`。后端校验文件专用短期凭证后，
|
||
302 跳转至 COS 官方 HTTPS 签名 URL。入口不要求登录头，必须携带有效文件凭证。
|
||
文件链接属于临时访问凭据，不应写入日志或分享给无权访问的人。
|
||
部署时通过 `HERA_JWT_SECRET` 配置随机签名密钥，并通过 `TENCENT_COS_PUBLIC_BASE_URL`
|
||
配置生产 HTTPS 域名下的 `/file/` 地址。小程序需配置入口和跳转目标的 HTTPS 合法域名。
|
||
当前 HTTP IP 地址供联调使用，不满足正式小程序的 HTTPS 域名要求。
|
||
|
||
### COS 验证
|
||
|
||
`mvn test` 执行本地签名、目录归属和模拟上传测试，不访问真实 COS。
|
||
`mvn test -Dhera.cos.integration=true` 额外启用真实 COS 联调：从运行配置读取密钥，
|
||
在 `hera/avatar/9223372036854775807/` 和 `hera/files/9223372036854775807/`
|
||
创建本次随机命名的测试对象，校验匿名访问为 403、签名下载内容一致，以及后端文件入口的跳转。
|
||
测试结束后删除本次创建的对象，因此联调账号还需要这两个测试目录的 `cos:DeleteObject` 权限。
|
||
此测试不会操作数据库，也不会验证远端 Nginx 是否已部署。
|
||
|
||
## 开发说明
|
||
|
||
- 当前已默认关闭微信 mock，并接入微信 `jscode2session`。
|
||
- 数据持久层使用 MyBatis Mapper XML，首次启动会执行 `schema.sql` 创建缺失的数据表。
|
||
- 数据库连接默认指向 `101.43.139.56:3306/hera`，生产部署建议通过 `DB_URL`、`DB_USERNAME`、`DB_PASSWORD` 覆盖。
|
||
- `WECHAT_APP_SECRET` 请优先使用服务器环境变量配置，不建议提交到公开仓库。
|
||
- `/api/auth/sms` 开发阶段返回 `mockCode`，接入短信厂商后移除返回值。
|
||
- 正式上线前需要替换 `hera.jwt-secret`、短信服务实现和协议正文。
|
||
|
||
## 数据表 CRUD
|
||
|
||
小程序用户业务已统一到 `user_account` 与 `user_profile`：微信身份、昵称和手机号
|
||
保存在账号表；性别、生日、出生时辰、头像、现居住地区与资料修改额度保存在资料表。
|
||
`User` 仅作为联合查询模型；业务接口不再读写 `hera_user`。
|
||
|
||
首次启动会由 `UserTableMigration` 为既有正式表补齐缺失字段，并将 `password_hash` 调整为
|
||
可空（纯微信用户未设置密码），因此数据库账号需要相应的建表及 ALTER 权限。
|
||
如发现旧表 `hera_user`，会保留用户 ID，将旧用户和资料迁入正式表，同时保留原表。
|
||
迁移使用数据库锁、事务及版本记录；身份或手机号冲突时停止迁移，不覆盖冲突账号。
|
||
旧用户的资料修改周期以原 `updated_at` 为起点；新周期为首次修改起六个月，最多五次。
|
||
重启前应备份数据库；本地 H2 测试不代表已执行远端 MySQL 迁移。
|
||
|
||
`POST /api/auth/wx-login` 对已绑定手机号的用户额外返回 `token` 和 `user`；未绑定时，
|
||
继续通过 `sessionKey` 和 mock 短信验证码调用 `/api/auth/bind-phone` 完成注册或绑定。
|
||
绑定成功会核销会话与验证码。禁用账号不能登录或使用个人资料接口。
|
||
个人资料接口的字段名保持不变；资料尚未填写时，生日、时辰及五行报告可能为空，不填充虚构资料。
|
||
|
||
以下接口均需要携带 `Authorization: Bearer <token>`，并支持统一操作：
|
||
|
||
- `GET /api/data/{resource}/{id}`：按主键查询
|
||
- `GET /api/data/{resource}?offset=0&limit=20`：分页列表，`limit` 最大为 100
|
||
- `POST /api/data/{resource}`：新增
|
||
- `PUT /api/data/{resource}/{id}`：更新
|
||
- `DELETE /api/data/{resource}/{id}`：删除
|
||
|
||
`resource` 可取 `nfc-chips`、`user-accounts`、`user-profiles`、`virtual-items`、
|
||
`user-virtual-items`、`offerings`、`transfers`。
|