# 乐活公益·暖心服务平台 —— Codex 开发文档包

> 版本：V1.0  
> 文档用途：作为 Codex / AI 编程智能体的长期开发上下文、项目规则和验收依据。  
> 最高原则：任何代码实现不得偏离本目录文档。发生冲突时，按本文档规定的优先级处理。

---

## 1. 项目一句话定义

“乐活公益·暖心服务平台”不是公益宣传页，而是一套以微信小程序为公众入口、Web 管理后台为工作人员入口、以“需求申请 → 受理评估 → 建档 → 派单 → 服务 → 反馈 → 回访 → 持续关爱”为核心闭环的公益服务数字化平台。

主要服务领域：

1. 关爱老年人、为老服务；
2. 困境妇女慈善帮扶；
3. 困境儿童关爱与帮扶；
4. 残疾人爱心救助与帮扶；
5. 其他困难群体服务；
6. 志愿者组织、公益活动、公益资源和社会参与。

---

## 2. Codex 每次开始工作前必须执行

按顺序阅读：

1. `00_README_FIRST.md`
2. `01_PROJECT_CONSTITUTION.md`
3. `02_PRODUCT_PRD_V1.md`
4. `03_ARCHITECTURE.md`
5. `04_DATA_MODEL.md`
6. `05_API_AND_WORKFLOW.md`
7. `06_SECURITY_PRIVACY.md`
8. `07_UI_UX.md`
9. `08_ENGINEERING_RULES.md`
10. `09_TEST_ACCEPTANCE.md`
11. `10_TASK_STATE.md`
12. `11_DECISIONS.md`

如果只是小范围修复，也至少必须阅读：

- `01_PROJECT_CONSTITUTION.md`
- `10_TASK_STATE.md`
- 与修改模块相关的文档
- `11_DECISIONS.md`

不得仅根据聊天中最近一句话修改项目。

---

## 3. 开发结束后必须回写

每完成一个任务，必须：

1. 更新 `10_TASK_STATE.md`；
2. 若产生架构/技术/业务决策，更新 `11_DECISIONS.md`；
3. 若接口变化，更新 API 文档；
4. 若表结构变化，更新数据模型与 migration；
5. 增加或更新自动化测试；
6. 执行 lint、typecheck、unit test、integration test、build；
7. 输出本次变更摘要、影响范围、风险、回滚方式。

禁止“只改代码、不改文档”。

---

## 4. 冲突处理优先级

从高到低：

1. 数据安全、隐私、法律合规；
2. `01_PROJECT_CONSTITUTION.md` 中的硬约束；
3. 已确认的产品业务规则；
4. 数据一致性和可审计性；
5. API 契约；
6. UI/UX 规范；
7. 工程偏好；
8. Codex 自己认为“更先进”的方案。

如果 Codex 认为有更好的方案，但会改变既有边界，必须记录到 `11_DECISIONS.md` 的“待确认建议”，不能擅自实施。

---

## 5. 代码仓库建议结构

```text
lehuo-public-service/
├─ apps/
│  ├─ miniprogram/       # 微信小程序
│  ├─ admin-web/         # Web 管理后台
│  └─ api/               # 后端 API
├─ packages/
│  ├─ contracts/         # DTO / enum / schema / API 契约
│  ├─ shared/            # 无业务副作用的共享代码
│  ├─ eslint-config/
│  └─ tsconfig/
├─ infra/
│  ├─ docker/
│  ├─ nginx/
│  ├─ scripts/
│  └─ backup/
├─ docs/
│  ├─ 本文档包
│  └─ diagrams/
├─ migrations/
├─ .env.example
├─ pnpm-workspace.yaml
├─ package.json
├─ AGENTS.md
└─ README.md
```

---

## 6. AGENTS.md 必须包含

仓库根目录 `AGENTS.md` 应复制以下核心规则：

- 先读 `docs/00_README_FIRST.md` 与 `docs/01_PROJECT_CONSTITUTION.md`。
- 不擅自改变产品定位、技术栈、数据库类型、认证方式。
- 不删除既有功能来“简化实现”。
- 不通过 mock 假装功能完成。
- 不将敏感信息写入日志。
- 每个业务状态变化必须可审计。
- 所有表结构变化必须 migration。
- 所有 API 变更必须同步 contracts。
- 完成任务必须更新 `docs/10_TASK_STATE.md`。
- 任何架构决策必须更新 `docs/11_DECISIONS.md`。
- 不因“AI认为更合理”而推翻已经批准的业务规则。