---
alwaysApply: false
description: 
---
1. 设计系统 (Design System)
所有页面必须基于统一的设计令牌，禁止硬编码颜色、间距、圆角等。

设计变量 (CSS Variables)
css
:root {
  /* 颜色 */
  --primary: #;      /* 主色 */
  --secondary: #;    /* 辅助色 */
  --background: #;   /* 背景 */
  --text: #;         /* 正文 */

  /* 字体 */
  --font-family: 'Inter', system-ui, sans-serif;

  /* 间距 (4的倍数) */
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 16px;
  --space-4: 24px;
  --space-5: 32px;



  /* 圆角 */
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-lg: 12px;

  /* 阴影 */
  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
}
统一风格要求
颜色以 黑白灰、蓝白 为主，保持简洁。

可适当使用毛玻璃效果（backdrop-filter: blur()）增强层次感。

圆角统一使用上述变量，避免零散定义。

尽量使用 emoji 提升界面亲和力（如 👍 表示点赞）。

2. 布局规范 (Layout Guidelines)
所有页面必须遵循响应式设计，确保在手机、平板、桌面及折叠屏上均无溢出、无横向滚动。

核心原则
使用 Flexbox 或 Grid 布局，禁止固定宽度。

容器必须设置 max-width（如 1200px）配合 margin: auto 居中。

全局设置 box-sizing: border-box。

禁止出现 overflow-x（除非必要且可控）。

图片：max-width: 100%; height: auto; object-fit: cover。

响应式断点
设备	视口宽度范围	布局策略
手机	360px – 640px	单列
平板	768px – 1024px	双列
桌面	1280px – 1920px	多列
大屏	>1920px	保持多列，容器居中
css
.container {
  max-width: 1200px;
  margin: 0 auto;
  padding: var(--space-3);
}

/* 平板及以上 */
@media (min-width: 768px) {
  .grid {
    display: grid;
    grid-template-columns: repeat(2, 1fr);
    gap: var(--space-4);
  }
}

@media (min-width: 1024px) {
  .grid {
    grid-template-columns: repeat(3, 1fr);
  }
}
折叠屏适配 (600px – 900px)
自动切换双列布局。

避免关键内容置于屏幕中央折痕区域。

内容可重新流式排列（利用 order 或网格调整）。

页面骨架
html
<AppLayout>
  <Header />
  <Main> <!-- 可滚动区域，padding-top 避开固定 header -->
    <Container>
      <PageContent />
    </Container>
  </Main>
  <Footer />
</AppLayout>
Main 区域设置 overflow-y: auto，确保内部滚动。

所有页面必须使用统一 AppLayout 组件，禁止各自实现布局。

3. 组件与代码结构
项目目录结构
text
src/
├── layout/          # 布局组件 (AppLayout, Header, Footer)
├── components/      # 可复用UI组件 (Button, Card, Modal)
├── pages/           # 页面级组件
├── styles/          # 全局样式、设计令牌
├── services/        # API请求
├── hooks/           # 自定义逻辑
└── utils/           # 工具函数
编码规范
禁止：position: absolute 做整体布局、固定 px 宽度、使用负 margin 修补结构。

函数拆分：单一职责，每个函数不超过 30 行。

变量命名：语义化，如 isLiked 而非 flag。

删除重复代码：提取公共逻辑到 hooks 或 utils。

日志：关键操作（如点赞、API调用）添加 console.log 便于追踪，上线前可移除。

4. API 设计规范
接口地址：/pms.php (支持 GET/POST)

参数说明
参数	类型	必填	说明
lid	int	否	点赞ID（存在时直接对该站点点赞/取消点赞，忽略其他参数）
id	int	否	站点ID，获取指定信息
like	flag	否	无值参数，表示对本次返回的站点执行点赞/取消点赞
dyn	string	否	朝代（英文逗号分隔，如 宋代,唐代）
tag	string	否	标签（英文逗号分隔，如 友情,柳树）
优先级：lid > id > 随机推荐。

返回格式
json
{
  "code": 0,          // 0成功，非0失败
  "msg": "success",   // 提示信息
  "data": { ... }     // 站点完整信息（含浏览次数、点赞数等）
}
重要：只要成功返回 data，该站点的日、月、总浏览次数自动 +1。

注意事项
朝代对应数据库字段 alias，标签对应 keywords。

点赞/取消点赞基于 IP 限制，同一 IP 可切换状态。

频率限制：每个 IP 每秒最多 2 次，超出返回 429。

5. 功能开发与测试（以点赞为例）
点赞逻辑核心要点
状态计算：使用新状态变量，避免旧状态干扰。

javascript
const newLikedState = !this.data.isLiked;
// 先计算新状态，再更新UI和存储
存储结构：本地存储 likedPoetry 为数组，包含诗词完整信息及 savedTime。

状态同步：页面加载时检查当前诗词是否已收藏（checkIfLiked）。

测试步骤
首页加载 → 点击点赞 → 按钮变为“取消点赞”，诗词存入收藏。

进入收藏页 → 能看到刚点赞的诗词。

返回首页 → 点赞状态保持为“取消点赞”。

点击取消点赞 → 按钮变回“点赞”，收藏页中该诗词消失。

重复上述步骤，确保状态切换正确，无重复提示。

6. AI协作规范
当使用AI辅助开发时，遵循以下指令模板可大幅提升产出质量：

总控 Prompt
text
你是资深前端架构师。本项目必须遵循：
1. 架构优先：先分析整体布局，再给出修改计划，最后修改代码。
2. 布局规则：flex/grid，无固定宽度，max-width容器，禁止横向溢出，响应式。
3. 设计系统：必须使用统一CSS变量，禁止自定义颜色。
4. 修改规则：如要改布局，必须整体重构，禁止只改局部组件。
5. 代码结构：按 layout / components / pages / styles 组织。
安全重构流程
分析当前结构 → 2. 输出修改计划 → 3. 等待确认 → 4. 执行修改

禁止事项
使用 overflow:hidden 解决布局问题。

直接修改入口文件（应只保留路由、Provider、样式引入）。

一次性改动过多文件（应分阶段：设计变量 → 布局容器 → 组件统一）。

7. 存量项目接入设计系统（安全策略）
若项目已上线，采用渐进式重构，避免大规模报错：

阶段1：添加 design-tokens.css，只定义变量，不修改任何页面。

阶段2：创建统一 AppLayout 组件，新页面强制使用，旧页面逐步包裹。

阶段3：建立 /dev-theme-test 页面，集中测试所有组件样式。

阶段4：按页面逐一迁移，不动业务逻辑。

核心思想：先视觉统一，再结构统一；不动业务，只换皮肤。

8. 性能优化与日志
拆分函数：避免过大的 Page 对象，逻辑抽离到独立模块。

减少冗余：使用 wx.setStorageSync 缓存必要数据，避免重复请求。

日志分级：

console.info 记录关键流程（如点赞成功）。

console.warn 记录异常但不影响使用。

console.error 记录错误，并考虑上报。

README更新：每次功能迭代后同步更新文档，包括接口变更、存储字段说明。

9. 通用建议
页面路径：新增页面必须在 app.json 中声明。

UI细节：按钮、卡片等组件统一圆角、阴影，营造精致感。

代码提交：遵循 type(scope): subject 格式，如 feat(like): 修复点赞状态反转问题。

核心三句话
Layout First – 布局决定体验
Design System First – 变量统一风格
Plan Before Code – 计划先行，安全重构