平台完善

本文是“平台完善”模块的规划与持续维护入口。当前内容用于确定模块边界、教学路线和代码框架，不表示所有功能已经开发或验证完成。后续每完成并验证一个小功能，再逐步补充实现代码、逐行解释、测试结果和常见问题。

文档版本	v0.2.0
更新时间	2026-08-26 11:34:30 +0800
本次更新	产品和项目正式由 devops（旧名） 更名为 devopsX，同步调整项目根路径和相关框架名称；博客分类 Python / devops 保持不变。
当前状态	模块规划稿，功能尚未开始或尚未全部验证
Django App	不单独创建 Django App

1 模块定位

负责跨模块的工程质量、可靠性、安全性、异步任务、日志、测试和部署规范。它不是一个笼统的 platform Django App，而是一组按需要落到配置包、common、测试和基础设施中的横切能力。

1.1 模块目标

• 建立统一但不过度抽象的公共规范。
• 完善异常、日志、异步任务和测试体系。
• 提升安全性、性能和可观测性。
• 形成开发、测试和生产环境的可重复配置。
• 保证新增模块可以按相同约定接入平台。

1.2 顺序不是固定合同

本文中的功能顺序只表示当前推荐的学习路线，不是永久不变的产品编号。以后可以在本模块中插入新的功能，也可以在整个平台中增加新的独立模块，不需要重命名本文、重排其他文章标题或重构其他 Django App。

2 模块边界

2.1 本模块负责

• 公共配置
• 异常和日志
• Celery 与 Redis
• 测试体系
• 安全与性能
• 部署和运维规范

2.2 本模块不负责

• 把所有业务逻辑塞入 common
• 创建无边界的 platform App
• 提前建设未被两个模块复用的抽象
• 用横切层直接访问各业务内部实现

边界的目的不是阻止模块协作，而是避免一个 App 直接承担其他 App 的业务职责。跨模块需求应通过公开服务、API、事件或稳定标识完成。

3 代码位置与目录规划

本篇描述跨模块工程能力，不创建一个包揽所有内容的 platform App。代码应放到真正负责它的配置、公共层、测试或基础设施位置。

C:\Users\lizexiong\devopsX
├── devopsX                 # 全局配置
├── common                 # 已被多个模块证明需要共享的代码
├── tests                  # 必要的跨模块测试
├── static
├── templates
└── requirements.txt

3.1 最小接入点

新增业务模块时，只应增加自己的 App、URL namespace、模板 namespace、权限前缀和必要的平台注册项。根配置允许增加少量明确的注册代码，但不能要求修改其他业务 App 的内部文件。

3.2 不提前制造复杂目录

文章展示的是发展方向，不要求第一节一次创建完整目录。初期优先使用 Django 默认生成的文件；只有 models.py、views.py、tests.py 等文件真实变大后，才按职责拆分。

4 候选数据模型

下面是当前候选模型，用于帮助理解领域，不代表第一节全部创建。每个模型都需要在对应功能开始时再次验证是否必要。

模型或能力	职责
默认不新增统一业务模型	横切能力优先通过配置、工具、基类和明确接口实现。
TimestampedModel	只有多个 App 已重复需要创建和更新时间时，才抽取公共抽象模型。
Task / Log metadata	由对应基础设施或领域模块保存，不能建立一个包办所有用途的大表。

5 当前功能路线

下面是当前推荐路线。以后可以增加、删除或调整某一步，而不影响其他模块文章和 App 结构。

当前顺序	功能	状态
1	整理 settings 和环境变量	按当前学习进度逐步确定
2	统一日志格式与敏感信息过滤	按当前学习进度逐步确定
3	建立全局异常处理边界	按当前学习进度逐步确定
4	引入 Redis 和 Celery	按当前学习进度逐步确定
5	建立定时任务和任务监控	按当前学习进度逐步确定
6	完善单元测试、集成测试和页面验证	按当前学习进度逐步确定
7	建立 API 规范和分页规范	按当前学习进度逐步确定
8	增加性能分析与数据库查询优化	按当前学习进度逐步确定
9	执行安全检查和依赖审计	按当前学习进度逐步确定
10	整理静态文件和生产部署	按当前学习进度逐步确定
11	建立备份、恢复和升级流程	按当前学习进度逐步确定

6 与其他模块的协作契约

• common 只接收已经被多个模块证明需要共享的稳定代码，不能成为杂物目录。
• 每个 App 保留自己的业务异常、服务和测试，平台层只定义最小公共契约。
• 新增模块通过配置注册、URL include 和公共约定接入，不要求修改其他业务 App。

6.1 避免内部耦合

其他 App 不应导入本模块的视图、表单或私有服务，也不应直接修改本模块数据库表。确实需要协作时，先定义最小公开接口；只有多个模块已经出现相同需求后，才考虑把稳定能力抽取到 common。

7 独立扩展规则

• 文章标题不依赖固定的全局数字编号。
• 文章内部继续使用 1、1.1、1.1.1 的标题层级。
• 模块使用稳定的 App 名称、URL namespace、模板 namespace 和权限前缀。
• 每个 App 管理自己的模型、迁移、服务、页面和测试。
• 新增未知模块时，新建自己的文章和 App，不重排现有文章和目录。
• 推荐学习顺序可以变化，但稳定标识和模块边界不能随意变化。
• 不为“未来可能需要”提前建设复杂插件系统；先用 Django 明确的注册点保持低耦合。

8 教学与练习方式

本模块后续每个小功能都按以下方式展开：

本节目标
→ 知识背景
→ 当前工作目录
→ 文件清单和完整路径
→ 完整命令与代码
→ 逐行或逐段解释
→ 执行流程和设计原因
→ 运行验证
→ 常见错误与调试
→ 跟随、修改、填空、独立和排错练习
→ 完成后的目录树
→ 等待用户反馈

默认由用户亲手创建文件、输入代码并执行命令。除非用户明确要求代为操作，否则不自动一次写完整个模块。

9 模块验收标准

• 测试可以在干净环境重复运行
• 日志不泄露密码或 Token
• 异步任务失败可观测且不会无限重试
• 关键页面和接口有性能基线
• 部署与恢复步骤能够被重复验证

只有具体功能通过相应测试和实际操作验证后，才把它标记为完成并整理为可复现教程。规划、候选模型和未来路线不能被描述为已经实现。

10 当前状态与维护方式

当前文章已完成模块边界和路线规划，具体代码将随着实际开发逐步补充。后续修改遵循以下原则：

• 用户在 Python / devops 分类中维护文章入口；
• 每次完成并验证功能后，更新对应文章正文；
• 架构变化时先判断影响范围，再更新 Skill 和相关模块文章；
• 只修改真正受影响的模块，不因为增加一个模块而批量重写其他文章；
• 文章可以持续优化，但必须保留准确的状态说明。