131 lines
3.8 KiB
Markdown
131 lines
3.8 KiB
Markdown
# 乐活公益·暖心服务平台 —— 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认为更合理”而推翻已经批准的业务规则。
|