73 lines
4.9 KiB
Markdown
73 lines
4.9 KiB
Markdown
# 前端开发指南（TDesign starter 深度说明）
|
||
|
||
> 2026-08-20 · 基于 apps/web 实际代码（starter 0.3.1）· 配套 docs/page-wireframes.md 使用。
|
||
|
||
## 1. 模板事实清单（实测）
|
||
|
||
| 项 | 事实 |
|
||
|---|---|
|
||
| 技术 | React 18.2 + Vite 2.9 + TS 4.8 + React Router 6 + Redux Toolkit + axios |
|
||
| 组件库 | tdesign-react 1.15 + tdesign-icons-react 0.6（MIT，可商用） |
|
||
| 目录 | src/pages(页面) / src/router(路由=菜单) / src/layouts(布局) / src/services(接口) / src/modules(redux) / src/configs(host.ts 环境) / mock(演示数据) |
|
||
| 模板页 | List/Base(表格列表) List/Card(卡片) Form/Base(表单) Form/Step(分步向导) Detail/Base(详情) Result(结果) User(成员) Dashboard(仪表盘) Login |
|
||
| 环境 | npm run dev(真实API) / dev:mock(mock数据); host.ts 分 mock/development/test/release/site |
|
||
| 过渡 | 无路由切换动画；仅零散 hover transition 与组件自带动效（见 §4） |
|
||
|
||
## 2. 关键机制（对接方式）
|
||
|
||
- **路由即菜单**：src/router/modules/ 每个 .ts 一个顶级菜单；meta{title, Icon, hidden, single}；children 即子菜单；isFullPage=true 为全屏页（登录页）。
|
||
- **布局**：src/layouts/components/ AppLayout(整体) + Header + Menu + Footer + Page；新页面只需加路由+页面文件。
|
||
- **接口**：src/services 为 axios 封装示例；把 src/configs/host.ts 的 development.API 指向 Go 服务器（如 http://localhost:8080）。
|
||
- **状态**：Redux Toolkit（modules/user 存登录态）；实时状态用原生 WebSocket（/ws，JWT 鉴权），事件 task.*/challenge.*/notification.*。
|
||
- **mock 移除**：删除 mock 目录与 vite-plugin-mock 使用，全部走真实 API。
|
||
|
||
## 3. 组件清单与场景映射
|
||
|
||
| TDesign 组件 | 适用场景 | 本项目页面 |
|
||
|---|---|---|
|
||
| Table + Tag + Pagination + Popconfirm | 数据列表/状态/二次确认 | 任务列表/素材/账号台账/成员/审计/租户/Agent总览 |
|
||
| Form + Input + Textarea + Select + Checkbox + Radio + Switch | 表单 | 登录/新建发布/设置/成员邀请 |
|
||
| Steps | 分步向导 | 新建发布四步 |
|
||
| DatePicker / DateRangePicker | 时间选择 | 定时发布/筛选 |
|
||
| Calendar | 月历 | 排期日历（若 1.15 无此组件则用卡片网格自绘，需 D6 前验证） |
|
||
| Upload + Progress + ImageViewer | 上传/预览 | 素材库 |
|
||
| Dialog | 模态弹窗 | 绑定扫码/验证码输入/邀请 |
|
||
| Drawer | 侧滑详情 | 任务详情/审核预览 |
|
||
| Timeline | 时间线 | 任务事件流 |
|
||
| Badge + Tag | 状态角标 | 绑定状态/任务状态/通知 |
|
||
| Message + Notification + Loading + Skeleton | 全局反馈 | 全站 |
|
||
| Tabs | 分栏 | 审核分平台预览/设置子页 |
|
||
| 二维码 | TDesign 无此组件 | 唯一新增依赖：qrcode.react（token 本地渲染） |
|
||
|
||
## 4. 过渡效果说明（结论：本期不做页面动画）
|
||
|
||
- starter 本身**没有**路由切换动画（实测仅 hover 背景/颜色 transition 与 Tree 组件动效）。
|
||
- TDesign 组件自带动效，直接使用：Drawer 滑入、Dialog 渐入、Message/Notification 渐入渐出、Tabs 下划线滑动、Loading 旋转。
|
||
- 约定：页面级不做过渡动画（保持响应快、实现简单）；若后续需要统一 fade，用 TDesign 主题变量 --td-anim-duration-base 统一加，本期不排。
|
||
|
||
## 5. 直接套用规范（每个页面怎么做）
|
||
|
||
| 我们的页面 | 复制哪个模板 | 改动点 |
|
||
|---|---|---|
|
||
| 登录页 | pages/Login | 去第三方登录/注册，接 /api/auth/login |
|
||
| 仪表盘 | pages/Dashboard/Base | 替换统计卡片与最近任务表格 |
|
||
| 任务列表/账号台账/成员/审计 | pages/List/Base | 改 columns、操作列、接 API |
|
||
| 素材库 | pages/List/Card | 卡片项=素材缩略图+操作 |
|
||
| 新建发布 | pages/Form/Step | 四步：素材→平台账号→内容→定时提交 |
|
||
| 任务详情 | pages/Detail/Base → Drawer 化 | Timeline 事件流 + 回执截图 |
|
||
| 审核中心 | pages/List/Base + Drawer | 预览用 Tabs 分平台 |
|
||
| 设置 | pages/Form/Base + Tabs | 资料/安全/通知渠道/Agent设备 |
|
||
| admin 两页 | pages/List/Base | /admin 路由域 + 角色守卫 |
|
||
|
||
## 6. 菜单与路由改造清单（D1 完成）
|
||
|
||
- router/modules 改为：dashboard(工作台)、publish(发布管理: 任务列表/新建发布/排期日历)、material(素材库)、account(账号管理)、review(审核中心)、challenge(通知与挑战)、member(成员与权限)、setting(设置)、audit(审计日志)、admin(平台管理域)。
|
||
- 任务详情为 hidden 路由（不进菜单）。
|
||
- 权限：utils 增 auth.ts（角色→菜单过滤 + 路由守卫），角色：admin/reviewer/operator/platform_admin。
|
||
|
||
## 7. 前后端联调约定
|
||
|
||
- REST：/api/*，Header Authorization: Bearer <JWT>；401 自动 refresh 重试一次。
|
||
- WS：原生 WebSocket，连接 /ws?token=<JWT>；心跳由服务端协议统一（10s/25s）。
|
||
- 分页约定：{ list, total, page, pageSize }；错误码约定：业务码 + message，前端 Message 提示。
|