ShaoHua
cf96c56bed
本次提交完成了多项清理与规范工作： 1. 移除默认管理员硬编码配置与云同步相关代码 2. 简化前端与MAUI端的配置，关闭静态资源托管以外的冗余功能 3. 清理.gitignore与协调目录，移除临时文件与冗余规则 4. 统一项目命名规范，修正包名与版本号 5. 重构后端数据模型，移除ABP审计字段与云同步相关逻辑 6. 简化WebView配置与系统栏样式，移除不必要的平台检测代码 7. 更新文档与规则文件，完善项目规范与版本记录
35 lines
1.8 KiB
Markdown
35 lines
1.8 KiB
Markdown
---
|
||
alwaysApply: true
|
||
description: 强制项目注释规范（C# / TypeScript）：新增或修改代码必须补全必要注释，便于维护与跨平台开发。
|
||
---
|
||
|
||
# 注释规范（必须遵守）
|
||
|
||
> 适用范围：本规则属于 **全局规则**（跨项目通用），针对 C# / TypeScript / Vue 代码的注释要求。
|
||
|
||
## 通用
|
||
|
||
- 新增或修改的代码必须包含足够注释，使"不了解该模块的人"也能理解其职责、边界与关键决策。
|
||
- 优先使用 **XML 文档注释**（`///`），而不是随意的行内注释。
|
||
- 不允许无意义注释（例如"初始化变量""进入方法"）。注释必须解释"为什么/约束/边界/副作用"。
|
||
- 不允许出现"TODO/FIXME"但无上下文或无处理方案的注释。
|
||
|
||
## C#（.NET / MAUI）
|
||
|
||
- 所有 `public` / `protected` 的 **类、接口、方法、属性** 必须提供 XML 文档注释，至少包含：
|
||
- `summary`：一句话说明用途
|
||
- 对关键参数/返回值：`param` / `returns`
|
||
- 对异常或副作用：在 `summary` 中明确说明（例如会注册系统钩子/会启动后台服务）
|
||
- 对 **跨平台逻辑**：
|
||
- 禁止在同一文件内混写多个平台的大段 `#if` 实现；应优先使用 `partial`、接口与平台目录分离。
|
||
- 平台分离后的公共入口处必须说明"平台差异在哪里、默认实现是什么、为什么这么做"。
|
||
- 对 **异步/后台任务**：
|
||
- 必须说明启动时机、错误处理策略、是否需要 UI 线程、以及是否可并发/可重入。
|
||
- 对 **安全/隐私**：
|
||
- 禁止在日志或注释中输出密钥、Token、用户隐私信息。
|
||
|
||
## TypeScript / Vue（前端）
|
||
|
||
- 对导出的函数/类型必须有注释，解释用途与输入输出。
|
||
- 对"与后端/MAUI 交互"的协议字段（例如全局变量、事件名）必须注释说明来源与约束。
|