规划
Harness学院网站功能路线图
按 M0 到 M2 的阶段拆解网站功能范围、上线判据与跨阶段技术底座。
共 8 个模块、209 项功能条目。
按交付顺序逐个功能看，含门禁与外部审批依赖：上线里程碑主轴
阶段
阶段划分
- M0
- 开发前约定
- 备案与资质启动、内容契约、URL 与付费管线定稿
- M1a
- 可收录最小站
- 首页、首发专栏、SEO 基线与上线收录
- M1b
- 内容品类与运营
- 博客、速查表、内容治理、数据与可观测性
- M2
- 能收钱
- 账号、付费墙、微信支付、售后与站长后台
- 远期
- 按需增强
- 会员、订阅、学习进度与外部内容工具链
功能清单
M0 · 开发前约定
先把外部审批、内容契约和发布基线定死
合规与准入（最先启动）
- 域名注册与实名认证
- ICP 备案提交与管局审核
- 服务器接入商核验
- 备案通过前只用本地与预览环境
- 上线后 30 日内公安联网备案
- 盘点收款主体资质，M1 中期启动商户号
工具与内容契约
- Next.js + Fumadocs 版本冒烟
- Node 22、pnpm 与构建命令约定
- 构建不通时整栈回退上一个可用版本
- frontmatter 字段和内容目录结构
- columnId、chapterId、order 稳定标识符
- access 字段区分免费、试读、付费
- 已有 Markdown 存稿归位
URL 与路由契约
- 教程、博客、速查表路径前缀定稿
- trailingSlash 与反代配置对齐
- slug 命名规范与大小写约定
- 不做多语言，不预留 i18n 路径前缀
- 内容铺开后不再调整 URL 结构
付费隔离与内容管线
- content-paid 放在 docs 集合外
- 显式不参与静态构建
- 章节页预留付费正文注入挂点
- 付费正文投递到生产的方式定稿
- 付费正文渲染归属：构建期片段或运行时渲染
- 试读范围以 frontmatter 为默认，后台只做覆盖
发布基线
- 静态构建与本地预览
- 自有 Nginx、try_files 与缓存策略
- HTTPS 证书签发与续期
- 移动端无横向滚动
M1a · 可收录最小站
尽早上线能被收录的最小站点，让索引时钟开始走
首屏与品牌最小集
- 首页与全站导航
- Logo、favicon、自有配色
- 关于、联系、隐私和 404
- 深色模式与移动端适配
首发专栏
- 首发 3 到 5 篇可读章节
- 专栏详情页与章节列表
- 有序章节与独立侧栏 topic
- 代码高亮、行标记与一键复制
- 免费、试读、付费访问级别标记
- 付费章节只给静态提示，不放死按钮
SEO 基线
- 每篇 title、description、slug
- 首页与标题位使用流量关键词
- 品牌词不占 SEO 标题位
- 自动 sitemap 与 robots.txt
- Article 与 TechArticle JSON-LD
- OG 图与图片 alt
- Lighthouse SEO 大于等于 90
上线与收录启动
- 备案通过后解析域名并部署
- 站长平台验证并提交 sitemap
- Orama 索引与中文检索冒烟
- 不索引付费正文
- 记录收录起始日并跟踪收录率
- 验收判据：首发专栏可读且已提交收录
M1b · 内容品类与治理
在已上线站点上扩品类、补治理，并稳住周更节奏
教程目录与筛选
- 教程目录卡片墙
- 封面、简介与篇数
- 按难度、标签、最新筛选排序
速查表与博客
- 速查表列表、详情与锚点跳转
- 命令一键复制
- 博客列表、详情、分页和标签
- RSS 与文章封面
富媒体
- B 站视频 MDX 卡片
- 懒加载与比例占位防 CLS
内容治理
- 最后更新时间与修订记录
- 过期内容提示
- slug 变更 301 重定向
- 死链与图片检查
周更节奏
- 开发与写作按周切分时间
- 周更频率与文章收录率作为前导指标
- 一个主题先做全再铺下一个
- 专栏管线：Claude Code 到 Codex 到具体 skill
M1b · 运营与可观测
知道流量从哪里来，也知道哪里坏了
数据分析
- 自然搜索 UV 作为北极星
- 来源词与落地页
- 教程详情 CTA 点击
- 站内搜索零结果
- 404 访问记录
- 采集入口与定期复盘
页级反馈
- 文章纠错与建议入口
- 自动附带当前页面 URL
- 初期不引入完整评论系统
可观测性与恢复
- 站点可用性监控
- HTTPS 证书到期监控
- 构建与部署失败报警
- 404 报警
- 定期备份
- 恢复演练
M1b+ · 第三方教程
接入外部开源教程，但先解决重复内容和边界
接入前提
- 原创内容收录情况已验证
- 评估重复内容风险后再决定接入
- 排在 M1b 主线之后，不与首发专栏抢时间
重复内容与 SEO
- rel=canonical 指向上游原文
- 高度重复页面 noindex
- 不占用首页与教程目录主推位
- 单独观察镜像内容的收录与流量
来源与版权
- 顶部导航或教程目录入口
- 本站课程入口页
- 许可证页面
- 来源与非官方声明
- 更新责任与命令安全提醒
上游同步
- Git submodule 独立管理
- 上游源码只读
- fast-forward 更新
- 主仓库提交子模块指针
内容适配
- 只发布目标语言与读者所需路径
- 排除脚本、内部文档和搜索噪声
- loader 补 title
- 关闭错误的 editUrl 与 issueUrl
- 相对 Markdown 链接转本站路由
- 未发布页面回退上游 GitHub
- 缺失图片改用本站 public 资源
- 避免重复页面标题
上线验收
- pnpm run build 通过
- 入口到首页到模块页链路测试
- 桌面与移动端截图检查
- 链接、图片、搜索索引与许可证检查
- canonical 与 noindex 抽查
- 确认上游子模块工作树干净
- 第二或第三个项目后再抽象集中配置
M2 · 账号与交易
判据达成后再从阅读转向购买
启动判据
- 连续 4 周自然搜索 UV 达标
- 首发专栏章节数达标
- 收到明确付费意愿反馈
- 收款主体与微信支付商户号已就绪
- Laravel、Filament 与 filamentboot 版本兼容性复核
- 判据未达成则继续 M1b 内容循环
账号与个人中心
- 邮箱或手机注册
- 密码与昵称
- 账号密码登录
- Sanctum 第一方会话与 HttpOnly Secure Cookie
- 不使用 localStorage 存 token
- 邮箱或手机找回密码
- 修改昵称与密码
- 已购专栏与订单记录
账号安全与数据权利
- 邮箱或手机验证
- 登录与找回密码限流
- 防撞库
- 注销账号
- 个人数据导出或删除
付费墙
- 未购显示试读与购买卡
- 服务端验证登录与购买记录
- 已购后拉取全文并客户端注入
- 付费正文永不进入 dist
- 免费与试读内容对爬虫可见
- 注入后补代码高亮与复制
- 付费墙 JSON-LD 标注 isAccessibleForFree 为 false
- paywall 区域标注且试读段有真实价值
- 正文接口按章节粒度返回
- 内容接口限流与异常批量下载告警
商品与定价
- 按专栏单独售卖，不做全站会员
- 单价与试读范围后台可配
- 下单写入价格快照
- 购买 CTA、价格与已购数
- 专栏上架与下架
微信 Native 支付
- 创建订单并返回二维码
- 前端轮询支付状态
- 支付成功自动解锁并写入已购记录
- 回调验签与幂等
- 查单接口兜底，回调或查单任一成功即解锁
- 订单状态机
- Native 扫码不需要 openid
- 使用 yansongda laravel-pay，不引入 easywechat
售后与交易通知
- 待支付订单过期
- 重复支付与支付异常处理
- 退款处理与退款后撤销权益
- 购买须知与退款规则
- 发票规则前置到购买须知
- 注册验证与找回密码通知
- 支付成功、退款与订单状态通知
- 初期以邮件为主，短信后置
站长后台
- Filament 与 filamentboot 基建
- 认证、RBAC、菜单和操作日志
- 用户、订单与客服按订单定位
- 站点配置
- 后台不编辑内容，Markdown 仍由 Git 管理
跨阶段 · 技术与安全
把前后台架构、安全和性能预算托住
前台生态
- Next.js + Fumadocs（Node 运行时）
- shadcn/ui + Tailwind v4
- Markdown + Git 管理内容
- Orama 站内搜索
- Shiki 代码高亮与复制
- 博客与文档双 collection
- Bilibili MDX 组件
- Sitemap 与 JSON-LD
- Docker + Nginx 反代 + CDN + HTTPS
后台生态
- Laravel API
- Filament 管理端
- filamentboot 基础能力
- yansongda laravel-pay
- 前台与 API 同一可注册顶级域
- Cookie 跨子域会话
安全
- 密码加密
- 防注入与 XSS
- 服务端 Policy 或 Gate 验权
- 不信任客户端标志或隐藏 UI
- CORS 显式允许凭据
- 支付验签
性能预算
- 移动 4G 首屏 LCP 小于 2 秒
- 图片懒加载
- 富媒体 CLS 小于 0.1
- 预渲染优先 ISR 承载周更
- Node 进程守护与健康检查
- 单人运营流程保持轻量
远期 · 按需增强
有真实需求后再扩展，并守住范围边界
按需排期
- 会员与专栏打包
- 优惠码与早鸟
- 评论，按 giscus 这类轻量嵌入方案评估
- 邮件订阅
- 学习进度
- 大规模内容时评估外部搜索
- 外部文档导入工具链
明确不做
- 全站会员制
- 原创视频课
- 原创设计系统
- 前台运行 Node 服务
- 多语言与 i18n 路径
- App 与小程序
计划调整记录
- 备案与收款资质前置到 M0
- ICP 备案是外部审批、周期不受开发进度影响，域名实名与备案提交排在 M0 第一步；个体工商户或企业主体与微信支付商户号在 M1 中期并行启动，不等 M2 开工再申请。
- M1 拆成 M1a 与 M1b
- 自然搜索收录有 1 到 3 个月滞后，先用最小可收录站点起跑索引时钟；博客、速查表、筛选排序与内容治理放到 M1b，避免上线前先做几个月功能。
- 付费内容管线在 M0 定稿
- content-paid 不进 dist 只是隔离结论，还必须先定它如何投递到生产、由谁渲染，以及 columnId、chapterId、order 等稳定标识符，否则 M2 后台无法关联章节。
- URL 与路由结构在 M0 定死
- 路径前缀、trailingSlash 与 slug 规范先于内容铺开；内容量上来后再改结构只能靠 301 补救，成本远高于前期约定。
- 第三方教程补重复内容策略
- 镜像开源教程与上游构成重复内容，接入排在 M1b 之后，并需要 rel=canonical指向上游、必要页面 noindex，先验证原创内容收录情况再铺量。
- M2 增加可执行启动判据
- 用连续 4 周自然搜索 UV、首发专栏章节数和付费意愿反馈决定是否开工，避免在零流量时先投入数倍工作量做支付与后台。
- 去掉死按钮与重复条目
- 购买 CTA、价格与已购数占位移入 M2，M1a 只保留访问级别标记和静态提示；备份、监控与恢复演练只在 M1b 运营模块出现一次，不再与技术底座重复。
- 评论方案重新放开候选
- 原否决 Waline 与 Twikoo 的理由是它们需要 Node 或云函数，与“线上不运行 Node 服务”冲突；该约束已随前台改用 Next.js（Node 运行时）而消失，两者重新进入候选。远期在 giscus、Waline、Twikoo 之间按运维负担评估，不再以“是否需要 Node”为排除条件。