# 01 项目开发宪法（不可随意修改）

## 1. 产品定位硬约束

本项目必须始终是：

> 公益服务数字化平台，而不是宣传网站、商城、社交平台或复杂互联网平台。

V1.0 第一目标：让真实服务闭环跑通。

主链路：

```text
服务对象/代申请人提交需求
→ 工作人员受理
→ 需求评估
→ 建立/关联服务对象档案
→ 创建服务工单
→ 分配工作人员/志愿者
→ 执行服务
→ 留痕
→ 服务对象确认/反馈
→ 回访
→ 必要时继续跟进
```

任何新功能都必须回答：“是否增强这条主链路？”

---

## 2. 用户体验硬约束

1. 小程序优先服务普通群众、老人和低数字技能用户。
2. 主要操作不得依赖复杂手势。
3. 核心按钮大、清楚、可理解。
4. 服务申请尽量在 3~4 个步骤内完成。
5. 表单遵循“少填、可选、可拍、可说、可代办”。
6. 不在前端暴露技术术语、内部状态码。
7. 不为了视觉炫技牺牲加载速度和可理解性。
8. 所有失败状态必须给普通人能看懂的说明与下一步动作。
9. 适老化不是“放大字体”这么简单，必须包含点击区域、对比度、信息密度、步骤数量、错误恢复能力。
10. 功能完成度优先于动画和装饰。

---

## 3. 技术硬约束

1. 国内网络环境可稳定开发、构建、部署和访问。
2. 微信小程序作为公众端。
3. Web 管理后台作为机构工作人员端。
4. 后端采用模块化单体优先，V1.0 禁止为了“先进”拆微服务。
5. MySQL 为核心关系数据库。
6. Redis 只用于缓存、限流、短期状态等可恢复数据，不作为业务事实唯一存储。
7. 文件不保存到应用容器本地磁盘；生产环境使用对象存储。
8. 必须 Docker 化。
9. 环境分 dev / test / staging / prod。
10. 配置必须环境变量化，禁止把密钥提交 Git。
11. 所有数据库修改必须 migration。
12. 生产部署必须有备份、恢复、日志、监控和健康检查。
13. 对外部供应商能力必须封装 Adapter，不让业务层直接绑定云厂商 SDK。
14. V1.0 不引入 Kubernetes。
15. V1.0 不引入复杂事件总线，必要异步任务先使用可靠 Job/Queue 模式。

---

## 4. 安全硬约束

平台会处理老人、困境妇女、儿童、残疾人、困难家庭等敏感服务信息。

必须做到：

- 默认最小权限；
- 后台 RBAC；
- 资源级权限校验；
- 敏感字段脱敏；
- 操作审计；
- 不允许越权查询；
- 不允许通过 ID 枚举他人服务记录；
- 数据导出必须受控；
- 文件下载必须鉴权；
- 上传文件做类型、大小、扩展名、MIME 校验；
- Token、手机号、身份证件、地址、儿童信息不得写入普通日志；
- 删除业务数据优先软删除/归档，禁止随意物理删除；
- 关键状态变更保留历史；
- 不满 14 周岁相关信息按监护人授权与更严格权限原则处理；
- 不把真实生产数据复制到开发环境；
- 测试数据必须脱敏或生成。

---

## 5. 可靠性硬约束

1. 所有写请求应支持幂等或防重复提交。
2. 重要状态迁移必须使用数据库事务。
3. 不允许“接口成功但数据库只写了一半”。
4. 异步任务失败必须可重试、可查询。
5. 外部服务失败不能拖垮主业务。
6. 外部短信、订阅消息、对象存储失败应有降级和补偿。
7. 服务工单状态必须经过状态机校验，不能任意改字符串。
8. 每个关键实体保留 `created_at / updated_at / created_by / updated_by`。
9. 每个关键业务操作有 audit log。
10. 任何“已完成”都必须有可验证结果，不能只靠前端显示。

---

## 6. 易维护硬约束

- 避免自研基础组件；
- 避免魔法数字；
- 枚举集中管理；
- DTO 与数据库 Entity 分离；
- Controller 不写复杂业务；
- Service 不直接散落第三方 SDK；
- Repository 层负责数据访问；
- 公共错误码统一；
- 日志统一；
- 配置集中；
- 每个模块有 README 或模块说明；
- 复杂逻辑写测试；
- 删除代码前检查是否有业务依赖；
- 依赖升级必须经过测试，不追新版本。

---

## 7. V1.0 禁止范围

除非后续明确批准，V1.0 禁止：

- 在线公开募捐核心交易系统；
- 复杂社交/朋友圈；
- 即时 IM 聊天系统自研；
- AI 自动作出救助资格决定；
- 人脸识别；
- 未经必要性论证收集身份证完整信息；
- 微服务/K8s；
- 大数据平台；
- 区块链；
- 自研工作流引擎；
- 复杂积分商城；
- 过度游戏化；
- 对外开放 API 平台；
- 多租户 SaaS 架构。

---

## 8. AI 功能原则

AI 是效率工具，不是 V1.0 主角。

后续 AI 必须：

- 默认建议、不自动做高风险决定；
- AI 结果明确标记；
- 工作人员确认后才写入正式业务记录；
- 不把敏感数据发送到未经批准的外部模型；
- 能关闭；
- 业务流程不依赖 AI 才能运行。