docs: 项目文档、设计图、工具、协议模块、部署说明

docs/frontend-guide.md

@@ -0,0 +1,72 @@
+# 前端开发指南（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 提示。