dachui/hfb_jysh
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(init): 初始化解忧商行项目并完成 Phase 0 基座

Browse Source
This commit is contained in:
yml2213
2026-10-30 11:46:10 +08:00
commit 8d9481c251
689 changed files with 138703 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/Phase0-验收报告.md
+287
View File
@@ -0,0 +1,287 @@
# Phase 0 验收报告
> 日期：2026-10-30
> 项目：解忧商行（hfb_jysh）
> 阶段：Phase 0 · 项目初始化与契约冻结
> 结论：**通过**
---
## 1. 本阶段目标
- 建立 `hfb_jysh` 仓库骨架。
- 复制 `hfb_sys` 后端、迁移、部署与必要脚本。
- 配置解忧商行独立环境：`zuhaoc.com`、新数据库、新 Redis、新对象存储、新后台路径。
- 在空库执行全部 89 个迁移，并与旧项目迁移重建的 schema 对比。
- 跑通后端构建、健康检查、全量测试。
- 搭建 React 19 + Ant Design 5 前端壳。
- 跑通前端页面、API 代理、登录与商品列表。
---
## 2. 环境
| 项 | 版本 / 值 |
|---|---|
| Go | 1.27.1 |
| Node | 24.15.0 |
| npm | 12.0.2 |
| Docker | 29.8.2 |
| Docker Compose | v5.5.0 |
| Goose | v3.27.1 |
| MySQL | 8.4（容器） |
| Redis | 7.4（容器） |
| MinIO | RELEASE.2025-09-07T16-13-09Z |
---
## 3. 已落地目录
```text
hfb_jysh/
├── backend/ # 后端、89 个迁移、Dockerfile
├── deploy/ # Caddy、Compose、MySQL 配置
├── distribution-admin/ # 现有 React + AntD 分销后台（已复制，待品牌轻改）
├── frontend/ # 新建 React 19 + Vite + Ant Design 5
├── docs/ # 项目计划、品牌规范、Phase 0 报告
├── scripts/ # 检查、迁移、部署、备份脚本
├── .gitignore
├── .dockerignore
└── README.md
```
---
## 4. 后端复用结果
### 4.1 复制范围
- `backend/` 全量业务代码、`cmd/`、`internal/`、`pkg/`、`migrations/`。
- `deploy/` Caddy、Compose、MySQL 配置。
- `scripts/` 代码门禁、迁移、部署、备份脚本。
- `distribution-admin/` 现有 React 分销后台源码。
- 后端数据库与业务规则文档已放入 `docs/backend/`。
### 4.2 明确排除
- 旧 `backend/.env`、旧日志、旧编译二进制。
- 旧 Vue 前端、旧品牌素材、旧构建产物。
- 旧 Git 历史（当前尚未初始化 Git）。
### 4.3 配置调整
| 项 | 新值 |
|---|---|
| 主域名 | `zuhaoc.com` |
| `www` | `www.zuhaoc.com` 301 到主域名 |
| 后台路径 | `/console-jy8k3m`（环境变量可改） |
| 分销后台 | `distribution.zuhaoc.com` |
| 数据库 | `hfb_jysh` |
| MySQL 端口（开发） | `23306` |
| Redis 端口（开发） | `26379` |
| MinIO API / 控制台 | `29090` / `29091` |
| 对象存储 Bucket | `jieyou-sys` |
| 后端端口（开发） | `18089` |
| 前端端口（开发） | `5289` |
| 短信 | `SMS_PROVIDER=mock` |
| 实名 | `REALNAME_PROVIDER=mock` |
| 支付 | 暂空白，后续后台配置 |
### 4.4 Go module 路径
当前仍保留 `hfb_sys/backend`，这是有意为之：先保证复制后的后端零业务改动、可编译、可测试。彻底改名为 `hfb_jysh/backend` 应作为独立机械提交，不和 UI 改造混在一起。
---
## 5. 数据库验收
### 5.1 空库迁移
- 新建空库 `hfb_jysh`，字符集 `utf8mb4`，排序规则 `utf8mb4_unicode_ci`。
- 执行 `backend/migrations` 下全部 Goose Up 迁移。
- 结果：
```text
OK 000089_user_realname_identity_unique.sql
goose: successfully migrated database to version: 89
```
- `goose_db_version` 应用记录：89 条。
- 业务表数量：70 张。
### 5.2 Schema 对比
在旧项目独立库 `hfb_sys_schema_ref` 中用旧迁移重建 schema，再与新库对比：
```text
SCHEMA_MATCH
```
对比前已归一化 `AUTO_INCREMENT` 与 dump 注释。表、列、索引、唯一约束、外键结构一致。
### 5.3 SQL 门禁
```text
[sql-guard] 未初始化 Git，跳过已发布迁移变更检查
[sql-guard] SQL 约束检查通过
```
> 新仓库尚未 `git init`，脚本会跳过“已发布迁移不可修改”的历史检查；初始化 Git 后会自动恢复。
---
## 6. 后端验收
### 6.1 构建与静态检查
```text
go build ./... 通过
go vet ./... 通过
```
### 6.2 健康检查
```json
{
"dependencies": { "mysql": "ok", "redis": "ok" },
"service": "hfb-api",
"status": "ok"
}
```
- `GET /health`：200
- `GET /health/ready`：200
- 初始管理员：`admin`（开发环境密码见 `backend/.env`）
### 6.3 全量测试
```text
go test ./... -count=1
```
结果：**全部通过**，覆盖 `internal/e2e`、`order`、`payment`、`wallet`、`withdrawal`、`distribution`、`listing`、`chat`、`dispute` 等核心包。
其中：
```text
ok hfb_sys/backend/internal/e2e 7.884s
```
### 6.4 测试数据
开发库已创建：
- 测试用户：`13800138000 / Jieyou123`
- 测试商品：`202610300001`
- 商品状态：`published / approved`
- 商品标题：`解忧柜选 · 三角洲行动 高资产账号`
- 商品截图已上传到本地 MinIO。
> 以上仅为开发联调数据，不进入生产库。
---
## 7. 前端验收
### 7.1 技术栈
- React 19
- TypeScript 5.9
- Vite 7
- Ant Design 5
- React Router 7
- TanStack Query 5
- Zustand 5
- Axios
- dayjs
### 7.2 已完成页面
| 路由 | 页面 | 状态 |
|---|---|---|
| `/` | PC 商行首页 + 商品列表 + 流程 + 规则 | 已完成 |
| `/login` | 解忧商行登录页 | 已完成 |
| `/console-jy8k3m/*` | 管理后台 Phase 0 占位 Shell | 已完成 |
| `*` | 404 页 | 已完成 |
### 7.3 视觉落地
- 使用解忧商行真实 logo PNG。
- 主色：`#1E4D42`
- 印章红：`#A64332`
- 米白底：`#F6F2E8`
- 标题宋体 + 正文黑体。
- 首页为编辑式首屏 + 柜签式商品卡，不是旧站海报轮播 + 胶囊筛选。
- 登录页为深绿品牌面板 + 米白表单卡。
- 后台占位为浅色纸感 Shell，不是旧站深蓝后台。
### 7.4 构建与联调
```text
npm run typecheck 通过
npm run build 通过
```
开发服务：
```text
http://localhost:5289/
```
验证结果：
- 前端首页：HTTP 200
- `/api/listings` 代理：HTTP 200
- 通过前端代理登录：`code=ok`，返回 token
- 商品列表：返回 1 件联调商品
构建产物：
```text
dist/index.html 0.94 kB │ gzip 0.54 kB
dist/assets/index-*.js 150.90 kB │ gzip 53.25 kB
dist/assets/vendor-react-*.js 222.95 kB │ gzip 69.56 kB
dist/assets/vendor-antd-*.js 728.64 kB │ gzip 232.01 kB
```
> Ant Design 首包仍偏大，Phase 1 需要按路由懒加载、组件按需引入、图标按需导入和更细的 manualChunks 优化。
---
## 8. 当前可访问地址
| 服务 | 地址 |
|---|---|
| 前端 | `http://localhost:5289/` |
| 后端 | `http://localhost:18089/` |
| 健康检查 | `http://localhost:18089/health/ready` |
| MySQL | `127.0.0.1:23306` |
| Redis | `127.0.0.1:26379` |
| MinIO API | `http://localhost:29090` |
| MinIO 控制台 | `http://localhost:29091` |
---
## 9. 已知限制
1. Go module 路径仍是 `hfb_sys/backend`，尚未做机械改名。
2. 管理后台只有占位 Shell，43 个后台页面尚未迁移。
3. 分销后台已复制源码，但尚未做品牌主题轻改。
4. 支付、短信、实名保持空白；开发环境用 mock，生产未配置会快速失败。
5. Logo 只有 PNG，尚无矢量 SVG。
6. Ant Design 首包偏大，需在 Phase 1 优化。
7. 尚未初始化 Git 仓库，因此 SQL 门禁跳过迁移历史检查。
8. 生产 Caddy / Compose 配置已改，但尚未部署验证。
9. 开发库含测试用户与测试商品，不可直接用于生产。
---
## 10. Phase 1 建议
1. 初始化 Git 仓库并建立首个提交（需用户确认后执行）。
2. 完成解忧商行 SVG logo 与 favicon 全套。
3. 建立 Design Token、基础组件库和三端 Layout。
4. 按路由懒加载，优化 AntD 首包。
5. 接入后台登录与权限 Shell。
6. 开始 C 端商品详情、订单、钱包页面迁移。
7. 逐步接入分销站点识别与 `X-Distribution-Site-Code`。
docs/backend/business-rules.md
+34
View File
@@ -0,0 +1,34 @@
# 业务规则
## 商品
- 用户完成登录和实名认证后才能发布租赁商品。
- 商品提交审核并通过后才可公开上架；处于交易中的商品不能被另一订单锁定。
- 主动下架、交易离架、异常和封存是不同状态，必须保留状态事件。
## 订单
- 创建订单后进入待支付；支付成功后进入待交接并锁定商品。
- 号主提交交接信息，租客确认后开始计算租期。
- 租客归还后进入结账协商，双方确认或客服仲裁后完成结算。
- 结账内容区分「结账备注」与「系统结算信息」：备注仅为双方留言，不参与结算计算；结算金额以系统结算信息（额外消耗品、哈夫币实际消耗、押金赔付扣除）为准。
- 订单状态、交接状态和结算状态共同描述流程，禁止仅修改其中一个字段绕过状态机。
## 支付与退款
- 金额均使用整数分，支付单和退款单必须具有唯一业务单号。
- 渠道通知必须先验签，再按幂等规则推进本地状态。
- 已进入终态的支付或退款记录不能被迟到通知回退。
- 人工退款、关闭订单、封存订单和仲裁退款的业务语义不同，均需审计记录。
## 钱包与提现
- 钱包区分可用余额和冻结余额，每次变更必须产生流水。
- 创建提现申请时，可用余额转为冻结余额；取消或拒绝时原额返还。
- 审核通过后只有确认打款才能最终扣减冻结余额，重复审核或重复确认必须被拒绝。
## 管理操作
- 管理后台使用独立认证和 RBAC 权限。
- 关闭、退款、封存、异常、仲裁和余额调整等高风险操作必须写入审计日志。
- 客服只能通过服务端返回的可用动作执行订单状态转换。
docs/backend/database.md
+25
View File
@@ -0,0 +1,25 @@
# 数据库设计
## 设计原则
- MySQL 8.4 是生产事实源，Redis 只保存限流、验证码、会话辅助和缓存数据。
- 金额统一以 `*_cent` 的整数分存储；数量和比例字段按业务精度单独定义。
- 核心写入通过 GORM 事务完成，钱包账户更新使用行锁并同步写入不可变流水。
- 表结构由 `backend/migrations` 下的 Goose 迁移管理，应用启动不自动修改生产表结构。
## 核心领域
- 用户与权限：`users`、`admin_users`、角色、权限及关联表。
- 商品：租赁商品、账号、资产截图、审核记录和状态事件。
- 订单：租赁订单、交接记录、结账协商、过程事件和申诉。
- 资金：支付单、退款单、钱包账户、钱包流水、收款账号和提现申请。
- 运营：系统配置、公告、通知、聊天、二维码池、推送规则和撞车商品。
## 一致性约束
- 下单时在事务内锁定可租商品，避免重复出租。
- 支付状态、订单状态和商品状态在同一业务事务内推进。
- 钱包每次余额变化必须生成对应流水，提现在待审核阶段将可用余额转为冻结余额。
- 支付通知和业务单号使用唯一索引实现幂等。
索引、慢查询、连接池和备份恢复细则见[数据库 SQL 约束与运维](数据库SQL约束与运维.md)。
docs/backend/数据库SQL约束与运维.md
+77
View File
@@ -0,0 +1,77 @@
# 数据库 SQL 约束与运维
本项目使用 MySQL 8.4、GORM 和 Goose。本文是提交、上线和故障排查的数据库基线；SQL 静态检查不能替代真实数据量下的执行计划。
## 提交前约束
新增或修改 SQL、GORM 查询或迁移必须满足：
1. 列表查询必须有分页、最大数量或明确日期范围，禁止无界读取订单、流水、消息和日志历史。
2. `GROUP BY`、`COUNT(DISTINCT)`、窗口函数、跨表聚合、`UNION` 和相关子查询必须在接近生产数据量的 MySQL 上保存 `EXPLAIN FORMAT=JSON` 或 `EXPLAIN ANALYZE` 结果。
3. 高频查询先限定当前时间范围或当前页 ID，再做关联和聚合；禁止读取用户全部历史记录后在应用层过滤。
4. 新增索引必须通过新的 Goose migration 提交，并在迁移注释中说明覆盖的查询条件、排序和基数；大表索引要评估锁影响和上线窗口。
5. SQL 值必须使用 GORM 参数绑定或 `?` 占位符，禁止拼接请求参数。动态排序字段只能来自白名单。
6. 已应用的迁移文件禁止修改或删除，只能新增迁移完成结构修复；除 `000001_init.sql` 外的新迁移必须包含 `-- +goose Up` 和 `-- +goose Down`。
7. 角色、权限、推送渠道、客服组等小型配置表允许全量读取，但必须保持数量边界或在本文件的白名单中登记；业务数据不得套用该例外。
本地 `scripts/check.sh` 会执行 `scripts/check-sql-guard.sh`，保护关键索引、时间范围和迁移完整性。它只防止关键代码被重构移除，不判断执行计划是否优秀。
## 执行计划
在维护库或只读副本上替换真实参数后执行：
```sql
EXPLAIN FORMAT=JSON
SELECT ...;
EXPLAIN ANALYZE
SELECT ...;
```
重点检查扫描行数、实际返回行数、索引使用、临时表、文件排序和 join 顺序。财务首页的仪表盘、结算明细和提现合并列表属于必须定期复核的查询。
## 生产观测
生产 MySQL 应保持 `performance_schema` 开启，并启用慢查询日志。项目的 `deploy/mysql/my.cnf` 默认记录超过 500ms 的语句；应用日志只记录 SQL 形状、耗时和返回行数，不记录绑定参数值。
常用排查 SQL：
```sql
SELECT
DIGEST_TEXT,
COUNT_STAR,
ROUND(SUM_TIMER_WAIT / 1000000000000, 2) AS total_seconds,
ROUND(AVG_TIMER_WAIT / 1000000000, 2) AS avg_ms,
SUM_ROWS_SENT,
SUM_ROWS_EXAMINED
FROM performance_schema.events_statements_summary_by_digest
ORDER BY SUM_TIMER_WAIT DESC
LIMIT 30;
SELECT THREAD_ID, EVENT_NAME, TIMER_WAIT, SQL_TEXT, ROWS_EXAMINED
FROM performance_schema.events_statements_current
WHERE SQL_TEXT IS NOT NULL
ORDER BY TIMER_WAIT DESC;
```
应用慢查询阈值由 `DATABASE_SLOW_QUERY_THRESHOLD_MS` 配置。阈值调整后要同步检查 MySQL `long_query_time`，避免应用和数据库观测口径长期不一致。
## 连接、超时与容量
- `DATABASE_MAX_OPEN_CONNS` 是单个 backend 实例的连接上限，总量必须按实例数核算，不能简单随实例扩容同比增加。
- `DATABASE_MAX_IDLE_CONNS`、`DATABASE_CONN_MAX_LIFETIME_MINUTES` 和 `DATABASE_CONN_MAX_IDLE_TIME_MINUTES` 控制空闲连接和连接轮换。
- 请求必须设置 Go `context` 截止时间；锁等待由 MySQL `innodb_lock_wait_timeout` 控制。长报表查询应进入异步任务或汇总表。
- 数据量增长后，排行榜、财务历史统计和审计报表应迁移到日汇总表、缓存或只读副本，不能持续依赖在线全表聚合。
- 修改连接池或容器资源后，用 `docker compose config` 核对最终插值；资源限额应高于稳定 RSS 峰值并留出数据库连接和备份余量。
## 备份与恢复
生产使用 XtraBackup 全量备份加 MySQL ROW binlog 归档实现时间点恢复。备份对象先客户端加密，再使用独立 OSS bucket 的服务端加密；恢复必须在隔离目录和隔离 MySQL 容器演练，禁止直接向生产实例回放。
```bash
./scripts/backup-online.sh status
./scripts/archive-binlog.sh verify
./scripts/restore-online.sh prepare <complete.env-OSS-URI>
```
备份完成标识、SHA-256、manifest、server UUID 和 Goose 版本必须一致；恢复演练至少按月验证一次，并记录恢复时间点和结果。
docs/品牌与UI规范.md
+600
View File
@@ -0,0 +1,600 @@
# 解忧商行 · 品牌与 UI 规范
> 版本：v1.0
> 日期：2026-10-30
> 适用：PC 前台、移动端 `/m`、管理后台、分销后台、营销物料
> 目标：建立一套与旧站 hfb_sys 明显区隔、可长期扩展的「新中式现代商行」视觉系统
---
## 1. 品牌定位
### 1.1 一句话
**解忧商行，是一家把规则讲清楚、把账算明白、把交接做稳妥的账号租赁商行。**
### 1.2 品牌关键词
- 可信：敢把费用、押金、退款、责任边界写在明面上。
- 温润：不催促、不制造焦虑、不用夸张促销。
- 克制：少而准的信息，不用霓虹、不用满屏徽章。
- 有账本感：像一家经营多年的商行，单据、印章、编号、留痕。
### 1.3 品牌语气
| 场景 | 推荐 | 避免 |
|---|---|---|
| 首屏 | 解忧商行，租得明白，还得安心 | 全网最低、限时秒杀 |
| 下单 | 确认订单，费用逐项列明 | 立即抢购、手慢无 |
| 交接 | 按步骤完成交接，双方都有记录 | 马上发货、极速到账 |
| 错误 | 这一步没有完成，你的钱和订单都没有变化 | 系统异常、未知错误 |
| 空状态 | 这里还没有记录，先去挑选一件合适的账号 | 暂无数据 |
| 加载 | 正在核对商行账本… | 加载中… |
---
## 2. 视觉方向
### 2.1 核心意象
**东方商行 · 纸张账本 · 朱砂印章 · 墨绿柜台**
- 不是古风复刻，不做繁复纹样。
- 不是游戏电竞风，不用霓虹、发光、金属质感。
- 不是传统金融风，不用大面积冷灰和强压迫感。
- 用现代排版承载东方气质：留白、细线、印章、纸张、编号。
### 2.2 已提供 logo 的延展
现有 logo 包含：
- 深墨绿底。
- 朱砂红方形印章，内为「解忧」。
- 米白中文「解忧商行」。
- 英文辅助字 `JIEYOU TRADING HOUSE`。
从现有 PNG 直接采样的准确色值：
| 部位 | 色值 |
|---|---|
| 品牌深绿底 | `#1E4D42` |
| 朱砂印章 | `#A64332` |
| 印章内细线 / 暖金边 | `#ECD0B1` |
| 品牌反白文字 | `#F0F4F2` |
| 页面米白底 | `#F6F2E8` |
> 目前没有矢量源文件。Phase 1 需要按现有 PNG 重绘 SVG：印章边框与「解忧」二字转为路径，中文主标题与英文辅助字转曲，交付横版、方形、单色、反白、竖版五套文件。
需要交付的 logo 版本：
1. 横版主标（印章 + 中文 + 英文）。
2. 方形印章标（App icon / favicon / 头像）。
3. 中文单色版。
4. 反白版。
5. 竖版组合（移动端启动页 / 海报）。
6. SVG 矢量源文件。
### 2.3 禁止出现的旧站元素
- 橙色 `#ff6a00` 作为主色。
- 深蓝黑后台侧栏 `#1a1f36 / #101428`。
- 蓝紫渐变 `#4f7cff → #6c5ce7`。
- 大面积浅橙背景 `#fff7ed`。
- 金色游戏质感 `#fbbf24`。
- 胶囊型筛选按钮满屏堆叠。
- 海报式大轮播 + 促销角标。
- Element Plus / Vant 默认组件的视觉签名。
- 旧站 logo、旧站 favicon、旧站分享图、旧站空状态插画。
---
## 3. 色彩系统
### 3.1 品牌色
| Token | 色值 | 用途 |
|---|---|---|
| `brand-ink` | `#1E4D42` | 主品牌色、深色头部、主按钮、重点文字 |
| `brand-ink-deep` | `#153A32` | 深色背景、hover、页脚 |
| `brand-seal` | `#A64332` | 印章、风险提示、重要强调、少量 CTA |
| `brand-seal-line` | `#ECD0B1` | 印章内细线、暖金边 |
| `brand-brass` | `#B08A4A` | 细节点缀、分隔线、等级标识 |
| `paper` | `#F6F2E8` | 页面主背景 |
| `paper-warm` | `#FFFDF8` | 卡片、弹窗、内容区 |
| `ink` | `#1C2521` | 主文字 |
| `ink-secondary` | `#5E6B64` | 次级文字 |
| `ink-muted` | `#8A948E` | 辅助说明 |
| `line` | `#E4DED2` | 边框、分割线 |
| `sage` | `#6F857C` | 中性辅助、图标 |
| `success` | `#2F7D5C` | 成功、已完成、可租 |
| `warning` | `#C17A2B` | 待处理、待确认 |
| `danger` | `#A64332` | 失败、风险、不可逆操作 |
| `info` | `#3E6B7A` | 信息提示、链接 |
### 3.2 使用比例
- 60%：米白 / 暖白背景。
- 25%：墨绿文字、边框、深色区块。
- 10%：青灰、黄铜辅助。
- 5%：朱砂红强调。
朱砂红只用于「印章、风险、关键确认」，不要整页铺红，也不要所有按钮都用红。
### 3.3 语义色
| 状态 | 颜色 | 表现 |
|---|---|---|
| 可租 / 已完成 | `#2F7D5C` | 绿色细边框标签 |
| 待支付 / 待确认 | `#C17A2B` | 琥珀色标签 |
| 租赁中 / 进行中 | `#3E6B7A` | 青蓝色标签 |
| 异常 / 已关闭 | `#8A948E` | 灰色标签 |
| 风险 / 争议 | `#A64332` | 朱砂标签 |
所有状态标签使用「浅底 + 深字 + 细边框」，不使用高饱和实心块。
---
## 4. 字体系统
### 4.1 字体选择
| 用途 | 字体 |
|---|---|
| 品牌标题 / 大标题 | 思源宋体 / Noto Serif SC |
| 正文 / 后台 UI | 思源黑体 / Noto Sans SC |
| 英文辅助 | Inter / IBM Plex Sans |
| 数字 / 金额 | Inter Tabular / DIN 风格等宽数字 |
字体加载策略：
- 首屏只加载必要字重：宋体 600、黑体 400/500/600。
- 使用 `font-display: swap`。
- 中文大字体文件必须子集化，避免首屏阻塞。
- 后台可使用系统字体栈，减少加载成本。
### 4.2 字号
| Token | 字号 / 行高 | 用途 |
|---|---|---|
| `display` | 48 / 1.2 | 首页主标题（PC） |
| `h1` | 36 / 1.25 | 页面主标题 |
| `h2` | 28 / 1.3 | 区块标题 |
| `h3` | 22 / 1.35 | 卡片标题 |
| `body-lg` | 16 / 1.7 | 商品详情正文 |
| `body` | 14 / 1.6 | 常规正文、后台 |
| `caption` | 12 / 1.5 | 辅助说明、表格次要信息 |
后台表格正文 13–14px，行高 44px；财务数字右对齐，使用等宽数字。
---
## 5. 布局与栅格
### 5.1 PC 前台
- 最大内容宽度：1280px。
- 12 列栅格，24px gutter。
- 页面左右留白：桌面 ≥ 48px，宽屏 ≥ 80px。
- 首屏采用 7:5 非对称布局，不使用全宽轮播。
- 区块之间使用 80–120px 留白，形成编辑式节奏。
### 5.2 移动端
- 基准宽度 375px，最大 480px。
- 页面左右留白 16px。
- 卡片间距 12px。
- 底部固定操作栏高度 64px + 安全区。
- 触控目标 ≥ 44 × 44px。
### 5.3 管理后台
- 侧栏 232px，折叠后 64px。
- 顶栏 56px。
- 内容区最大宽度 1600px。
- 页面内边距 24px。
- 表格页采用「筛选条 + 工具条 + 表格 + 分页」四段式。
- 详情页优先使用独立页面或右侧 Drawer，避免多层 Modal。
---
## 6. 形状、边框与阴影
| Token | 值 | 用途 |
|---|---|---|
| `radius-xs` | 2px | 标签、印章边 |
| `radius-sm` | 4px | 输入框、按钮 |
| `radius-md` | 8px | 卡片、弹窗 |
| `radius-lg` | 12px | 大面板、抽屉 |
| `border` | 1px solid `#E4DED2` | 常规边框 |
| `border-strong` | 1px solid `#C9C0B0` | 强调边框 |
阴影只用两级：
```css
--shadow-paper: 0 1px 2px rgba(29, 36, 33, 0.05), 0 8px 24px rgba(29, 36, 33, 0.05);
--shadow-float: 0 8px 32px rgba(29, 36, 33, 0.12);
```
禁止：
- 多层彩色阴影。
- 发光效果。
- 玻璃拟态。
- 大圆角胶囊铺满页面。
---
## 7. 图标与插画
### 7.1 图标
- 线性图标，线宽 1.5–1.75px。
- 圆角端点，但不过度圆润。
- 统一 20/24px 尺寸。
- 关键业务使用自定义图标：交接、归还、结账、押金、申诉、分站。
- 不使用 Element Plus / Vant 默认图标作为品牌图标。
### 7.2 插画
- 纸张、账本、印章、柜台、封签、信封、算盘等意象。
- 单色墨绿 + 朱砂点缀。
- 不画卡通人物，不做 3D 吉祥物。
- 空状态插画保持克制，不卖萌。
### 7.3 图片
- 商品图以真实账号资产截图为主。
- 统一 4:3 或 3:2 裁切，圆角 4px。
- 图片上可叠加纸质标签，不使用霓虹渐变蒙层。
- 首页主视觉优先使用真实场景图 + 纸张质感，不使用游戏海报拼贴。
---
## 8. 动效
| 场景 | 时长 | 缓动 |
|---|---|---|
| hover / focus | 120ms | ease-out |
| 弹窗 / 抽屉 | 200ms | cubic-bezier(0.2, 0, 0, 1) |
| 页面区块进入 | 240ms | ease-out |
| 骨架屏 | 1.4s 循环 | ease-in-out |
原则：
- 动效用于表达层级和状态，不用于炫技。
- 不做大面积视差滚动。
- 不做弹跳、闪烁、旋转加载。
- 尊重 `prefers-reduced-motion`。
---
## 9. 核心组件规范
### 9.1 按钮
| 类型 | 样式 |
|---|---|
| 主按钮 | 墨绿底、暖白字、4px 圆角 |
| 次按钮 | 暖白底、墨绿边框、墨绿字 |
| 危险按钮 | 朱砂底或朱砂边框，仅用于不可逆操作 |
| 文本按钮 | 无底色，墨绿文字，hover 出现浅绿底 |
按钮高度：PC 40px，移动端 44–48px。
不使用渐变按钮，不使用胶囊按钮作为主 CTA。
### 9.2 输入框
- 高度 40px，圆角 4px。
- 边框 `#E4DED2`，聚焦墨绿 1px + 2px 浅绿外环。
- 标签在输入框上方，不使用漂浮标签。
- 错误信息就近显示，不只用 Toast。
- 金额、身份证、手机号使用对应键盘与格式化。
### 9.3 卡片
- 暖白底，1px 细边框，轻阴影。
- 标题使用宋体或 600 字重黑体。
- 卡片内边距 20–24px。
- 商品卡不使用大阴影悬浮，hover 只做边框加深 + 轻微上移 2px。
### 9.4 标签
- 浅底、深字、1px 边框。
- 圆角 2px，不使用全圆胶囊。
- 状态标签前可加 4px 圆点。
- 风险标签使用朱砂，成功使用墨绿。
### 9.5 表格
- 表头暖白 / 浅米底，文字 12px 大写间距。
- 行高 44px，分隔线 1px `#E4DED2`。
- 数字右对齐，等宽数字。
- 操作列固定在右侧。
- 批量操作时顶部出现「已选 N 项」工具条。
- 空状态包含说明 + 主操作，不只显示「暂无数据」。
### 9.6 弹窗与抽屉
- 常规编辑用 Drawer，宽度 480–640px。
- 轻量确认用 Modal，宽度 400–480px。
- 高风险操作必须显示影响说明 + 原因输入。
- 不使用「弹窗里再开弹窗」的多层结构。
### 9.7 状态与反馈
- 成功：顶部细条 + 简短文案，不撒花。
- 失败：明确说明「什么没成功、有没有影响资金/订单、下一步怎么做」。
- 加载：骨架屏优先，避免全屏 Spinner。
- 空状态：插画 + 一句解释 + 一个主操作。
---
## 10. PC 前台页面蓝图
### 10.1 首页
结构：
1. 顶部导航：logo、商品、撞车、公告、邀请、订单、消息、登录/头像。
2. Hero：左侧宋体大标题 + 说明 + 两个操作；右侧一张主视觉或商品拼贴。比例 7:5。
3. 信任条：实名审核 / 资金托管 / 流程留痕 / 售后仲裁。
4. 本周柜选：3–6 个商品卡，按主题分组，不使用轮播。
5. 分类柜签：横向标签或卡片，不做满屏胶囊。
6. 交易流程：挑选 → 下单 → 交接 → 归还 → 结账，5 步时间线。
7. 规则说明：押金、退款、责任边界。
8. 常见问题。
9. 页脚：品牌、备案、联系方式、服务条款。
视觉：
- 背景米白，区块之间用细线和留白分隔。
- 标题宋体，正文黑体。
- 朱砂只用于印章、风险提示、关键数字。
- 首屏不出现大面积橙色或促销角标。
### 10.2 商品列表
- 左侧 240px 筛选栏：分类、价格、押金、账号属性、排序。
- 右侧结果区：工具条 + 商品网格 + 分页。
- 已选筛选条件以「细边框标签 + 清除」展示，不使用彩色胶囊。
- 移动端筛选收进底部 Drawer。
### 10.3 商品详情
- 左侧：图集、账号属性、资产说明、交接流程、风险提示。
- 右侧：粘性购买卡，包含价格、押金、费用明细、可租状态、主 CTA。
- 费用逐项列出：租金、押金、额外消耗、平台服务费、预计退款。
- 号主信息使用「商行认证」标签，不展示过多个人隐私。
- 底部提供规则说明和常见问题。
### 10.4 订单中心
- 顶部状态印章 + 订单号 + 下一步动作。
- 时间线展示：下单、支付、交接、租用、归还、结账。
- 右侧或底部展示金额明细与凭证。
- 操作按钮只保留当前状态允许的动作。
- 移动端使用卡片流，不使用宽表格。
### 10.5 结账
- 三步：确认账单 → 确认金额 → 完成。
- 系统结算信息与手填备注视觉上明确分开。
- 额外消耗、哈夫币消耗、押金赔付逐项展示。
- 双方确认状态用印章式状态块，不用聊天气泡代替。
---
## 11. 移动端页面蓝图
- 底部导航：首页、订单、消息、我的（可按业务加「分类」）。
- 首页：品牌条 + 搜索 + 主视觉 + 分类 + 推荐商品 + 流程说明。
- 商品详情：图集、价格卡、属性、流程、底部固定 CTA。
- 订单详情：状态印章、时间线、下一步卡片、金额明细。
- 聊天：会话列表、消息气泡、快捷回复、订单上下文卡片。
- 我的：头像、实名状态、钱包、邀请、客服、设置。
- 所有底部操作栏适配 `env(safe-area-inset-bottom)`。
---
## 12. 管理后台蓝图
### 12.1 Shell
- 浅暖白侧栏，墨绿 active 状态。
- 顶栏：面包屑、全局搜索、待办、消息、管理员菜单。
- 侧栏分组：工作台、交易、商品、用户、财务、分销、运营、系统。
- 折叠后只保留图标，hover 显示名称。
### 12.2 工作台
- 第一行：今日订单、待审核、待处理申诉、待审核提现。
- 第二行：交易趋势、订单状态分布。
- 第三行：异常提醒、待办队列、最近操作。
- 不同角色看到不同卡片，不把所有指标堆给所有人。
### 12.3 列表页
统一结构：
1. PageHeader：标题、说明、主操作。
2. FilterBar：常用筛选 + 高级筛选 + 保存视图。
3. Toolbar：批量操作、列设置、导出。
4. DataTable：固定表头、固定操作列、服务端分页。
5. Detail Drawer：点击行打开，不跳转丢失筛选。
### 12.4 表单页
- 分组卡片：基本信息、业务规则、资金信息、备注。
- 两列布局，长文本跨列。
- 粘性底部：取消、保存草稿、提交。
- 高风险字段增加说明和二次确认。
- 长表单支持草稿自动保存。
### 12.5 配置页
- 左侧分组导航，右侧配置表单。
- 敏感字段掩码显示，修改时单独确认。
- 保存前展示变更摘要。
- 所有配置变更写审计日志。
---
## 13. Ant Design Token 落地
```ts
import type { ThemeConfig } from 'antd'
export const jieyouTheme: ThemeConfig = {
token: {
colorPrimary: '#1E4D42',
colorInfo: '#3E6B7A',
colorSuccess: '#2F7D5C',
colorWarning: '#C17A2B',
colorError: '#A64332',
colorText: '#1C2521',
colorTextSecondary: '#5E6B64',
colorTextTertiary: '#8A948E',
colorBgBase: '#FFFDF8',
colorBgLayout: '#F6F2E8',
colorBorder: '#E4DED2',
borderRadius: 4,
borderRadiusLG: 8,
fontFamily:
'"Noto Sans SC", "Source Han Sans SC", "PingFang SC", "Microsoft YaHei", sans-serif',
fontSize: 14,
controlHeight: 40,
},
components: {
Button: {
borderRadius: 4,
primaryShadow: 'none',
defaultShadow: 'none',
},
Card: {
borderRadiusLG: 8,
boxShadowTertiary: '0 1px 2px rgba(29,36,33,.05)',
},
Table: {
headerBg: '#F6F2E8',
headerColor: '#5E6B64',
rowHoverBg: '#FBF8F1',
borderColor: '#E4DED2',
},
Menu: {
itemSelectedBg: '#E6EEE9',
itemSelectedColor: '#1E4D42',
itemHoverBg: '#F1F5F0',
},
Modal: {
borderRadiusLG: 12,
},
Drawer: {
colorBgElevated: '#FFFDF8',
},
},
}
```
品牌页面标题使用独立 CSS：
```css
.brand-title {
font-family: 'Noto Serif SC', 'Source Han Serif SC', serif;
font-weight: 600;
letter-spacing: 0.04em;
}
```
---
## 14. 内容与文案规范
### 14.1 语气
- 先说结论，再说原因。
- 不制造焦虑，不催促。
- 金额、时间、责任写清楚。
- 不使用「秒杀、抢购、爆款、全网最低」。
### 14.2 关键文案示例
| 场景 | 文案 |
|---|---|
| 首页主标题 | 解忧商行，租得明白，还得安心 |
| 首页副标题 | 实名审核、流程留痕、账单逐项列明 |
| 商品卡 CTA | 查看详情 |
| 详情页 CTA | 确认租赁 |
| 支付页 | 核对账单后再支付 |
| 交接页 | 按步骤完成交接，双方都有记录 |
| 归还页 | 提交归还后，等待号主确认 |
| 结账页 | 账单有疑问，可以发起协商 |
| 空订单 | 还没有订单，先去挑选一件合适的账号 |
| 网络错误 | 这一步没有完成，你的钱和订单都没有变化 |
| 无权限 | 当前账号没有这个操作权限，请联系管理员 |
---
## 15. 视觉验收清单
### 15.1 与旧站区隔
- [ ] 不出现旧站橙色 `#ff6a00`。
- [ ] 不出现旧站深蓝侧栏 `#1a1f36 / #101428`。
- [ ] 不出现蓝紫渐变 `#4f7cff → #6c5ce7`。
- [ ] 不使用旧站 logo、favicon、分享图。
- [ ] 首页不是海报轮播 + 胶囊筛选结构。
- [ ] 后台不是深色侧栏 + 蓝色高亮。
- [ ] 卡片不是大圆角 + 重阴影。
- [ ] 组件不是 Element Plus / Vant 默认外观。
- [ ] 文案不出现旧站品牌名和促销语气。
- [ ] 10 张核心页并排评审，至少 8 张通过非同源判断。
### 15.2 页面完整性
- [ ] 加载状态。
- [ ] 空状态。
- [ ] 错误状态。
- [ ] 无权限状态。
- [ ] 移动端适配。
- [ ] 键盘可操作。
- [ ] 对比度 AA。
- [ ] 图片有 alt。
- [ ] 表单错误就近提示。
### 15.3 性能
- [ ] C 端首屏 JS ≤ 250KB gzip。
- [ ] 路由 chunk ≤ 350KB gzip。
- [ ] LCP ≤ 2.5s。
- [ ] CLS ≤ 0.1。
- [ ] 图片 WebP/AVIF + 懒加载。
- [ ] 字体子集化。
---
## 16. 禁止事项
- 禁止直接把旧站 CSS 变量改个色继续用。
- 禁止在业务页面写裸色值。
- 禁止同一页面混用 AntD 与自造表单控件两套交互。
- 禁止用朱砂红铺满按钮区。
- 禁止用大面积渐变、发光、玻璃拟态。
- 禁止把后台做成「深色电竞风」。
- 禁止把 C 端做成「后台表格风」。
- 禁止使用旧站图片、旧站插画、旧站图标。
- 禁止只改 logo 和标题就宣称完成品牌替换。
---
## 17. 交付物
1. 品牌 logo SVG 全套。
2. Design Token 文件。
3. AntD 主题配置。
4. 基础组件库与 Storybook / 组件预览页。
5. PC 首页、列表、详情、订单、结账高保真稿。
6. 移动端首页、详情、订单、我的高保真稿。
7. 后台 Shell、工作台、列表页、详情页、表单页高保真稿。
8. 视觉回归基线截图。
9. 品牌字符串审计清单。
10. 上线前视觉验收报告。
docs/项目计划.md
+592
View File
@@ -0,0 +1,592 @@
# 解忧商行 · 项目实施计划
> 版本：v1.0
> 日期：2026-10-30
> 基线项目：`/Users/yml/codes/hfb_sys`
> 目标项目：`/Users/yml/codes/hfb_jysh`
> 前端技术栈：React 19 + TypeScript + Vite + Ant Design 5
> 后端策略：Go 后端业务逻辑整体复用，前端重写，品牌与界面彻底重构
---
## 1. 项目目标
### 1.1 总目标
以 `hfb_sys` 的后端能力为基座，重建一套属于「解忧商行」的前端产品：
- 后端保留订单、商品、支付、钱包、提现、分销、邀请、聊天、申诉、实名等完整业务能力。
- 前端从 Vue + Element Plus + Vant 整体迁移到 React + Ant Design + Ant Design Mobile。
- 不是换皮，而是重新设计信息架构、页面布局、组件语言、文案语气和后台工作流。
- 让熟悉旧站的人在不看代码、不看域名的情况下，无法从界面上判断两个项目同源。
### 1.2 硬约束
1. 后端业务逻辑不重写，接口协议保持不变。
2. 新项目名称统一为「解忧商行」，英文辅助名 `JIEYOU TRADING HOUSE`。
3. 前端统一使用 Ant Design 体系，不混用 Material UI。
4. 新视觉不得复用旧站的橙色、深蓝后台、蓝紫渐变、胶囊筛选、海报式轮播等标志性元素。
5. 生产部署仍采用 Caddy + Docker Compose + MySQL + Redis 的成熟结构。
6. 所有金额、状态、权限、分账、结算规则以后端返回为准，前端不得重新计算业务结果。
### 1.3 非目标
- 本阶段不重构 Go 领域模型。
- 本阶段不引入微服务、消息队列或新的基础设施。
- 本阶段不做小程序、App 原生端。
- 本阶段不强制 SSR；是否引入预渲染在 Phase 0 单独决策。
---
## 2. 品牌与差异化策略
完整规范见 [`品牌与UI规范.md`](./品牌与UI规范.md)。
### 2.1 品牌关键词
**东方商行 · 可信 · 温润 · 克制 · 有账本感**
不是游戏交易站的霓虹感，也不是传统金融的冷硬感，而是「一家把规则讲清楚、把账算明白的现代商行」。
### 2.2 视觉母体
基于已提供的 logo：
- 深墨绿底色。
- 朱砂红方形印章。
- 米白 / 暖白的品牌字。
- 中文主标题 + 英文小字辅助。
### 2.3 与旧站的强制区隔
| 维度 | 旧站 hfb_sys | 新站 解忧商行 |
|---|---|---|
| 主色 | 橙色 `#ff6a00` | 墨绿 `#1E4D42` |
| 辅助色 | 金色、亮蓝、蓝紫渐变 | 朱砂红 `#A64332`、黄铜 `#B08A4A` |
| 页面底色 | 白色 + 浅橙 | 米白 `#F6F2E8` + 暖白 `#FFFDF8` |
| 后台侧栏 | 深蓝黑渐变 | 暖白 / 浅米色，绿色 active |
| 圆角 | 大量 12–24px 胶囊 | 2–8px，印章式克制圆角 |
| 首页结构 | 海报轮播 + 胶囊筛选 | 编辑式首屏 + 柜台式筛选 |
| 卡片 | 阴影卡片堆叠 | 纸张标签 + 细边框 + 少量抬升 |
| 图标 | Element / Vant 默认图标 | 自定义线性图标 + 印章符号 |
| 文案 | 促销、抢购、爆款 | 说明规则、核对账目、安心托付 |
| 动效 | 快速、强反馈 | 160–240ms 纸感淡入，克制 |
**验收口径：** 10 张核心页面截图与旧站并排评审，至少 8 张在布局语法、色彩、字体、组件形态上明显不同，评审者无法仅凭截图判断同源。
---
## 3. 技术选型
| 层 | 选择 | 说明 |
|---|---|---|
| 框架 | React 19 + TypeScript | 与现有 `distribution-admin` 技术栈一致 |
| 构建 | Vite 7 | 保留 SPA 部署方式，改造成本最低 |
| 路由 | React Router 7 | 三套路由树：PC 前台、移动端、管理后台 |
| 后台 UI | Ant Design 5 | 复杂表格、表单、弹窗、描述列表 |
| 后台增强 | ProComponents（按需） | ProTable / ProForm / ProLayout，减少重复代码 |
| 移动 UI | Ant Design Mobile 5 | 对齐现有 Vant 组件概念 |
| 服务端状态 | TanStack Query | 缓存、失效、轮询、并发请求管理 |
| 全局状态 | Zustand | 会话、站点、布局、草稿 |
| 表单 | Ant Design Form | 统一校验、联动、弹窗提交 |
| 表格 | Ant Design Table + DataTable 封装 | 固定列、列设置、批量操作、导出 |
| 图表 | ECharts | 财务、分销、运营看板 |
| HTTP | Axios | 移植现有拦截器与刷新队列 |
| 日期 | dayjs | 与 AntD 生态一致 |
| 样式 | AntD Token + CSS Modules | 禁止在业务组件中散落裸色值 |
| 测试 | Vitest + Testing Library + Playwright | 单元、组件、E2E、视觉回归 |
| 类型 | tygo 或 OpenAPI 生成 | 从 Go DTO 生成 TS 类型，降低漂移 |
### 3.1 不引入的东西
- 不引入 Material UI。
- 不引入 Tailwind 默认 Preflight，避免与 AntD Reset 冲突；如使用 Tailwind，必须关闭 Preflight。
- 不在同一个页面混用两套组件库。
- 不在前端重新实现分账、结算、押金、退款规则。
---
## 4. 目标仓库结构
```text
hfb_jysh/
├── backend/ # 从 hfb_sys 复制，业务逻辑保持
│ ├── cmd/
│ ├── internal/
│ ├── migrations/
│ └── Dockerfile
├── deploy/ # Caddy / Compose / MySQL 配置，改域名与路径
├── distribution-admin/ # 独立分销后台，React + AntD，按新品牌改造
├── frontend/ # 新建 React 主前端
│ ├── src/
│ │ ├── app/ # 启动、Provider、路由、权限守卫
│ │ ├── brand/ # Logo、品牌资产、Design Token
│ │ ├── components/ # 通用业务组件
│ │ ├── features/
│ │ │ ├── storefront/ # PC 前台
│ │ │ ├── mobile/ # /m 移动端
│ │ │ ├── admin/ # 管理后台
│ │ │ ├── auth/
│ │ │ ├── orders/
│ │ │ ├── listings/
│ │ │ ├── wallet/
│ │ │ ├── chats/
│ │ │ └── distribution/
│ │ ├── layouts/
│ │ ├── shared/
│ │ │ ├── api/
│ │ │ ├── auth/
│ │ │ ├── types/
│ │ │ └── utils/
│ │ └── styles/
│ └── vite.config.ts
├── docs/
├── scripts/
└── README.md
```
### 4.1 单应用还是多应用
**默认采用一个 Vite 主应用 + 一个独立分销后台。**
- 主应用内部用三套路由树区分 PC 前台、`/m` 移动端、隐藏路径管理后台。
- 所有页面按路由懒加载，后台代码不会进入 C 端首包。
- 分销后台继续独立构建，沿用现有 `distribution-admin` 的 React + AntD 资产，减少重复开发。
- 生产仍由 Caddy 分别托管 `/srv/dist` 和 `/srv/distribution-admin`，部署方式不变。
---
## 5. 信息架构与页面范围
### 5.1 PC 前台
- 首页：品牌首屏、严选商品、分类柜签、交易流程、保障说明、常见问题。
- 商品列表：左侧筛选栏、结果区、排序、分页、空状态。
- 商品详情：图集、账号属性、价格构成、押金说明、交接流程、风险提示、下单操作。
- 撞车商品：分类、列表、详情、下单。
- 登录 / 注册 / 找回密码 / 实名认证。
- 卖家中心：发布、编辑、提交审核、我的商品、提号记录。
- 订单中心：列表、详情、支付、交接、归还、结账、申诉。
- 钱包：余额、流水、提现、收款账户。
- 消息：会话列表、聊天详情、系统通知。
- 公告、邀请返利、个人资料。
### 5.2 移动端 `/m`
与 PC 对齐，但按移动场景重新组织：
- 首页、商品列表、商品详情。
- 登录 / 注册 / 实名。
- 发布 / 编辑商品。
- 订单列表、订单详情、支付、交接、归还、结账。
- 消息、通知、钱包、提现、邀请、我的。
- 底部导航建议 4–5 项，主要操作放在拇指区。
- 详情页使用底部固定操作栏，结账使用分步流程。
### 5.3 管理后台（43 个页面）
按 6 种页面原型统一：
1. **列表页**：筛选、表格、批量操作、导出、详情抽屉。
2. **详情页**：状态摘要、时间线、关联信息、操作区。
3. **表单页**：分组表单、粘性提交栏、草稿保存、内联校验。
4. **看板页**：KPI、趋势、待办、异常提醒。
5. **配置页**：分组配置、敏感项掩码、变更确认。
6. **会话页**：会话列表、聊天窗口、快捷回复、用户上下文。
页面分组：
| 分组 | 页面 |
|---|---|
| 工作台 | 仪表盘、待办、异常提醒 |
| 交易 | 订单、订单详情、退款审核、申诉仲裁、手工订单 |
| 商品 | 商品列表、商品详情、审核、撞车商品、分类与配置 |
| 用户 | 用户列表、用户详情、实名信息、角色与权限 |
| 财务 | 财务看板、资金明细、支付流水、提现审核、运营支出 |
| 分销 | 站点、规则、订单、结算、二维码池、分销用户、公告 |
| 运营 | 公告、邀请返利、推送、追踪链接、客服群、快捷回复 |
| 系统 | 支付配置、系统配置、审计日志、备份、管理员 |
### 5.4 分销后台
沿用现有 11k 行 React + AntD 代码，按新品牌改造：
- 登录、站点、规则、订单、账号、钱包、结算、用户、邀请、公告、店铺装修、支付、设置。
- 保留业务逻辑，替换主题、布局、文案、图表和空状态。
- 统一使用主站 Design Token，不出现旧站深蓝/橙色元素。
---
## 6. 页面优化重点
### 6.1 C 端
- 首页从「轮播海报 + 筛选胶囊」改为「编辑式首屏 + 柜台式筛选」。
- 筛选从一屏 20 个胶囊压缩为 6 个主筛选项 + 高级筛选抽屉。
- 商品卡统一展示：价格、押金、账号属性、可租状态、认证标识。
- 详情页把费用拆清楚：租金、押金、额外消耗、平台服务费、退款规则。
- 订单中心以「下一步动作」为核心，不做信息堆砌。
- 所有空状态、错误状态、加载状态重新写文案，不使用旧站语气。
### 6.2 管理后台
- 统一浅色暖白 Shell，取消旧站深蓝侧栏。
- 顶部全局搜索 + 命令面板，支持跳订单、商品、用户。
- 列表页统一筛选条、列设置、保存视图、批量操作栏。
- 详情页统一右侧抽屉或独立页，减少弹窗套弹窗。
- 43 个页面收敛为 6 种原型，组件复用率目标 ≥ 70%。
- 高风险操作统一二次确认 + 原因填写 + 审计提示。
### 6.3 移动端
- 触控目标 ≥ 44px。
- 主要操作固定在底部安全区。
- 列表使用骨架屏、下拉刷新、上拉加载。
- 订单详情使用状态印章 + 时间线 + 下一步卡片。
- 表单按步骤拆分，避免一屏几十个字段。
---
## 7. 后端复用与契约冻结
### 7.1 复制范围
- `backend/`
- `deploy/`
- `scripts/check.sh`、`check-sql-guard.sh`、`prepare-test-db.sh`、`deploy-prod.sh` 等必要脚本
- `docs/database.md`、`docs/business-rules.md` 等后端文档
- 不复制旧前端、旧品牌素材、旧构建产物
### 7.2 已定稿的配置
| 配置项 | 定稿 |
|---|---|
| 主域名 | `zuhaoc.com` |
| `www` 域名 | `www.zuhaoc.com`，建议 301 到主域名 |
| 移动端 | 继续使用 `/m` 路径；不强制独立 `m.` 域名 |
| 管理后台隐藏路径 | 由 `VITE_ADMIN_BASE_PATH` / `ADMIN_BASE_PATH` 控制，默认建议 `/console-jy8k3m`，不得沿用旧站 `/manage-7x9k2p` |
| 分销管理后台 | `distribution.zuhaoc.com` |
| 分销后台策略 | 保留现有 React + AntD 应用，只做品牌主题、登录页、Logo、布局和文案改造，不新建功能 |
| MySQL | 全新数据库，建议库名 `hfb_jysh`；保留全部 89 个迁移 |
| Redis | 新实例或新 DB，不与旧站共用 |
| 对象存储 | 新 Bucket，建议 `jieyou-sys`；旧站 Bucket 不混用 |
| 支付商户 | 暂时空白，后台支付配置页后续录入 |
| 短信签名 / 模板 | 暂时空白；开发环境使用 `SMS_PROVIDER=mock` |
| 实名服务 | 暂时空白；开发环境使用 `REALNAME_PROVIDER=mock` |
| ICP / 页脚 / 客服 | 使用解忧商行新品牌信息，上线前补齐 |
| 容器名 / 部署目录 | 使用 `hfb_jysh` 项目名，避免与旧站容器混用 |
> 支付、短信、实名在未配置时，生产环境应通过现有 `ValidateProductionSecurity` 快速失败，而不是带空配置上线。开发与演示环境使用 mock 适配器。
### 7.3 全新数据库与迁移基线
采用“保留全部迁移、在空库重建”的方式，不做旧库数据迁移。
执行顺序：
1. 新建空数据库 `hfb_jysh`，字符集 `utf8mb4`。
2. 逐条执行 `backend/migrations` 下全部 Goose Up 迁移，保留 89 个历史迁移，不压缩、不删除。
3. 执行 `goose status`，确认全部为 `Applied`。
4. 用 `mysqldump --no-data` 导出旧库与新库结构，对比表、列、索引、唯一约束、外键。
5. 运行 `scripts/check-sql-guard.sh`，确认关键索引与分页防线仍存在。
6. 运行 `go test ./...`，包括租赁全链路与分销 e2e。
7. 对新库执行核心冒烟：注册/登录、发布、审核、下单、支付、交接、归还、结账、提现、分销结算。
8. 记录迁移基线与 schema 差异报告，作为上线前证据。
> 如果 89 个迁移在空库执行时出现顺序依赖问题，优先修复迁移链，不允许直接改生产库结构绕过。
### 7.4 需要冻结的前端契约
| 契约 | 要求 |
|---|---|
| 响应格式 | `{ code, message, data }` |
| 用户认证 | Bearer Token + Refresh Token |
| 管理员认证 | HttpOnly Cookie，请求必须 `withCredentials` |
| 401 刷新 | 单飞刷新 + 等待队列，禁止并发刷新 |
| 分站识别 | `X-Distribution-Site-Code` 必须随请求发送 |
| 文件上传 | `multipart/form-data`，字段 `file` + `scene` |
| 私有文件 | 走 Blob 接口，不直接使用对象 URL |
| 聊天 | SSE 长连接 + 断线重连 |
| 权限 | 使用后端权限码，不按角色名硬编码 |
| 状态 | 使用后端状态字符串，前端只做展示映射 |
### 7.5 Go module 路径
默认保留 `hfb_sys/backend`，降低复制风险。如果决定彻底分家，再单独做一次全局 import 替换：
1. 替换 `hfb_sys/backend` → `hfb_jysh/backend`。
2. `gofmt` 全量格式化。
3. `go build ./...`、`go vet ./...`、`go test ./...` 全绿。
4. 该改动单独提交，不与 UI 改造混在一起。
### 7.6 后端品牌文案审计
后端逻辑不动，但运行期文案需要审计：
- 短信模板、通知模板、系统配置默认值。
- 结账系统信息、订单状态文案、公告默认内容。
- 页脚、客服信息、分享标题。
- 旧品牌名「大锤商行」「哈夫币」等展示文案。
原则：**改配置与展示文案，不改状态机、金额计算和接口字段。**
---
## 8. 分阶段实施计划
### Phase 0：项目初始化与契约冻结（3–5 天）
> 状态：**已完成（2026-10-30）**。验收结果见 [`Phase0-验收报告.md`](./Phase0-验收报告.md)。
- 创建仓库骨架。
- 复制后端、迁移、部署、必要脚本。
- 配置新数据库 `hfb_jysh`、新 Redis、新对象存储 Bucket、`zuhaoc.com`、后台路径 `/console-jy8k3m`。
- 在空库执行全部 89 个迁移，完成 schema 对比与迁移基线记录。
- 复制现有 `distribution-admin`，先保持功能不动，只记录后续品牌轻改清单。
- 开发环境配置 `SMS_PROVIDER=mock`、`REALNAME_PROVIDER=mock`，支付配置留空。
- 跑通 `/health`、`/health/ready`、后台登录、商品列表、下单查询。
- 生成第一版 TS 类型。
- 建立 API 契约清单、前端路由清单和双品牌隔离清单。
**验收：** 新目录可本地启动，后端接口可访问，前端空壳可登录并拉到真实数据。
### Phase 1：品牌与设计系统（1 周）
- 重绘 logo SVG：横版、方形印章、单色、反白。
- 落地 Design Token：颜色、字体、间距、圆角、阴影、动效。
- 搭建 AntD `ConfigProvider` 主题。
- 完成基础组件：Button、Input、Card、Tag、Table、Modal、Drawer、Empty、Loading、PageHeader。
- 完成 PC / 移动 / 后台三套 Layout 骨架。
- 输出 10 张关键页面高保真稿。
**验收：** 设计规范可执行，组件库可复用，页面骨架不再出现旧站视觉元素。
### Phase 2：前端基础设施（1 周）
- Axios 客户端、响应解包、错误提示、请求日志。
- 用户 Bearer 与管理员 Cookie 双认证。
- 401 单飞刷新队列。
- 路由守卫：登录、实名、管理员权限、密码强制修改。
- 分站识别与 `X-Distribution-Site-Code`。
- TanStack Query Provider、全局错误边界。
- 文件上传、私有文件 Blob、图片压缩。
- SSE 聊天连接与重连。
- 通用 DataTable、FilterBar、FormModal、MoneyText、StatusTag。
**验收：** 登录、刷新、权限、分站、上传、聊天六条基础链路可用。
### Phase 3：C 端 PC + 移动端（3 周）
- 首页、商品列表、商品详情、撞车商品。
- 登录、注册、找回密码、实名认证。
- 卖家发布、编辑、提交审核。
- 订单创建、支付、交接、归还、结账。
- 钱包、提现、收款账户。
- 消息、通知、公告、邀请、个人资料。
- 移动端完整对齐。
**验收：** 用户可以完成从浏览到下单、支付、交接、归还、结账的完整闭环。
### Phase 4：管理后台核心（4–5 周）
- 后台登录、工作台、订单列表、订单详情。
- 商品列表、商品详情、审核。
- 用户列表、用户详情、实名信息。
- 支付流水、退款审核、提现审核。
- 角色权限、审计日志。
- 统一列表页、详情页、表单页原型。
**验收：** 客服与运营可以完成日常订单处理、商品审核、用户处理和资金审核。
### Phase 5：后台长尾 + 分销后台轻改（2–2.5 周）
- 财务看板、资金明细、运营支出。
- 申诉仲裁、手工订单、提号、客服群、快捷回复。
- 分销站点、规则、订单、结算、二维码池、分销用户、公告。
- 公告、邀请返利、推送、追踪链接。
- 系统配置、支付配置、备份、管理员管理。
- 现有 React 分销后台仅做品牌主题、Logo、登录页、Shell 和文案轻改，不改功能。
**验收：** 43 个后台页面全部可用，分销后台与主站视觉统一，分销业务流程不变。
### Phase 6：质量、性能与上线（2 周）
- 关键流程 E2E。
- 1440 / 1024 / 390 三档视觉回归。
- 无障碍与键盘操作检查。
- 性能预算与图片优化。
- SEO、分享卡片、favicon、404、错误页。
- Caddy 切换、灰度、回滚演练。
- 旧站与新站截图对照评审。
**验收：** 关键流程通过，性能达标，视觉评审通过，具备回滚方案。
---
## 9. 排期建议
假设团队：
- 前端 2–3 人
- UI/品牌设计 1 人
- QA 1 人
- 后端/运维 0.5 人（只做配置与环境）
建议 S0 启动 3–5 天 + 8 个两周 Sprint，总计约 **13–15 周**：
| Sprint | 目标 |
|---|---|
| S0 | 初始化、契约冻结、环境跑通 |
| S1 | 品牌、设计系统、三端 Shell、基础设施 |
| S2 | C 端首页、列表、详情、移动端首页 |
| S3 | 登录、实名、发布、订单创建、支付 |
| S4 | 交接、归还、结账、钱包、提现、消息 |
| S5 | 后台工作台、订单、商品、审核、用户 |
| S6 | 财务、支付、退款、提现、申诉、提号 |
| S7 | 分销后台轻改、系统配置、长尾页面 |
| S8 | E2E、视觉回归、性能、上线缓冲 |
单人全职开发预计 **4–5 个月**；不建议单人压缩到 3 个月内，否则后台长尾和联调质量不可控。
---
## 10. 质量与验收标准
### 10.1 视觉验收
- 核心 10 页与旧站并排评审，至少 8 页通过“非同源”判断。
- 页面不出现旧站主色：`#ff6a00`、深蓝后台 `#1a1f36/#101428`、蓝紫渐变 `#4f7cff→#6c5ce7`。
- 所有页面使用统一 Token，不允许业务组件散落裸色值。
- 所有页面具备加载、空、错误、无权限四种状态。
### 10.2 功能验收
- 用户：注册/登录 → 浏览 → 下单 → 支付 → 交接 → 归还 → 结账。
- 卖家：实名 → 发布 → 审核 → 上架 → 接单 → 交接 → 收款。
- 客服：订单查询 → 关闭/退款 → 申诉仲裁 → 提现审核。
- 管理员：商品审核 → 用户处理 → 财务查看 → 权限管理。
- 分销：站点开通 → 规则配置 → 订单归属 → 结算批次。
### 10.3 性能预算
- C 端首屏 JS ≤ 250KB gzip。
- 单个路由 chunk ≤ 350KB gzip。
- LCP ≤ 2.5s（4G 模拟）。
- CLS ≤ 0.1。
- 图片统一 WebP/AVIF，列表懒加载。
- 后台万级表格启用虚拟滚动或服务端分页。
### 10.4 无障碍与可用性
- 文字对比度达到 WCAG AA。
- 所有交互可键盘完成。
- 焦点态清晰可见。
- 移动端触控目标 ≥ 44px。
- 表单错误就近提示，不只用顶部 Toast。
### 10.5 工程质量
- TypeScript 严格模式。
- API 层禁止 `any`。
- ESLint + Prettier + Stylelint。
- Vitest 覆盖核心工具、hooks、权限、金额格式化。
- Playwright 覆盖 12 条关键链路。
- 每个页面至少一张视觉回归截图。
---
## 11. 风险与应对
| 风险 | 影响 | 应对 |
|---|---|---|
| 双品牌配置串用 | 旧站订单、支付、短信、存储被误用 | 新数据库、新 Redis、新 Bucket、新容器、新域名完全隔离；启动日志打印环境指纹 |
| 43 个后台页面工作量大 | 延期 | 先做 6 种页面原型与 DataTable/FormModal，复用率 ≥ 70% |
| 管理员 Cookie 认证被误做成 Bearer | 后台持续 401 | 独立 `adminClient`，强制 `withCredentials` |
| 401 并发刷新 | 请求风暴、退出登录 | 单飞刷新 + 等待队列 |
| 分站站点码漏传 | 订单归属错误、串站 | 请求拦截器统一注入，E2E 覆盖 |
| 图片上传压缩改变业务预期 | 图片不清晰或透明丢失 | 移植现有压缩与透明 PNG 处理 |
| 支付回调域名未更新 | 支付成功但订单不推进 | 上线前逐渠道核对回调地址 |
| 支付 / 短信 / 实名空配置误上线 | 生产不可用或安全校验失败 | 生产启动前强制检查 `.env`；未配置则禁止发布 |
| 短信签名 / 模板审核周期 | 登录验证码不可用 | 待品牌主体就绪后立即提交，预留 3–4 周审核缓冲 |
| Logo 无矢量源文件 | 重绘偏差、不同尺寸模糊 | 以 PNG 采样色为准重绘 SVG，输出多尺寸并在 1x/2x/3x 下验收 |
| 旧品牌文案残留 | 被看出同源 | 建立品牌字符串审计清单，发布前全量搜索 |
| 未使用后端模块仍暴露 | 攻击面变大 | 前端隐藏不等于下线，后续单独裁剪路由与模块 |
---
## 12. 上线与切换
1. 新域名、新数据库、新对象存储 Bucket 独立部署。
2. 支付渠道回调地址逐项切换并验证。
3. 短信签名、模板、实名服务凭证验证。
4. Caddy 先切测试域名，跑完整 E2E。
5. 生产灰度：先内部账号，再小流量，再全量。
6. 保留旧站只读或回滚入口至少 7 天。
7. 监控 `/health/ready`、支付回调失败率、退款任务、订单超时任务。
8. 上线后 72 小时重点观察：下单、支付、交接、结算、提现。
---
## 13. 已定稿决策
| 决策项 | 定稿 |
|---|---|
| 业务模型 | 与 `hfb_sys` 完全一致，账号租赁、押金、结算、分销全部保留；只是两个独立品牌 |
| 数据策略 | 全新数据库，不迁旧业务数据；保留全部 89 个迁移，在空库完整重建并做 schema 对比 |
| SEO | 不要求搜索引擎收录；默认 SPA，不做 SSR，预留后续预渲染能力 |
| 分销后台 | 现状保留，不新建功能；只做品牌主题、登录页、Logo、布局与文案改造；域名 `distribution.zuhaoc.com` |
| 支付 / 短信 / 实名 | 先留空；开发环境用 mock，生产未配置时快速失败，后续在后台配置 |
| 域名 | 主站 `zuhaoc.com`；`www.zuhaoc.com` 建议 301；移动端继续用 `/m` |
| 后台隐藏路径 | 环境变量可配置；默认建议 `/console-jy8k3m`，与旧站旧路径完全不同 |
| Logo | 没有矢量源文件；按现有 PNG 重绘 SVG，交付横版、方形、单色、反白、竖版 |
### 13.1 品牌资产执行
1. 以 PNG 为参考，重绘印章边框与「解忧」二字路径。
2. 中文主标题、英文辅助字转曲，避免字体缺失导致变形。
3. 使用采样色：深绿 `#1E4D42`、朱砂 `#A64332`、暖金边 `#ECD0B1`、反白 `#F0F4F2`。
4. 输出 favicon、App icon、分享图、登录页 logo、后台侧栏 logo。
5. 旧 PNG 只作为设计参考，不直接进入生产页面。
### 13.2 域名与路径
| 用途 | 地址 |
|---|---|
| 主站 | `https://zuhaoc.com` |
| `www` | `https://www.zuhaoc.com`，建议 301 到主站 |
| 移动端 | `https://zuhaoc.com/m` |
| 管理后台 | `https://zuhaoc.com${VITE_ADMIN_BASE_PATH}` |
| 分销后台 | `https://distribution.zuhaoc.com` |
| 健康检查 | `https://zuhaoc.com/health`、`/health/ready` |
> Caddy 的 `ADMIN_BASE_PATH` 与前端构建期 `VITE_ADMIN_BASE_PATH` 必须使用同一个值，否则后台静态资源和 API 路由会错位。
### 13.3 环境策略
- 开发环境：`APP_ENV=development`，短信与实名使用 mock，支付配置留空。
- 预发环境：尽量接近生产，但支付可继续使用沙箱或 mock。
- 生产环境：支付、短信、实名未配置完成前不得上线；现有 `ValidateProductionSecurity` 会阻止空配置启动。
- 所有密钥只放在服务器 `.env`，不写入仓库。
### 13.4 可并行推进的外部事项
- 域名 DNS 解析与服务器准备。
- 支付商户进件与回调域名报备。
- 阿里云短信签名、模板审核。
- 实名服务账号与额度。
- ICP、客服联系方式、页脚信息。
这些事项不阻塞前端 Phase 0–3，但会阻塞生产上线。
---
## 14. 下一步
1. **Phase 0**：建立 `hfb_jysh` 仓库骨架，复制后端、迁移、部署与必要脚本。
2. 在空库执行全部迁移，完成 schema 对比与核心冒烟。
3. 完成品牌 SVG、Design Token、三端 Shell。
4. 先实现「登录 + 商品列表 + 商品详情 + 后台订单列表」第一版可评审切片。
5. 评审通过后进入 C 端全量页面与后台 43 页迁移。
6. 最后接入支付、短信、实名并做生产切换。
> 原则：先冻结契约，再统一设计语言，最后批量实现页面。不要一边改后端、一边换 UI、一边补业务。