二次开发指南

阅读顺序

接手 MDMS 项目进行二次开发前，请按以下顺序阅读项目根目录下的六层路标文档:

PHILOSOPHY.md 设计哲学（不可违反的原则）

DICTIONARY.md 项目字典（术语定义和隐含规则）

CONVENTIONS.md 开发规范（命名/注释/前端约束）

ARCHITECTURE.md 技术架构（当前系统结构）

ROADMAP.md 演进路标（未来方向和扩展点）

CHANGELOG.md 更新日志（版本历史）

设计红线

以下原则不可违反，违反等同于创建新项目而非 MDMS 的二次开发:

输出物必须是纯静态文件，不依赖运行时服务

搜索框必须出现在所有公共页面

六色体系不可突破（黑白灰蓝红绿 + 五级灰阶）

四级字号不可新增（10px / 12px / 15px / 20px）

LLM 是助手不是主人，用户手动输入永远优先

命名规范

Handler 函数: handle + 模块单数 + 动作，如 handleArticleSave

路由路径: /admin/模块复数/动作，如 /admin/articles/batch

配置字段: Go 大驼峰 WebSearchDomain，JSON 蛇形 web_search_domain

模板文件: 蛇形命名，如 search_terms.html

代码标记

在源代码中搜索以下标记可快速定位关键位置:

ANCHOR: 架构扩展点（可替换的模块）

ROADMAP: 未来改动方向

DEBT: 技术债务（应修未修）

新增功能的标准流程

第一步，在 ROADMAP.md 中确认功能是否已规划，了解其影响范围和风险等级。

第二步，阅读相关源文件顶部的重构路标注释，理解依赖关系。

第三步，编写代码，遵循命名规范和注释规范。

第四步，新文件顶部必须添加重构路标注释块。

第五步，编译测试: go build -o mms . && ./mms -mode=build

第六步，更新 CHANGELOG.md 和版本号（config/version.go）。

前台 VI 规范

六色体系: #1a1a1a（黑）/ #fff（白）/ #f5f5f5 #ccc #999 #555 #333（五级灰）/ #1a73e8（蓝）/ #e53935（红）/ #00897b（绿）

四级字号: 10px 辅助标签 / 12px 正文 / 15px 品牌 / 20px 标题

禁止使用 emoji，禁止使用 | 作为视觉分隔符，禁止引入规范外的颜色和字号。