版本记录

这里记录每个可下载版本对使用、配置、部署和兼容性的影响。下载或升级时，请以版本化 ZIP、SHA-256 和本页说明为准。

1.0.0-alpha.26

• 作者阅读自己发布的付费文章、集合拥有者查看自己的付费集合时，不再显示单独解锁、支付或兑换入口。
• 有效订阅用户和已经单独解锁文章或集合的用户，在服务端确认可读后不会再次看到购买操作；集合权益也会继续开放集合内对应文章。
• 尚未获得阅读权限的用户仍会看到原有订阅或单独解锁入口，付费产品的标题、价格、分享和推荐信息保持不变。
• 创建订单和兑换前会再次校验当前账号是否已经可读，避免绕过页面重复购买自己的内容或已经拥有权益的内容。
• Web、真实 Space API、完整 Mock、共享契约与回归测试使用同一套阅读权益边界；缺少明确可读状态时不会误挂载结算组件。

兼容性：没有数据库迁移、环境变量或 Secret 变化，现有文章、集合、内容商品、订单、订阅和阅读权益数据保持不变。升级前仍应备份数据库、.env、.secrets/ 和持久卷，并运行 pnpm ops:template:preflight；回滚只切换到 1.0.0-alpha.25 或上一个已验证源码版本，复用同一环境配置与持久卷，不要删除订单、权益数据或清空卷。

1.0.0-alpha.25

• 文章、集合和闪念列表支持最多 5 条有序置顶；后台可以搜索候选内容、调整顺序或取消置顶，公开列表按后台顺序展示，左上角统一显示置顶标识且不遮挡封面与正文。
• 动态页把排序和类型拆成两个可组合维度：可在最新 / 最热之间切换，也可筛选全部、讨论、闪念、文章和集合；真实 API、独立 Full Mock 与 Web 使用同一组查询和返回语义。
• 所有明确的图片上传入口统一接入裁剪队列，支持保留原图、自由裁剪和场景推荐比例；文章封面推荐 5:2、集合封面推荐 4:3、横向题图推荐 16:9、头像固定 1:1，多图可逐张处理。
• 图片处理弹窗改为可复用的 fit 模式：裁剪画布、比例工具栏和操作区会尽量完整适配当前视口，桌面与移动端均避免双重滚动；通用 Dialog 仍保留默认滚动模式供长表单使用。
• 模板覆盖层补齐全局裁剪 Provider、第三方裁剪样式与业务样式，并为置顶管理、列表顺序和动态筛选补齐独立 Full Mock；导出门禁会阻止只同步正式站、遗漏模板入口或 Mock 语义的发行包。

兼容性：新增 0102_space_content_pins.sql，首次启动或升级时会创建有序置顶表；没有新增环境变量或 Secret，图片裁剪也不改变现有上传 API 和对象存储字段。升级前备份数据库、.env、.secrets/ 和持久卷，运行 pnpm ops:template:preflight 后再按标准流程构建；回滚只切换到 1.0.0-alpha.24 或上一个已验证源码版本并复用同一环境配置与持久卷，不要删除迁移表或清空卷。旧版本无法管理新增置顶记录，但不会影响文章、集合和闪念本身。

1.0.0-alpha.24

• 抽奖后台补齐多活动上下文：活动工作台选中的活动会同步到参与记录、中奖履约和审计记录，URL 可以恢复当前活动；操作区持续显示活动名称，避免活动增多后误处理其他活动。
• 中奖履约支持按活动、奖品、领奖状态和权益状态筛选，既可以单个处理，也可以批量给选中中奖者发送站内信。
• 月度会员、年度会员、文章和专栏等虚拟奖品可在履约工作台直接批量开通并自动通知；已有有效会员从当前到期日继续顺延，同一批请求使用幂等键防止重复发放或重复通知。
• 模板后台、真实 Space API 和独立 Full Mock 完整注册抽奖与通用收货地址；解压运行时不再出现“源码已包含但模板入口或服务未装配”的半链路状态。
• 新增抽奖 Full Mock 履约回归和一次性 PostgreSQL 16 集成测试命令，覆盖中奖者列表、会员权益、站内通知、地址簿、真实迁移、开奖事务与行锁语义；导出门禁会检查 Web、真实 API、Mock、迁移和测试脚本必须同时存在。

兼容性：没有新增迁移、环境变量或 Secret；继续使用 0098_space_lottery.sql、0100_space_lottery_award_notifications.sql、0101_space_lottery_entitlement_fulfillment.sql 与既有服务端地址字段加密。升级前备份数据库、.env、.secrets/ 和持久卷，先运行 pnpm ops:template:preflight，再按标准升级流程构建。回滚只切换到 1.0.0-alpha.23 或上一个已验证源码版本并复用同一环境配置与持久卷；不要删除抽奖记录、权益记录、地址数据、迁移或卷。

1.0.0-alpha.23

• 正式同步社区抽奖、我的抽奖、中奖领奖和通用收货地址；后台可以维护活动、审计开奖证据并在权限允许时处理履约，公开页面与后台路由均纳入完整档案检查。
• 分享卡同步抽奖专用布局，并保留通用 AMA、全球 Maker 和 Maker 需求卡片；页面分享、来源追踪、复制图片与下载 PNG 使用同一份数据语义。
• 交付包完整包含 @zaowu/web-analytics，Space、Auth 和模板文档站可按公开配置分别接入自托管 Umami；本地、HTTP、非生产和非白名单域名继续不追踪。
• 交付文档只描述通用自托管与可选对象存储发布，不依赖发行方的域名、Bucket、私有路径和七牛发布钩子；七牛文档站发布改为显式的可选命令。
• 导出门禁新增工作区依赖、运维脚本依赖、转换后源码语法、页面与后台档案检查；发布验收会从实际 ZIP 解压后完成锁文件安装、类型检查、全量测试和生产构建，避免开发目录通过但正式交付缺文件或模板定制文件没有同步。
• 清理交付范围之外的专有发现工具、邀请来源和公开文案，同时保留社区模板可复用的抽奖、分析、媒体和证书维护运行时。

兼容性：本版本把现有 0098_space_lottery.sql 迁移正式纳入可用交付，收货地址继续复用 space_commerce_addresses 及服务端字段加密；没有新增 Secret。升级前必须备份数据库、.env 和 .secrets/，对照 .env.example 补充可选的 Umami 公开配置，运行 pnpm ops:template:preflight 后再执行标准升级。回滚只切换到上一个已验证源码版本并复用原环境配置和持久卷；不要回写迁移、删除抽奖/地址数据、清空卷或重新开奖。

1.0.0-alpha.22

• 生产预检新增模板文档站、所有 Qiniu 公开资源 Origin 与原生 Apple 标识检查，部署前即可阻止 example 占位值进入运行容器。
• APNs 或 App Store 启用时，预检要求 AASA、Topic、Bundle ID 与商品 ID 完整且非占位；相关能力关闭时仍保持可选。
• 模板导出继续排除不属于交付范围的测试文件，避免后续回归用例破坏源码包发布门禁。
• 交付源码同步共享合同的 3D 模型资源类型与上传权限，并完整注册模型资源、自动消息和后台路由；相关模块启用后即可通过类型检查、构建和真实 API 调用。
• 完整 Mock 的 AMA 批量排期、动态候选时段和预约冲突校验保持一致，交付内回归测试可直接验证实际 Mock 服务。
• Web 生产镜像为非 root 运行用户预建可写的 Next.js 缓存目录，避免预渲染缓存更新因容器权限失败。

兼容性：没有数据库迁移。升级前备份现有 .env，配置真实的 TEMPLATE_DOCS_PUBLIC_URL；使用原生 iOS 能力的部署还需要填写 SPACE_IOS_ASSOCIATED_APP_ID，并在启用 APNs / App Store 前配置对应标识。运行 pnpm ops:template:preflight 通过后重新构建并创建 Web 服务。

1.0.0-alpha.21

• AMA 后台新增连续可预约时间池管理，支持按日期范围、星期和每日时间段批量设置，也保留临时单次加开；提交前可以预览将生成的具体窗口。
• 批量排期会原子写入并跳过完全重复的窗口，真实 API 与完整 Mock 共用同一套合并、去重和冲突算法；预约创建会在服务端再次检查，避免两个用户获得交叉时段。
• 30 / 60 / 90 分钟咨询产品会按剩余连续时间动态生成候选时段。例如两小时窗口先约掉前 30 分钟后，后续 90 分钟仍可继续预约。
• 个人主页分享卡优化长简介布局，在窄屏、长文本和图片导出时保持简介与页脚信息不重叠。
• 交付导出测试新增 AMA 排期 contract、后台管理器、真实 API、Mock 集成测试和分享卡布局测试的完整性断言，避免后续同步时只带页面、不带规则或测试。

兼容性：没有新增数据库迁移或环境变量。升级只需要部署新源码；已有咨询产品、可预约窗口、预约、积分与支付记录保持原样。回滚到上一版时历史 capacity 字段仍保留，但不要把它当作已支持的并发咨询人数。

1.0.0-alpha.20

• 新增通用“推荐与返利”模块，年度会员默认 20%、创始会员默认 30%，同一套链接与账本覆盖会员、内容、实物、数字商品、活动和积分补充。
• 会员计划、内容、实物、数字商品和活动详情页支持直接分享；同一成员对同一对象只保留一条永久短链接，重复分享自动复用。个人中心用于查看目录、点击与返利明细；后台新增伙伴、规则、链接、交易裁决、人工核销和人工结现七个分区。
• 订阅永久邀请关系优先于临时推荐链接，同一交易只能在现金返利、邀请积分、无奖励三种通道中选择一种；自推、兑换、零元、测试与无有效归因不会生成返利。
• 返利按优惠后的真实现金净收入计算，不含运费；退款会冲减未结现返利，已结现退款形成可审计追偿，并在后续结现批次中逐笔、分段且不重复抵扣。
• full Mock 新增三种互斥裁决、返利伙伴、链接、核销和结现场景；模板配置新增 referrals 开关。

兼容性：新增推荐返利数据库迁移与 SPACE_REFERRAL_TOKEN_SECRET。升级前保留数据库备份，在 .env 中配置独立的 32 位以上高熵 Secret，运行 pnpm ops:template:preflight 后再部署；既有邀请积分和早期版本的活动/小铺推荐记录不会自动改写。

1.0.0-alpha.19

• 文档首页、顶部导航和侧边栏新增独立的“二次开发”入口，人工开发、AI 协作开发与 Provider 扩展不再藏在部署说明中。
• 新增 AI 二次开发指南，明确上下文读取顺序、先设计再实现、代码边界、Secret 与生产数据保护、验证矩阵和交付报告格式。
• 源码包根目录新增 AGENTS.md，代码 Agent 解压后即可读取与文档一致的安全操作规则。
• 人工二次开发说明补充标准工作流、移动端走查、真实 API 与 Mock 对齐，以及新模板版本的分支合并方式。

兼容性：没有数据库迁移、环境变量或运行时功能变化。已有二次开发仓库可以只同步文档站、AGENTS.md 和对应导航配置。

1.0.0-alpha.18

• 生产预检优先复用正在运行的 Nginx 容器读取证书副本，避免部分 Docker 环境创建临时 ACME 容器后卡在清理阶段。
• Nginx 尚未启动时仍会回退到 ACME 容器，首次部署与存量升级都保持同一套证书、腾讯 VOD 防盗链和回调检查。

1.0.0-alpha.17

• 正式源码包完整包含独立的 SSO / Auth API、登录界面和社区回调链路，本地演示可以直接体验登录、会话与退出。
• 站点名称、简称、备案信息和登录品牌由同一份社区配置驱动，二次开发时不需要逐页修改原站文案。
• 增加二次开发说明、可复现安装检查和源码包完整性校验，便于在独立 Git 仓库中持续定制。
• 补齐返利仪表盘与七种数字商品账号场景；演示下载包会校验文件存在性、大小、SHA-256 和 ZIP 文件签名。
• 收紧生产容器、首次证书申请、反向代理、备份工具和敏感文件排除规则，减少误公开配置或把本地凭据打进镜像与提交的风险。

兼容性：没有数据库迁移。升级前请保留现有 .env、.secrets/ 与持久卷；重新对照 .env.example 补充备份存储的区域和 HTTPS Endpoint 配置，并重新运行生产预检。

1.0.0-alpha.16

• 数字商品发布入口现在根据版本号自动识别大版本线；例如 1.8.0 自动归入大版本线 1，2.0.0 自动归入大版本线 2。
• Space API、完整 Mock 和数据库共同拒绝版本号与大版本线不一致的发行记录，避免旧大版本权益账号误获未来大版本。
• 发布确认会明确展示版本号和最终大版本线；切换当前大版本不会扩大或撤销已有账号权益。
• 已获得当前大版本权益的账号仍可重复申请该大版本线内已发布版本的短时下载地址，不限制下载次数。

兼容性：新增软件发行版本一致性数据库约束，不增加环境变量。升级前会检查已有发行记录；若历史版本号与大版本线不一致，迁移会停止，需先人工确认数据归属，不能自动改写授权范围。

1.0.0-alpha.15

• 后台新增“数字商品交付”，可以从已启用的商品目录选择模板、主题、插件或素材，并登记新的不可变发行包。
• 发行表单会按商品生成私有文件路径建议，同时校验版本号、大版本线、文件大小、SHA-256、公开时间和用户更新说明。
• 同一套界面展示各个数字商品的发行历史；新增其他数字商品时不需要再开发专用发布页面。
• 活动票种折扣码、兑换码、报价和超时释放能力继续包含在本版本中。

兼容性：没有新增数据库迁移或环境变量。发布前仍需先将 ZIP 上传到配置好的私有交付存储，再在后台登记完全一致的文件大小与 SHA-256。

1.0.0-alpha.14

• 活动报名接入通用折扣码与兑换码；同一套后台可以分别配置会员、内容、实物商品、数字商品和活动票种代码。
• 活动码绑定一场活动和一个票种，支持百分比、固定减免、最低金额、有效期、总次数与启停状态；兑换码可以把指定票种变为 0 元报名。
• 报价和报名提交会重复校验活动、票种、销售期、金额与代码规则；待审核、待支付、支付成功、审核拒绝、用户取消和超时关闭分别维护代码的预占、核销与释放。
• 活动报名页可先验证代码并查看原价、优惠和应付金额；“我的活动”保留代码来源和价格快照。
• 定时维护同时关闭过期的小铺、数字商品和活动待支付记录，释放对应名额与未核销代码。
• 模板 Worker 默认启用交易维护并复用站内机器令牌；通用健康巡检和摘要示例仍保持 dry-run。

兼容性：新增活动报名价格快照、代码绑定字段，并允许通用商品码使用 event / event_ticket 范围；升级需要执行数据库迁移。已核销活动码在活动退款后不会恢复次数，避免重复退款套利；未付款取消、审核拒绝和超时关闭会恢复次数。

1.0.0-alpha.13

• 小铺折扣码与兑换码扩展为通用商品能力，后台可分别绑定实物商品或数字商品。
• 数字商品码按产品 key 和“当前大版本 / 终身更新”档位配置；兑换成功后直接发放对应下载权益。
• 实物商品码按商品 ID 或 slug 配置；兑换码只抵扣一件目标商品，购物车中的其他数量、商品与运费继续正常结算。
• 报价、下单和支付完成前都会重新核对代码、商品、价格、库存、次数与有效期；取消或超时订单会释放预占。
• 年度会员、创始会员、当前大版本购买、终身购买与兑换权益在商品页分别显示来源，不再使用笼统的“已经拥有”提示。

兼容性：新增通用商品码预占记录、数字商品报价与订单有效期字段；升级需要执行数据库迁移。已有会员与内容码保持原有范围，不会自动作用于实物或数字商品。

1.0.0-alpha.12

• 小铺入口统一为“浏览全部商品”，继续同时展示实体商品与数字商品。
• 补齐年度订阅到期、期内新大版本、续订、当前大版本和终身更新的权益边界。
• 已拥有权益和相同待支付订单会被服务端拦截；已取消订单不能再次确认支付。
• 本地 Mock 与真实 API 对齐未来版本隐藏、短时下载和订阅包含开关。
• 数字商品发行文件除七牛私有空间外，也可放入服务器私有目录，通过主站生成短时下载地址。

兼容性：新增软件权益保留迁移；升级需要执行数据库迁移。启用文件系统交付时需增加对应目录挂载和独立下载签名 Secret；继续使用七牛交付不需要迁移发行数据。

1.0.0-alpha.11

• 文档按产品与功能、开始使用、部署与维护、购买与交付重新分组，并新增产品概览、使用场景、功能介绍、部署概览、人工部署、价格与下载说明。
• 主站小铺新增通用数字商品能力，模板、主题、插件和资源包可以复用同一套商品列表、详情、定价、版本和账号授权下载组件。
• 社区模板作为首个数字商品上架，支持年度订阅、当前大版本和终身更新三种获得方式。
• 支付成功后在服务端写入版本权益；下载时重新校验账号授权并生成短时地址。
• 仅供维护者使用的发布流程已移出用户文档站。
• 交付包的生产商品目录默认留空；本地 Mock 保留示例商品用于体验完整购买流程。

兼容性：增加软件订单表和数字商品展示字段；升级需要执行数据库迁移。旧 /template 地址会跳转到小铺中的对应商品详情。

1.0.0-alpha.10

• 首页右侧私有部署图升级为高清品牌插画，保留“你的域名、你的服务器、你的数据库连接社区模板”的原有结构和信息顺序。
• 插画继续展示内容、社区、订阅与小铺四类能力，并针对桌面与移动端统一了比例和清晰度。

兼容性：没有代码配置、环境变量或数据库迁移；只调整文档站首页视觉素材。

1.0.0-alpha.9

• 重组使用说明，首页和导航现在直接通往本地体验、功能配置、生产部署、安全与升级。
• “包含内容”页面明确区分源码能力、本地演示、上线前准备和当前不直接提供的服务。
• 本地示例身份和演示版本说明统一为中性内容，便于替换为自己的品牌与业务数据。
• 文档首页补充源码工程、本地演示环境、部署升级手册和 Provider 配置提示。

兼容性：没有代码、配置或数据库迁移；只调整文档结构与文案。

1.0.0-alpha.8

• 首页“独立部署”和后台“配置与文档”直接使用文档站地址，避免跨域重定向产生 RSC 控制台错误。
• 保留 /template 兼容入口，旧书签仍会跳转到当前配置的文档站。

兼容性：没有数据库或配置迁移。部署时继续通过 TEMPLATE_DOCS_PUBLIC_URL 指定文档站地址。

1.0.0-alpha.7

• 补齐共建计划的只读建议列表接口，/next 可按产品体验、内容选题和实验想法三组展示演示数据。
• 修正版本更新接口的分页响应结构，/updates 不再因读取不到 items 落入错误边界。

兼容性：没有数据库或配置迁移，只修复本地 Mock 的两个只读响应。

1.0.0-alpha.6

• 将 11 个平铺头部入口收敛为“社区、内容、商业、Maker、AI”五个顶级入口，下拉菜单支持键盘导航和焦点恢复。
• 修复“我的问答与预约、我的 Maker 提交、邀请中心、个人联系方式与授权”等本地演示页面的读取接口。
• 文档导航聚焦功能配置、部署、包含内容、升级、版本与安全说明。
• 共享 UI 组件和设计令牌完整包含在源码包中。
• 63 个页面完成桌面与 390px 移动端共 126 次真实渲染检查。

兼容性：没有数据库迁移。头部信息架构有调整；如果定制代码依赖旧导航 DOM，请改为使用新的分组触发器。

1.0.0-alpha.5

• 补齐文章、集合、内容详情和编辑器使用的共享内容样式。
• 恢复 /template 文档入口，首页“独立部署”和后台配置入口可以正常打开说明站。
• 缺少实体素材时使用稳定尺寸的演示封面，避免文件名占位图干扰走查。
• 增加桌面与移动端视觉检查，覆盖封面尺寸、首屏层级、横向溢出、资源兜底和文档内链。

兼容性：没有配置或数据迁移，只修复源码包内容与本地演示表现。

1.0.0-alpha.4

• 建立社区、内容、订阅、商业、活动、问答、Maker 目录/需求、通知、邀请、数字文件交付、AI 与自动化的基础模块集合。
• community-template.json 升级到 schemaVersion: 2，模块键统一为可配置的通用能力。
• full 场景改为完整的虚构 Maker 案例，覆盖内容浏览、会员、订单、活动、协作与运营入口。
• 增加默认只读或 dry-run 的通用自动化服务，以及显式配置后的 GitHub 官方公开元数据示例。
• 本地 Mock 支持上传、视频直传/播放、模拟支付、规则 AI 与邮件 outbox。

兼容性：旧配置需要依据功能配置重新确认模块开关。

1.0.0-alpha.3

• 补齐本地视频上传计划、原始文件直传、完成确认、播放授权和进度恢复链路。
• 新增 /__mock/providers，报告对象存储、支付、视频、外链预览、AI 和邮件的本地运行状态。
• 新增邮件 outbox 的写入、查看、清空与场景重置能力。
• 新增外部服务 Mock，说明每种本地替代链路覆盖和不覆盖什么。
• YouTube、B 站与 X 示例使用离线预览卡片，不自动加载第三方播放器或脚本。

兼容性：配置结构仍为 schemaVersion: 1。生产环境不得暴露 /__mock/*。

1.0.0-alpha.2

• 增加 full Mock 一键体验，同时启动社区 Web、Mock API 和 VitePress 文档站。
• 演示数据覆盖文章、动态、集合、订阅、商品、订单、活动、邀请、Maker 与数字文件下载。
• 增加本地体验、界面预览、品牌定制、升级回滚与版本记录文档。
• 备案号改为可配置项；设置为 null 时页脚不显示备案链接。

兼容性：配置结构仍为 schemaVersion: 1。

1.0.0-alpha.1

• 首个可安装和构建的 Web 模板压缩包。
• 提供功能模块、Provider、AI 部署、安全和文档站部署说明。
• 下载文件附带交付清单与 SHA-256 校验值。

Alpha 版本用于验证使用路径和部署机制，升级前必须阅读兼容性说明并保留可用备份与回滚版本。