# 前端路由清单 + 后端接口清单

文档编号：pcbjia-ROUTER-API-V1.0
约定：

1. 前端为主站统一域名下的 SPA 路由，全部支持 URL 直接访问。
2. 接口统一前缀 `/api/v1`，返回 `{ code, msg, data }`。
3. 鉴权：`Authorization: Bearer {token}`。
4. 分页：`page`、`page_size`；排序：`sort_field`、`sort_order`。
5. 删除默认软删除，由服务端统一处理。

---

## 一、前端路由表

### 1.1 全局

| 路由 | 页面 | 状态 |
| --- | --- | --- |
| `/` | 首页 | 已上线 |
| `/login` | 登录（邮箱 / 短信 OTP） | 已上线 |
| `/register` | 注册 | 已上线 |
| `/search` | 全站搜索 | 已上线 |
| `/user-center` | 个人中心 | 已上线 |
| `/messages` | 消息中心 | 已上线 |
| `/notification` | 通知列表 | 规划 |
| `/help` | 帮助中心 | 规划 |
| `/downloads` | 下载中心 | 已上线 |

### 1.2 商城与交易

| 路由 | 页面 | 状态 |
| --- | --- | --- |
| `/mall` | 商城首页 | 已上线 |
| `/mall/cart` | 购物车 | 已上线 |
| `/request-quote` | 发起报价 | 已上线 |
| `/pricing/impedance` | 阻抗计算与报价 | 已上线 |
| `/orders` | 订单列表 | 已上线 |
| `/orders/:id` | 订单详情 | 已上线 |
| `/dfm-analysis` | DFM 分析 | 已上线 |
| `/dfm-checklist` | DFM 检查清单 | 已上线 |
| `/dfm-online-check` | DFM 在线检查 | 已上线 |
| `/sample-request` | 样品申请 | 已上线 |

### 1.3 家狗服务商频道

| 路由 | 页面 |
| --- | --- |
| `/jiagou` | 频道首页 |
| `/jiagou/bids` | 标单大厅 |
| `/jiagou/bids/:id` | 标单详情与报价 |
| `/jiagou/providers` | 服务商广场 |
| `/jiagou/providers/:providerId` | 服务商店铺 |
| `/jiagou/workspace` | 我的工作台 |
| `/jiagou/rules` | 规则中心 |
| `/jiagou/cert` | 资质认证 |

### 1.4 社区

| 路由 | 页面 |
| --- | --- |
| `/pcb-chat` | 聊天室首页 |
| `/pcb-chat?room=:roomId` | 房间定位 |
| `/forum` | 论坛首页 |
| `/forum?bridge=:id` | 聊天室沉淀帖承接 |
| `/forum/post/:id` | 帖子详情 |

### 1.5 工具与软件

| 路由 | 页面 |
| --- | --- |
| `/software-center` | 工业软件中心 |
| `/software/:channel/:packageId` | 软件详情 |
| `/tools/cam-core` | CAM 内核自检 |
| `/tools/3d-viewer` | 3D 查看器 |
| `/downloads/view` | 文档站内预览 |

### 1.6 规划中的社区路由

| 路由 | 页面 |
| --- | --- |
| `/pcb-chat/room/:roomId` | 房间主页 |
| `/pcb-chat/room/:roomId/thread/:threadId` | 子线程详情 |
| `/forum/section/:sectionId` | 版块列表 |
| `/forum/post/create` | 发帖 |
| `/forum/column` | 专栏合集 |
| `/pm` | 私信列表 |
| `/user/auth-apply` | 专家认证申请 |

---

## 二、后端接口清单

### 2.1 账号与用户

```
POST   /user/login
POST   /user/register
GET    /user/info
PUT    /user/info
GET    /user/profile/:uid
GET    /user/credit/log
GET    /user/collect
POST   /user/collect
DELETE /user/collect/:id
POST   /user/follow/:uid
DELETE /user/follow/:uid
POST   /user/blacklist/:uid
GET    /user/setting
PUT    /user/setting
POST   /user/expert/apply
```

### 2.2 企业与子账号

```
GET    /company/info
PUT    /company/info
GET    /company/members
POST   /company/members
PUT    /company/members/:id/role
DELETE /company/members/:id
GET    /company/credit
```

### 2.3 询价与比价

```
POST   /inquiry
GET    /inquiry/list
GET    /inquiry/:id
POST   /inquiry/:id/cancel
GET    /inquiry/:id/quotes
POST   /inquiry/:id/quote
POST   /inquiry/:id/select
GET    /inquiry/:id/export
```

### 2.4 订单与履约

```
GET    /order/list
GET    /order/:id
POST   /order
POST   /order/:id/cancel
POST   /order/:id/track
GET    /order/:id/track/list
```

### 2.5 DFM 与工程文件

```
POST   /file/upload
GET    /file/:id/preview
GET    /file/:id/download
POST   /dfm/analyze
GET    /dfm/report/:fileId
POST   /dfm/risk-confirm
```

### 2.6 CAR 品质工单

```
POST   /car
GET    /car/list
GET    /car/:id
PUT    /car/:id/status
POST   /car/:id/8d
GET    /car/:id/export
```

### 2.7 服务商频道

```
GET    /provider/list
GET    /provider/:id
GET    /provider/:id/reviews
POST   /provider/:id/review
POST   /provider/cert/apply
GET    /bid/list
GET    /bid/:id
```

### 2.8 社区（聊天室 + 论坛）

```
GET    /chat/room/list
GET    /chat/room/:id
GET    /chat/room/:id/online
GET    /chat/room/:id/thread
POST   /chat/thread
PUT    /chat/thread/:id/essence
POST   /chat/thread/:id/satisfy
POST   /chat/thread/:id/transfer-to-forum
GET    /chat/thread/:id/messages
POST   /chat/message
PUT    /chat/message/:id
DELETE /chat/message/:id

GET    /forum/section/list
GET    /forum/post/list
POST   /forum/post
GET    /forum/post/:id
PUT    /forum/post/:id
PUT    /forum/post/:id/essence
PUT    /forum/post/:id/status
POST   /forum/post/:id/bind-chat
POST   /forum/reply
PUT    /forum/reply/:id/best
GET    /forum/tag/list
```

### 2.9 通知与私信

```
GET    /notification/list
PUT    /notification/read/:id
PUT    /notification/read-all
GET    /pm/conv/list
POST   /pm/conv
GET    /pm/conv/:id/messages
POST   /pm/message
```

### 2.10 AI 统一底座

```
POST   /ai/chat/ask
POST   /ai/forum/pre-answer
POST   /ai/similar
POST   /ai/tag-gen
POST   /ai/translate
POST   /ai/summary
GET    /ai/usage
```

### 2.11 搜索与举报

```
GET    /search/global
POST   /report/submit
```

### 2.12 外贸单证（P32）

```
GET    /trade/template/list
POST   /trade/template/save
POST   /trade/doc/generate
GET    /trade/doc/list
GET    /trade/doc/:id
POST   /trade/doc/save-edit
POST   /trade/doc/export-pdf
GET    /trade/doc/versions
POST   /trade/doc/revert
GET    /trade/hs/list
```

### 2.13 积分与任务（P34）

```
POST   /point/sign
GET    /point/sign/calendar
GET    /task/list
POST   /task/reward
GET    /point/account
GET    /point/log
GET    /point/goods/list
POST   /point/goods/exchange
```

---

## 三、WebSocket 事件

上行：`join_room`、`join_thread`、`send_msg`、`edit_msg`、`delete_msg`
下行：`new_msg`、`msg_edited`、`msg_deleted`、`online_change`、`thread_essence_changed`、`thread_bind_forum`、`thread_archived`、`notify`

---

## 四、统一返回码

| code | 含义 |
| --- | --- |
| 200 | 成功 |
| 400 | 参数错误 |
| 401 | 未登录或 token 失效 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 429 | 限流或额度耗尽 |
| 500 | 服务异常 |

---

## 五、服务端统一校验

1. 富文本 XSS 过滤。
2. 上传校验 MIME、后缀、体积，必要时杀毒。
3. 新用户与普通用户限流，专家与版主白名单豁免。
4. 外链加 rel 属性并做域名拦截。
5. AI 输出统一追加免责说明，前端不可移除。
6. 所有修改与删除写操作日志。

---

## 六、社区数据模型要点

完整建表见 `db_core_schema.sql`「社区域」段落，此处仅列关键关系：

1. `forum_post.bind_chat_thread_id` 与 `chat_thread.bind_forum_post_id` 双向一对一，解绑只清字段不删内容。
2. 附件统一挂 `attachment`，用 `rel_type + rel_id` 关联，流转复用同一条记录。
3. AI 知识库只读取 `essence_index`，由精华动作写入与失效，不自动抓取普通聊天。
4. 悬赏积分先入 `credit_freeze` 冻结，采纳后才扣减并写 `user_credit`。
5. 编辑历史独立表，不污染主内容表。