Initial commit: Flutter 无书应用项目
This commit is contained in:
Developer
243
.trae/rules/design-rules.md
Normal file
243
.trae/rules/design-rules.md
Normal file
@@ -0,0 +1,243 @@
|
||||
---
|
||||
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 – 计划先行，安全重构
|
||||
|
||||
364
.trae/rules/layout-rules.md
Normal file
364
.trae/rules/layout-rules.md
Normal file
@@ -0,0 +1,364 @@
|
||||
---
|
||||
alwaysApply: false
|
||||
description:
|
||||
---
|
||||
页面必须是响应式布局，不允许任何元素溢出屏幕。
|
||||
|
||||
必须适配：
|
||||
- 手机
|
||||
- 平板
|
||||
- 桌面
|
||||
|
||||
布局要求：
|
||||
|
||||
1 所有元素使用 flex 或 grid 布局
|
||||
2 不允许使用固定宽度
|
||||
3 必须使用 max-width
|
||||
4 必须使用 box-sizing: border-box
|
||||
5 页面内容不能超出 viewport
|
||||
6 禁止 overflow-x
|
||||
|
||||
所有图片必须：
|
||||
max-width:100%
|
||||
height:auto
|
||||
object-fit:cover
|
||||
|
||||
页面内容必须考虑 header 高度，
|
||||
主体区域必须使用 padding-top。
|
||||
|
||||
主体区域必须允许垂直滚动
|
||||
overflow-y:auto
|
||||
|
||||
请编写一个现代前端页面。
|
||||
|
||||
要求：
|
||||
|
||||
1 页面必须是响应式布局
|
||||
2 所有屏幕尺寸必须适配
|
||||
3 不允许任何元素溢出屏幕
|
||||
4 必须使用 flex 或 grid 布局
|
||||
5 不允许使用固定宽度
|
||||
6 图片必须 max-width:100%
|
||||
7 页面必须适配手机、平板、桌面
|
||||
8 包含 media query (768px / 1024px)
|
||||
9 不允许出现 horizontal scroll
|
||||
10 所有组件必须保持在 viewport 内
|
||||
|
||||
代码必须通过 Chrome responsive mode 测试，
|
||||
确保不会出现 overflow 或布局错位。
|
||||
|
||||
所有页面必须有 container 容器
|
||||
max-width:1200px
|
||||
margin:auto
|
||||
padding:16px
|
||||
|
||||
推荐结构
|
||||
container
|
||||
header
|
||||
main
|
||||
section
|
||||
grid
|
||||
card
|
||||
foote
|
||||
|
||||
|
||||
| 你的规则 | 行业术语 | 说明 |
|
||||
| --------------------- | ---------------------------------- | ------ |
|
||||
| 所有元素用 flex/grid | **Modern Layout System** | 现代布局系统 |
|
||||
| 不使用固定宽度 | **Fluid Layout** | 流式布局 |
|
||||
| 使用 max-width | **Content Container Pattern** | 内容容器模式 |
|
||||
| box-sizing:border-box | **Universal Box Model Reset** | 盒模型重置 |
|
||||
| 不能超出 viewport | **Viewport Safe Layout** | 视口安全布局 |
|
||||
| 禁止 overflow-x | **Horizontal Overflow Prevention** | 防止横向滚动 |
|
||||
|
||||
Responsive Layout Best Practices
|
||||
Modern Responsive UI Architecture
|
||||
|
||||
| 你的说法 | 行业术语 | 说明 |
|
||||
| ---- | --------------------------------- | ------- |
|
||||
| 大屏 | **Large Screen / Desktop Layout** | 桌面显示器 |
|
||||
| 小屏 | **Mobile Layout** | 手机 |
|
||||
| 折叠屏 | **Foldable Layout** | 可折叠设备 |
|
||||
| 小窗 | **Windowed / Resizable Layout** | 浏览器窗口缩放 |
|
||||
|
||||
|
||||
Responsive Web Design (RWD)
|
||||
|
||||
过渡动画
|
||||
该页面必须实现响应式布局 (Responsive Layout)。
|
||||
|
||||
适配以下 viewport：
|
||||
|
||||
Mobile: 360px - 640px
|
||||
Tablet: 768px - 1024px
|
||||
Desktop: 1280px - 1920px
|
||||
Large Screen: >1920px
|
||||
|
||||
要求：
|
||||
|
||||
1 使用 flex 或 grid 布局
|
||||
2 不允许固定宽度
|
||||
3 使用 max-width 控制容器
|
||||
4 所有图片 max-width:100%
|
||||
5 页面禁止 horizontal overflow
|
||||
6 组件必须在小屏幕自动换行
|
||||
7 在小屏幕使用单列布局
|
||||
8 在大屏幕使用多列布局
|
||||
9 页面必须支持浏览器窗口缩放
|
||||
|
||||
页面必须支持 foldable devices。
|
||||
|
||||
当 viewport 在 600px - 900px 之间时：
|
||||
|
||||
1 自动切换为双列布局
|
||||
2 避免关键元素位于屏幕中央折叠区域
|
||||
3 内容必须允许重新流式排列
|
||||
|
||||
|
||||
页面必须支持 foldable devices。
|
||||
|
||||
当 viewport 在 600px - 900px 之间时：
|
||||
|
||||
1 自动切换为双列布局
|
||||
2 避免关键元素位于屏幕中央折叠区域
|
||||
3 内容必须允许重新流式排列
|
||||
|
||||
|
||||
布局必须遵循 mobile-safe 和 desktop-safe 的响应式设计原则。
|
||||
|
||||
生成一个现代响应式网页。
|
||||
|
||||
要求：
|
||||
|
||||
1 默认 viewport 为 desktop (1280px)
|
||||
2 页面必须支持 mobile、tablet、desktop
|
||||
3 使用 flex 或 grid 布局
|
||||
4 不允许固定宽度
|
||||
5 所有图片 max-width:100%
|
||||
6 不允许 horizontal overflow
|
||||
7 小屏幕自动单列布局
|
||||
8 大屏幕自动多列布局
|
||||
9 页面必须支持浏览器窗口缩放
|
||||
10 代码必须通过 Chrome responsive mode
|
||||
|
||||
|
||||
|
||||
先架构，后页面；先设计系统，后组件；先计划，后改代码。
|
||||
|
||||
🧠 一、AI 前端开发“终极总控 Prompt”
|
||||
|
||||
你以后可以直接复制这个作为基础模板：
|
||||
|
||||
你是资深前端架构师。
|
||||
|
||||
本项目必须遵循以下原则：
|
||||
|
||||
【架构优先】
|
||||
1. 先分析整体布局结构
|
||||
2. 先给出修改计划
|
||||
3. 再进行代码修改
|
||||
4. 禁止只修改局部组件而忽略整体布局
|
||||
|
||||
【布局规则】
|
||||
1. 使用 flex 或 grid
|
||||
2. 不允许固定宽度
|
||||
3. 必须使用 max-width 容器
|
||||
4. 所有元素 box-sizing: border-box
|
||||
5. 禁止 horizontal overflow
|
||||
6. 页面必须支持窗口缩放
|
||||
7. 小屏自动单列，大屏多列
|
||||
|
||||
【设计系统】
|
||||
必须遵循统一 design system：
|
||||
- 颜色
|
||||
- 字体
|
||||
- 间距
|
||||
- 圆角
|
||||
- 阴影
|
||||
- 按钮样式
|
||||
|
||||
【修改规则】
|
||||
如果需要改布局：
|
||||
必须重构整体 layout，
|
||||
不能只修改一个组件。
|
||||
🏗 二、标准项目结构（强烈推荐）
|
||||
|
||||
让 AI 按这个结构生成代码：
|
||||
|
||||
/src
|
||||
/layout
|
||||
/components
|
||||
/pages
|
||||
/styles
|
||||
/design-system
|
||||
|
||||
Prompt 加一句：
|
||||
|
||||
请按以下结构组织代码：
|
||||
layout / components / pages / styles。
|
||||
|
||||
这样多个 AI 写的代码天然统一。
|
||||
|
||||
🎨 三、统一风格（解决色调不一致）
|
||||
|
||||
多个 AI 最大问题是：
|
||||
|
||||
一个用蓝色
|
||||
|
||||
一个用紫色
|
||||
|
||||
一个按钮圆角不同
|
||||
|
||||
一个阴影不同
|
||||
|
||||
解决方法：强制使用设计系统。
|
||||
|
||||
Prompt 加：
|
||||
|
||||
所有页面必须使用统一设计系统变量，
|
||||
禁止自定义颜色。
|
||||
必须使用 CSS 变量或主题系统。
|
||||
|
||||
例如：
|
||||
|
||||
:root {
|
||||
--primary: #2563eb;
|
||||
--background: #f8fafc;
|
||||
--text: #0f172a;
|
||||
}
|
||||
📱 四、响应式统一规则模板
|
||||
|
||||
如果页面需要适配：
|
||||
|
||||
移动端 + 平板 + 桌面
|
||||
|
||||
加这段：
|
||||
|
||||
必须使用响应式设计。
|
||||
|
||||
断点：
|
||||
- 640px
|
||||
- 768px
|
||||
- 1024px
|
||||
- 1280px
|
||||
|
||||
小屏幕：单列布局
|
||||
中屏幕：双列布局
|
||||
大屏幕：多列布局
|
||||
🪟 五、桌面专用页面模板
|
||||
|
||||
如果某些页面 不需要响应式：
|
||||
|
||||
该页面为 Desktop-only。
|
||||
|
||||
设计基准：1280px。
|
||||
|
||||
不需要 mobile 适配。
|
||||
不需要 media query。
|
||||
|
||||
这样 AI 不会乱写。
|
||||
|
||||
🔄 六、防止 AI 只改局部的“强制整体重构模板”
|
||||
|
||||
这是你刚才说的核心问题。
|
||||
|
||||
用这个：
|
||||
|
||||
如果需要修改布局：
|
||||
|
||||
1. 先分析当前整个页面结构
|
||||
2. 输出完整布局结构图
|
||||
3. 制定整体重构方案
|
||||
4. 然后一次性修改所有相关区域
|
||||
5. 禁止只修改单个组件
|
||||
|
||||
这句话非常关键。
|
||||
|
||||
🧩 七、强制布局骨架（最稳定方式）
|
||||
|
||||
让 AI 必须使用这种结构：
|
||||
|
||||
App
|
||||
├ Header
|
||||
├ Sidebar
|
||||
├ Main
|
||||
└ Footer
|
||||
|
||||
Prompt：
|
||||
|
||||
页面必须采用标准 App Layout 结构。
|
||||
main 区域负责滚动。
|
||||
header 和 sidebar 为固定结构。
|
||||
🛑 八、禁止错误写法（必须写）
|
||||
禁止：
|
||||
- position: absolute 进行整体布局
|
||||
- 固定 px 宽度
|
||||
- overflow:hidden 用于解决布局问题
|
||||
- 使用 margin 负值修复结构
|
||||
🧱 九、AI 写页面的标准流程（最重要）
|
||||
|
||||
以后让 AI 改布局，一定这样写：
|
||||
|
||||
步骤：
|
||||
|
||||
1. 分析当前布局
|
||||
2. 给出修改计划
|
||||
3. 等我确认
|
||||
4. 再修改代码
|
||||
|
||||
这样可以避免：
|
||||
|
||||
无限循环改局部
|
||||
|
||||
进度为 0
|
||||
|
||||
越改越乱
|
||||
|
||||
🚀 十、真正专业团队的做法
|
||||
|
||||
大型团队通常会：
|
||||
|
||||
1️⃣ 先写 Design System
|
||||
2️⃣ 再写 Layout System
|
||||
3️⃣ 再写 Component Library
|
||||
4️⃣ 最后写 Pages
|
||||
|
||||
AI 也必须按这个顺序。
|
||||
|
||||
💎 十一、终极万能 Prompt（推荐收藏）
|
||||
|
||||
你可以直接用这个：
|
||||
|
||||
请作为高级前端架构师开发页面。
|
||||
|
||||
要求：
|
||||
|
||||
- 优先设计整体布局结构
|
||||
- 使用 flex/grid
|
||||
- 响应式设计
|
||||
- 使用统一设计系统
|
||||
- 不允许固定宽度
|
||||
- 不允许 horizontal overflow
|
||||
- 修改布局时必须整体重构
|
||||
- 不允许只改局部组件
|
||||
- 输出清晰结构
|
||||
- 代码必须可维护
|
||||
🎯 最后总结
|
||||
|
||||
解决你所有问题的核心只有三句话：
|
||||
|
||||
Layout First
|
||||
Design System First
|
||||
Plan Before Code
|
||||
|
||||
只要做到这三点：
|
||||
|
||||
不会溢出
|
||||
|
||||
不会错位
|
||||
|
||||
不会风格混乱
|
||||
|
||||
不会局部修改失控
|
||||
|
||||
多 AI 开发也能统一
|
||||
Reference in New Issue
Block a user