通用数字产品 开发核心规则
该 DOCX 包含不完整的 Office 元数据关系，已使用兼容模式恢复正文和媒体。
通用数字产品 开发前核心规则
本规则适用于 通用数字产品 网站全部开发工作。开始编写代码之前必须阅读并遵守。
1. 当前目标
当前阶段先完成一个：
可以正常上线、稳定运行、方便维护、以后能够继续扩展的个人博客基础版本。
当前不追求复杂架构，不追求大量高级功能，不提前制作未来暂时用不到的系统。
原则：
先把基础版本做好并上线，再逐步迭代。
2. 最重要原则：禁止强绑定
本项目必须具有良好的可迁移性。
不得让网站只能运行在：
某一个固定服务器
某一个固定云平台
某一个固定域名
某一个固定数据库
某一个固定对象存储
某一个固定 CDN
某一个固定接口
某一台电脑
某一个本地目录
某一个固定端口
未来如果更换这些环境，应尽量只修改配置或少量基础设施代码，而不是大面积修改整个项目。
3. 禁止硬编码
正式业务代码中禁止直接写死：
域名
IP
服务器地址
API 地址
端口
本地电脑路径
上传路径
数据库地址
对象存储地址
Secret
Token
API Key
密码
云服务配置
需要变化的内容必须统一配置管理。
例如：
不要：
应该：
API_BASE_URL
4. 禁止平台锁定
允许使用第三方平台、SDK、数据库和云服务。
但是：
使用 ≠ 绑定。
如果使用：
Cloudflare
Vercel
大型科技企业云
Supabase
Firebase
AWS
第三方对象存储
第三方 API
不得把对应平台的代码大量写进页面和业务逻辑。
平台专属实现应集中管理。
以后更换平台时，应尽量只替换对应实现，而不是修改整个网站。
5. 核心资源尽量本地化
网站运行所必需的核心资源不得无必要依赖第三方在线资源。
特别包括：
网站字体
Logo
图标
核心图片
核心 CSS
核心 JavaScript
网站必要素材
例如：
如果字体可以本地部署，就不要让网站必须访问某个外部字体网站才能正常显示。
第三方资源不可访问时，不得导致整个网站无法使用。
6. 配置必须集中
以下内容必须统一管理：
字体
颜色
字号
间距
圆角
页面宽度
API 地址
网站地址
上传设置
数据库配置
存储配置
第三方服务配置
环境变量
禁止同一个配置散落在大量页面里。
以后修改一个设置时，应尽量只改一个地方。
7. 模块之间不要绑死
不同功能尽量独立。
例如：
博客项目资源留言后台登录上传
某一个模块发生故障时，不应该导致整个网站一起无法运行。
例如：
上传服务故障：
应该：
上传暂时不可使用
而不是：
整个后台崩溃整个网站无法访问
8. 外部服务必须考虑替换
如果项目需要：
数据库
文件存储
AI API
邮件
登录
搜索
分析统计
设计时必须考虑：
如果未来不用当前供应商，能不能换？
不要求做到任何服务都可以一键替换。
但是禁止设计成：
更换一个服务，需要修改几十个页面和大量业务代码。
9. 不要偷偷增加依赖
未经必要性判断，不得擅自加入大量：
npm 包
SDK
框架
插件
云服务
在线资源
添加新的重要依赖前必须判断：
为什么需要？
原项目是否已经能实现？
是否增加平台绑定？
是否增加未来维护难度？
是否有更简单的方案？
优先使用简单、成熟、长期可维护的方案。
10. 不要过度设计
本规则要求：
可维护、可迁移。
但不意味着为了“解耦”制造大量复杂架构。
禁止为了一个简单博客提前建立：
大量无意义抽象层
不会使用的 Provider
不会使用的 Adapter
复杂微服务
复杂事件系统
过度封装
为未来假想需求开发代码
判断标准：
当前需要 + 未来明显可能需要。
没有实际用途的架构不要提前开发。
11. 禁止擅自修改
只修改当前任务要求涉及的内容。
不得擅自：
删除已有功能
重构无关模块
修改其他页面
更换技术栈
更换依赖
修改数据库结构
修改部署方式
改变设计系统
删除文件
修改用户没有要求修改的功能
如果发现其他问题：
记录。
不要顺手修改。
12. 保持普通服务器可部署
项目不能默认：
最终一定部署到某个平台。
开发时必须考虑：
网站未来可能部署到普通 Linux 云服务器。
因此不能因为开发环境方便，而依赖某个开发平台独有能力。
如果某个功能必须使用平台专属能力：
必须明确标记。
不得隐藏。
13. 开发过程中自行检查
每完成一个主要功能后，自行检查：
是否出现新的硬编码
是否加入新的第三方依赖
是否产生平台绑定
是否产生固定路径
是否出现重复配置
是否影响其他模块
是否可以正常 Build
是否存在明显错误
发现问题应立即说明。
14. 完成代码以后再进行完整测试
注意：
开发前不用执行完整迁移测试。
当前首先按照以上规则完成开发。
待基础版本代码完成以后，再进入：
通用数字产品 可移植性与隐藏依赖检测阶段。
到时候需要针对实际代码检查：
硬编码
隐藏依赖
平台绑定
域名绑定
服务器绑定
路径绑定
CDN 依赖
字体依赖
数据库耦合
存储耦合
API 耦合
构建环境依赖
部署环境依赖
第三方服务故障影响
检测应由开发工具自动执行。
用户不负责手动修改：
端口
域名
文件目录
系统环境
Provider
需要进行这些测试时，由开发工具创建测试环境并自行验证。
15. 测试与修复必须分开
完成开发以后：
第一步：
只测试。
输出问题报告。
不要边测试边偷偷修复。
第二步：
由用户确认问题和修复范围。
第三步：
再统一修复。
第四步：
重新测试。
流程：
开发规则↓编写代码↓基础功能完成↓完整检测↓问题报告↓修复↓重新检测↓部署
16. 完成开发时必须说明
每次主要开发任务完成后，必须明确告诉用户：
做了什么
修改了哪些文件
新增了哪些依赖
是否新增第三方服务
是否存在平台专属实现
是否存在当前已知限制
Build 是否通过
是否已经测试
不得只回复：
已完成。
17. 最终原则
本项目追求的不是：
永远不使用任何第三方技术。
而是：
可以使用，但不能被它控制。
任何第三方：
平台
服务
数据库
存储
API
SDK
CDN
都应该是项目可以选择使用的工具，
而不是项目无法脱离的前提。
当前执行要求
阅读本规则后：
先遵守规则进行开发。
当前不要执行迁移测试，因为项目尚未完成。
基础代码完成后，再根据项目实际情况执行完整的可移植性、耦合与隐藏依赖检测。