commit c55598494bdde0d8e9153f67ed38f3243dc40521 Author: selfrelease Date: Tue Jun 16 00:55:20 2026 +0800 init: AI培训与智能巡检系统 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..5de5bbd --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +# AI培训与智能巡检系统 + diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..7a73a41 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,2 @@ +{ +} \ No newline at end of file diff --git a/0-req.md b/0-req.md new file mode 100644 index 0000000..270bb08 --- /dev/null +++ b/0-req.md @@ -0,0 +1,249 @@ +# 中国机车图鉴 · 产品与技术方案 + +> 一个面向铁路爱好者的、可众包维护的机车知识库与社区平台 +> 数据基础:`中国铁路车型统计表(总表)` 共 12 张分类表 + +--- + +## 1. 项目愿景 + +打造一个**「科学严谨 + 趣味探索 + 社区共建」**的中国机车数字图鉴: + +- 对爱好者:一个能"逛得进去、查得明白、玩得起来"的机车百科 + 打卡社区。 +- 对数据:一份持续生长、有据可查、版本可追溯的开放车型数据库。 +- 对社区:一个有荣誉感、有归属感、有交流沉淀的爱好者聚集地。 + +一句话定位:**机车界的「维基百科 + 观鸟记录 App + 兴趣社区」**。 + +--- + +## 2. 数据现状分析 + +现有 Excel 已覆盖 12 个分类,字段相当完整,是天然的"数据底座"。 + +| 分类 | 代表字段 | 数据特征 | +|------|----------|----------| +| 蒸汽机车(建国前/后) | 型号、生产商、年代 | 历史向,强时间轴属性 | +| 电力机车 | 牵引力、供电方式、轴列式、时速 | 技术参数密集 | +| 内燃机车 | 系列、传动方式、动力来源 | 有"系列→型号"层级 | +| 动车组(和谐号/复兴号/CJ) | 编组、节数、试验/量产状态 | 强版本/谱系关系 | +| 货车 | 车型大类、车型代码、载重、容积、车钩 | 编码体系清晰 | +| 客车 | 型号、用途 | 数量大 | +| 检测车 / 综合检测列车 | 车号、功能、配属、状态、涂装 | 强"个体实例"属性(精确到车号) | +| 旅游列车 | — | 运营/线路向 | + +**关键洞察:** + +1. **存在两个数据粒度**——"车型(Model)"与"具体车辆个体(Unit,精确到车号)"。检测车表已经到了车号粒度,这正是众包打卡的核心载体。 +2. **存在层级与谱系关系**——系列 → 型号 → 改型(如 C62A / C64K),动车组有试验型→量产型演化,适合做"技术族谱"可视化。 +3. **字段需要标准化**——现表中存在合并单元格、单位混排(如"整备重量 / 轴重 /t")、空表头等问题,入库前需清洗与字段规范化。 +4. **天然带时间维度与空间维度**——首产/停产年份 → 时间轴;配属路局/运营线路 → 地图。 + +--- + +## 3. 核心数据模型 + +采用三层模型,兼顾科学性与众包扩展性: + +``` +车型分类 (Category) + └── 车型 (Model) ← 百科主体,技术参数挂这里 + └── 车辆个体 (Unit) ← 精确到车号,爱好者打卡/拍摄对象 + └── 目击记录 (Sighting) ← 用户众包内容:时间+地点+照片 +``` + +**Model(车型)核心字段**(统一字段表,跨分类通用 + 分类专有) + +- 通用:型号、别名、分类、系列、生产商、**制造国/地区**、**国别属性(国产/进口/引进仿制/中外合资)**、首产年、停产年、状态、用途、产量、缩略图 +- 尺寸/重量:车长、车宽、车高、整备重量、轴重、轴距、轴列式 +- 动力:牵引力(起动/持续)、最高时速、供电方式、传动方式、动力来源 +- 关系:父型号(改型自)、衍生型号(构成"族谱")、**原型车/技术来源(指向国外车型,如 8K↔法国、ND 系列↔进口内燃)** + +**Unit(车辆个体)字段**:车号、所属车型、配属路局、涂装、当前状态(现役/封存/报废/保存于博物馆)、首次/末次目击。 + +**Sighting(目击/打卡)字段**:用户、车辆、时间、地点(经纬度+车站)、照片、描述。 + +> 字段命名、单位统一在数据字典中维护,所有数值字段拆出独立"数值 + 单位"避免现表的混排问题。 + +--- + +## 4. 展示模式(既有趣又科学) + +不押注单一视图,而是提供**多视图切换**,让不同诉求的人各取所需。 + +### 4.1 时间轴视图 ⭐ 推荐主视图 +- 横轴为年代(1881 至今),按分类分泳道。 +- 每个车型是轴上一个节点,点击展开详情卡。 +- 适合呈现"蒸汽→内燃→电力→动车组"的技术演进,**科学感与故事性兼具**。 + +### 4.2 地图视图 ⭐ 推荐 +- 两种用法: + - **配属地图**:按路局展示车型分布(适合机车/检测车)。 + - **目击热力图**:聚合用户打卡记录,展示"哪里能拍到什么车"——这是社区活跃度的可视化,趣味性极强。 +- 技术:MapLibre / 高德地图,聚合点 + 热力图。 + +### 4.3 技术族谱图(谱系树)⭐ 差异化亮点 +- 用有向图展示车型演化(如 韶山系列、和谐号→复兴号、C 系列敞车改型)。 +- 节点=车型,连线=改进/衍生关系。最能体现"科学"且独此一家。 + +### 4.4 图鉴/卡牌视图 +- 类似宝可梦图鉴的卡片墙,按分类筛选,带"已收集/未收集"状态(结合打卡)。 +- 是趣味性与收集欲的核心载体。 + +### 4.5 参数对比视图 +- 勾选 2–4 个车型,雷达图/对比表并排比较(时速、牵引力、轴重等)。 +- 满足"硬核党"的科学需求。 + +### 4.6 详情页 +- 集成:参数表、历史沿革、图集、族谱位置、目击地图、相关讨论。 + +**结论**:以 **时间轴 + 图鉴卡牌** 为日常入口,**地图 + 族谱 + 对比** 为深度探索,兼顾趣味与科学。 + +--- + +## 5. 众包维护机制(让爱好者有荣誉感) + +核心思路:**Wiki 式协作编辑 + 审核 + 贡献激励**。 + +### 5.1 编辑与审核流程 +- 任何登录用户可对车型发起"编辑建议"(修改字段、补充资料、上传图片)。 +- 采用 **修订版本(Revision)** 机制:每次修改生成版本记录,可对比、可回滚(类似维基百科历史)。 +- 审核分级: + - 新手编辑 → 进入审核队列,由资深用户/版主复核。 + - 高信誉用户 → 可直接生效(信任分机制)。 +- 每条字段可附**来源引用**(书籍、铭牌照片、官方资料),保障科学性。 + +### 5.2 荣誉与激励体系 +- **贡献积分**:新增车型、补全字段、上传被采用的照片、通过审核均得分。 +- **等级与头衔**:如"见习巡道员 → 司炉 → 司机 → 机务段长 → 总工程师"(铁路主题化)。 +- **徽章成就**:首张照片、集齐某分类、连续打卡、被采纳 N 次修订等。 +- **贡献榜**:周榜/月榜/总榜,详情页显示"本词条主要贡献者"署名——**直接给到荣誉感**。 +- **认领词条**:资深爱好者可"认领维护"某车型,成为该词条 maintainer,署名上墙。 + +### 5.3 数据质量保障 +- 字段校验(数值范围、单位、年代逻辑)。 +- 争议字段可发起讨论投票。 +- 完整修订历史,任何错误可追溯、可回滚。 + +--- + +## 6. 社区交流(保留交流历史) + +### 6.1 论坛/板块 +- 按分类、路局、主题(拍车/模型/历史考证)分板块。 +- 帖子、回复、@、点赞、收藏,**全部持久化保存,永久可查**(满足"保留交流历史")。 + +### 6.2 词条挂讨论 +- 每个车型/个体详情页内嵌讨论区,讨论与数据绑定沉淀。 + +### 6.3 打卡动态流 +- 用户上传目击照片形成 Feed,可评论互动——把"维护数据"和"社交"融为一体。 + +### 6.4 内容沉淀 +- 优质考证帖可被"精华化"并引用进词条来源,形成 UGC → 知识库的正循环。 + +--- + +## 7. 其他扩展(建议) + +| 方向 | 说明 | +|------|------| +| 📷 **打卡集邮** | 拍到某车号即"收集",类似观鸟/集邮,强收集欲 | +| 🗺️ **拍车攻略** | 基于目击热力图,推荐"在哪个站点能拍到什么车" | +| 🏛️ **退役/保存机车地图** | 标注各博物馆、公园保存的实车位置,便于线下打卡 | +| 🔔 **稀有车提醒** | 关注某车型,有新目击时推送 | +| 🧠 **AI 识车** | 上传照片自动识别车型(长期,基于社区图库训练) | +| 📊 **数据可视化大屏** | 全国保有量、技术演进、时速变迁等科普图表 | +| 🎮 **AR/3D 模型** | 部分经典车型 3D 展示或 AR 摆放 | +| 🌐 **开放 API / 数据导出** | 开放数据集供研究者使用,强化"科学开放"形象 | +| 🌍 **多语言** | 面向海外铁道迷 | + +--- + +## 8. 国外车型的考量 + +**当前方案以中国机车为中心,但国外车型不应被忽略**——原因是二者高度交织: + +- **历史渊源**:建国前蒸汽机车多为进口/外国制造(美、日等);建国后大量引进苏联、东欧、法国(8K 电力机车)、日本等机型,形成"**引进 → 仿制 → 自主**"的清晰技术脉络。 +- **强化族谱视图**:把国外原型车纳入后,技术族谱图能完整呈现"原型 → 引进 → 国产化 → 自主升级"链条,科学性和故事性都更强。 + +### 范围策略(按相关性分圈层收敛,避免范围失控) + +| 圈层 | 范围 | 优先级 | +|------|------|--------| +| 🟢 圈层一 | 中国铁路车型(现有数据) | MVP,立即做 | +| 🟡 圈层二 | **在华运用过的外国车型** + **中国车型的国外原型/技术来源** | 中期,价值最高 | +| 🔵 圈层三 | 与中国有渊源的延伸(如出口机车、同平台海外型号) | 长期 | +| ⚪ 圈层四 | 纯国外车型全球图鉴 | 视社区意愿再定,谨慎扩张 | + +### 设计要点 + +- 数据模型已预留**制造国/地区、国别属性、原型车/技术来源**字段,从一开始就为国外车型留好位置,无需后期重构。 +- 展示上增加"**按国别筛选**"和"**世界地图**"维度;族谱图跨国连线。 +- **建议**:先做好圈层一、二(与中国强相关的部分),这是差异化价值所在;是否扩到圈层四交给社区共建决定,而非一开始铺开全球数据。 + +### 注意事项 + +- 国外资料的**来源与版权**更需谨慎(多语言资料、图片授权)。 +- 字段需国际化(单位、命名、轴列式 UIC 标准 vs 中国习惯)。 +- 防止范围蔓延导致中国部分的深度被稀释——**深度优先于广度**。 + +--- + +## 9. 技术架构建议 + +**前端** +- Web 优先(响应式),后续 App。框架:React / Next.js(SEO 友好,利于百科被搜索到)。 +- 可视化:时间轴/族谱用 D3 或 ECharts,地图用 MapLibre/高德,对比用 ECharts 雷达图。 + +**后端** +- API:Node.js(NestJS) 或 Python(FastAPI)。 +- 数据库:PostgreSQL(结构化车型数据 + PostGIS 处理地理目击数据)。 +- 全文检索:Meilisearch / Elasticsearch(中文搜索)。 +- 对象存储:图片/图集(OSS / S3)。 +- 缓存:Redis。 + +**关键工程** +- **数据导入管线**:先做一个 Excel → 清洗 → 入库 的 ETL 脚本(处理合并单元格、单位拆分、字段映射),把现有 12 表作为初始种子数据。 +- **版本/审核服务**:修订记录、diff、回滚。 +- **权限与信誉系统**:RBAC + 贡献积分。 + +--- + +## 10. 分期路线图(MVP 优先) + +**Phase 1 · 数据底座(MVP)** +- Excel 清洗入库,统一字段字典。 +- 车型列表 + 详情页 + 搜索筛选。 +- 时间轴视图、图鉴卡牌视图。 + +**Phase 2 · 众包共建** +- 登录注册、Wiki 式编辑 + 审核 + 修订历史。 +- 贡献积分、等级、徽章、贡献榜。 + +**Phase 3 · 社区与空间** +- 论坛 + 词条讨论 + 打卡动态流。 +- 地图视图(配属 + 目击热力图)。 + +**Phase 4 · 进阶玩法 + 圈层扩展** +- 族谱图、参数对比、保存机车地图、稀有车提醒。 +- 接入圈层二:在华运用的外国车型 + 中国车型的国外原型,跨国族谱连线。 + +**Phase 5 · 智能化** +- AI 识车、数据大屏、开放 API、AR/3D。 + +--- + +## 11. 风险与注意事项 + +- **数据版权与来源**:众包内容需标注来源,图片需声明授权,避免侵权。 +- **数据准确性**:以"来源引用 + 审核 + 可回滚"对冲错误;争议字段公开讨论。 +- **冷启动**:先邀请核心爱好者圈子共建种子内容与首批 maintainer。 +- **审核成本**:信誉分越高审核越宽松,平衡质量与活跃度。 +- **隐私与合规**:目击地点等 UGC 注意敏感区域与合规要求。 + +--- + +## 12. 小结 + +以现有 12 张分类表为种子,构建"**车型→个体→目击**"三层数据模型;用**时间轴 + 图鉴 + 地图 + 族谱**多视图兼顾趣味与科学;以 **Wiki 式协作 + 信誉荣誉体系**驱动众包维护;用**论坛 + 词条讨论 + 打卡动态**沉淀社区交流历史。建议从数据底座 MVP 起步,逐步叠加共建、社区与智能化能力。 diff --git a/1-prd.md b/1-prd.md new file mode 100644 index 0000000..8643a23 --- /dev/null +++ b/1-prd.md @@ -0,0 +1,237 @@ +# 1-PRD · 中国机车图鉴平台 产品需求文档 + +> 版本:v1.0 +> 来源:基于 `方案.md` 全文细化 +> 状态:草稿(待评审) +> 一句话定位:机车界的「维基百科 + 观鸟记录 App + 兴趣社区」 + +--- + +## 0. 文档说明 + +本 PRD 将 `方案.md` 的产品构想细化为可评审、可拆解的需求集合,覆盖目标、用户、范围、功能需求、数据需求、非功能需求、指标与里程碑。技术实现细节(架构选型、表结构)留待后续设计文档(2-design)展开,本文只在"约束"层面引用。 + +--- + +## 1. 产品目标与背景 + +### 1.1 背景 +铁路爱好者群体对机车型号、参数、历史与现役状态有强烈的查询、收集、考证与交流需求,但现有资料分散在 Excel、贴吧、论坛、个人博客中,缺乏一个**结构化、可信、可持续生长**的统一平台。本项目以现有《中国铁路车型统计表》12 张分类表为种子数据,构建该平台。 + +### 1.2 产品目标 +| 维度 | 目标 | +|------|------| +| 知识库 | 提供权威、结构化、可追溯的机车车型数据库 | +| 趣味体验 | 通过时间轴、图鉴卡牌、地图、族谱等多视图让浏览"既有趣又科学" | +| 众包共建 | 让爱好者低门槛参与维护,并获得荣誉感与归属感 | +| 社区沉淀 | 提供交流空间,且交流历史永久可查 | + +### 1.3 设计原则 +1. **科学严谨**:数据可溯源、可审核、可回滚。 +2. **趣味探索**:多视图、收集机制、可视化。 +3. **社区共建**:低门槛编辑 + 荣誉激励 + 信任分级。 +4. **深度优先于广度**:先做透中国车型,国外车型按相关性分圈层扩展。 + +--- + +## 2. 目标用户与画像 + +| 角色 | 描述 | 核心诉求 | +|------|------|----------| +| 浏览型爱好者(游客/轻度) | 偶尔查车型、看历史 | 快速查询、有趣的浏览 | +| 拍车/打卡党 | 线下追车、拍照记录 | 记录目击、收集车号、拍车攻略 | +| 硬核考据党 | 关注参数、历史、谱系 | 准确参数、对比、技术族谱、可溯源 | +| 贡献者/编辑 | 补全和维护数据 | 便捷编辑、荣誉署名、贡献统计 | +| 版主/维护者 | 审核与质量把控 | 审核队列、修订对比、回滚 | +| 管理员 | 平台运营 | 权限、内容治理、数据治理 | + +--- + +## 3. 范围定义 + +### 3.1 数据范围(圈层策略) +| 圈层 | 范围 | 阶段 | +|------|------|------| +| 🟢 圈层一 | 中国铁路车型(现有 12 表) | MVP | +| 🟡 圈层二 | 在华运用的外国车型 + 中国车型的国外原型 | 中期 | +| 🔵 圈层三 | 出口机车、同平台海外型号 | 长期 | +| ⚪ 圈层四 | 纯国外全球图鉴 | 视社区意愿 | + +### 3.2 阶段范围(对应方案路线图) +- **Phase 1(MVP)**:数据底座 + 列表/详情/搜索 + 时间轴 + 图鉴卡牌。 +- **Phase 2**:账户体系 + Wiki 编辑/审核/修订历史 + 荣誉体系。 +- **Phase 3**:社区(论坛/讨论/动态流)+ 地图视图。 +- **Phase 4**:族谱图 + 参数对比 + 保存机车地图 + 稀有车提醒 + 圈层二数据。 +- **Phase 5**:AI 识车 + 数据大屏 + 开放 API + AR/3D。 + +### 3.3 不在本期范围(MVP 明确排除) +- 用户登录与众包编辑(Phase 2) +- 社区论坛与打卡(Phase 3) +- AI 识车、AR/3D、开放 API(Phase 5) + +--- + +## 4. 数据需求 + +### 4.1 数据模型(三层 + 关系) +``` +Category 车型分类 + └── Model 车型(百科主体,技术参数) + └── Unit 车辆个体(精确到车号) + └── Sighting 目击记录(用户众包:时间+地点+照片) +Model ←→ Model:父型号 / 衍生型号 / 国外原型(族谱关系) +``` + +### 4.2 Model 字段字典(统一字段表) +| 分组 | 字段 | 说明/约束 | +|------|------|-----------| +| 标识 | 型号、别名、分类、系列 | 型号必填、唯一性校验 | +| 来源 | 生产商、制造国/地区、国别属性(国产/进口/引进仿制/合资) | 国别属性枚举 | +| 时间 | 首产年、停产年 | 年代逻辑校验(首产≤停产) | +| 状态 | 状态、用途、产量、缩略图 | 状态枚举 | +| 尺寸/重量 | 车长、车宽、车高、整备重量、轴重、轴距、轴列式 | 数值+单位分离 | +| 动力 | 牵引力(起动/持续)、最高时速、供电方式、传动方式、动力来源 | 数值+单位分离 | +| 关系 | 父型号、衍生型号、原型车/技术来源 | 指向其他 Model | +| 溯源 | 每字段可附来源引用(Phase 2) | 书籍/铭牌照片/官方资料 | + +> 约束:所有数值字段以"数值 + 单位"独立存储,杜绝现表的单位混排问题。 + +### 4.3 Unit / Sighting 字段 +- **Unit**:车号、所属车型、配属路局、涂装、当前状态(现役/封存/报废/博物馆保存)、首/末次目击。 +- **Sighting**:用户、车辆、时间、地点(经纬度+车站)、照片、描述。 + +### 4.4 数据导入(ETL) +- 将现有 12 张 CSV/Excel 清洗后入库作为种子数据。 +- 处理:合并单元格还原、空表头修复、单位拆分、字段映射到统一字典、系列→型号层级归并、改型关系识别。 +- 产出:导入报告(成功/失败/需人工复核条目)。 + +--- + +## 5. 功能需求(按模块) + +> 标注:【P1】MVP / 【P2】共建 / 【P3】社区 / 【P4】进阶 / 【P5】智能化 + +### 5.1 车型浏览与检索【P1】 +- FR-1.1 车型列表:分页、按分类筛选、按字段排序。 +- FR-1.2 多维筛选:分类、年代、时速区间、生产商、国别、状态。 +- FR-1.3 全文搜索:型号/别名/生产商中文检索,支持模糊与拼音(增强项)。 +- FR-1.4 车型详情页:参数表、历史沿革、图集、族谱位置、相关讨论入口。 +- FR-1.5 数值字段统一展示单位,缺失字段优雅留白。 + +### 5.2 展示视图【P1/P3/P4】 +- FR-2.1【P1】时间轴视图:年代横轴、分类泳道、节点点击展开详情卡。 +- FR-2.2【P1】图鉴卡牌视图:卡片墙、分类筛选、"已收集/未收集"占位(收集逻辑 P3 接入)。 +- FR-2.3【P4】参数对比:勾选 2–4 个车型,雷达图 + 对比表。 +- FR-2.4【P4】技术族谱图:有向图展示演化关系,支持跨国连线。 +- FR-2.5【P3】地图视图:配属地图 + 目击热力图,聚合点。 +- FR-2.6 视图间可相互跳转(如从族谱节点跳详情)。 + +### 5.3 账户与权限【P2】 +- FR-3.1 注册/登录(邮箱/第三方)。 +- FR-3.2 角色:游客、注册用户、信任用户、版主、管理员(RBAC)。 +- FR-3.3 个人主页:贡献统计、徽章、收集进度、目击记录。 + +### 5.4 众包编辑与审核【P2】 +- FR-4.1 编辑建议:登录用户可修改字段、补资料、传图。 +- FR-4.2 修订版本:每次修改生成 Revision,支持 diff 对比与回滚。 +- FR-4.3 审核分级:新手编辑入审核队列;信任用户直接生效。 +- FR-4.4 字段来源引用:可为字段附引用来源。 +- FR-4.5 字段校验:数值范围、单位、年代逻辑。 +- FR-4.6 争议字段:可发起讨论/投票。 + +### 5.5 荣誉与激励【P2】 +- FR-5.1 贡献积分:新增/补全/采用照片/通过审核计分。 +- FR-5.2 等级头衔:铁路主题等级(见习巡道员→…→总工程师)。 +- FR-5.3 徽章成就:首图、集齐分类、连续打卡、被采纳 N 次等。 +- FR-5.4 贡献榜:周/月/总榜;详情页显示"主要贡献者"署名。 +- FR-5.5 认领词条:成为 maintainer 并署名。 + +### 5.6 社区交流【P3】 +- FR-6.1 论坛板块:按分类/路局/主题分区。 +- FR-6.2 帖子与回复:发帖、回复、@、点赞、收藏,**永久持久化保存可查**。 +- FR-6.3 词条内嵌讨论区:讨论与数据绑定。 +- FR-6.4 打卡动态流:目击照片 Feed + 评论互动。 +- FR-6.5 内容沉淀:优质考证帖可精华化并引用进词条来源。 + +### 5.7 打卡与收集【P3/P4】 +- FR-7.1 目击打卡:记录车号、时间、地点、照片。 +- FR-7.2 图鉴收集:拍到即收集,图鉴显示进度。 +- FR-7.3【P4】拍车攻略:基于目击热力图推荐拍摄点。 +- FR-7.4【P4】保存机车地图:标注博物馆/公园保存实车。 +- FR-7.5【P4】稀有车提醒:关注车型新目击推送。 + +### 5.8 智能化与开放【P5】 +- FR-8.1 AI 识车(照片→车型)。 +- FR-8.2 数据可视化大屏(保有量/时速变迁等)。 +- FR-8.3 开放 API / 数据导出。 +- FR-8.4 AR/3D 模型展示。 +- FR-8.5 多语言(面向海外爱好者)。 + +--- + +## 6. 非功能需求 + +| 类别 | 需求 | +|------|------| +| 性能 | 列表/详情页 P95 < 1.5s;搜索响应 < 500ms | +| 可用性 | 响应式 Web 优先,移动端可用;SEO 友好(百科可被搜索引擎收录) | +| 可扩展 | 数据模型预留国别/原型字段,圈层扩展不需重构 | +| 数据质量 | 字段校验 + 来源引用 + 修订可回滚 | +| 安全 | RBAC 权限;UGC 内容审核;防刷分 | +| 合规 | 图片版权声明、来源标注;目击地点敏感区域脱敏 | +| 可观测 | 关键操作日志、审核日志、贡献流水 | +| 国际化 | 字段单位/命名国际化(UIC vs 中国习惯轴列式) | + +--- + +## 7. 成功指标(KPI) + +| 阶段 | 指标 | +|------|------| +| MVP | 种子数据完整入库(12 表全覆盖);车型详情可访问;时间轴/图鉴可用 | +| 共建 | 月活跃编辑者数、月新增/修订条目数、审核通过率 | +| 社区 | 月活、发帖/回复数、打卡数、收集完成率 | +| 留存 | 次周留存、贡献者复访率 | +| 质量 | 字段完整度、被回滚修订占比(越低越好)、争议解决时长 | + +--- + +## 8. 里程碑与交付物 + +| 里程碑 | 交付物 | 依赖 | +|--------|--------|------| +| M1(MVP) | ETL 入库 + 列表/详情/搜索 + 时间轴 + 图鉴卡牌 | 种子数据清洗 | +| M2 | 账户 + Wiki 编辑/审核/修订 + 荣誉体系 | M1 | +| M3 | 论坛/讨论/动态流 + 地图视图 | M2 | +| M4 | 族谱图 + 对比 + 保存机车地图 + 提醒 + 圈层二数据 | M2/M3 | +| M5 | AI 识车 + 大屏 + 开放 API + AR/3D | M4 | + +--- + +## 9. 风险与对策 + +| 风险 | 对策 | +|------|------| +| 数据版权/来源争议 | 强制来源标注、图片授权声明 | +| 数据准确性 | 来源引用 + 审核 + 可回滚 + 争议投票 | +| 冷启动乏力 | 邀请核心爱好者共建种子内容与首批 maintainer | +| 审核成本高 | 信任分级,高信誉自动生效 | +| 范围蔓延 | 圈层收敛,深度优先于广度 | +| 隐私合规 | 目击地点敏感区域处理与合规审查 | + +--- + +## 10. 待确认问题(Open Questions) + +1. 技术栈最终选型(Next.js + NestJS/FastAPI + PostgreSQL)是否锁定? +2. 是否需要原生 App,还是 PWA 即可? +3. 第三方登录渠道范围(微信/GitHub/邮箱)? +4. 地图服务选型(高德 vs MapLibre)与国内合规? +5. 图片对象存储与 CDN 选型? +6. MVP 是否需要最简账户(仅收藏)还是完全匿名? +7. 国外车型圈层二的启动时机与数据来源? + +--- + +## 附录 A · 现有数据分类清单(种子) +建国前蒸汽机车 / 建国后蒸汽机车 / 北京表(蒸汽机车)/ 普速客车 / 电力机车 / 内燃机车 / CJ 型及早期动车组及和谐号 / 复兴号 / 货车 / 普速检测车 / 高速综合检测列车 / 旅游列车(共 12 类)。 diff --git a/2-task.md b/2-task.md new file mode 100644 index 0000000..ca117c0 --- /dev/null +++ b/2-task.md @@ -0,0 +1,410 @@ +# 2-TASK · 中国机车图鉴平台 开发任务清单 + +> 版本:v1.0 +> 来源:基于 `1-prd.md` 细化 +> 用途:落实与跟进开发计划(开发 / 单元测试 / e2e 测试) + +## 进度日志 +- **2025 · 第 1 批**:完成 Phase 1A 数据底座(T-1.1 / T-1.2)。 + - ETL 导入 12 张 CSV → SQLite + JSON + 报告:**Model 540 / Unit 307**,跳过 10(空行),0 待复核。 + - 31 个单元/集成测试全部通过(含全量导入幂等性)。 + - 代码位于 `app/etl`、`app/tests`,产物位于 `app/data`,说明见 `app/README.md`。 + - 取舍:开发期用 SQLite(schema 设计为可移植到 PostgreSQL);Meilisearch/Redis/对象存储等基础设施待 Phase 1B/接入时引入。 +- **2025 · 第 2 批**:完成 Phase 1B 后端 API(T-1.3 / T-1.4),技术栈 **NestJS + TypeScript**(方案 B)。 + - 接口:`/api/health`、`/api/categories`、`/api/models`(列表/筛选/排序/分页)、`/api/models/:id`(详情)、`/api/units`、`/api/search`。 + - 参数化查询防注入;全局 ValidationPipe 校验非法参数(返回 400)。 + - 测试:14 个单元测试 + 9 个 e2e(supertest)全部通过;build 通过;真实库(540/307)联调通过。 + - 代码位于 `apps/api`(NestJS 标准结构),读取 `app/data/machines.db`。 + - 取舍:搜索先用 SQLite LIKE+排序实现(规模足够),Meilisearch 延后。 +- **2025 · 第 3 批**:完成 Phase 1C 前端(T-1.5 / T-1.6 / T-1.7),技术栈 **Vite + React + TS**(方案 B,独立前端 `apps/web`)。 + - 页面:列表页(筛选/排序/分页 + 列表/时间轴/图鉴 三视图切换)、详情页(参数表 + raw_json 保真表)、全局搜索框(防抖下拉)。 + - 时间轴:分类泳道 + 年代横轴刻度 + 节点跳转;图鉴:卡牌墙 + 已收集/未收集占位。 + - 测试:23 个单元测试(Vitest + Testing Library)全部通过;`npm run build`(tsc + vite)通过。 + - 全栈联调:Vite 代理 `/api`→NestJS,真实库 540 车型,列表/排序/搜索均正确返回。 + - 取舍:SSR/SEO、缩放平移、Playwright 脚本化 e2e 标记延后(已手动联调全栈通过)。 +- **2025 · 第 4 批(A:闭合 MVP)**:补齐 Phase 1 验收(T-1.8)。 + - 性能基准 `apps/api/bench.mjs`:list/filter/detail p95 ≤ 3ms(阈值 1500ms),search p95 1.3ms(阈值 500ms),全部达标。 + - Playwright e2e(`apps/web/e2e/smoke.spec.ts`):首页/筛选→详情/时间轴/图鉴/搜索 **5 项全通过**,webServer 自动拉起前后端。 + - 修复真实 UX bug:时间轴同年同泳道节点完全重叠导致不可点击 → 实现碰撞分行(错位堆叠)+ 标签 pointer-events:none。 + - **Phase 1(MVP)正式闭合**。累计测试:ETL 31 + API 23 + 前端单元 25 + e2e 5 = **84 个测试全绿**。 +- **2025 · 第 5 批(图鉴差异化)**:解决"列表与图鉴雷同"问题,落实方案"收集欲"主线。 + - 图鉴改为**图片优先卡牌墙**:按分类生成 SVG 占位缩略图(`lib/thumb.ts`,真实车照待 Phase 2/3 众包上传替换)。 + - 轻量**收集功能**:localStorage 记录已收集(`lib/useCollection.ts`),点卡片"收集"点亮缩略图,顶部显示收集进度条;Phase 3 账户上线后迁移云端。 + - 测试:前端单元增至 34(新增 thumb / GalleryCard),e2e 图鉴用例改为验证缩略图+收集交互;全绿。 +- **2025 · 第 6 批(前端全方位重构 · 主线串联)**:解决"首页死板、一屏过载、无主线"问题。 + - **叙事首页**(`HomePage`):英雄区 + 关键统计 + **时速演进曲线**(`EvolutionCurve`,SVG)+ **四个时代章节**(蒸汽→内燃→电力→高铁,每节代表车 + 进入探索),把技术演进主线显性串联。 + - **信息架构重组**:`/` 故事首页、`/explore` 探索页、`/models/:id` 详情;顶部导航 故事/探索 + 全局搜索。 + - **探索页减负**:筛选器收进可折叠面板(默认隐藏,带激活计数),默认图鉴视图,更大留白。 + - 章节链接经 `?category=` 跳入探索并自动筛选(URL 同步)。 + - 主线逻辑(时代/代表车/时速演进)抽到 `lib/eras.ts` 纯函数并单测。 + - 测试:前端单元 39 + e2e 7(覆盖首页→探索→详情/时间轴/搜索/章节跳转),全绿;build 通过。 +- **2025 · 第 7 批(专业图标 + 视图合并 + 全详情)**: + - **全部 emoji → 专业图标**:引入 `react-icons`,统一 `components/icons.tsx`(分类图标 + 品牌/锁/星/筛选/视图图标);缩略图改为 `Thumb`(分类渐变 + 专业图标),移除 emoji/data-URI 方案。 + - **探索页合并视图**:去掉"列表",统一用**图鉴**展示(默认),仅保留 图鉴 / 时间轴 两视图。 + - **详情页升级为"全部详情"**:缩略图 Hero + 标签 + 基本信息 / 尺寸与重量 / 动力与性能 / 原始数据 全字段分组展示。 + - 测试:前端单元 37 + e2e 7(图鉴收集改 aria-pressed、详情断言分组标题),全绿;build 通过。 +- **2025 · 第 8 批(图鉴分页 + 全中文 + 多图灯箱)**: + - **图鉴分页**:客户端分页 18/页,分页器置于卡牌墙**上方**;筛选变化回到第 1 页;编号跨页连续。 + - **详情全中文**:新增 `lib/fieldLabels.ts`(英文规范键→中文),"原始数据"区英文键全部映射为中文(model 17 等已核对全覆盖)。 + - **详情多图 + 灯箱**:`lib/useImages.ts`(每车型本地图册,localStorage)+ `Lightbox`(缩放/滚轮/拖拽平移/上下张/Esc);详情新增"图册"区可添加多张图片并点开缩放欣赏;云端众包上传待 Phase 2/3。 + - 测试:前端单元 39 + e2e 8(新增分页/全中文/图册上传缩放),全绿;build 通过。 +- **2025 · 第 9 批(接入 Wikimedia Commons 真实照片)**: + - 每页改为 **21**;详情"图册"接入 **Wikimedia Commons**(`lib/commons.ts` + `useCommonsImages`):浏览器端 origin=* CORS 检索自由授权实拍图,**署名(作者/许可证/来源链接)显示在灯箱**。 + - 图片优先级:Commons 真实照片 → 本地上传 → 系统生成示意图(兜底,永不空);卡片角标区分来源(Commons/我的/示意图)。 + - 健壮回退:无网/无匹配/请求失败时静默回退示意图;结果做内存 + sessionStorage 缓存。 + - 灯箱升级为通用图源(URL/dataURL)并展示署名。 + - 注:构建/测试沙箱仅放行 npm,无法联网验证 Commons 覆盖率,需在浏览器端验证(如 CR400AF / HXD1型)。 + - 测试:前端单元 42 + e2e 8,全绿;build 通过。 +- **2025 · 第 10 批(Phase 2 启动 · T-2.1 账户体系,采用 B1)**: + - 架构:新增**独立可写库 `app/data/app.db`**(`WritableDbService`,含迁移),与只读 `machines.db` 分离,避免被 ETL 重建清空。 + - 后端:`AuthModule`(NestJS + @nestjs/jwt + bcryptjs)——注册/登录/`/api/auth/me`;`JwtAuthGuard` + `RolesGuard`(游客<注册<信任<版主<管理员 等级);密码 bcrypt,邮箱规范化小写,密码不外泄。 + - 前端:`AuthProvider` 上下文 + 登录/注册模态框 + 顶栏用户菜单 + 个人主页(贡献积分/已收集/加入日期)。 + - 安全提示:JWT secret 走 `JWT_SECRET` 环境变量,默认值仅供开发,生产须替换。 + - 测试:后端单元 18 + e2e 14(含注册/重复 409/非法 400/登录 401/me 鉴权);前端单元 42 + e2e 9(含注册→用户菜单→个人主页);build 通过。 +- **2025 · 第 11 批(T-2.2 编辑/修订 + T-2.3 审核)**: + - 数据:`app.db` 增 `revisions` / `revision_changes` / `model_overrides` 三表;编辑不改只读 `machines.db`,而以"字段覆盖"叠加,详情接口读取时合并(标记 `overridden`)。 + - 后端:`ContribModule`——`POST /api/models/:id/revisions`(提交编辑,含 old→new diff)、`GET .../revisions`(历史)、`GET /api/revisions/pending`(版主队列)、`approve`/`reject`(版主+)、`GET /api/editable-fields`;字段白名单 + 校验(年代范围/状态枚举/国别枚举);信任级以上自动通过;通过即应用覆盖并给作者 +5 积分。 + - 引导管理员:`ADMIN_EMAIL` 环境变量命中即注册为 admin(便于审核演示/测试)。 + - 前端:详情页"编辑词条"模态(白名单字段表单)、"修订历史"区(状态/作者/diff)、`/review` 审核页(版主+,通过/驳回)、顶栏"审核"入口(按角色显示)。 + - 测试:后端单元 18 + e2e 21(提交/历史/403/管理员审核生效/自动通过/非法 400);前端单元 42 + e2e 10(含登录后编辑→待审核修订);两端 build 通过。 +- **2025 · 第 12 批(T-2.4 荣誉与激励)→ Phase 2 完成**: + - 等级头衔(`community/levels.ts` 纯函数):见习巡道员→巡道员→司炉→副司机→司机→机务段长→总工程师(按积分阈值);徽章(首改采纳/高产编辑/资深贡献/总工殊荣)。 + - `/api/auth/me` 增等级/徽章/被采纳数;`CommunityModule`:`GET /api/leaderboard`(贡献榜),`GET/POST/DELETE /api/models/:id/maintainers`(词条认领署名)。 + - 前端:个人主页等级进度条 + 徽章;`/leaderboard` 贡献榜页(金银铜);详情页"词条维护者"认领/署名;顶栏"贡献榜"入口。 + - 测试:后端单元 22 + e2e 25(含 me 等级、贡献榜、认领、未登录 401);前端单元 42 + e2e 13(含认领署名、等级徽章、贡献榜);两端 build 通过。 + - **Phase 2(众包共建)完成**:账户 + Wiki 式编辑/审核/修订历史 + 荣誉体系全部跑通。 +- **2025 · 第 13 批(测试账号一键登录)**:后端开机幂等预置 3 个演示账号(admin@demo.com / mod@demo.com / user@demo.com,密码 demo1234,角色 admin/moderator/user;仅非生产,`SEED_TEST_USERS=false` 可关);登录框加"测试账号一键填入"。e2e 15。 +- **2025 · 第 14 批(Phase 3 启动 · T-3.1 论坛 + T-3.2 词条讨论)**: + - 可写库增 `threads` / `thread_replies` 表(板块 + 可选 model_id 绑定词条)。 + - 后端 `ForumModule`:`GET /api/boards`、`GET/POST /api/threads`(板块/词条过滤、发帖)、`GET /api/threads/:id`、`POST /api/threads/:id/replies`;DTO 校验,发帖/回复需登录。 + - 前端:`/community` 论坛(板块标签 + 发帖 + 帖子列表)、`/thread/:id` 帖子页(正文 + 回复 + 回复框)、详情页"讨论区"(绑定该车型的话题 + 发起讨论);顶栏"社区"入口。 + - 测试:后端 e2e 29(发帖/回复/板块/词条绑定/401/400);前端 e2e 16(社区发帖→帖子页回复);两端 build 通过。 +- **2025 · 第 15 批(T-3.3 打卡 + T-3.4 地图)→ Phase 3 完成**: + - 可写库增 `sightings` 表;`SightingsModule`:`POST/GET /api/models/:id/sightings`、`GET /api/sightings/recent`(动态流)、`GET /api/sightings/map`;坐标校验(IsLatitude/IsLongitude),跨库用只读库补 model_code/分类。 + - 前端:详情页"目击打卡"区(经纬度/用我的位置 geolocation/车站/车号 + 列表);`/map` 打卡地图(**MapLibre + OpenStreetMap 免费瓦片**,标记 + 弹窗 + 最新打卡侧栏);顶栏"打卡地图"入口。 + - 修复:sighting 补全用 `category_id` join 分类(model 表无 category 列)导致的 500。 + - 取舍:地图先用点位标记(OSM 栅格瓦片,遵守使用政策并署名);热力图/路局聚合/PostGIS 后续;打卡暂不计贡献积分(保持榜单=数据编辑)。 + - 测试:后端 e2e 31(打卡/动态/地图/401/非法坐标 400);前端 e2e 18(详情打卡→列表、地图页加载);两端 build 通过。 + - **Phase 3(社区与空间)完成**:论坛 + 词条讨论 + 打卡动态 + 地图。 +- **2025 · 第 16 批(修复 + T-4.1 参数对比)**: + - 修复:贡献榜列表 class 名 `.lb` 与灯箱 `.lb`(全屏 fixed 遮罩)冲突,导致无法离开贡献榜页 → 列表改名 `.leaderboard`,加回归测试。 + - T-4.1 参数对比(Phase 4 起步):`/compare` 页,搜索加入 2–4 车型,自绘 **SVG 雷达图**(`lib/compare.ts` 归一化纯函数 + `RadarChart`)+ 对比表;URL 同步 ids;详情页"加入对比"按钮;顶栏"对比"入口。 + - 测试:前端单元 45(新增 compare 归一化)+ e2e 21(含贡献榜可离开回归、参数对比雷达图);build 通过。 +- **2025 · 第 17 批(完成 Phase 4 主体:T-4.2/4.3/4.4)**: + - T-4.2 技术族谱(`/family`):后端 `GET /api/models/families` 按分类→系列聚合;前端分类标签 + 系列泳道 + 型号节点(非国产标记),点击进详情。 + - T-4.3 拍车攻略:后端 `GET /api/sightings/spots` 按车站聚合"在哪能拍到什么车",打卡地图页展示热门打卡点;稀有车提醒(轻量):`useFollow`(localStorage 关注)+ 详情"关注"按钮 + 个人主页"关注车型最新目击"汇总。 + - T-4.4 国别维度:探索筛选器已有"国别",族谱标注非国产;制造国/国别属性/原型字段就位且可众包编辑。 + - 取舍:真正的父/衍生/原型有向图、跨国连线、保存机车地图(缺坐标)、提醒推送基建 → 待数据/基建后续。 + - 测试:后端 e2e 33(含 families/spots);前端单元 45 + e2e 23(含族谱跳详情、关注汇总);两端 build 通过。 + - **Phase 4 主体完成**(数据可得部分),余项已明确标注待数据/基建。 +- **2025 · 第 18 批(Phase 5:数据大屏 + 开放 API + AI 识车占位)**: + - 数据大屏(`/stats`):后端 `GET /api/stats`(分类/国别/年代/时速演进聚合);前端 KPI + 柱状图 + 时速演进曲线。 + - 开放 API / 导出:`GET /api/export/models.json|csv`(CSV 转义)+ `/api-docs` 接口一览与下载按钮;底部导航入口。 + - AI 识车(`/identify`):诚实占位页(上传本地预览 + 明确声明非真实识别 + 示例候选),不伪造识别。 + - 修复:vite 代理 `/api` 前缀误吞前端路由 `/api-docs` → 改为正则 `^/api/` 仅代理真实接口;加回归测试。 + - 取舍(如实标注延后):AR/3D(需 3D 资产)、多语言(需翻译工作量)、真实 AI 模型(需图库训练/算力)。 + - 测试:后端 e2e 36(含 stats/export);前端 e2e 28(含大屏/开放API/AI占位 + 两条回归);两端 build 通过。 + - **Phase 5 数据可得部分完成**;五个阶段全部推进完毕,未尽项均有明确原因与后续路径。 +- **2025 · 第 19 批(前端专业美化)**: + - 导航分组:顶栏收敛为 故事 / 图鉴▾ / 社区▾ / 数据▾ / 审核(`NavMenu` 点击展开下拉,路由/外部点击/Esc 关闭,可访问性 aria)。 + - 统一组件与设计令牌:扩充 CSS tokens(间距/圆角/阴影刻度 + 焦点环);新增 `components/ui.tsx`(Button / PageHeader / EmptyState / Tag)+ 统一 `.btn` 体系;统一卡片悬浮过渡、毛玻璃粘性头部。 + - UX 一致性:下拉/焦点/卡片/页头统一;族谱页改用 PageHeader + EmptyState。 + - 族谱卡片加列车图片:family 节点改为带封面(Thumb 分类插画)的卡片。 + - e2e 适配分组导航(图鉴→探索、社区→论坛);前端单元 45 + e2e 28 全绿;build 通过。 +- **2025 · 第 20 批(统一组件 100% 收敛)**: + - 各页改用 `ui` 基础组件:`PageHeader`(贡献榜/社区/对比/大屏/开放API/AI识车/打卡地图/审核/族谱)、`EmptyState`(贡献榜/社区/对比)、`Button`(社区发帖发布、帖子回复、个人退出、审核通过/驳回、详情编辑/关注/加入对比/添加图片/认领/打卡/发起讨论、编辑模态、探索筛选、开放API 导出)。 + - 保留差异化控件(分段控件视图切换/板块标签、登录模态、定位按钮)以维持模式语义。 + - 文案/类名保持不变,e2e 全绿(前端单元 45 + e2e 28);build 通过。 +- **2025 · 第 21 批(图鉴改为管理员独占管理,用户只读)**: + - 风险收口:图鉴词条编辑与图片上传仅管理员可用,普通用户只读。 + - 后端:`POST /api/models/:id/revisions` 加 `@Roles('admin')`(普通用户 403,未登录 401)。 + - 前端:详情页"编辑词条"、"图册 + 添加图片"入口仅 `role==='admin'` 可见(含 file input 一并隐藏);图册文案改为"由管理员维护"。 + - 测试:后端 e2e 36(普通用户编辑 403、管理员编辑自动生效、白名单 400);前端 e2e 29(管理员编辑生效、普通用户无编辑/上传入口、管理员上传+灯箱);两端 build 通过。 + - 说明:当前管理员图片上传仍是浏览器本地(localStorage,非共享);"管理员云端管理共享图库 + 公共图库 + 上传/打卡即收集 + 云端收集同步 + 集邮成就"为后续批次(已有完整实现方案)。 +- **2025 · 第 22 批(后端图片云存储 + 管理员上传写入共享图库)**: + - 可写库新增 `photos` 表;服务端文件存储 `app/data/uploads/`(`UPLOAD_DIR` 可覆盖),`main.ts` 用 express.static 暴露 `/uploads`。 + - `PhotosModule`:`POST /api/models/:id/photos`(**仅管理员**,multer multipart,类型/大小校验)、`GET /api/models/:id/photos`(公共,所有人可看)、`DELETE /api/photos/:pid`(管理员)。 + - 车型列表 API 附带 `cover_url`(共享图库首图),**图鉴卡片用真实照片作封面**(管理员上传后所有访客可见)。 + - 详情"图册"改为共享图库:管理员上传(multipart)→ 所有人查看 + 灯箱;移除原 localStorage 本地图方案。 + - Vite 增 `^/uploads/` 代理。 + - 测试:后端 e2e 40(上传 403/201/非图片 400/删除 + 公共列表);前端 e2e 29(管理员上传→共享→灯箱);两端 build 通过;真实管线 curl 验证(上传→入库→静态 200→代理 200)。 +- **2025 · 第 23 批(候选/确认机制 + 批量取图脚本)**: + - `photos` 加 `status('candidate'|'confirmed')` + `source_url/author/license`(已存在库自动补列)。管理员手动上传=`confirmed`;脚本入库=`candidate`。 + - **卡片封面只取 `confirmed`**;详情图册显示"候选/图库"角标 + 署名(作者/许可证/来源),管理员可逐张"✓确认/✕删除",并有"确认全部候选"。 + - API:`POST /api/photos/:pid/confirm`(管理员)。 + - **取图脚本** `apps/api/scripts/fetch-images.mjs`(`npm run fetch-images`,在有网本机跑):按 **Wikidata P18 → Commons 同名分类 → 关键词搜索** 顺序为缺图车型下载候选图入库(candidate),记录署名,输出命中报告;支持 `--limit/--category/--dry`。 + - 测试:后端 e2e 41(含候选→确认流程);前端单元 45 + e2e 29;两端 build 通过。 + - 说明:脚本需联网访问 wikidata/commons,本沙箱不可联网,需在用户本机运行。 +- **2025 · 第 24 批(管理员候选审图页)**: + - 后端 `GET /api/photos/candidates`(管理员):全站候选图聚合 + 车型信息(跨只读库补 model_code/分类)。 + - 前端 `/admin/photos` 审图页(仅管理员):候选图网格(缩略图 + 车型链接 + 署名/来源)、逐张确认/删除、"全部确认";顶栏管理员专属"候选审图"入口(普通用户不可见)。 + - 测试:前端 e2e 31(含管理员可访问、普通用户无入口);两端 build 通过。 +- **2025 · 第 25 批(图鉴展示与封面优化 · 4 项)**: + - 1) 卡片封面始终展示最佳可用图:`cover_url`(共享图库 confirmed)→ Commons 实拍(懒取)→ 分类示意图;移除"未收集锁/暗色遮罩",★ 改为个人"收藏"书签(aria 收藏/已收藏)。 + - 2) 详情头图改用真实图:hero = featured 封面 → confirmed 图库 → Commons[0] → 示意图(`.detail-hero-img` 覆盖填充)。 + - 3) 管理员可指定展示图:`photos` 加 `featured` 列;`POST /api/photos/:pid/feature`(管理员,清同车型其它 featured 并置 confirmed);卡片 cover 查询优先 `featured` 再最小 id;详情图册 confirmed 图加"★ 设为封面"(当前封面金色高亮),候选图保留"✓ 确认"。 + - 4) 图鉴可直接输入型号筛选:探索工具条加 `.kw-input`(防抖 300ms → `query.q`)。 + - 测试:前端单元 45 + e2e 31(新增"型号关键字筛选""管理员设为封面");后端单元 22 + e2e 42(新增"封面优先 featured + 权限受控");修复 models.service 单测夹具缺 `photos` 表;两端 build 通过。 +- **2025 · 第 26 批(Commons 下载到本地,运行时不再访问外部图源)**: + - 诉求:把原先浏览器端实时检索的 Wikimedia Commons 照片**全部下载到本地共享图库**,应用运行时只读本地 `/uploads`,不再发外部请求。 + - 前端:移除浏览器端 Commons(删除 `lib/commons.ts` / `lib/useCommonsImages.ts` / `lib/commons.test.ts`)。`GalleryCard` 封面只取本地 `cover_url`(否则分类示意图),不再懒取 Commons;`DetailPage` 图册改为「本地共享图库照片 + 系统示意图」,头图取 featured/confirmed 本地照片;移除"正在从 Commons 检索"提示与 Commons 角标,图注署名仍展示(下载时已存库)。 + - 取图脚本升级(`apps/api/scripts/fetch-images.mjs`,本机联网跑一次即可):新增 `--per N`(每车型多张)、`--confirm`(直接入库为 confirmed,封面/图册立即可见,替代原实时 Commons 展示);多来源去重;保存到本地 `app/data/uploads/` + `photos` 表并记录署名(作者/许可证/来源)。 + - 说明:构建/测试沙箱仅放行 npm、不可联网,无法在此执行实际下载;需在用户本机运行 `node scripts/fetch-images.mjs --per 3 --confirm` 完成落地。未下载到照片的车型自动回退分类示意图(永不空)。 + - 测试:前端单元 42(移除 commons 3 项)+ e2e 31,全绿;后端单元 22 + e2e 42 不变;两端 build 通过。 +- **2025 · 第 27 批(修正:下载图片一律进入候选审图)**: + - 问题:上一批脚本提供了 `--confirm`,按该建议运行后下载图直接入库为 `confirmed`,**跳过了"候选审图"双闸门**。 + - 修正:取图脚本移除 `--confirm`,所有下载图**一律入库为 `candidate`**,进入管理员「候选审图」队列,人工确认后才作封面/图册(恢复"候选 + 人工确认"准确性闸门)。 + - 数据修复:将已下载的 Commons 图片(含 `source_url`)从 confirmed 改回 `candidate`(清 featured);并清除早期 e2e 测试误写入生产库的 8 张 1×1 占位图(行 + 文件)。 + - 验证:管理员登录 `GET /api/photos/candidates` 返回 15 张候选(带署名),`/admin/photos` 审图页可见可逐张确认。 +- **2025 · 第 28 批(图鉴分页记忆 + 去收集示例 + 首页紧凑/带图)**: + - 1) 图鉴翻页记忆:图鉴页码存入 URL `?gp=N`(`GalleryView` 改为受控分页),从卡片进详情后"← 返回图鉴"用 `navigate(-1)` 回到来路并停在原页;筛选/关键字变化时自动回到第 1 页(`gp` 清除)。 + - 2) 图鉴页移除"收集示例"按钮(保留收集进度条与单卡收藏)。 + - 3) 首页更紧凑(英雄区/时代轨/留白收敛);时代代表车的 mini 卡在有真实封面(`cover_url`)时直接显示照片,且 `pickRepresentatives` 优先挑有图车型"带出来"。 + - 测试:前端单元 42 + e2e 33(新增"翻页进详情返回仍在该页""不再显示收集示例"),目标子集全绿;build 通过。 +- **2025 · 第 29 批(全站专业图标 + 数据大屏重构 + AI 识车接入通义千问)**: + - 图标:扩充 `components/icons.tsx`(编辑/对比/确认/关闭/删除/维护/定位/返回/前进/警告/下拉/论坛/图片/奖杯/站点/缩放/翻页等 react-icons 出口);替换 DetailPage、NavMenu、Lightbox、Auth/Edit 模态、ComparePage、ProfilePage、各页返回链接、首页 CTA、EmptyState 等处的 emoji/符号为专业图标;EmptyState `icon` 改为 ReactNode。(保留原始数据 diff 的 `→` 与原生 `