From 1c7c7d673e349761bed69fde7b7a51a84b6f7ce6 Mon Sep 17 00:00:00 2001 From: ishenwei Date: Sun, 26 Apr 2026 21:32:31 +0800 Subject: [PATCH] docs(fonrey): add web coding startup checklist --- Project/fonrey/WEB_CODING_开工前缺失清单.md | 101 ++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 Project/fonrey/WEB_CODING_开工前缺失清单.md diff --git a/Project/fonrey/WEB_CODING_开工前缺失清单.md b/Project/fonrey/WEB_CODING_开工前缺失清单.md new file mode 100644 index 00000000..e42abaaf --- /dev/null +++ b/Project/fonrey/WEB_CODING_开工前缺失清单.md @@ -0,0 +1,101 @@ +# Fonrey Web Coding 开工前缺失清单 + +> 记录时间：2026-04-26 +> 目的：在开始 Web Coding 落地前，把缺失但会直接卡住实施的文档一次补齐。 + +## 一、必须补齐的 6 份关键文档 + +### 1. 项目入口文档 +- README.md / 项目总览 +- 本地启动步骤 +- 环境变量说明 +- 数据库初始化与迁移说明 +- 种子数据说明 + +### 2. ADR 架构决策记录 +需要冻结以下决策： +- 登录态：session / token / 混合方案 +- django-tenants 本地开发模式 +- 单租户 MVP 与多租户架构共存方式 +- HTMX 页面局刷约定 +- 目录结构最终落点 +- 状态机与枚举字典权威来源 + +### 3. 枚举字典 / 状态字典 +建议新增： +- ENUMS.md +- STATE_MACHINE.md + +至少冻结： +- 客源状态 +- 客源等级 +- 房源状态 +- 操作日志类型 +- 租户状态机 + +要求统一： +- 中文值 +- 英文值 +- 数据库 CHECK 值 +- UI 展示值 +- 允许的状态迁移 + +### 4. 页面路由 + 组件映射 +需要明确： +- 每个模块有哪些页面 +- 每个页面对应什么 URL +- 每个页面复用哪些组件 +- 哪些页面是列表 / 详情 / 弹窗 / 抽屉 / partial +- 每个页面的空态、加载态、错误态、权限态 + +### 5. API 契约规范 +需要明确： +- 请求 / 响应格式 +- 错误码规范 +- 分页规范 +- 搜索 / 筛选规范 +- 上传规范 +- 文件下载规范 +- 权限拒绝返回规范 + +### 6. 本地开发与验证手册 +需要明确： +- 本地环境启动方式 +- PostgreSQL / Redis / Celery 启动方式 +- django-tenants 初始化方式 +- 测试租户创建方式 +- 管理员账号 seed 方式 +- 静态资源与对象存储本地替代方案 +- dev / staging / production 配置差异 + +## 二、建议优先级 + +### P0：先补，不补就不能稳定开工 +- 项目入口文档 +- ADR +- 枚举字典 / 状态字典 +- 页面路由 + 组件映射 + +### P1：随后补，直接影响实现质量 +- API 契约规范 +- 本地开发与验证手册 + +## 三、当前项目的直接风险 + +- 需求、数据模型、任务表已经较完整，但“可执行工程包”还不够 +- Review 已指出枚举不一致、分页规范缺位、性能基准缺位等问题 +- 没有启动手册和种子数据，Web Coding 容易停留在文档层，无法稳定进入实现层 + +## 四、建议的落地顺序 + +1. 先补 README / 启动手册 +2. 冻结 ADR +3. 冻结 ENUMS / STATE_MACHINE +4. 补页面路由与组件映射 +5. 补 API 契约 +6. 补本地开发与验证手册 +7. 再开始正式 Web Coding + +--- + +这份清单的目标不是增加文档数量，而是减少实现时的来回返工。