first

2026-05-11 15:28:27 +08:00
commit edd1a02157
302 changed files with 67193 additions and 0 deletions
--- a/docs/deploy/anxinyan-api.service.example
+++ b/docs/deploy/anxinyan-api.service.example
@@ -0,0 +1,17 @@
+[Unit]
+Description=Anxinyan webman API service
+After=network.target
+
+[Service]
+Type=forking
+WorkingDirectory=/www/wwwroot/anxinyan-api
+ExecStart=/usr/bin/php /www/wwwroot/anxinyan-api/start.php start -d
+ExecReload=/usr/bin/php /www/wwwroot/anxinyan-api/start.php reload -d
+ExecStop=/usr/bin/php /www/wwwroot/anxinyan-api/start.php stop
+Restart=always
+RestartSec=3
+User=www
+Group=www
+
+[Install]
+WantedBy=multi-user.target
--- a/docs/deploy/api.anxinjianyan.com.nginx.conf.example
+++ b/docs/deploy/api.anxinjianyan.com.nginx.conf.example
@@ -0,0 +1,21 @@
+server {
+    listen 80;
+    server_name api.anxinjianyan.com;
+
+    client_max_body_size 50m;
+
+    location / {
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_read_timeout 120s;
+        proxy_send_timeout 120s;
+        proxy_pass http://127.0.0.1:8787;
+    }
+}
+
+# 如已配置 HTTPS，可在 443 server 中复用同样的 location 代理逻辑。
--- a/docs/deploy/backend-api-online-deploy.md
+++ b/docs/deploy/backend-api-online-deploy.md
@@ -0,0 +1,157 @@
+# 安心验后端 API 线上部署说明
+
+## 1. 当前部署目标
+
+- API 域名：`api.anxinjianyan.com`
+- 项目目录建议：`/www/wwwroot/anxinyan-api`
+- 服务监听端口：`8787`
+
+当前后端基于 `webman`，推荐部署方式：
+
+1. 代码上传到服务器
+2. 使用 `php start.php start -d` 启动常驻进程
+3. 使用 `Nginx` 反向代理到 `127.0.0.1:8787`
+4. 用 `systemd` 管理进程自启动
+
+## 2. 本次已准备好的发布包
+
+发布包路径：
+
+- [/Users/wushumin/www/biyou/anxinyan/releases/anxinyan-server-api-20260422.zip](/Users/wushumin/www/biyou/anxinyan/releases/anxinyan-server-api-20260422.zip)
+
+建议上传后解压到：
+
+```bash
+mkdir -p /www/wwwroot/anxinyan-api
+unzip anxinyan-server-api-20260422.zip -d /www/wwwroot/anxinyan-api
+```
+
+## 3. 服务器要求
+
+- PHP 8.1+
+- 扩展：
+  - `pdo`
+  - `pdo_mysql`
+  - `pcntl`
+  - 建议 `opcache`
+- MySQL 8+
+- Redis 6/7
+- `Nginx`
+- `systemd`
+
+## 4. 部署步骤
+
+### 4.1 上传并解压
+
+```bash
+cd /www/wwwroot
+mkdir -p anxinyan-api
+tar -xzf /path/to/anxinyan-server-api-20260422.tar.gz -C anxinyan-api
+cd anxinyan-api
+```
+
+### 4.2 检查目录权限
+
+```bash
+mkdir -p runtime/logs storage/payment-certs
+chmod -R 775 runtime storage
+```
+
+### 4.3 确认环境变量
+
+发布包中已包含当前 `.env`，但上线前仍需人工确认：
+
+- `APP_ENV=production`
+- `APP_DEBUG=false`
+- 数据库连接是否为正式库
+- Redis 连接是否为正式实例
+
+## 5. 启动命令
+
+### 首次启动
+
+```bash
+cd /www/wwwroot/anxinyan-api
+php start.php start -d
+```
+
+### 重载
+
+```bash
+cd /www/wwwroot/anxinyan-api
+php start.php reload -d
+```
+
+### 停止
+
+```bash
+cd /www/wwwroot/anxinyan-api
+php start.php stop
+```
+
+## 6. Nginx 配置
+
+示例文件：
+
+- [api.anxinjianyan.com.nginx.conf.example](/Users/wushumin/www/biyou/anxinyan/docs/deploy/api.anxinjianyan.com.nginx.conf.example)
+
+核心逻辑：
+
+- 对外监听 `80/443`
+- 反向代理到 `127.0.0.1:8787`
+- 保留真实 IP、协议头和 Host
+
+## 7. systemd 配置
+
+示例文件：
+
+- [anxinyan-api.service.example](/Users/wushumin/www/biyou/anxinyan/docs/deploy/anxinyan-api.service.example)
+
+放置路径建议：
+
+```bash
+/etc/systemd/system/anxinyan-api.service
+```
+
+启用命令：
+
+```bash
+systemctl daemon-reload
+systemctl enable anxinyan-api
+systemctl start anxinyan-api
+systemctl status anxinyan-api
+```
+
+## 8. 上线后立即检查
+
+### 接口联通
+
+```bash
+curl http://127.0.0.1:8787/
+curl https://api.anxinjianyan.com/
+```
+
+### 冒烟验证
+
+```bash
+cd /www/wwwroot/anxinyan-api
+php tools/smoke_check.php
+php tools/release_audit.php
+```
+
+## 9. 当前仍需人工确认的阻塞项
+
+- 小程序正式配置：
+  - `mini_program.app_id`
+  - `mini_program.app_secret`
+  - `mini_program.original_id`
+
+## 10. 特别说明
+
+- 当前数据库中的支付证书路径仍是本机绝对路径，若线上要用微信支付，建议在服务器后台重新上传：
+  - `apiclient_key.pem`
+  - `apiclient_cert.pem`
+- 后台系统配置中的支付回调地址已调整为：
+  - `https://api.anxinjianyan.com`
+- H5 页面根地址已调整为：
+  - `https://m.anxinjianyan.com`
--- a/docs/deploy/delivery-notes.md
+++ b/docs/deploy/delivery-notes.md
@@ -0,0 +1,138 @@
+# 安心验当前交付说明
+
+## 1. 当前交付范围
+
+本阶段已覆盖以下端与能力：
+
+- 用户端 H5
+- 用户端小程序共用代码
+- 管理后台
+- 履约主流程
+- 报告验真与下载
+- 用户消息通知
+
+本阶段不纳入：
+
+- 上门鉴定复杂预约
+- 积分商城
+- 内容社区
+- 直播 / 短视频
+- 裂变分销
+- 官网
+- 商家后台
+
+## 2. 已完成模块
+
+### 用户端
+
+- 登录
+  - 手机号 + 密码
+  - 手机号 + 验证码
+- 发起鉴定
+  - 选择服务方式
+  - 选择商品信息
+  - 补充购买信息
+  - 上传鉴定资料
+  - 订单确认
+- 订单中心
+  - 列表页
+  - 详情页
+  - 寄送页
+  - 补料页
+- 报告中心
+  - 报告列表
+  - 报告详情
+  - 报告验真
+- 消息中心
+- 工单中心
+- 地址管理
+- 我的 / 设置
+
+### 后台
+
+- 管理员登录
+- 订单中心
+- 鉴定作业台
+- 商品资料中心
+- 报告中心
+- 消息中心
+- 客服与售后
+- 用户管理
+- 仓库中心
+- 权限中心
+- 系统配置
+
+## 3. 已完成履约链路
+
+### 送检链路
+
+- 下单确认时选择寄回地址
+- 订单创建后锁定送检仓库
+- 用户可在寄送前切换检测中心
+- 用户提交寄送运单
+- 后台标记鉴定中心签收
+
+### 鉴定链路
+
+- 鉴定
+- 补料发起
+- 用户补料
+- 报告生成
+- 报告发布
+
+### 寄回链路
+
+- 用户确认寄回地址
+- 后台登记回寄运单
+- 用户端查看回寄物流
+- 后台标记用户签收
+- 消息中心同步回寄与签收通知
+
+## 4. 历史兼容处理
+
+当前代码已兼容以下历史数据问题：
+
+- 老订单没有 `order_return_addresses` 快照时
+  - 用户端订单详情会自动回退展示默认地址
+  - 后台登记回寄运单时会自动用默认地址补写快照
+- 历史 `verify_qrcode_url` 不是图片链接时
+  - 用户端报告详情会直接本地生成二维码 SVG
+- 历史 `display_status` 与当前真实履约状态不一致时
+  - 用户端和后台订单列表会优先按真实物流状态推导展示
+
+## 5. 当前仍建议人工重点确认
+
+- 老订单回寄状态是否符合实际业务预期
+- 订单列表中 `待寄回 / 物品已寄回 / 已完成` 的显示是否满足运营口径
+- 管理后台权限是否满足正式分工
+- 支付、短信、小程序正式配置是否完整
+
+## 6. 当前已知上线前必须处理项
+
+根据 `php tools/release_audit.php` 当前结果，当前仍剩以下未完成项：
+
+- 小程序正式配置仍为空：
+  - `mini_program.app_id`
+  - `mini_program.app_secret`
+  - `mini_program.original_id`
+
+已完成但需要运维知晓的变更：
+
+- 后端 `.env` 已切换为生产开关：
+  - `APP_ENV=production`
+  - `APP_DEBUG=false`
+- 前端生产 API 域名已替换为正式域名
+- 测试管理员已停用
+- 默认超级管理员密码已旋转，不再使用初始密码
+
+## 7. 建议的最终上线动作
+
+1. 跑 `tools/release_audit.php`
+2. 在后台补齐小程序正式配置
+3. 执行 `cd user-app && npm run sync:mp-config`
+4. 再次运行 `tools/release_audit.php`
+5. 修正审计结果中的剩余 `FAIL`
+6. 跑 `tools/smoke_check.php`
+7. 按 [fulfillment-smoke-checklist.md](/Users/wushumin/www/biyou/anxinyan/docs/deploy/fulfillment-smoke-checklist.md) 执行人工验收
+8. 清理测试数据
+9. 构建正式包并发布
--- a/docs/deploy/deploy-plan.md
+++ b/docs/deploy/deploy-plan.md
@@ -0,0 +1,130 @@
+# 安心验部署说明
+
+## 1. 项目结构
+
+- `server-api`
+  技术栈：PHP 8 + webman + MySQL + Redis
+- `user-app`
+  技术栈：uni-app + Vue 3 + TypeScript
+  产物：
+  - H5
+  - 微信小程序
+- `admin-web`
+  技术栈：Vue 3 + Vite + TypeScript + Element Plus
+
+## 2. 当前已确认域名
+
+- 用户端 H5：`m.anxinjianyan.com`
+- 后端 API：`api.anxinjianyan.com`
+- 管理后台：`admin.anxinjianyan.com`
+
+说明：
+
+- H5 页面根地址会用于生成报告页、验真页、扫码跳转链接
+- API 域名会用于 H5、后台、小程序请求
+
+## 3. 本地常用命令
+
+### 后端
+
+```bash
+cd /Users/wushumin/www/biyou/anxinyan/server-api
+php start.php start -d
+php start.php reload -d
+php tools/smoke_check.php
+php tools/release_audit.php
+```
+
+### 用户端 H5
+
+```bash
+cd /Users/wushumin/www/biyou/anxinyan/user-app
+npm run dev:h5
+npm run type-check
+npm run build:h5
+```
+
+### 管理后台
+
+```bash
+cd /Users/wushumin/www/biyou/anxinyan/admin-web
+npm run build
+```
+
+### 小程序配置同步
+
+```bash
+cd /Users/wushumin/www/biyou/anxinyan/user-app
+npm run sync:mp-config
+npm run build:mp-weixin
+```
+
+## 4. 部署顺序建议
+
+1. 导入数据库结构与种子数据
+2. 执行 schema 升级脚本
+3. 配置后端 `.env`
+4. 在后台完成系统配置
+5. 构建并部署 `admin-web`
+6. 构建并部署 `user-app` H5
+7. 同步小程序 AppID 并构建小程序包
+8. 跑 `smoke_check.php`
+9. 执行人工履约链路验收
+
+## 5. 当前必须执行的 schema 升级
+
+已存在脚本：
+
+- `php tools/schema_upgrade_warehouses.php`
+- `php tools/schema_upgrade_order_shipping_targets.php`
+- `php tools/schema_upgrade_order_return_flow.php`
+- `php tools/schema_upgrade_manual_reports.php`
+- `php tools/schema_upgrade_user_login_sms.php`
+
+建议在正式环境按上述顺序执行一次。
+
+## 6. 后台必须配置的分组
+
+- 小程序配置
+- H5 配置
+- 短信配置
+- 微信支付 / 商户平台配置
+
+其中：
+
+- H5 根地址必须指向正式域名
+- 小程序 AppID 必须同步到 `manifest.json`
+- 支付证书和商户密钥必须在后台上传或保存
+
+## 7. 部署后必须验证的主链路
+
+- 用户下单
+- 用户提交寄送运单
+- 后台标记鉴定中心签收
+- 后台发起补料
+- 用户补料
+- 后台发布报告
+- 用户确认寄回地址
+- 后台登记回寄运单
+- 后台标记用户签收
+- 用户报告验真
+
+## 8. 当前状态
+
+当前代码库已经具备：
+
+- 用户端主流程
+- 后台订单履约主流程
+- 多仓库 / 改派仓库
+- 补料任务
+- 报告发布与验真
+- 寄回地址确认
+- 回寄运单登记
+- 用户签收闭环
+
+剩余工作更偏向：
+
+- 正式环境配置
+- 测试数据清理
+- 人工验收
+- 上线前口径确认
--- a/docs/deploy/fulfillment-smoke-checklist.md
+++ b/docs/deploy/fulfillment-smoke-checklist.md
@@ -0,0 +1,113 @@
+# 安心验履约链路冒烟检查表
+
+## 目标
+
+确认用户端、后台、消息中心围绕以下主链路已经闭环：
+
+1. 用户下单
+2. 用户寄送商品并提交运单
+3. 鉴定中心签收
+4. 鉴定中 / 补料
+5. 报告出具
+6. 用户确认寄回地址
+7. 后台登记回寄运单
+8. 用户签收回寄商品
+
+## 自动检查
+
+先执行：
+
+```bash
+cd /Users/wushumin/www/biyou/anxinyan/server-api
+php tools/smoke_check.php
+```
+
+预期：
+
+- 输出 `SMOKE_OK`
+- `app` 与 `admin` 关键接口全部通过
+- 报告详情接口包含 `verify_qrcode_url`
+
+## 人工检查
+
+### 1. 新建订单
+
+- 用户端发起一笔新订单
+- 在确认订单页必须可以选择“寄回地址”
+- 未选择寄回地址时，不能提交订单
+- 订单创建成功后，订单详情应显示：
+  - 收货仓库
+  - 寄回地址
+  - 下单资料
+
+### 2. 用户寄送
+
+- 订单状态应为 `待寄送` 或 `已提交运单`
+- 用户寄送页应只展示“寄往鉴定中心”物流
+- 提交运单后：
+  - 订单详情提示改为“等待鉴定中心签收”
+  - 订单列表状态应显示 `已提交运单`
+
+### 3. 鉴定中心签收
+
+- 后台订单详情点击“标记鉴定中心签收”
+- 订单状态应变为 `鉴定中心已收货`
+- 用户端订单详情同步显示已签收
+
+### 4. 补料
+
+- 后台发起补料后：
+  - 用户端订单状态应显示 `等待您补充资料`
+  - 鉴定作业台任务状态应显示 `待用户补料`
+  - 不得出现 `已退回` 这类容易误解成回寄商品的文案
+
+### 5. 报告出具
+
+- 后台发布报告后：
+  - 用户端报告中心出现报告
+  - 报告详情页显示验真二维码
+  - 订单状态应显示 `待寄回`
+  - 消息中心收到“报告已出具”
+
+### 6. 用户确认寄回地址
+
+- 订单详情页 `寄回给您` 区块应显示地址
+- 老订单若没有寄回快照，应自动回退显示用户默认地址
+- 用户可在回寄前修改寄回地址
+
+### 7. 后台登记回寄运单
+
+- 后台订单详情点击“登记回寄运单”
+- 若订单没有寄回地址快照，但用户有默认地址，应能自动补写后继续登记
+- 登记成功后：
+  - 订单状态应显示 `物品已寄回`
+  - 用户端订单详情显示回寄物流
+  - 消息中心收到“鉴定物品已寄回”
+
+### 8. 标记用户签收
+
+- 后台订单详情点击“标记用户签收”
+- 完成后：
+  - 订单状态应显示 `已完成`
+  - 回寄物流状态应为 `用户已签收`
+  - 消息中心收到“回寄商品已签收”
+  - 用户端订单详情应提示本次订单已完成
+
+## 当前已实现的关键点
+
+- 下单确认时选择寄回地址
+- 订单详情展示寄回地址与回寄物流
+- 后台登记回寄运单
+- 后台标记用户签收
+- 回寄消息通知联动
+- 用户端与后台订单状态口径统一
+- 报告详情二维码显示
+
+## 仍建议重点人工确认
+
+- 历史老订单在没有寄回地址快照时的展示是否符合预期
+- `completed` 状态下，列表页是否准确区分：
+  - 物品已寄回
+  - 已完成
+- 用户消息中心的回寄通知点击跳转是否总是进入正确订单
+- 报告页二维码在 H5 与小程序环境下都能正常扫描
--- a/docs/deploy/release-checklist.md
+++ b/docs/deploy/release-checklist.md
@@ -0,0 +1,67 @@
+# 安心验上线检查清单
+
+## 1. 环境变量
+- 替换 [server-api/.env.example](/Users/wushumin/www/biyou/anxinyan/server-api/.env.example) 中的数据库、Redis 等占位值
+- 确认 `APP_ENV=production`
+- 确认 `APP_DEBUG=false`
+- 确认 [admin-web/.env.production](/Users/wushumin/www/biyou/anxinyan/admin-web/.env.production) 与 [user-app/.env.production](/Users/wushumin/www/biyou/anxinyan/user-app/.env.production) 指向正式 API 域名，而不是 `localhost / 127.0.0.1 / example.com`
+
+## 2. 后台系统配置
+- 在后台 `系统配置` 中填写并保存：
+  - 小程序 `AppID / AppSecret / 原始ID`
+  - H5 `AppID / AppSecret / OAuth 回调地址 / H5 页面根地址`
+  - 短信 `阿里云 AccessKey ID / AccessKey Secret / 短信签名 / 登录模板 Code / Region ID`
+  - 支付 `MchID / APIv3 Key / 商户证书序列号 / 商户私钥 / 平台证书序列号 / 支付回调地址`
+- 严禁保留演示值：
+  - `wx1234567890test`
+  - `h5_app_demo`
+  - `1900000109`
+  - `demo_api_v3_key_1234567890`
+
+## 3. 管理后台安全
+- 修改默认超级管理员密码：
+  - `13800138000 / Admin@123456`
+- 删除或停用测试管理员：
+  - `13800138001 / Test@123456`
+- 按实际运营需要分配角色与权限
+
+## 4. 业务数据清理
+- 清理测试工单、测试订单、测试物流、测试消息
+- 清理 `server-api/public/uploads/` 下测试图片和 PDF
+- 确认用户昵称、地址等演示数据已替换或清空
+
+## 5. 构建与回归
+- 后端执行：
+  - `php tools/smoke_check.php`
+- 前端执行：
+  - `cd user-app && npm run type-check`
+  - `cd user-app && npm run build:h5`
+  - `cd admin-web && npm run build`
+- 核验关键链路：
+  - 用户端下单 -> 提交运单 -> 补资料 -> 报告 -> 验真
+  - 用户工单 -> 客服回复 -> 消息提醒
+  - 后台登录 -> 权限控制 -> 系统配置保存
+
+## 6. 微信相关
+- 在后台 `系统配置` 保存正式小程序 `AppID` 后，执行：
+  - `cd user-app && npm run sync:mp-config`
+- 再执行：
+  - `cd user-app && npm run build:mp-weixin`
+- 构建前确认 [user-app/src/manifest.json](/Users/wushumin/www/biyou/anxinyan/user-app/src/manifest.json) 中 `mp-weixin.appid` 已同步为正式值
+- 确认后台 `H5 页面根地址` 指向正式 H5 域名，例如 `https://m.example.com`，用于生成扫码查看报告和验真页链接
+- H5 授权域名、支付域名、回调域名已在微信平台完成配置
+- 微信支付商户平台证书与 APIv3 Key 已完成正式部署
+
+## 7. 短信登录
+- 在后台 `系统配置 -> 短信配置` 中填写阿里云短信参数
+- 确认短信签名与登录模板已在阿里云短信服务中审核通过
+- 确认登录模板包含 `code` 变量
+- 正式环境下验证：
+  - 非微信浏览器 H5 可通过 `手机号 + 验证码` 登录
+  - 已设置密码的账号可通过 `手机号 + 密码` 登录
+
+## 8. 发布前建议
+- 先跑一遍 `tools/release_audit.php`
+- 如需打包小程序，先跑一遍 `npm run sync:mp-config`
+- 审核巡检输出中的 `FAIL / WARN`
+- 完成替换后再做最终上线