316702372/anxinyan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first

Browse Source
This commit is contained in:
wushumin
2026-05-11 15:28:27 +08:00
commit edd1a02157
302 changed files with 67193 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/api/api-list.md Normal file
View File

@@ -0,0 +1,5 @@
# API List
## 第三方开放接口
- [第三方订单对接文档](./third-party-openapi.md)：客户推送订单、订单查询、签名鉴权、Webhook 回调说明。

385
docs/api/third-party-openapi.md Normal file
View File

@@ -0,0 +1,385 @@
# 第三方订单对接文档
版本：v1
更新日期：2026-05-08
## 1. 对接说明
本文档用于第三方系统对接安心验开放接口。第三方推送订单时，只需要提供第三方自己的订单号 `external_order_no`，不需要提前传物品信息。具体物品信息会在鉴定师鉴定时由平台侧补充完善。
接口域名以实际环境为准，本文统一使用：
```text
https://{api-domain}
```
## 2. 凭证与安全
平台会为每个对接方分配：
| 参数 | 说明 |
| --- | --- |
| `app_key` | 调用方身份标识 |
| `app_secret` | 签名密钥，请妥善保管，不要传给前端或泄露到日志中 |
所有开放接口都需要签名。请求必须使用 HTTPS，并携带以下请求头：
| Header | 必填 | 说明 |
| --- | --- | --- |
| `Content-Type` | 是 | 固定为 `application/json` |
| `X-AXY-App-Key` | 是 | 平台分配的 `app_key` |
| `X-AXY-Timestamp` | 是 | Unix 秒级时间戳，有效期 300 秒 |
| `X-AXY-Nonce` | 是 | 随机字符串，同一个 `app_key` 下不可重复使用 |
| `X-AXY-Signature` | 是 | 请求签名 |
### 2.1 签名算法
签名使用 HMAC-SHA256，小写十六进制输出。
```text
body_hash = sha256(raw_body)
base = UPPERCASE_HTTP_METHOD + path_with_query + timestamp + nonce + body_hash
signature = hex_hmac_sha256(base, app_secret)
```
字段说明：
| 字段 | 说明 |
| --- | --- |
| `raw_body` | 原始请求体字符串。GET 请求没有请求体时为空字符串 |
| `path_with_query` | 请求路径加查询字符串，例如 `/api/open/v1/orders?external_order_no=T202605080001` |
| `timestamp` | 与 `X-AXY-Timestamp` 完全一致 |
| `nonce` | 与 `X-AXY-Nonce` 完全一致 |
注意事项：
- `path_with_query` 必须与实际请求完全一致，包括查询参数顺序和 URL 编码。
- POST 请求签名时使用实际发送的 JSON 字符串，不要签名一个格式化版本、发送另一个压缩版本。
- GET 请求的 `body_hash` 为 `sha256("")`。
- `nonce` 会做防重放校验，重试请求需要重新生成 `nonce` 和签名。
### 2.2 Node.js 签名示例
```js
import crypto from 'node:crypto';
function sign({ method, pathWithQuery, body = '', timestamp, nonce, appSecret }) {
const bodyHash = crypto.createHash('sha256').update(body).digest('hex');
const base = method.toUpperCase() + pathWithQuery + timestamp + nonce + bodyHash;
return crypto.createHmac('sha256', appSecret).update(base).digest('hex');
}
```
### 2.3 PHP 签名示例
```php
function sign_request(string $method, string $pathWithQuery, string $body, string $timestamp, string $nonce, string $appSecret): string
{
$bodyHash = hash('sha256', $body);
$base = strtoupper($method) . $pathWithQuery . $timestamp . $nonce . $bodyHash;
return hash_hmac('sha256', $base, $appSecret);
}
```
## 3. 通用响应格式
成功响应：
```json
{
"code": 0,
"message": "ok",
"data": {}
}
```
失败响应：
```json
{
"code": 422,
"message": "external_order_no 不能为空",
"data": {}
}
```
常见错误码：
| code | 说明 |
| --- | --- |
| `401` | 鉴权失败、签名错误、时间戳过期、`nonce` 重复 |
| `404` | 订单不存在 |
| `409` | 幂等冲突，例如同一个 `external_order_no` 请求内容不一致 |
| `422` | 请求参数不合法 |
| `500` | 服务端处理失败 |
## 4. 创建订单
```text
POST /api/open/v1/orders
```
第三方创建订单时只需要传 `external_order_no`。平台会创建一笔待收货订单，后续物品信息由鉴定师在鉴定工作台补充。
### 4.1 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `external_order_no` | string | 是 | 第三方订单号。同一对接客户下必须唯一 |
| `service_provider` | string | 否 | 服务方，可选 `anxinyan`、`zhongjian`，默认 `anxinyan` |
| `product_info` | object | 否 | 物品信息，当前可不传 |
| `materials` | array | 否 | 鉴定资料图片 URL 列表，当前可不传 |
| `return_address` | object | 否 | 退回地址，当前可不传；如传任一地址字段，则必填完整地址 |
| `inbound_logistics` | object | 否 | 寄入物流信息，当前可不传 |
| `express_company` | string | 否 | 寄入快递公司，可替代 `inbound_logistics.express_company` |
| `tracking_no` | string | 否 | 寄入运单号，可替代 `inbound_logistics.tracking_no` |
| `extra_info` | object | 否 | 扩展信息，当前可不传 |
### 4.2 最小请求示例
```json
{
"external_order_no": "THIRD202605080001"
}
```
### 4.3 带可选字段请求示例
```json
{
"external_order_no": "THIRD202605080002",
"service_provider": "anxinyan",
"inbound_logistics": {
"express_company": "顺丰速运",
"tracking_no": "SF1234567890"
},
"return_address": {
"consignee": "张三",
"mobile": "13800138000",
"province": "浙江省",
"city": "杭州市",
"district": "西湖区",
"detail_address": "文三路 1 号"
}
}
```
### 4.4 cURL 示例
```bash
curl -X POST 'https://{api-domain}/api/open/v1/orders' \
-H 'Content-Type: application/json' \
-H 'X-AXY-App-Key: your_app_key' \
-H 'X-AXY-Timestamp: 1778227200' \
-H 'X-AXY-Nonce: 7b7b2a2f9c9e4d1f' \
-H 'X-AXY-Signature: calculated_signature' \
-d '{"external_order_no":"THIRD202605080001"}'
```
### 4.5 成功响应示例
```json
{
"code": 0,
"message": "订单已创建",
"data": {
"idempotent": false,
"order": {
"customer_id": "CUST001",
"customer_code": "CUST001",
"external_order_no": "THIRD202605080001",
"order_id": 123,
"order_no": "AXY20260508120000123",
"appraisal_no": "AXY-APP-20260508-1001",
"order_status": "pending_shipping",
"display_status": "待寄送商品",
"payment_status": "paid",
"pay_amount": 99,
"estimated_finish_time": "2026-05-09 12:00:00",
"created_at": "2026-05-08 12:00:00",
"timeline": [
{
"node_code": "created",
"node_text": "下单成功",
"node_desc": "大客户订单已推送并创建成功",
"occurred_at": "2026-05-08 12:00:00"
},
{
"node_code": "pending_shipping",
"node_text": "待寄送商品",
"node_desc": "请将商品寄送至鉴定中心",
"occurred_at": "2026-05-08 12:00:00"
}
],
"inbound_logistics": null,
"return_logistics": null,
"report_summary": null
}
}
}
```
### 4.6 幂等规则
同一个对接客户下，`external_order_no` 作为幂等键：
- 第一次请求会创建订单。
- 后续使用相同 `external_order_no` 且请求内容一致时，不会重复创建订单，会返回已有订单，`data.idempotent` 为 `true`。
- 后续使用相同 `external_order_no` 但请求内容不一致时，返回 `409`。
建议第三方重试创建订单时保持请求 JSON 内容一致，仅重新生成 `timestamp`、`nonce` 和 `signature`。
## 5. 查询订单
支持按第三方订单号或平台订单号查询订单进度。
### 5.1 按第三方订单号查询
```text
GET /api/open/v1/orders/{external_order_no}
```
示例：
```bash
curl -X GET 'https://{api-domain}/api/open/v1/orders/THIRD202605080001' \
-H 'Content-Type: application/json' \
-H 'X-AXY-App-Key: your_app_key' \
-H 'X-AXY-Timestamp: 1778227200' \
-H 'X-AXY-Nonce: f0f74a6baf764d8f' \
-H 'X-AXY-Signature: calculated_signature'
```
### 5.2 通过查询参数查询
```text
GET /api/open/v1/orders?external_order_no=THIRD202605080001
GET /api/open/v1/orders?order_no=AXY20260508120000123
```
### 5.3 响应示例
```json
{
"code": 0,
"message": "ok",
"data": {
"order": {
"customer_id": "CUST001",
"customer_code": "CUST001",
"external_order_no": "THIRD202605080001",
"order_id": 123,
"order_no": "AXY20260508120000123",
"appraisal_no": "AXY-APP-20260508-1001",
"order_status": "report_published",
"display_status": "报告已发布",
"payment_status": "paid",
"pay_amount": 99,
"estimated_finish_time": "2026-05-09 12:00:00",
"created_at": "2026-05-08 12:00:00",
"timeline": [],
"inbound_logistics": {
"express_company": "顺丰速运",
"tracking_no": "SF1234567890",
"tracking_status": "submitted",
"latest_desc": "客户已提交寄送运单：顺丰速运 SF1234567890，等待鉴定中心签收。",
"latest_time": "2026-05-08 12:00:00"
},
"return_logistics": null,
"report_summary": {
"report_no": "R202605080001",
"report_title": "鉴定报告",
"report_status": "published",
"publish_time": "2026-05-08 18:00:00",
"verify_url": "https://{h5-domain}/verify?id=xxx",
"report_page_url": "https://{h5-domain}/report/xxx",
"verify_status": "valid"
}
}
}
}
```
## 6. 订单状态
常见订单状态如下，最终以接口返回的 `order_status` 和 `display_status` 为准。
| order_status | display_status | 说明 |
| --- | --- | --- |
| `pending_shipping` | 待寄送商品 | 订单已创建，等待物品到仓或人工确认收货 |
| `received` | 鉴定中心已收货 | 物品已到仓 |
| `appraising` | 物品鉴定中 | 鉴定师正在鉴定 |
| `generating_report` | 物品鉴定完成 | 鉴定完成，报告生成中 |
| `report_published` | 报告已发布 | 报告已发布，可查看报告摘要 |
| `return_shipped` | 物品已寄回 | 物品已退回寄出 |
| `completed` | 已完成 | 订单完成 |
| `pending_supplement` | 需要补充资料 | 需要补充资料 |
## 7. Webhook 事件回调
如需接收订单状态变化通知，第三方需向平台提供可公网访问的 `webhook_url`，并由平台开启回调。
平台会以 POST JSON 方式推送事件：
| Header | 说明 |
| --- | --- |
| `Content-Type` | `application/json` |
| `X-AXY-App-Key` | 平台分配给该客户的 `app_key` |
当前 webhook 仅携带 `X-AXY-App-Key`，暂未实现回调签名。如第三方需要回调验签，可与平台另行约定后升级。
回调超时时间：
| 项目 | 值 |
| --- | --- |
| 连接超时 | 3 秒 |
| 总超时 | 6 秒 |
| 成功判定 | HTTP 状态码为 2xx 且无网络错误 |
### 7.1 回调报文
```json
{
"event_code": "order_created",
"event_text": "订单创建",
"customer_id": "CUST001",
"customer_code": "CUST001",
"external_order_no": "THIRD202605080001",
"order_no": "AXY20260508120000123",
"appraisal_no": "AXY-APP-20260508-1001",
"status_code": "pending_shipping",
"status_text": "待寄送商品",
"occurred_at": "2026-05-08 12:00:00",
"data": {},
"event_id": 1
}
```
### 7.2 事件类型
| event_code | event_text | status_code | status_text |
| --- | --- | --- | --- |
| `order_created` | 订单创建 | `pending_shipping` | 待寄送商品 |
| `inbound_received` | 快递已到仓 | `received` | 鉴定中心已收货 |
| `appraising` | 物品鉴定中 | `appraising` | 物品鉴定中 |
| `appraisal_finished` | 物品鉴定完成 | `generating_report` | 物品鉴定完成 |
| `report_published` | 报告已发布 | `report_published` | 报告已发布 |
| `return_shipped` | 物品已寄回 | `return_shipped` | 物品已寄回 |
| `completed` | 订单已完成 | `completed` | 已完成 |
| `supplement_required` | 需要补充资料 | `pending_supplement` | 需要补充资料 |
### 7.3 回调接收建议
第三方接收 webhook 时建议：
- 使用 `event_id` 做事件幂等，避免重复处理。
- 收到事件后返回 HTTP 2xx。
- 如需强一致的最新状态，可以收到 webhook 后再调用订单查询接口确认。
## 8. 对接流程建议
1. 平台分配 `app_key` 和 `app_secret`。
2. 第三方完成签名调试。
3. 第三方调用创建订单接口，只传 `external_order_no` 即可。
4. 第三方可通过查询接口主动查询订单状态。
5. 如启用 webhook，平台在订单状态变化时主动通知第三方。

3
docs/database/er-design.md Normal file
View File

@@ -0,0 +1,3 @@
# ER Design
Pending fill-in based on the confirmed table structure.

17
docs/deploy/anxinyan-api.service.example Normal file
View File

@@ -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

21
docs/deploy/api.anxinjianyan.com.nginx.conf.example Normal file
View File

@@ -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 代理逻辑。

157
docs/deploy/backend-api-online-deploy.md Normal file
View File

@@ -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`

138
docs/deploy/delivery-notes.md Normal file
View File

@@ -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. 构建正式包并发布

130
docs/deploy/deploy-plan.md Normal file
View File

@@ -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. 当前状态
当前代码库已经具备：
- 用户端主流程
- 后台订单履约主流程
- 多仓库 / 改派仓库
- 补料任务
- 报告发布与验真
- 寄回地址确认
- 回寄运单登记
- 用户签收闭环
剩余工作更偏向：
- 正式环境配置
- 测试数据清理
- 人工验收
- 上线前口径确认

113
docs/deploy/fulfillment-smoke-checklist.md Normal file
View File

@@ -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 与小程序环境下都能正常扫描

67
docs/deploy/release-checklist.md Normal file
View File

@@ -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`
- 完成替换后再做最终上线

126
docs/flow/state-machine.md Normal file
View File

@@ -0,0 +1,126 @@
# 安心验履约状态机
## 1. 订单主状态
### 用户提交前
- `pending_payment`
说明：订单待支付，当前项目里基本不作为主流履约状态使用。
- `pending_submission`
说明：待补充下单资料，尚未进入正式送检流转。
### 用户寄送阶段
- `pending_shipping`
说明：订单已创建，等待用户寄送商品到鉴定中心。
典型展示：
- 未填运单：`待寄送商品`
- 已填运单：`已提交运单`
- `received`
说明：鉴定中心已签收商品，等待进入鉴定处理。
### 鉴定阶段
- `in_first_review`
说明：鉴定处理中。
- `pending_supplement`
说明：鉴定师发起补料，等待用户补交资料。
- `generating_report`
说明：已完成鉴定，正在生成报告。
### 报告与寄回阶段
- `report_published`
说明：报告已发布，等待平台安排寄回商品。
典型展示：`待寄回`
- `completed`
说明：订单已完成。
注意：`completed` 下根据回寄物流再细分展示：
- 已登记回寄运单但用户未签收：`物品已寄回`
- 用户已签收回寄商品：`已完成`
## 2. 鉴定任务状态
### 任务阶段
- `first_review`
说明：鉴定任务
### 任务状态值
- `pending`
对外文案：`待处理`
- `processing`
对外文案：`处理中`
- `returned`
对外文案：`待用户补料`
注意：这是任务被打回补料，不是货品寄回用户。
- `submitted`
对外文案：`已提交`
- `completed`
对外文案：`已完成`
## 3. 物流状态
### 物流类型
- `send_to_center`
说明：用户寄送到鉴定中心
- `return_to_user`
说明：平台回寄给用户
### 物流节点状态
#### 用户寄送物流
- `submitted`
文案：`已提交运单`
- `in_transit`
文案：`运输中`
- `received`
文案：`已签收`
#### 回寄物流
- `submitted`
文案：`已登记回寄运单`
- `in_transit`
文案：`回寄途中`
- `received`
文案：`用户已签收`
## 4. 关键状态迁移
### 下单到鉴定
1. 用户创建订单
2. 订单进入 `pending_shipping`
3. 用户提交寄送运单
4. 后台标记鉴定中心签收
5. 订单进入 `received`
6. 鉴定任务进入 `processing`
### 补料分支
1. 鉴定师发起补料
2. 当前任务状态改为 `returned`
3. 订单状态改为 `pending_supplement`
4. 用户补料完成后，订单重新进入 `in_first_review`
### 出报告到寄回
1. 后台发布报告
2. 订单进入 `report_published`
3. 用户确认寄回地址
4. 后台登记回寄运单
5. 订单进入 `completed`
6. 若回寄物流未签收，对外显示 `物品已寄回`
7. 后台标记用户签收后，对外显示 `已完成`
## 5. 当前关键口径
- “补料”只能表示资料补充，不得使用“退回”对外表达。
- “待寄回”表示报告已出具但平台尚未登记回寄运单。
- “物品已寄回”表示平台已登记回寄运单，但用户尚未签收。
- “已完成”只用于回寄商品已签收，或无需回寄的最终完成态。
- 订单报告未发布前，不允许登记回寄运单或安排物品寄回。

3
docs/prd/mvp-prd.md Normal file
View File

@@ -0,0 +1,3 @@
# MVP PRD
Pending fill-in based on the confirmed product scope.

226
docs/static-data-audit-20260423.md Normal file
View File

@@ -0,0 +1,226 @@
# 安心验静态数据与展示映射审计
审计时间：2026-04-23
## 一、已确认的真实问题
### 1. 后台订单详情页存在“接口有值但页面没展示完整”的问题
- 文件：`admin-web/src/pages/orders/index.vue`
- 现象：
- 接口已返回 `product_info.color`
- 接口已返回 `extra_info.condition_desc` / `remark`
- 页面原先只展示了 `size_spec` 和 `usage_status`
- 导致后台看到的内容与接口实际内容不一致，且卡片出现大面积空白
- 本轮已修复：
- 商品信息区补充 `颜色 / 规格`
- 补充信息区补充 `补充说明`
### 2. 鉴定作业台也存在同类字段遗漏
- 文件：`admin-web/src/pages/appraisal-tasks/index.vue`
- 现象：
- 页面已有 `product_info.color`
- 但工作区与上下文区未展示，导致检测侧看到的信息不完整
- 本轮已修复：
- 商品与送检区补充 `颜色 / 规格`
- 工作台左侧上下文区补充 `颜色 / 规格`
### 3. 用户端多个页面在接口失败时会静默回退到 mock 数据
- 风险级别：高
- 问题本质：
- 页面请求失败后，没有给用户明确错误态
- 而是继续显示 `src/mocks/app.ts` 中的示例数据
- 会造成“接口已经失败，但页面仍像有真实数据”的错觉
- 这类问题比普通静态文案更危险，因为会直接影响业务判断
## 二、前端仍在使用 mock / fallback 的页面
### 1. 用户端高风险页面
以下页面在请求失败时，会直接沿用 mock 或 fallback 数据：
- `user-app/src/pages/home/index.vue`
- `user-app/src/pages/address/index.vue`
- `user-app/src/pages/message/index.vue`
- `user-app/src/pages/mine/index.vue`
- `user-app/src/pages/order/detail.vue`
- `user-app/src/pages/order/shipping.vue`
- `user-app/src/pages/report/detail.vue`
- `user-app/src/pages/help/index.vue`
- `user-app/src/pages/help/detail.vue`
- `user-app/src/pages/settings/index.vue`
- `user-app/src/pages/support/index.vue`
- `user-app/src/pages/support/detail.vue`
- `user-app/src/pages/support/create.vue`
- `user-app/src/pages/verify/result.vue`
统一来源：
- `user-app/src/mocks/app.ts`
### 2. 风险说明
- 订单、报告、消息、地址、工单、验真都属于真实业务数据
- 这些页面不适合在接口失败时展示示例数据
- 正确策略应该是：
- 显示错误态
- 提供重试按钮
- 保留空态，但不能伪造业务内容
## 三、后端接口本身仍是静态拼装的数据
### 1. 首页接口
- 文件：`server-api/app/controller/app/HomeController.php`
- 当前静态内容：
- `banners`
- `service_entries`
- `quick_entries`
- `trust_metrics`
- `trust_points`
- `faqs`
- 当前只有 `category_entries` 来自数据库
补充说明：
- `user-app/src/pages/home/index.vue` 原先没有消费 `banners`
- 即使接口已经返回首页头图文案，前端页面也仍然使用写死标题
- 本轮已修复为直接读取接口 `banners[0]`
### 2. 帮助中心接口
- 文件：`server-api/app/controller/app/HelpCenterController.php`
- 当前问题：
- 帮助分类与文章内容全部写在控制器里
- 搜索和分类筛选只是对本地数组做过滤
- 结论：
- 当前帮助中心已经“可用”，但本质仍是写死内容，不是后台可运营内容
### 3. 设置页协议入口
- 文件：`server-api/app/controller/app/SettingsController.php`
- 当前静态内容：
- `legal_entries`
- 跳转的帮助中心关键词
### 4. 下单预览协议文案
- 文件：`server-api/app/controller/app/AppraisalController.php`
- 当前静态内容：
- `preview()` 中的 `agreements`
- `service_agreement`
- `privacy_policy`
- `appraisal_notice`
## 四、前端仍然硬编码的业务选项
这些不一定是 bug，但如果要达到“后台可维护、线上可运营”的标准，后续建议逐步改成可配置或接口下发。
### 1. 用户端
- `user-app/src/pages/support/create.vue`
- 工单类型 `typeOptions`
- `user-app/src/pages/support/index.vue`
- 常见问题快捷入口 `quickTypes`
- `user-app/src/pages/appraisal/product.vue`
- 颜色建议 `colorSuggestions`
- 规格建议 `sizeSuggestions`
- `user-app/src/pages/appraisal/extra.vue`
- 购买渠道
- 使用情况
- 附件情况
### 2. 管理后台
- `admin-web/src/pages/orders/index.vue`
- 服务筛选项
- 状态筛选项
- `admin-web/src/pages/appraisal-tasks/index.vue`
- 阶段筛选项
- 状态筛选项
- 结果选项
- `admin-web/src/pages/reports/index.vue`
- 服务筛选项
- 报告状态项
- 结果项
- `admin-web/src/pages/tickets/index.vue`
- 工单类型与状态筛选
说明：
- 这类枚举型选项短期内可以先保留
- 但工单类型、结果模板、服务文案如果未来需要运营调整，建议迁移为后台字典表或系统配置
## 五、已发现的“假入口 / 假交互”
- `user-app/src/pages/appraisal/upload.vue`
- `查看示例` 按钮无实际功能
- `查看拍摄示例` 入口无实际功能
- `user-app/src/pages/home/index.vue`
- 未识别的快捷入口会落到“该功能正在完善中”
- `user-app/src/pages/mine/index.vue`
- 未识别入口也会落到“该功能正在完善中”
## 六、推荐开发顺序
### P0：先清掉会误导真实业务判断的 fallback
优先处理以下页面：
- 订单详情
- 报告详情
- 消息中心
- 地址管理
- 工单列表 / 工单详情
- 设置页
- 验真页
目标：
- 失败时显示明确错误状态，不再显示 mock 业务数据
### P1：把接口里已返回但页面没展示完整的字段补齐
优先处理以下模块：
- 后台订单详情
- 鉴定作业台
- 用户端订单详情
- 报告详情页的商品摘要 / 估值摘要一致性
目标：
- 页面展示与接口字段保持一致
- 同一份订单数据在用户端、后台、报告端口径一致
### P2：把后端静态内容迁移为可维护内容
优先处理：
- 首页内容
- 帮助中心
- 设置页协议入口
- 下单预览协议区
推荐做法：
- 新建内容配置表 / 帮助中心表 / 协议配置表
- 后台增加内容维护入口
- 用户端改为读取接口配置
### P3：把前端硬编码枚举逐步改为字典化
优先处理：
- 工单类型
- 鉴定结果模板
- 用户端下单辅助枚举
## 七、建议的下一步落地动作
1. 先移除用户端业务页面对 `user-app/src/mocks/app.ts` 的依赖，改为错误态 + 重试。
2. 统一订单 / 报告 / 鉴定任务三端字段口径，补齐 `color`、`condition_desc`、`remark`、`accessories` 等实际字段。
3. 设计内容配置模型，把首页、帮助中心、协议说明迁到后台管理。
4. 最后再做字典化，把工单类型、辅助选项、结果模板迁到接口配置。