前端开发指南（Web-only V1）

2026-08-21 · 基于 apps/web 实际代码。客户端/Agent 页面不属于当前菜单和验收。

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）

路由即菜单：src/router/modules/ 每个 .ts 一个顶级菜单；meta{title, Icon, hidden, single}；children 即子菜单；isFullPage=true 为全屏页（登录页）。
布局：src/layouts/components/ AppLayout(整体) + Header + Menu + Footer + Page；新页面只需加路由+页面文件。
接口：src/services 为 axios 封装示例；开发期使用 Vite /api 代理到 Go 127.0.0.1:8090，网页默认访问 127.0.0.1:3013。
状态：Redux Toolkit（modules/user 存登录态）；实时状态用原生 WebSocket（/ws/browser，JWT 鉴权），事件 task./challenge./notification.*。
mock 移除：删除 mock 目录与 vite-plugin-mock 使用，全部走真实 API。

TDesign 组件	适用场景	本项目页面
Table + Tag + Pagination + Popconfirm	数据列表/状态/二次确认	任务列表/素材/账号台账/成员/审计/租户
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	QR URL/token 本地渲染；真实扫码状态由 Browser WS/REST 更新

starter 本身没有路由切换动画（实测仅 hover 背景/颜色 transition 与 Tree 组件动效）。
TDesign 组件自带动效，直接使用：Drawer 滑入、Dialog 渐入、Message/Notification 渐入渐出、Tabs 下划线滑动、Loading 旋转。
约定：页面级不做过渡动画（保持响应快、实现简单）；若后续需要统一 fade，用 TDesign 主题变量 --td-anim-duration-base 统一加，本期不排。

router/modules 改为：dashboard(工作台)、publish(发布管理: 任务列表/新建发布/排期日历)、material(素材库)、account(账号管理)、review(审核中心)、challenge(通知与挑战)、notification(站内通知)、member(成员与权限)、setting(工作区资料/安全)、audit(审计日志)、admin(平台管理域)。
任务详情为 hidden 路由（不进菜单）。
权限：utils 增 auth.ts（角色→菜单过滤 + 路由守卫），角色：admin/reviewer/operator/platform_admin。