first commit

MeetSpot/postmortem/PM-2025-001.yaml

@@ -0,0 +1,42 @@
+id: PM-2025-001
+created_at: '2026-01-13T05:56:50.491275Z'
+source_commit: bb5c8b0
+severity: high
+title: 限制缓存大小以防止免费层内存溢出
+description: 在免费层环境中，因缓存未限制大小导致内存溢出，触发 Render 512MB 内存限制错误，影响服务稳定性。
+root_cause: Geocode 和 POI 缓存未设置大小限制，导致缓存无限增长，最终耗尽内存。
+triggers:
+  files:
+  - app/tool/*.py
+  functions:
+  - CafeRecommender.geocode_cache
+  - CafeRecommender.poi_cache
+  patterns:
+  - geocode_cache
+  - poi_cache
+  - Field\(default_factory=dict\)
+  keywords:
+  - 缓存
+  - cache
+  - memory
+  - OOM
+  - 内存溢出
+fix_pattern:
+  approach: 为缓存添加大小限制，并在超限时采用 FIFO 策略逐出最旧条目。
+  key_changes:
+  - 添加 GEOCODE_CACHE_MAX 和 POI_CACHE_MAX 常量，分别限制缓存大小为 100 和 50。
+  - 在 geocode_cache 和 poi_cache 写入逻辑中添加 FIFO 驱逐逻辑。
+verification:
+- 验证 geocode_cache 和 poi_cache 的大小是否符合限制。
+- 检查 FIFO 驱逐逻辑是否正确执行。
+- 在内存受限环境中运行服务，确保不会触发 OOM 错误。
+- 测试缓存命中率是否符合预期，避免过多 API 调用。
+related:
+  files_changed:
+  - app/tool/meetspot_recommender.py
+tags:
+- geocoding
+- memory
+- cache
+- performance
+- api

MeetSpot/postmortem/PM-2025-002.yaml

@@ -0,0 +1,35 @@
+id: PM-2025-002
+created_at: '2026-01-13T05:56:55.380581Z'
+source_commit: 4d12fbe
+severity: medium
+title: 推荐系统搜索半径扩大至50公里以解决无结果问题
+description: 在推荐系统中，当使用fallback策略搜索地点无结果时，搜索半径被扩大至50公里（API最大值），以确保获取更多结果。此变更影响了推荐系统的搜索范围。
+root_cause: 原有的搜索半径限制导致在某些情况下无法获取足够的推荐结果。
+triggers:
+  files:
+  - app/tool/*.py
+  functions:
+  - _search_pois
+  patterns:
+  - radius=10000
+  - radius=50000
+  keywords:
+  - fallback
+  - 搜索半径
+  - API最大
+fix_pattern:
+  approach: 将搜索半径从10公里扩大到50公里以获取更多结果。
+  key_changes:
+  - radius=10000
+  - radius=50000
+verification:
+- 验证在扩大搜索半径后，推荐系统能够返回更多的结果。
+- 确保API调用在50公里半径下正常工作。
+- 检查日志信息是否正确反映搜索半径的变化。
+related:
+  files_changed:
+  - app/tool/meetspot_recommender.py
+tags:
+- recommender
+- api
+- search radius

MeetSpot/postmortem/PM-2025-003.yaml

@@ -0,0 +1,36 @@
+id: PM-2025-003
+created_at: '2026-01-13T05:56:59.697193Z'
+source_commit: 3ba4b1d
+severity: high
+title: 修复地理编码跨城市歧义问题，提升演示可靠性
+description: 在地理编码过程中，某些地标名称可能导致跨城市的歧义，影响系统的准确性和演示的可靠性。此次修复通过添加地标映射解决了这一问题。
+root_cause: 缺乏对常见地标的明确城市映射，导致地理编码结果不准确。
+triggers:
+  files:
+  - app/tool/*.py
+  functions:
+  - _get_address
+  patterns:
+  - landmark_mapping\s*=\s*\{
+  keywords:
+  - geocoding
+  - landmark
+  - ambiguity
+  - 城市歧义
+fix_pattern:
+  approach: 通过添加45个以上的地标映射，确保地标名称能够正确解析到对应的城市。
+  key_changes:
+  - 新增 landmark_mapping 字典
+  - 在 _get_address 函数中增加地标映射逻辑
+verification:
+- 验证地标名称是否正确映射到对应城市
+- 检查新增地标映射是否覆盖主要城市的常见地标
+- 确保地理编码结果在演示中表现良好
+related:
+  files_changed:
+  - app/tool/meetspot_recommender.py
+tags:
+- geocoding
+- data-mapping
+- 城市歧义
+- demo-reliability

MeetSpot/postmortem/PM-2025-004.yaml

@@ -0,0 +1,45 @@
+id: PM-2025-004
+created_at: '2026-01-13T05:57:03.601645Z'
+source_commit: a97fad3
+severity: medium
+title: 修复非合成动画以通过 Lighthouse 审核
+description: 移除了使用 width 属性的非 GPU 加速动画，解决了 Lighthouse 中的非合成动画审核失败问题。此问题可能导致页面性能下降，影响用户体验。
+root_cause: 部分动画使用了 width 和 box-shadow 等非 GPU 加速属性，导致 Lighthouse 审核失败。
+triggers:
+  files:
+  - docs/*.md
+  - templates/pages/*.html
+  - image*.png
+  - '*.png'
+  functions: []
+  patterns:
+  - .*width.*
+  - .*box-shadow.*
+  keywords:
+  - non-composited animations
+  - Lighthouse
+  - GPU acceleration
+  - transform
+  - opacity
+fix_pattern:
+  approach: 移除非 GPU 加速的动画属性，确保所有动画仅使用 transform 和 opacity。
+  key_changes:
+  - 移除了 slideProgress 和 typewriter 动画的 keyframes
+  - '将 pulseGlow 动画的 box-shadow 替换为 transform: scale()'
+verification:
+- 检查所有动画是否仅使用 transform 和 opacity 属性
+- 运行 Lighthouse 审核，确保通过非合成动画检查
+- 验证页面性能是否提升
+related:
+  files_changed:
+  - '"docs/\347\216\260\345\234\272\345\261\225\346\274\224\350\257\235\346\234\257.md"'
+  - image copy 2.png
+  - image copy.png
+  - image.png
+  - templates/pages/home.html
+  - '"\347\272\277\344\270\213\350\201\232\344\274\232\346\225\260\346\215\256.png"'
+tags:
+- ui
+- performance
+- animation
+- Lighthouse

MeetSpot/postmortem/PM-2025-005.yaml

@@ -0,0 +1,43 @@
+id: PM-2025-005
+created_at: '2026-01-13T05:57:06.915651Z'
+source_commit: b8b64fa
+severity: high
+title: 修复 Render 部署环境变量读取问题
+description: 在 Render 部署时，LLM 的环境变量未正确读取，导致无法生成 LLM 传输提示，影响智能推荐功能。
+root_cause: 代码未优先读取环境变量 LLM_API_BASE 和 LLM_MODEL，导致配置错误。
+triggers:
+  files:
+  - app/config.py
+  - app/tool/*.py
+  functions:
+  - Config.__init__
+  - _get_llm
+  patterns:
+  - os.getenv\("LLM_API_BASE"
+  - os.getenv\("LLM_MODEL"
+  keywords:
+  - LLM_API_BASE
+  - LLM_MODEL
+  - Render
+  - 环境变量
+fix_pattern:
+  approach: 优先从环境变量读取 LLM 配置，并在初始化时验证 API Key 的有效性。
+  key_changes:
+  - 在 config.py 中添加对 LLM_API_BASE 和 LLM_MODEL 环境变量的支持。
+  - 调整 _get_llm 函数，增加 API Key 验证逻辑。
+  - 添加 LLM 初始化状态的日志记录。
+verification:
+- 确保环境变量 LLM_API_BASE 和 LLM_MODEL 被正确读取。
+- 验证 _get_llm 函数是否正确初始化 LLM 实例。
+- 检查日志是否记录 LLM 初始化状态。
+- 测试在 Render 部署环境下是否生成 LLM 传输提示。
+related:
+  files_changed:
+  - app/config.py
+  - app/tool/meetspot_recommender.py
+tags:
+- llm
+- api
+- environment
+- render
+- deployment

MeetSpot/postmortem/PM-2025-006.yaml

@@ -0,0 +1,36 @@
+id: PM-2025-006
+created_at: '2026-01-13T05:57:10.607031Z'
+source_commit: b6831e5
+severity: medium
+title: 地图标记添加位置名称标签修复
+description: 地图标记未显示位置名称标签，导致用户无法直观识别标记位置。此问题影响用户体验，尤其是在多个标记密集的情况下。
+root_cause: 地图标记未包含位置名称标签的渲染逻辑。
+triggers:
+  files:
+  - app/tool/*.py
+  functions:
+  - CafeRecommender
+  patterns:
+  - 'markerContent = `<div style="background-color: \${{color}};'
+  keywords:
+  - map
+  - marker
+  - label
+  - 位置名称
+fix_pattern:
+  approach: 为地图标记添加位置名称标签，并调整样式以提高可读性。
+  key_changes:
+  - 为中心点和用户位置标记添加标签显示逻辑
+  - 调整标签样式，包括背景色、阴影和字体
+verification:
+- 检查地图标记是否正确显示位置名称标签
+- 验证标签样式是否符合设计规范
+- 确保其他标记（如场所标记）未受影响
+related:
+  files_changed:
+  - app/tool/meetspot_recommender.py
+tags:
+- ui
+- map
+- label
+- user experience

MeetSpot/postmortem/PM-2025-007.yaml

@@ -0,0 +1,42 @@
+id: PM-2025-007
+created_at: '2026-01-13T05:57:14.136672Z'
+source_commit: defe545
+severity: medium
+title: 修复重复加载指示器并添加 Agent 品牌标识
+description: 在加载过程中出现重复的加载指示器（“两个圈”），影响用户体验。问题还涉及品牌标识未正确显示。
+root_cause: Toast 通知与内联加载指示器同时显示，导致重复加载动画；加载文本未包含品牌标识。
+triggers:
+  files:
+  - public/meetspot_finder.html
+  functions:
+  - renderLoadingIndicator
+  - updateLoadingMessage
+  patterns:
+  - \bloading\b
+  - \bspinner\b
+  - \btoast\b
+  keywords:
+  - loading indicator
+  - spinner
+  - toast notification
+  - Agent branding
+fix_pattern:
+  approach: 移除重复的加载指示器，保留内联加载动画，并更新加载文本以动态显示品牌标识和搜索关键词。
+  key_changes:
+  - 移除 toast 通知加载动画
+  - 保留内联加载指示器
+  - 更新加载文本以包含 Agent 品牌标识
+  - 动态显示加载消息中的搜索关键词
+verification:
+- 确保加载过程中仅显示一个加载指示器
+- 检查加载文本是否正确显示 Agent 品牌标识
+- 验证动态加载消息是否包含搜索关键词
+- 确认用户界面在加载时无视觉冲突
+related:
+  files_changed:
+  - public/meetspot_finder.html
+tags:
+- ui
+- branding
+- loading
+- ux

MeetSpot/postmortem/PM-2025-008.yaml

@@ -0,0 +1,41 @@
+id: PM-2025-008
+created_at: '2026-01-13T05:57:18.566066Z'
+source_commit: 0843bfd
+severity: medium
+title: LLM交通建议超时保护修复
+description: 在生成交通与停车建议时，因未设置超时导致请求超时，影响用户体验。修复后添加了15秒超时保护，避免Render 30秒请求超时。
+root_cause: 缺少超时保护导致请求在30秒后超时。
+triggers:
+  files:
+  - app/tool/*.py
+  functions:
+  - _llm_generate_transport_tips
+  - _generate_default_transport_tips
+  patterns:
+  - asyncio.wait_for
+  - asyncio.TimeoutError
+  keywords:
+  - 超时
+  - timeout
+  - LLM
+  - 交通建议
+  - transport tips
+fix_pattern:
+  approach: 添加15秒超时保护，并在超时时使用默认建议。
+  key_changes:
+  - 使用asyncio.wait_for设置15秒超时
+  - 在超时时捕获asyncio.TimeoutError异常
+  - 记录超时警告日志
+  - 调用_generate_default_transport_tips提供默认建议
+verification:
+- 检查是否在15秒内返回交通建议
+- 验证超时时是否使用默认建议
+- 确认超时警告日志是否记录
+related:
+  files_changed:
+  - app/tool/meetspot_recommender.py
+tags:
+- timeout
+- LLM
+- transport
+- asyncio

MeetSpot/postmortem/PM-2025-009.yaml

@@ -0,0 +1,36 @@
+id: PM-2025-009
+created_at: '2026-01-13T05:57:21.963815Z'
+source_commit: cb1784c
+severity: high
+title: 修复SEO缓存问题以解决Render冷启动问题
+description: 由于Render冷启动导致Google Search Console出现“Couldn't fetch”错误，影响了网站的SEO表现。通过扩展sitemap和robots的缓存策略解决了该问题。
+root_cause: sitemap.xml和robots.txt的缓存时间过短，导致在Render冷启动时无法及时响应搜索引擎爬虫请求。
+triggers:
+  files:
+  - api/index.py
+  functions:
+  - add_cache_headers
+  patterns:
+  - max-age=3600
+  - max-age=86400, stale-while-revalidate=604800
+  keywords:
+  - sitemap.xml
+  - robots.txt
+  - Cache-Control
+  - cold start
+fix_pattern:
+  approach: 增加缓存时间并添加stale-while-revalidate策略以确保在冷启动时仍能提供缓存内容。
+  key_changes:
+  - max-age从3600秒增加到86400秒
+  - 添加stale-while-revalidate=604800
+verification:
+- 确认sitemap.xml和robots.txt的Cache-Control头包含正确的max-age和stale-while-revalidate值
+- 使用Google Search Console验证爬虫是否能够正常获取sitemap和robots文件
+- 模拟Render冷启动环境，确保缓存策略有效
+related:
+  files_changed:
+  - api/index.py
+tags:
+- seo
+- cache
+- api

MeetSpot/postmortem/PM-2025-010.yaml

@@ -0,0 +1,49 @@
+id: PM-2025-010
+created_at: '2026-01-13T05:57:29.616214Z'
+source_commit: 9ebaacf
+severity: high
+title: 修复 Google Search Console 抓取超时问题
+description: 由于 Render 冷启动导致 Google 爬虫超时，出现 GSC 'Couldn't fetch' 错误，影响了网站的 SEO 表现。
+root_cause: Render 冷启动导致响应时间过长，Google 爬虫无法及时获取 sitemap 和 robots.txt。
+triggers:
+  files:
+  - api/routers/seo_pages.py
+  - .github/workflows/keep-alive.yml
+  functions:
+  - sitemap
+  - robots_txt
+  patterns:
+  - .*sitemap.*
+  - .*robots\.txt.*
+  - .*Cache-Control.*
+  - .*stale-while-revalidate.*
+  keywords:
+  - sitemap
+  - robots.txt
+  - Cache-Control
+  - stale-while-revalidate
+  - Googlebot
+  - Render cold start
+fix_pattern:
+  approach: 通过增加缓存策略、提高 keep-alive 频率以及模拟 Googlebot 爬虫访问来解决冷启动问题。
+  key_changes:
+  - 为 sitemap.xml 和 robots.txt 添加长时间缓存策略（max-age=86400, stale-while-revalidate=604800）
+  - 提高 keep-alive 频率从 10 分钟到 5 分钟
+  - 为冷启动响应添加 --max-time 30 超时限制
+  - 模拟 Googlebot 爬虫访问以验证抓取可用性
+verification:
+- 检查 sitemap.xml 和 robots.txt 是否正确设置了 Cache-Control 头
+- 验证 Cloudflare CDN 是否在冷启动期间提供缓存内容
+- 通过 Google Search Console 验证爬虫抓取是否正常
+- 模拟 Googlebot 爬虫访问，确保返回有效响应
+- 检查 keep-alive 机制是否按预期运行
+related:
+  files_changed:
+  - .github/workflows/keep-alive.yml
+  - api/routers/seo_pages.py
+tags:
+- seo
+- api
+- performance
+- googlebot
+- cache

MeetSpot/postmortem/PM-2025-011.yaml

@@ -0,0 +1,39 @@
+id: PM-2025-011
+created_at: '2026-01-13T05:57:33.139741Z'
+source_commit: 2456df8
+severity: high
+title: 修复SEO问题：添加/sitemap.xml和/robots.txt显式路由
+description: 由于StaticFiles挂载路径问题，Google Search Console报告“无法读取站点地图”。此问题影响了搜索引擎对网站的抓取和索引。
+root_cause: sitemap.xml和robots.txt文件路径不正确，导致搜索引擎无法访问。
+triggers:
+  files:
+  - api/index.py
+  - public/sitemap.xml
+  functions:
+  - sitemap
+  - robots
+  patterns:
+  - '@app.api_route\("/sitemap.xml"'
+  - '@app.api_route\("/robots.txt"'
+  keywords:
+  - sitemap
+  - robots.txt
+  - SEO
+  - StaticFiles
+fix_pattern:
+  approach: 添加显式路由以正确提供sitemap.xml和robots.txt文件，并设置适当的HTTP头。
+  key_changes:
+  - 在api/index.py中添加/sitemap.xml和/robots.txt路由
+  - 为sitemap.xml和robots.txt设置正确的Content-Type头
+verification:
+- 确保/sitemap.xml和/robots.txt路由返回正确的文件内容
+- 验证Google Search Console中不再出现“无法读取站点地图”错误
+- 检查sitemap.xml的lastmod日期是否更新
+related:
+  files_changed:
+  - api/index.py
+  - public/sitemap.xml
+tags:
+- SEO
+- api
+- routing

MeetSpot/postmortem/PM-2025-012.yaml

@@ -0,0 +1,44 @@
+id: PM-2025-012
+created_at: '2026-01-13T05:57:38.272426Z'
+source_commit: bc3efc7
+severity: medium
+title: 修复UI距离选项和重定向路径问题
+description: 在应用中，距离选项更新为5/10/20/30/50公里，并修复了重定向和资源路径问题。这些问题可能导致用户体验不佳和资源加载失败。
+root_cause: 原始代码中距离选项设置不合理，且重定向和资源路径配置错误。
+triggers:
+  files:
+  - app/tool/*.py
+  - public/*.html
+  functions:
+  - CafeRecommender
+  patterns:
+  - href="/css/
+  - href="/public/meetspot_finder.html"
+  - src="/js/
+  keywords:
+  - distance options
+  - redirect
+  - asset paths
+  - window.location.href
+fix_pattern:
+  approach: 更新距离选项，修正重定向方式和资源路径。
+  key_changes:
+  - 距离选项更新为5/10/20/30/50公里
+  - 大城市默认距离设置为10公里
+  - 使用window.location.href替代window.open
+  - 返回链接指向根目录
+  - 更新CSS和JS资源路径
+verification:
+- 验证距离选项是否正确显示
+- 检查重定向是否正常工作
+- 确认资源路径是否正确加载
+- 确保返回链接指向正确页面
+related:
+  files_changed:
+  - app/tool/meetspot_recommender.py
+  - public/meetspot_finder.html
+tags:
+- ui
+- redirect
+- resource paths
+- distance options

MeetSpot/postmortem/PM-2025-013.yaml

@@ -0,0 +1,38 @@
+id: PM-2025-013
+created_at: '2026-01-13T05:57:42.048224Z'
+source_commit: 384bf6f
+severity: high
+title: 修复环境变量加载问题，确保AI聊天机器人正常运行
+description: AI聊天机器人显示“配置中”，因为未能加载.env文件中的环境变量，影响了关键配置的使用。
+root_cause: .env文件中的环境变量未被正确加载，导致配置缺失。
+triggers:
+  files:
+  - api/*.py
+  - web_server.py
+  functions:
+  - main
+  patterns:
+  - load_dotenv\(\)
+  keywords:
+  - .env
+  - 环境变量
+  - python-dotenv
+  - 配置中
+fix_pattern:
+  approach: 使用python-dotenv库加载.env文件中的环境变量。
+  key_changes:
+  - 在api/index.py和web_server.py中添加load_dotenv()调用
+verification:
+- 确保.env文件中的所有关键环境变量都被正确加载。
+- 验证AI聊天机器人不再显示“配置中”状态。
+- 检查python-dotenv库是否在requirements.txt中正确列出。
+related:
+  files_changed:
+  - api/index.py
+  - requirements.txt
+  - web_server.py
+tags:
+- environment
+- configuration
+- api
+- chatbot

MeetSpot/postmortem/PM-2025-014.yaml

@@ -0,0 +1,38 @@
+id: PM-2025-014
+created_at: '2026-01-13T05:57:45.466710Z'
+source_commit: 5d694dc
+severity: high
+title: 修复 sitemap.xml 和 robots.txt 的 HEAD 请求支持
+description: Google Search Console 报告 sitemap.xml 无法获取，原因是 HEAD 请求返回 405 Method Not
+  Allowed，影响搜索引擎爬虫的文件访问检查。
+root_cause: sitemap.xml 和 robots.txt 的 API 路由未支持 HEAD 请求，导致爬虫无法验证文件可访问性。
+triggers:
+  files:
+  - api/routers/seo_pages.py
+  functions:
+  - sitemap
+  - robots_txt
+  patterns:
+  - '@router.api_route\(.*methods=\[.*HEAD.*\]\)'
+  keywords:
+  - HEAD method
+  - sitemap.xml
+  - robots.txt
+  - Google Search Console
+fix_pattern:
+  approach: 为 sitemap.xml 和 robots.txt 的 API 路由添加 HEAD 请求支持。
+  key_changes:
+  - 将 @router.get 替换为 @router.api_route，并添加 methods=["GET", "HEAD"] 参数。
+  - 确保 HEAD 请求返回正确的 HTTP 状态码和响应头。
+verification:
+- 验证 sitemap.xml 和 robots.txt 的 HEAD 请求是否返回 200 状态码。
+- 检查 HEAD 请求是否正确返回 Content-Type 和其他必要的响应头。
+- 通过 Google Search Console 确认问题已解决，文件可正常访问。
+related:
+  files_changed:
+  - api/routers/seo_pages.py
+tags:
+- seo
+- api
+- crawler
+- google

MeetSpot/postmortem/PM-2025-015.yaml

@@ -0,0 +1,41 @@
+id: PM-2025-015
+created_at: '2026-01-13T05:57:50.946672Z'
+source_commit: c13279a
+severity: high
+title: 智能城市推断修复简短地名解析错误
+description: 用户输入简短地名时，地理编码错误地解析到错误城市，导致中心点计算错误和POI搜索失败，前端显示数据处理异常。
+root_cause: 高德API将简短地名解析到错误城市，未能正确识别用户意图。
+triggers:
+  files:
+  - app/tool/*.py
+  - public/*.html
+  functions:
+  - _geocode
+  - _smart_city_inference
+  patterns:
+  - geocode_result
+  - geocode_results
+  keywords:
+  - 智能城市推断
+  - geocode
+  - 解析错误
+fix_pattern:
+  approach: 通过智能城市推断功能检测并纠正错误的城市解析，前端处理无结果的成功搜索。
+  key_changes:
+  - 添加智能城市推断功能
+  - 前端处理无结果的成功搜索
+  - 更新文档说明
+verification:
+- 验证简短地名能正确解析到预期城市
+- 检查中心点坐标计算是否正确
+- 确认前端显示友好的无结果提示
+related:
+  files_changed:
+  - CLAUDE.md
+  - app/tool/meetspot_recommender.py
+  - public/meetspot_finder.html
+tags:
+- geocoding
+- ui
+- api
+- error-handling

MeetSpot/postmortem/PM-2025-016.yaml

@@ -0,0 +1,50 @@
+id: PM-2025-016
+created_at: '2026-01-13T05:57:54.839321Z'
+source_commit: 9c847c1
+severity: medium
+title: 网站内容优化修复，提升用户体验
+description: 修正了网站内容，使其更具用户友好性，移除了技术性术语并扩展了FAQ页面。影响用户对网站功能的理解和使用体验。
+root_cause: 网站内容过于技术化，影响用户体验和理解。
+triggers:
+  files:
+  - api/routers/seo_pages.py
+  - templates/pages/about.html
+  - templates/pages/faq.html
+  - templates/pages/home.html
+  - templates/pages/how_it_works.html
+  functions:
+  - faq_page
+  patterns:
+  - 移除技术性内容
+  - 扩展至10个实用问题
+  - 重写为用户导向内容
+  - 四步骤卡片式布局
+  keywords:
+  - 用户体验
+  - 技术术语
+  - FAQ
+  - 内容优化
+fix_pattern:
+  approach: 通过参考README优化网站内容，移除技术性术语，增加用户友好描述和实用问题。
+  key_changes:
+  - 首页内容优化
+  - FAQ页面扩展
+  - 关于页面重写
+  - 使用指南布局调整
+verification:
+- 检查首页是否移除技术术语
+- 确认FAQ页面包含10个问题
+- 确保关于页面内容用户导向
+- 验证使用指南布局是否为卡片式
+related:
+  files_changed:
+  - api/routers/seo_pages.py
+  - templates/pages/about.html
+  - templates/pages/faq.html
+  - templates/pages/home.html
+  - templates/pages/how_it_works.html
+tags:
+- content
+- ui
+- user_experience
+- documentation

MeetSpot/postmortem/PM-2025-017.yaml

@@ -0,0 +1,34 @@
+id: PM-2025-017
+created_at: '2026-01-13T05:57:58.465498Z'
+source_commit: 19f9e93
+severity: medium
+title: 修复变量命名冲突导致的flake8 F823错误
+description: 在meetspot_recommender.py中，变量命名冲突导致flake8 F823错误，影响GitHub Actions CI的正常运行。
+root_cause: 局部变量名与导入模块名冲突，导致变量在赋值前被引用。
+triggers:
+  files:
+  - app/tool/*.py
+  functions:
+  - CafeRecommender
+  patterns:
+  - local variable 'html' referenced before assignment
+  keywords:
+  - flake8
+  - F823
+  - 命名冲突
+  - html
+fix_pattern:
+  approach: 重命名冲突变量以避免与导入模块名重复。
+  key_changes:
+  - 将变量名从`html`改为`html_content`
+verification:
+- 确保变量名与导入模块名不冲突
+- 运行flake8检查确保无F823错误
+- 验证GitHub Actions CI通过
+related:
+  files_changed:
+  - app/tool/meetspot_recommender.py
+tags:
+- ci
+- linting
+- python

MeetSpot/postmortem/PM-2025-018.yaml

@@ -0,0 +1,44 @@
+id: PM-2025-018
+created_at: '2026-01-13T05:58:02.063142Z'
+source_commit: a34acd4
+severity: high
+title: Bing验证文件访问优化 - 支持HEAD请求和防缓存
+description: Bing站长工具验证失败，HEAD请求返回405错误，导致验证无法通过。同时，CDN缓存问题导致验证文件不可达，robots.txt配置可能阻止验证文件爬取。
+root_cause: 验证文件路由未正确支持HEAD请求，且未设置防缓存headers，导致验证失败。
+triggers:
+  files:
+  - api/index.py
+  - public/robots.txt
+  functions:
+  - google_verification
+  - bing_verification
+  patterns:
+  - '@app.api_route'
+  - Cache-Control
+  - robots.txt
+  keywords:
+  - BingSiteAuth.xml
+  - HEAD请求
+  - 防缓存
+  - robots.txt
+fix_pattern:
+  approach: 优化验证文件路由，支持HEAD请求并添加防缓存headers，同时更新robots.txt明确允许验证文件爬取。
+  key_changes:
+  - 在api/index.py中为Google和Bing验证文件路由添加HEAD请求支持
+  - 为验证文件响应添加防缓存headers
+  - 更新robots.txt，明确Allow验证文件路径
+verification:
+- 验证HEAD请求是否返回200 OK
+- 检查验证文件是否包含防缓存headers
+- 确认robots.txt中允许验证文件路径
+- 通过curl命令测试验证文件的GET和HEAD请求是否正常
+related:
+  files_changed:
+  - api/index.py
+  - public/robots.txt
+tags:
+- api
+- SEO
+- robots.txt
+- CDN
+- validation

MeetSpot/postmortem/PM-2025-019.yaml

@@ -0,0 +1,32 @@
+id: PM-2025-019
+created_at: '2026-01-13T05:58:04.940805Z'
+source_commit: a27c796
+severity: medium
+title: 修复CSS hover语法错误导致的样式问题
+description: 在 public/index.html 中发现无效的 CSS hover 属性，导致页面样式在某些浏览器中无法正常显示。此问题影响了用户体验。
+root_cause: 内联样式中使用了无效的 hover 属性，未被浏览器正确解析。
+triggers:
+  files:
+  - public/index.html
+  functions: []
+  patterns:
+  - hover\s*:\s*[^;]+;
+  keywords:
+  - CSS
+  - hover
+  - 样式错误
+fix_pattern:
+  approach: 移除无效的内联 hover 样式，确保 CSS 语法正确。
+  key_changes:
+  - 删除无效的 hover 属性
+verification:
+- 检查所有 CSS hover 属性的语法是否正确。
+- 确保页面在不同浏览器中显示一致。
+- 验证页面 hover 效果是否符合设计预期。
+related:
+  files_changed:
+  - public/index.html
+tags:
+- ui
+- css
+- bugfix

MeetSpot/postmortem/PM-2025-020.yaml

@@ -0,0 +1,39 @@
+id: PM-2025-020
+created_at: '2026-01-13T05:58:09.424945Z'
+source_commit: aba844e
+severity: medium
+title: 修复二维码用途和描述错误
+description: 二维码用途和描述错误，导致用户无法正确识别微信群和支付二维码，影响用户体验。
+root_cause: 二维码图片和描述信息配置错误，导致用途混淆。
+triggers:
+  files:
+  - docs/vx_chat.png
+  - public/index.html
+  functions: []
+  patterns:
+  - vx_chat.png
+  - vx_payment.png
+  keywords:
+  - 二维码
+  - 微信
+  - 支付
+  - 交流群
+fix_pattern:
+  approach: 更新二维码图片及描述信息，确保用途明确。
+  key_changes:
+  - 修改vx_chat.png为微信交流群二维码
+  - 修改vx_payment.png为请喝咖啡支付码
+  - 移除个人微信二维码
+  - 优化支持页面的文案和图标
+verification:
+- 确认vx_chat.png显示为微信群二维码
+- 确认vx_payment.png显示为支付二维码
+- 检查支持页面文案和图标是否正确
+related:
+  files_changed:
+  - docs/vx_chat.png
+  - public/index.html
+tags:
+- ui
+- documentation
+- user-experience

MeetSpot/postmortem/PM-2025-021.yaml

@@ -0,0 +1,33 @@
+id: PM-2025-021
+created_at: '2026-01-13T05:58:12.599589Z'
+source_commit: 355b89e
+severity: high
+title: 修复Google Search Console验证文件访问问题
+description: 由于Google Search Console验证文件无法从根路径访问，导致验证超时问题，影响网站的搜索引擎优化。
+root_cause: 缺少专门的路由来处理Google Search Console验证文件的请求。
+triggers:
+  files:
+  - api/index.py
+  functions:
+  - google_verification
+  patterns:
+  - '@app.get\("/google48ac1a797739b7b0.html"\)'
+  keywords:
+  - Google Search Console
+  - 验证文件
+  - 超时
+fix_pattern:
+  approach: 添加专门的路由以确保验证文件可从根路径访问。
+  key_changes:
+  - 添加google_verification函数
+  - 定义新的路由
+verification:
+- 确认google48ac1a797739b7b0.html文件可以从根路径访问
+- 检查Google Search Console验证状态是否正常
+related:
+  files_changed:
+  - api/index.py
+tags:
+- seo
+- api
+- verification

MeetSpot/postmortem/PM-2025-022.yaml

@@ -0,0 +1,36 @@
+id: PM-2025-022
+created_at: '2026-01-13T05:58:16.981664Z'
+source_commit: 53c15bb
+severity: high
+title: 修复图像响应的令牌计算问题
+description: 在处理图像响应时，令牌计算存在错误，可能导致不正确的计费或资源分配问题。此问题影响了图像处理模块的准确性。
+root_cause: 图像响应处理逻辑中缺少对令牌的正确计算。
+triggers:
+  files:
+  - app/image_processing/*.py
+  functions:
+  - calculate_token_usage
+  - process_image_response
+  patterns:
+  - calculate\s*\(.*\)
+  - token_usage\s*=\s*.*
+  keywords:
+  - token
+  - image response
+  - accounting
+  - fix
+fix_pattern:
+  approach: 修复了图像响应处理中的令牌计算逻辑，确保令牌使用量的准确性。
+  key_changes:
+  - 修正了 calculate_token_usage 函数中的计算公式
+  - 更新了 process_image_response 函数以正确处理令牌
+verification:
+- 检查 calculate_token_usage 函数的计算逻辑是否正确
+- 验证 process_image_response 函数在不同图像输入下的令牌计算是否准确
+- 确保所有图像响应的令牌使用量记录在案
+related:
+  files_changed: []
+tags:
+- image processing
+- token accounting
+- bug fix

MeetSpot/postmortem/PM-2025-023.yaml

@@ -0,0 +1,40 @@
+id: PM-2025-023
+created_at: '2026-01-13T05:58:20.762479Z'
+source_commit: a57e614
+severity: high
+title: 修复CafeRecommender类缺失execute方法导致的运行时错误
+description: 在系统运行时，CafeRecommender类缺失execute方法导致服务不可用。此问题影响了推荐功能的正常使用。
+root_cause: CafeRecommender类中缺失execute方法，导致调用时出现属性错误。
+triggers:
+  files:
+  - web_server.py
+  - app/__pycache__/*.pyc
+  functions:
+  - CafeRecommender.execute
+  patterns:
+  - def execute\(
+  - from app.tool.meetspot_recommender import CafeRecommender
+  keywords:
+  - CafeRecommender
+  - execute
+  - fallback
+  - MockResult
+fix_pattern:
+  approach: 在CafeRecommender类中添加execute方法，并实现回退机制。
+  key_changes:
+  - 在CafeRecommender类中添加execute方法
+  - 实现原始推荐器调用失败时的回退机制
+  - 创建fallback_result.html页面
+verification:
+- 检查CafeRecommender类中是否存在execute方法
+- 验证execute方法在原始推荐器不可用时是否正确回退到MockResult
+- 确保fallback_result.html页面在回退时正确显示
+related:
+  files_changed:
+  - app/__pycache__/__init__.cpython-312.pyc
+  - app/__pycache__/exceptions.cpython-312.pyc
+  - web_server.py
+tags:
+- runtime_error
+- recommendation_system
+- fallback_mechanism

MeetSpot/postmortem/PM-2025-024.yaml

@@ -0,0 +1,49 @@
+id: PM-2025-024
+created_at: '2026-01-13T05:58:25.760808Z'
+source_commit: b481fbc
+severity: high
+title: 修复 Python 和 YAML 语法错误，优化工作流文件
+description: 多个 Python 文件和 YAML 工作流文件存在语法错误，导致部分功能无法正常运行，影响了代码的正常执行和 CI/CD 流程的稳定性。
+root_cause: 缺少必要的模块导入和工作流文件配置错误，导致语法错误和功能异常。
+triggers:
+  files:
+  - app/tool/*.py
+  - .github/workflows/*.yml
+  functions:
+  - meetspot_recommender_fixed.py
+  - llm.py
+  patterns:
+  - import .*
+  - f".*"
+  - 'workflow: .*'
+  keywords:
+  - syntax error
+  - datetime
+  - ChatCompletion
+  - workflow
+  - f-string
+fix_pattern:
+  approach: 添加缺失的模块导入，修复 HTML 模板中的 f-string 冲突，清理并保留有效的工作流文件。
+  key_changes:
+  - 在 meetspot_recommender_fixed.py 中添加 datetime 模块导入
+  - 在 llm.py 中添加 ChatCompletion 模块导入
+  - 修复 HTML 模板中 f-string 与 JavaScript 的冲突
+  - 删除重复或损坏的工作流文件，仅保留 ci.yml、auto-merge.yml 和 update-badges.yml
+verification:
+- 确保所有 Python 文件运行时无语法错误
+- 验证 HTML 模板渲染是否正确
+- 检查工作流文件是否能正常触发并执行
+- 确认 CI/CD 流程是否稳定运行
+related:
+  files_changed:
+  - .github/workflows/auto-merge-clean.yml
+  - .github/workflows/auto-merge-dependabot.yml
+  - .github/workflows/ci-clean.yml
+  - .github/workflows/ci-simple.yml
+  - app/tool/meetspot_recommender_fixed.py
+tags:
+- syntax
+- ci/cd
+- python
+- yaml
+- workflow

MeetSpot/postmortem/PM-2025-025.yaml

@@ -0,0 +1,42 @@
+id: PM-2025-025
+created_at: '2026-01-13T05:58:29.615227Z'
+source_commit: 810e8f3
+severity: high
+title: 修复llm.py和meetspot_recommender_fixed.py中的Python语法错误
+description: 在llm.py和meetspot_recommender_fixed.py中存在Python语法错误，导致应用程序无法正常运行。这些错误包括缺少导入和f-string语法问题。
+root_cause: 缺少必要的导入和f-string语法使用不当。
+triggers:
+  files:
+  - app/llm.py
+  - app/tool/*.py
+  functions:
+  - window.onload
+  patterns:
+  - from openai.types.chat import ChatCompletion
+  - f"{{.*}}"
+  keywords:
+  - ChatCompletion
+  - f-string
+  - JavaScript
+  - HTML
+fix_pattern:
+  approach: 添加缺失的导入，修复f-string语法错误，并调整注释格式。
+  key_changes:
+  - 添加ChatCompletion导入到llm.py
+  - 将f-string中的单花括号替换为双花括号
+  - 将JavaScript中的//注释替换为/* */注释
+verification:
+- 确保所有必要的导入都存在
+- 检查f-string语法是否正确
+- 验证JavaScript注释格式是否正确
+related:
+  files_changed:
+  - GITHUB_ACTIONS_FINAL_REPORT.md
+  - app/llm.py
+  - app/tool/meetspot_recommender_fixed.py
+tags:
+- syntax
+- import
+- f-string
+- JavaScript
+- HTML

MeetSpot/postmortem/PM-2025-026.yaml

@@ -0,0 +1,40 @@
+id: PM-2025-026
+created_at: '2026-01-13T05:58:33.486366Z'
+source_commit: b601e97
+severity: high
+title: 修复 GitHub Actions 工作流语法错误
+description: 部分 GitHub Actions 工作流文件存在 YAML 语法错误，导致 CI/CD 无法正常运行。问题影响了自动化构建和依赖管理流程。
+root_cause: 工作流文件中存在不规范的 YAML 语法，导致无法通过验证。
+triggers:
+  files:
+  - .github/workflows/*.yml
+  functions: []
+  patterns:
+  - ^.*:\s+\[.*\]$
+  - ^.*:\s+\{.*\}$
+  keywords:
+  - syntax error
+  - YAML validation
+  - GitHub Actions
+fix_pattern:
+  approach: 清理工作流文件，移除语法错误并简化复杂逻辑。
+  key_changes:
+  - 移除有问题的工作流文件，保留 ci-clean.yml 和 auto-merge-clean.yml
+  - 简化 update-badges.yml 文件，避免复杂的 shell 语法
+  - 新增 GITHUB_ACTIONS_CLEANUP_REPORT.md，记录详细清理日志
+verification:
+- 确保所有工作流文件通过 YAML 验证
+- 验证 CI/CD 流程是否正常运行
+- 检查 update-badges.yml 的 shell 逻辑是否简化且可执行
+- 确认 GITHUB_ACTIONS_CLEANUP_REPORT.md 包含完整清理记录
+related:
+  files_changed:
+  - .github/workflows/auto-merge-clean.yml
+  - .github/workflows/ci-clean.yml
+  - .github/workflows/update-badges.yml
+  - GITHUB_ACTIONS_CLEANUP_REPORT.md
+tags:
+- ci
+- github-actions
+- yaml
+- automation

MeetSpot/postmortem/PM-2025-027.yaml

@@ -0,0 +1,43 @@
+id: PM-2025-027
+created_at: '2026-01-13T05:58:38.080214Z'
+source_commit: 7a124b0
+severity: medium
+title: 修复构建状态徽章和 GitHub Actions 配置问题
+description: 构建状态徽章的 URL 路径错误，导致显示不正确，同时 GitHub Actions CI 配置文件需要重新创建，影响了项目的持续集成状态。
+root_cause: 构建徽章的 URL 路径配置错误，以及 GitHub Actions CI 配置文件丢失或损坏。
+triggers:
+  files:
+  - README.md
+  - README_EN.md
+  - GITHUB_CONTRIBUTOR_RECRUITMENT.md
+  - GITHUB_ISSUE_TEMPLATE.md
+  - .github/workflows/ci.yml
+  functions: []
+  patterns:
+  - workflows/CI%20Tests/badge.svg
+  - actions/workflows/ci.yml/badge.svg
+  keywords:
+  - 构建徽章
+  - GitHub Actions
+  - CI 配置
+fix_pattern:
+  approach: 更正构建徽章的 URL 路径并重新创建 GitHub Actions CI 配置文件。
+  key_changes:
+  - 更正 README 文件中的徽章 URL
+  - 重新创建 .github/workflows/ci.yml 文件
+verification:
+- 检查 README 文件中构建徽章的 URL 是否正确
+- 验证 GitHub Actions CI 配置文件是否存在并正确配置
+- 确保所有相关文档中的徽章链接均已更新
+related:
+  files_changed:
+  - .github/workflows/ci.yml
+  - GITHUB_CONTRIBUTOR_RECRUITMENT.md
+  - GITHUB_ISSUE_TEMPLATE.md
+  - README.md
+  - README_EN.md
+  - README_RESOLVED.md
+tags:
+- ci
+- documentation
+- github

MeetSpot/postmortem/PM-2026-001.yaml

@@ -0,0 +1,35 @@
+id: PM-2026-001
+created_at: '2026-01-13T05:53:56.241279+00:00'
+source_commit: 3e221be
+severity: medium
+title: 添加大学全称映射，修复华南理工大学等地址解析错误
+description: '问题：用户输入大学全称（如''华南理工大学''）时，地址增强不生效，
+
+  高德API返回错误地址（如大连的公交站而非广州的大学）
+
+
+  修复：在university_mapping中同时添加简称和全称映射，
+
+  覆盖45所主要高校的简称+全称共90+条映射'
+root_cause: See commit body for details
+triggers:
+  files:
+  - CLAUDE.md
+  - app/tool/meetspot_recommender.py
+  functions:
+  - _enhance_address
+  patterns: []
+  keywords:
+  - general
+fix_pattern:
+  approach: 添加大学全称映射，修复华南理工大学等地址解析错误
+  key_changes:
+  - 添加大学全称映射，修复华南理工大学等地址解析错误
+verification:
+- Review related code changes
+related:
+  files_changed:
+  - CLAUDE.md
+  - app/tool/meetspot_recommender.py
+tags:
+- general

MeetSpot/postmortem/PM-2026-002.yaml

@@ -0,0 +1,35 @@
+id: PM-2026-002
+created_at: '2026-01-13T05:56:41.686707Z'
+source_commit: 3e221be
+severity: high
+title: 修复大学全称解析错误，确保地址增强准确性
+description: 用户输入大学全称时，地址增强功能未生效，导致高德API返回错误地址，影响用户体验。
+root_cause: 大学全称未在映射中，导致地址解析不准确。
+triggers:
+  files:
+  - app/tool/*.py
+  functions:
+  - _enhance_address
+  patterns:
+  - university_mapping
+  keywords:
+  - 大学全称
+  - 地址解析
+  - 高德API
+fix_pattern:
+  approach: 在university_mapping中添加大学全称映射，确保地址解析准确。
+  key_changes:
+  - 在university_mapping中添加45所高校的简称和全称映射
+  - 更新 _enhance_address 函数以使用新的映射
+verification:
+- 检查university_mapping中是否包含所有主要高校的简称和全称
+- 验证 _enhance_address 函数在处理全称时返回正确的地址
+- 测试高德API返回的地址是否与预期一致
+related:
+  files_changed:
+  - CLAUDE.md
+  - app/tool/meetspot_recommender.py
+tags:
+- geocoding
+- api
+- address enhancement

MeetSpot/postmortem/PM-2026-003.yaml

@@ -0,0 +1,39 @@
+id: PM-2026-003
+created_at: '2026-01-13T05:56:45.473246Z'
+source_commit: 83f25ab
+severity: medium
+title: 修复 CI 管道失败问题：添加 create_meetspot_agent 存根
+description: 由于未定义名称错误，CI 管道失败。通过添加 create_meetspot_agent 存根函数解决此问题。
+root_cause: create_meetspot_agent 函数未定义导致 flake8 F821 错误。
+triggers:
+  files:
+  - api/index.py
+  functions:
+  - create_meetspot_agent
+  patterns:
+  - def create_meetspot_agent\(
+  keywords:
+  - CI
+  - flake8
+  - F821
+  - create_meetspot_agent
+fix_pattern:
+  approach: 添加 create_meetspot_agent 存根函数以避免未定义名称错误。
+  key_changes:
+  - 添加 create_meetspot_agent 存根函数
+  - 更新 README 文件
+verification:
+- 确保 create_meetspot_agent 函数存在且不会被调用
+- 检查 CI 管道是否成功运行
+- 验证 README 文件中的图片是否正确显示
+related:
+  files_changed:
+  - CLAUDE.md
+  - README.md
+  - README_ZH.md
+  - api/index.py
+  - public/docs/vx_group.png
+tags:
+- ci
+- documentation
+- agent