先知道每个文件#
| 文件 | 作用 |
|---|---|
frontend/index.html |
文档标题、root 容器和入口脚本 |
src/main.tsx |
创建 React root、加载全局与品牌样式 |
src/App.tsx |
屏幕切换、登录、首页、详情、编辑、个人页、搜索、设置和后台 |
src/api.ts |
fetch、token、超时、错误、统一解包、401事件 |
src/types.ts |
请求/响应相关类型 |
src/mock.ts |
仅显式开启原型演示时使用的数据 |
src/styles.css |
原有组件的基础布局 |
src/journal.css |
本次生活手册品牌层和响应式调整 |
public/assets |
默认本地摄影和头像 |
vite.config.ts |
React 插件、开发代理、固定本机监听 |
当前采用 App 内屏幕状态,没有新引入路由库。刷新会回到默认首页,token仍恢复登录;它不承诺每篇笔记有可直接分享的独立 URL。未来引入路由应同时处理浏览器后退、刷新、加载权限和404。
React 的四个概念#
组件是返回页面的函数,例如 NoteCard。props 是上层传入的数据和动作;state 是本组件会变化的数据;effect 在挂载或依赖变化后与外部系统同步。useState([]) 保存笔记,setNotes 触发重新渲染;不能直接改数组然后期待页面知道。
useEffect 不是“任意代码都放进去”的容器。首页请求依赖页签、页码和登录状态,清理函数让旧请求结果不覆盖已切换页签。React StrictMode 开发时可能额外运行 effect 检查清理,因此网络看到两次初始读取并不一定是业务重复写入。
请求封装的真实数据结构#
request 设置 Accept、JSON 或 FormData 请求格式,附带 token,15秒AbortController超时,验证响应是 JSON,检查 HTTP 状态与 success,返回业务 data。FormData 不手动写 Content-Type,因为浏览器需要自动加 boundary。
401 清理失效 token 并派发 session-expired,App 切回首页和提示登录。网络错误不会静默返回 demoNotes。发布与修改返回 Note,页面拿真实 ID;资料更新返回 Profile,因此实际头像 URL 替换本地 blob 预览。
页面的几个边界#
发现推荐、关注、最新使用同一真实搜索入口;关注需要登录,空态给出下一步。搜索区分笔记/用户,筛选枚举统一映射;个人笔记使用 cursor;评论、关系和搜索用页码。用户不能因为一个列表只加载了20条就误以为总共只有20条。
详情点赞和收藏乐观更新,失败回滚。加载详情的 effect 依赖笔记 ID 和登录状态,不能每次按钮改变对象引用就重读旧状态覆盖刚刚的操作。删除和私密后,列表重新读取后端,不能只本地隐藏却让直接请求继续成功。
视觉 skill 的应用#
参考文件在 third_party/skills/frontend-design,来源和许可在第三方说明 ↗。先写视觉方案再实现:蓝色书脊、摄影主导、黄色便签集中表达个性;删除轨道装饰和大面积渐变;标题不靠单词变色制造层次。
桌面4列、平板3/2列、手机2列;小屏首屏重排拼贴;主题入口可横向滚动但整页不溢出。字号、留白、作者行和图片裁切共同决定层级,不能只把按钮换成另一种蓝色就说完成设计。
可访问性和安全#
所有交互保留键盘焦点,卡片可 Enter/Space 激活,内层按钮事件不误触整张卡。弹窗声明 dialog/aria-modal,Escape关闭;反馈使用 role=status;减少动画媒体查询禁用非必要运动。标题和昵称用 JSX 文本,不直接插入服务端 HTML。图片带 alt,失败头像回本地资源且移除重复 onError 防循环。
构建与联调#
npm.cmd ci --prefix frontend npm.cmd run build --prefix frontend |
构建包括 TypeScript 严格检查;依赖的 peer 兼容不等于页面行为正确,仍需浏览器上传、发布、评论与后台检查。截图保存在 docs/reports/screenshots;实际通过范围以验证报告为准。